Share via

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

  • 09/18/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

Comments

  • Anonymous
    November 15, 2013
    Thanks for the tutorial! I am getting the error "Not all generic types could be resolved" when selecting the "System.Collections.ObjectModel.Collection<T>" type. Any help is appreciated.

  • Anonymous
    February 12, 2014
    Hi Steve, please ensure you select "String" in the dropdown between the < and the > in the dialog before clicking OK to avoid that dialog.

  • Anonymous
    February 13, 2014
    Hello I am trying to add a 'From' email address to my Email Activity. It will only have one email address in there not a collection of email addresses. How do I go about doing this? Thanks

  • Anonymous
    February 28, 2014
    Hi Yoshi, The Email activity does not currently support custom 'From' addresses.

  • Anonymous
    March 17, 2014
    This doesnt work for me - the workflow will start and then remain in started state indefinitely. If I add more WriteToHistory elements to it, I can see that it gets to sending email but that action never completes.

  • Anonymous
    May 06, 2014
    Hello. I'm trying to do pretty much the same thing, but the To field should be retrieved from a field in this same list. I am tried to use some of the controls (loading item into a dynamic variable--declaratively using LookupSPListItem) and then using that to "GetDynamicValueProperties" with the field holding the "Person/Group." Is that the way I should do it? Thanks for your help in advance.

  • Anonymous
    May 06, 2014
    Hello, What is the right way to do this if the recipient is in a Person/Group field within the same list?

  • Anonymous
    December 17, 2014
    I am Getting this error Error occurred in deployment step 'Install app for SharePoint': The System Account cannot perform this action. I Skipped the step 3 as I was not sure where to paste <p><a href="../_layouts/15/workflow.aspx">Site Workflow</a></p> in PagesDefault.aspx page. Please help me out

  • Anonymous
    December 18, 2014
    @Shamith That error normally means that you are currently logged in as a user that SharePoint perceives as the System Account. By design, SharePoint does not allow the System Account user to install apps. You need to log out and login again on your development computer as another user in the SharePoint site that you are using as your target.

  • Anonymous
    December 23, 2014
    can  any body let me know how to add Html table in Email body of above workflow

  • Anonymous
    April 16, 2015
    Does this work in office365 sharepoint app?

  • Anonymous
    July 02, 2015
    The comment has been removed

  • Anonymous
    August 03, 2015
    How  to send mail to multiple email ids?

  • Anonymous
    August 06, 2015
    Workflow is taking too much to build once multiple email format is done on each email activity (i have nearly 5 email activities on if conditions )...once i remove multiple fields from email body its building faster...?? Please help...

  • Anonymous
    August 25, 2015
    The comment has been removed

  • Anonymous
    August 25, 2015
    I have an issue with the "To" part of email activity. Based on the document: Note: Email activity accepts SharePoint user values in the form of email address, user ID, or claims user name. I am using email address but I get the following error: Details of last request: HTTP BadRequest to mysite.sharepoint.com/.../Items Correlation Id: 7d30f3c0-cd7b-1ba8-9d38-344466cfdeb1 Instance Id: 76d42cf0-20cf-40f5-9e2b-e4739db4f3a8 The expression "Id eq " is not valid. Why is it trying to resolve user when I actually passed the email address and not ID?? That REST command is built by the workflow not me and also it should be valid. I have tested the following and it works. mysite.sharepoint.com/.../Items$filter=Id eq 10 Any help?????