Step-by-step: Sending email messages from a workflow in an app for SharePoint 2013

The blog post on SharePoint Workflow Development with Office Developer Tools for Visual Studio 2012 introduced the development of SharePoint 2013 workflow apps. The “Getting Started
section of that post also describes the required software you need to install to build such an app. In this article, we will walk through the process of sending an email message from a workflow.

Walkthrough: Building a simple workflow to send email messages

Let’s start with a simple workflow that sends an email message to the user that initiates it. Start Visual Studio 2012 and follow these steps.

Complexity: Low

Overview: A user manually triggers the workflow, which then sends an email message to the user (workflow initiator) and adds a record in the workflow history that it has sent the email message.

  1. Create a new App for SharePoint 2013 as shown in Figure 1. We’ll use Visual Basic for this example, but the steps for C# are similar.

    Figure 1. Add new App for SharePoint 2013 Project Figure 1. Add new App for SharePoint 2013 Project

  2. Select the SharePoint-hosted type as shown in Figure 2 since this example does not require a separate web project in the solution then click on the Finish button.

    Figure 2. Selecting the app hosting type Figure 2. Selecting the app hosting type

  3. Once the app for SharePoint has been created, add a link to the app site workflows on the app home page by inserting the following HTML into the Pages\Default.aspx page.

     <p><a href="../_layouts/15/workflow.aspx">Site Workflow</a></p>
    

    The two main types of workflows are list workflows and site workflows. We will use a site workflow since we only intend to verify that we can send an email message.

  4. Next, add a Workflow item to the SharePoint app project as shown in Figure 3.

    Figure 3. Add a workflow to the project Figure 3. Add a workflow to the project

  5. Specify a name for the workflow and select Site Workflow as shown in Figure 4, thenchoose next.

    Figure 4. Selecting the workflow type Figure 4. Selecting the workflow type

  6. Select <Create New> as the history list on the list selection page of the SharePoint Customization Wizard shown in Figure 5. As a workflow runs, it can log useful information. This information is stored in the workflow history list. Then choose Next.

    Figure 5. Creating a new workflow history list Figure 5. Creating a new workflow history list

  7. Select the option to have a user manually start the workflow as shown in Figure 6, then choose Finish.

    Figure 6. Configuring workflow start options Figure 6. Configuring workflow start options

  8. When the workflow designer appears, expand the SP – Utilities tab on the Toolbox then drag the Email activity onto the designer as shown in Figure 7.

    Figure 7. Adding Email activity to the workflow Figure 7. Adding Email activity to the workflow

  9. Notice that the Email activity property grid has numerous properties. We will first set the String properties as follows:

    1. Set Body to “Demo of the Email activity”
    2. Set Subject to “Email Workflow Demo”
  10. To specify the recipients of the email message (To, CC, and BCC properties), we first need variables of type Collection<String>. To create a variable, first expand the Variables pane at the bottom of the workflow designer by choosing the label Variables, then choose Create Variable.

    1. Name the variable “recipients”
    2. Set its data type as follows:
      1. Select Browse for Types… from the Variable type dropdown list as shown in Figure 8.
        Figure 8. Setting the data type of workflow variables Figure 8. Setting the data type of workflow variables
      2. In the popup dialog box, type Collect into the Type Name text box to filter the selections as shown in Figure 9.
        Figure 9. Searching for a type for a workflow variable Figure 9. Searching for a type for a workflow variable
      3. Choose System.Collections.ObjectModel.Collection<T> , then specify String as the type (do this at the top of the dialog as shown in Figure 10). Choose OK.
        Figure 10. Closing the generic type Figure 10. Closing the generic type
  11. Now that we have a Collection<String> variable created, we need to populate it with some user information. For this walkthrough, we are interested in sending an email message to the workflow initiator. Therefore, we need to set the recipients variable to a Collection<String> containing the workflow initiator information.
    Note: Email activity accepts SharePoint user values in the form of email address, user ID, or claims user name.

  12. To retrieve the workflow initiator user name, add LookupWorkflowContextProperty activity to the workflow. In the property grid, set PropertyName to Initiator, as shown in Figure 11.

    Figure 11. Retrieving the workflow initiator user name Figure 11. Retrieving the workflow initiator user name

  13. To store the user name, create a new String variable called initiator, thenassign this variableto the Result property in the property grid as shown in Figure 12.

    Figure 12. Assigning workflow initiator user name to a variable Figure 12. Assigning workflow initiator user name to a variable

  14. Now add initiator to the recipient collection. We will use the BuildCollection<T> activity to do this.

    1. Type Col into the Toolbox search box then drag the BuildCollection<T> activity onto the workflow designer. Place it below the LookupWorkflowContextProperty activity.
    2. The dialog box in Figure 13 will be displayed, prompting for the type of collection to build. Select String from the dropdown list, then choose OK.
      Figure 13. Collection type selection dialog box Figure 13. Collection type selection dialog box
    3. In the property grid, choose the ellipses (…) button next to the Values property to start the Values dialog box shown in Figure 14.
    4. In the dialog box, choose Create Argument to specify a value to add to the collection.
      Figure 14. Collection values creation dialog box Figure 14. Collection values creation dialog box
    5. Type initiator into the Value column to add that variable to the collection, then choose OK to close the dialog box.
    6. In the activity property grid, set the Result property to the recipients variable.
  15. Now that the collection of recipients has been created, In the Email activity property grid, set the To property to the recipients variable. We’re finished with configuring the Email activity.

  16. Now, add an activity to log to our workflow history list indicating that an email message has been sent. Add the WriteToHistory activity to the end of the workflow (after the Email activity). Set its Message property in the property grid to this value:

     String.Format("An email was sent by {0}.", initiator)
    

We are finished with creating the workflow app.

Testing your app

So far, we’ve created a simple app for SharePoint containing a workflow that sends email messages. Let’s test it.

  1. Start debugging the project. You may be prompted to login first. A browser window will be started, taking us to the app home page. Choose the Site Workflows link to view the site workflows available to this app.
  2. Choose Workflow1 – WorkflowStart link to start our workflow.
  3. The workflow status will be updated to Completed after few moments. (You may have to refresh the page to see this.)
    Figure 15. Workflows page in SharePoint Figure 15. Workflows page in SharePoint
  4. Check your email client to verify that you received the email message.
  5. In the My Completed Workflows section of the Workflows page shown in Figure 15, choose your workflow that just completed. The page that is loaded will contain a comment logged by the workflow showing the SharePoint ID of the initiator.

We have now completed this walkthrough in which we have learned how to create a SharePoint-hosted app and how to build a site workflow for the app that sends an email message to the workflow initiator. For additional information, please refer to these documents:

Please feel free to submit any feedback you may have on the blog. Also be sure to check out the Apps for SharePoint 2013 forum if you need assistance with building your apps.

Saint Wesonga