Send e-mail in a workflow
You may want your workflow to send an e-mail message for any of a wide variety of purposes. For example, you might want the workflow to send you a notification each time that it begins to run.
1. A new item is added to the list or library, and the workflow starts.
2. The workflow sends you an e-mail message to let you know that it has started.
This article shows you how to set up your workflow to send an e-mail message. It also explains how to use workflow lookups both to address the mail and to include dynamic content in the message body, including how to insert or build hyperlinks. Finally, this article shows you how to format the content of the message, along with providing other information about working with workflow-generated e-mail messages.
What do you want to do?
Send a basic e-mail message from a workflow
By using the Send an Email action in the Workflow Designer, you can set up your custom workflow to send e-mail messages to you or to any other specified user or group. The available fields for an e-mail message are To, CC, Subject, and Body. These fields can contain both static text and text that is generated dynamically from workflow lookups.
You can use the Send an Email action to generate many kinds of messages, including notifications when the workflow reaches specified stages or performs specified actions (including the overall starting and stopping of the workflow) and reminders about tasks that are not complete by their due date.
Note: Outgoing e-mail settings must be configured on the server before your workflow can send e-mail messages. If you are unsure about the server's current e-mail settings, check with your server administrator. Find links to more information about outgoing e-mail settings in the See Also section.
In this example, you will set up your workflow to send you an e-mail notification each time that it starts to run on a new item.
-
On the File menu, point to New, and then click Workflow.
-
On the first page of the Workflow Designer, name the workflow, indicate the list or library that the workflow will be attached to, and then select the check boxes for the start options that you want.
-
Click Next.
-
On the next page of the Workflow Designer, type a name for this step of the workflow.
-
Click Actions, and then click Send an Email.
If this action does not appear in the list, click More Actions to see the full list.
-
In the action, click this message.
-
In the Define E-mail Message dialog box, enter your own e-mail address in the To box.
Notes:
-
To select users from a list or address book, click the Address Book
button at the end of the To box. -
The To address of a message can either be a specific, static address (for example, NORTHWINDTRADERS\junmin or junmin@northwindtraders.com) or a workflow lookup to variable information. To learn more about using workflow lookups to dynamically address e-mail messages sent from the workflow instead of using static addresses, see the next section Dynamically select users or groups to receive the message.
-
The sender address of the rendered message will always be the e-mail address of the server administrator, unless the server administrator changes the sender address for either the current Web application or all Web applications. Find links to more information about making this change in the See Also section.
-
-
In the Subject box, type a subject for the message, or click Display data binding
to define a workflow lookup to the text you want here.Note: You must make some entry in the Subject box in order for the workflow to compile correctly.
-
In the large box under the Subject box, type or paste the body text of the message.
Tip: No shortcut menu is available in this box. To copy text, press CTRL+C. To paste copied text, press CTRL+V. Text that you copy and paste cannot include any workflow lookups.
At this point, you could click OK to finish the message. On the other hand, it might be useful to include the title of the new item that has started the workflow, or even to include a link to that new item. Following sections will show you how to do those things, and also how to format the appearance of the message text. First, though, you will learn how to use workflow lookups to address your message dynamically.
Dynamically select users or groups to receive the message
If you supply static addresses in the To and Cc fields of your message, then any time that you need to change the recipients, you must open the workflow in the Workflow Designer and make the changes manually. If the addresses will change frequently, it is a better practice to use workflow lookups in the To and Cc fields. Lookups can reference addresses from a field in the current item, from a field in an item in another list or library, or from workflow variables.
Use a custom list to store recipient addresses
If the recipients change periodically, but not often enough that they must be specified on an initiation form each time that the workflow is started, you can create a custom Recipients list that contains one list item for each workflow that references it, and then create columns in which you can store the addresses to which each e-mail message from each workflow is to be sent. When the recipients for any workflow message change, all you have to do is change the addresses in the appropriate field in the Recipients list item for that workflow.
Important: The columns in which you store addresses for workflow e-mail messages can be either Single line of text, Multiple lines of text, or Person or Group type columns. If you use a Person or Group column, only one entry can be made in each field that the workflow will reference for e-mail addresses. When creating the column, be sure to select No under Allow multiple selections. If you want to use this type of column to specify multiple recipients, you can create a SharePoint group that includes the people that you want the workflow to address the e-mail to, and then specify the group in the field. When creating the column, be sure to select People and Groups under Allow selection of. Find a link to more information about creating lists and adding columns in the See Also section.
Note: When creating SharePoint groups, make sure that each group has at least Read permissions for the site, and that in the Group Settings area of the New Group Page, under Who can view the membership of the group, Everyone is selected.
To use a workflow lookup to a custom Recipients list:
-
In the browser, create a custom list named Recipients with the following three columns:
-
Change the name of the default Title column to Workflow Name.
-
Add a Person or Group column named To. In this column, allow selection of both People and Groups, but do not allow multiple selections.
-
Add a Single line of text column named Cc.
-
-
In the Recipients list, create a new item and then do the following:
-
In the Workflow Name field, type Document Review, which is the name of the example workflow used here.
-
In the To field, click Address Book
and then, in the Select People and Groups dialog box, select a single person or group to address messages to. -
In the Cc field, type the e-mail addresses of the recipients to address copies to, separating multiple addresses with semicolons.
-
-
In Microsoft Office SharePoint Designer 2007, in the Workflow Designer, click Actions, and then click Send an Email.
If this action does not appear in the list, click More Actions to see the full list.
-
In the action, click this message.
-
In the Define E-mail Message dialog box, at the end of the To box, click Address Book
. -
In the Select Users dialog box, in the Or select from existing Users and Groups list, click Workflow Lookup, and then click Add.
-
In the Define Workflow Lookup dialog box, choose the following options:
-
Source: Recipients, or the name of your custom list.
-
Field: To, or the field that holds the address you want.
-
Field: Recipients:Workflow Name
-
Value: Type Document Review, or the name of the current workflow.
This lookup says, "From the Recipients list, select the value of the To field where the Workflow Name equals Document Review."
The top half of the dialog box specifies the list and the column; the bottom half of the dialog box specifies the row.
-
-
In the Define Workflow Lookup dialog box, click OK.
-
In the message about ensuring unique lookups, click OK.
-
Click OK again to close the Select Users dialog box.
-
In the Define E-mail Message dialog box, at the end of the CC box, click Address Book
. -
In the Select Users dialog box, in the Or select from existing Users and Groups list, click Workflow Lookup, and then click Add.
-
In the Define Workflow Lookup dialog box, choose the following options:
-
Source: Recipients, or the name of your custom list.
-
Field: Cc, or the field that holds the address you want.
-
Field: Recipients:Workflow Name
-
Value: Type Document Review, or the name of the current workflow.
This lookup says, "From the Recipients list, select the value of the Cc field where the Workflow Name equals Document Review."
-
-
Click OK, click OK again in the warning message, and then click OK again to close the Select Users dialog box.
Now, when the workflow sends this e-mail message, it sends it to the addresses listed in the To and Cc fields of the Document Review item in the custom Recipients list. To change recipients, simply make the changes you want in the list item.
A single workflow may send multiple e-mail messages, and the messages may not all be sent to the same recipients. To store other addresses for additional messages sent by this workflow, you can add columns to the list to store the other addresses. In this case, you may want to name the columns "First message To," "Second message To," and so on.
Alternatively, you can design the list so that you create one item for each message that the workflow sends, instead of one item for each workflow. In this case, make sure that the name used to identify each message is unique, so that the lookups that retrieve the addresses return the unique value that you want.
Use the workflow initiation form to specify recipients
If you want recipients to be specified each time that a workflow is started manually, you can customize the workflow initiation form to collect the addresses from the person who starts the workflow. The workflow can then either simply use the entered addresses directly, or copy them into fields in the current item — where they will still be available for reference after the workflow has completed its current instance. If the workflow is set up so that it also starts automatically, you can specify default addresses in the initiation form for whenever an automatic start occurs.
Include information about the current item
So far, the body text in the example message is static: Every time the workflow creates an instance of the message, the text will be exactly the same.
It can be useful, however, to include text that changes in relation to the item on which the workflow is currently running. For example, it might be useful to include the title of the document needing review in the body of your message. To include this sort of dynamic information, you use a workflow lookup. Lookups retrieve data from different data sources such as lists, libraries, and workflow data.
To add the title of the document to the message text:
-
Type or paste the static text within which you want the lookup information to appear.
-
Position the insertion point where you want the lookup to be located.
Tip: Once a lookup is inserted, it cannot be dragged to a new location. (It is possible, however, to "relocate" a lookup by dragging other text around it.) Similarly, it is not possible to cut, to copy, or to paste either a lookup or any text that includes a lookup.
-
Click Add Lookup to Body.
-
In the Define Workflow Lookup dialog box, select Current Item in the Source box and Name in the Field box.
-
Click OK.
The inserted lookup appears in the message body.
When the workflow runs and the message is generated, the lookup is replaced by the title of the document.
Including the title of the document is useful, but it might be even more useful to include a hyperlink that would take you directly to the document itself. To do this, you include a lookup in the hyperlink. The later section Include a hyperlink to the current item will show how you how.
Include a static hyperlink
You can include a static hyperlink — that is, one that always links to the same address or location — in the body of your workflow e-mail message by using the HTML anchor tag (<a> and </a>) with the href attribute and specifying the target address as the value of the href attribute.
To visit the Northwind Traders site,
click <a href="http://www.northwindtraders.com/">here</a>.
In the resulting message, the text between the anchor tags is rendered as a hyperlink to the specified address.
Note: Some text-based e-mail programs are not capable of rendering HTML coding, and thus will not render the hyperlink.
To learn how to use a workflow lookup to create a dynamic hyperlink that points to varying addresses depending on the item on which the workflow is currently running, see the next section, Include a hyperlink to the current item.
Include a hyperlink to the current item
In the previous section, Include a static hyperlink, the address in the example hyperlink includes no variable information: Every time that the workflow sends the e-mail message, the hyperlink points to the same page.
By using a workflow lookup, however, you can create a dynamic link that uses information about the current item to decide which URL to point to.
If the current item is a document in a document library
In the workflow startup notification example, you might want to provide a link to the new document itself:
-
Type or paste the static text within which you want the link to appear.
-
Where you want the lookup to be located, type the following text.
<a href="">here</a>
Tip: Once a lookup is inserted, it cannot be dragged to a new location. (It is possible, however, to "relocate" a lookup by dragging other text around it.) Similarly, it is not possible to cut, to copy, or to paste either a lookup or any text that includes a lookup.
-
Position the insertion point between the two double quotation marks ("").
-
Click Add Lookup to Body.
-
In the Define Workflow Lookup dialog box, select Current Item in the Source box.
-
In the Field box, select Encoded Absolute URL, and then click OK.
When the recipient of the message clicks the link, the document opens for viewing or editing.
If the current item is a list item
When you create a link to a list item — for example, an announcement or a calendar event — you can choose to have the link open either the display form (DispForm.aspx) or the edit form (EditForm.aspx) of the list item.
To create a link that opens the list item for a document (instead of the document itself):
-
In the browser, navigate to the Shared Document library.
-
Open the list item for any existing document in the library, using View Item if you want your link to open the display form or Edit Item if you want your link to open the edit form.
-
Copy the address in the address bar from the beginning http: or https: through the first equal sign (=), as shown in the following illustrations.
The ?ID= text is a query string parameter that instructs the page to display the form for whichever item in the current list or library has the list ID that follows the equal sign (=) — which in this example will be the list ID of the current item, as identified by the workflow lookup.
Note: If the current item is a task that is created by one of the three workflow task actions, and if you want the link to open the custom task form (and not the default display or edit form for the Tasks list), see the later section If the current item is a custom task form. For tasks not created by a workflow task action, and for the display forms of even those tasks created by one of the workflow task actions, the current procedure is all that you need.
-
In the Define E-mail Message dialog box, in the location where you want the hyperlink to appear, paste the address.
-
Position the insertion point directly after the equal sign (=), and then click Add Lookup to Body.
-
In the Define Workflow Lookup dialog box, select Current Item in the Source box and ID in the Field box.
-
Click OK.
The inserted lookup appears in the message body.
Important: While the current item ID lookup is useful in building links to the current list item, the following lookups can present errors in the rendered path, and are thus not recommended for inclusion in e-mail message links: Path, Server Relative URL, Source URL, and URL path.
-
Add the remainder of the text for the hyperlink and for the anchor tag in which it is contained, as well as any associated message text that you want to include.
The following illustration shows link texts for both the display form and the edit form as they appear in the e-mail message.
If you plan to use a link more than once, see the later section Store a list item address as a workflow variable.
If the current item is a custom task form
If your workflow uses one of the three task actions to create a task, a custom task form is generated automatically when you compile the workflow. If you want a secondary workflow to send task reminders for a task that is created by a workflow task action, you will probably find it useful to include a link to this custom task form in the reminders.
The default forms for a tasks list, such as DispForm.aspx and EditForm.aspx, reside in the folder for that tasks list. But a custom task form resides in the folder of the workflow with which it is associated. Each workflow task has its own content type, and it is the content type of the workflow task that identifies the custom task form that the content type uses. Because the custom task form resides in a different location, building a URL to this form is different from building the URL to a typical display form or edit form for an item.
The URL of a custom task form looks like this.
Placeholders for variable information are in boldface type and bracketed.
The Source attribute specifies the task list that the current workflow is associated with. When you click Complete Task or Cancel on the custom task form, the form uses the address from the source attribute to know which list to return to. To create a link to a custom task form, you can copy and paste from the beginning of the URL through the ID=[item_ID] characters and ignore the remainder (the part that is highlighted in the example) .
The easiest way to get the URL for a custom task form is to run the workflow once, so that it creates a task. When you open the custom task form for that task in the browser, you can copy the part of the URL that you need, paste it into the body of the e-mail message in the Workflow Designer, and then add a workflow lookup that supplies the ID of the task item.
To include the lookup in the message text:
-
In the Workflow Designer, in the Define E-mail Message dialog box, type or paste all of the text for the link — except the lookup to the Item ID — into the body of the e-mail message.
-
Position the insertion point behind the equal sign (=), delete number for the current item ID, and then click Add Lookup to Body.
-
In the Define Workflow Lookup dialog box, select Current Item in the Source box, click ID in the Field list, and then click OK.
Remember that this example uses a secondary workflow running on the Tasks list, so the current item is the task. Linking to a custom task form from the primary workflow that actually creates the task item is different. To learn how to set up a workflow that uses a Collect Data from a User action to send custom notifications to the people to whom the task is assigned, see the later section Send your own custom task notifications.
To learn how you can set up this address so that you can use it elsewhere in the same workflow, see the next section, Store a list item address as a workflow variable.
Store a list item address as a workflow variable
You can store the URL of the display form or edit form of a list item in a workflow variable, so that you can use it in multiple locations in the same workflow.
-
In the Workflow Designer, click Actions, and then click Build Dynamic String.
If this action does not appear in the list, click More Actions to see the full list.
-
In the action click dynamic string.
-
In the String Builder dialog box, paste the static text portion of the URL (but not the lookup for the current item ID).
In this dialog box, use CTRL+C to copy, CTRL+X to cut, and CTRL+V to paste.
-
Position the insertion point after the equal sign (=) and then click Add Lookup.
-
In the Define Workflow Lookup dialog box, select Current Item in the Source box and ID in the Field box.
-
Click OK.
The lookup is added to the text in the dialog box.
-
Click OK to close the String Builder dialog box.
-
In the action, click the variable.
-
In the list, click Create a new variable and then, in the Edit Variable dialog box, type a name for the new variable.
-
Make sure that Type is set to String, and then click OK.
-
Add the Send an Email action to the workflow, and then click this message in the action.
-
To use the new variable in the Define E-mail Message dialog box, type or paste the surrounding text and HTML tags (including the double quotation marks) into the message body, position the insertion point between the quotation marks, and then click Add Lookup to Body.
-
In the Define Workflow Lookup dialog box, in the Source box list, click Workflow Data.
-
In the Field list, click Variable: name of variable, and then click OK.
You can now insert this variable anywhere that you want it in the current workflow.
Include an image
It is not possible to embed an image or graphics file in the body of an e-mail message that is sent by your workflow. However, you can include a graphic in your message by using the HTML image tag (<img/>) to link to an image that is stored as a JPEG (.jpg) file and uploaded to a picture library in your site.
-
In the body of your message, in the location where you want the linked image to appear, type the <img src=""/> HTML tag.
-
Position the insertion point between the two double quotation marks ("").
-
Type or paste the URL for the JPEG image file. The completed tag looks like this one.
When the message is sent, the image from the JPEG file appears instead of the link tag.
Format the content of your message
In preceding sections, HTML anchor tags (<a> and </a>) are used to create a hyperlink. You can use other HTML tags to specify the typeface, color, style, and other attributes of the text in your message.
Because the Workflow Designer supports only inline styles for formatting messages, and not external or embedded cascading style sheet (CSS) formatting, you must do any formatting that you want by using the style attribute with HTML tags. You can do this either by typing the HTML tags directly into the Define E-mail Message dialog box in the Workflow Designer, or by creating the body of your message in Code view and Design view and then pasting it into the Define E-mail Message dialog box.
-
Save your workflow by clicking Finish.
-
Create a new HTML page.
-
Switch to Split view, and then click anywhere in the Design view area.
-
With the insertion point still in the Design view area, double-click Style Application on the status bar.
The Style Application toolbar appears.
-
On the Style Application toolbar, make sure that Style Application is set to Manual and that Target Rule is set to (New Inline Style), as shown here.
If you format the message text in Code view and Design view, you must set Style Application to Manual so that Office SharePoint Designer 2007 does not add CSS classes, which the server cannot render in workflow mail. Also, you must work in Code view to enclose in span tags any text that is nested inside of already formatted text but for which you wish to specify different formatting. Once the span tags are in place, you can work in Design view to apply the formatting that you want.
-
Format text as usual by using WYSIWYG tools in Design view:
-
If you want to format text inside a tag — for example, <para> or <li> — position the insertion point in Code view, and then double-click the tag you want in the Toolbox.
-
Alternatively, you can type the tag, and then use IntelliSense to insert the style attribute and any property/value pairs that you want. Make sure to separate property/value pairs with a semicolon.
-
A few best practices:
-
Use paragraph tags (<p> and </p>) to define separate paragraphs, and to specify any default formatting for a paragraph that is different from the default formatting for the message overall.
-
Within a paragraph, use additional span tags to specify any local formatting that differs from the default formatting of the paragraph and the message overall.
-
The Workflow Designer renders any manual line break as an additional line break in the message. Because the paragraph tags already add appropriate space between paragraphs, you must remove all manual line breaks from the final version of the message in the Designer to avoid having too much space between paragraphs.
It may be easier to create your formatted text with line breaks for clarity, and then remove all extra spaces and line breaks before finalize the message in the Workflow Designer.
This best practice applies only if you are including paragraph tags or other tags that automatically add vertical space between units of text.
The following illustration presents an example of text formatted with HTML tags. Notice that no manual line breaks are present.
In the message sent by the workflow, that formatted content is rendered accordingly.
Once you are comfortable formatting the message text, you can create a wide variety of message styles. For more information about one way of using message text formatting, see the next section of this article, Send your own custom task notifications.
Send your own custom task notifications
By default, when a workflow uses one of the three custom task actions to create and assign a task, the Tasks list automatically sends e-mail notifications to the people to whom the new task is assigned. If you want to design your own custom task notification messages, you can set up a secondary workflow that runs on the Tasks list to send them.
To avoid sending duplicate notifications, you can turn off automatic notifications for the Tasks list:
-
On the Advanced Settings page for the Tasks list, in the E-Mail Notification area, click No under Send e-mail when ownership is assigned.
Note: Turning off automatic notification turns off all automatic task notifications for the site, including those generated by the predefined workflows that are available in Microsoft Office SharePoint Server 2007.
Once you have turned off automatic notifications, you can use a single secondary workflow to send the same notification for all tasks, or you can use conditions with multiple branching actions or with multiple secondary workflows to send various types of notification that are matched to various circumstances.
You can use the same secondary workflow or workflows to send e-mail reminders about tasks that are not yet complete when their due date approaches. For more information about secondary workflows, see the article Create a secondary workflow.
You can format your custom notifications any way you want. One way to get started is to customize the HTML content of the default automatic notifications, which you can copy directly from the following code sample.
<table style="border-collapse:collapse" width="100%" cellspacing="0" dir="ltr">
<tr style="background-color:#F8F8F9;border:1px;border:1px #E8EAEC solid;padding:12pt 10px 20px 10px"><td style="font-family:Verdana;font-size:16pt;background-color:#F8F8F9;border:1px;border:1px #E8EAEC solid;padding:12pt 10px 20px 10px">Task assigned by [Lookup to Workflow Name] on [Lookup to Task Creation Date].<br></td></tr>
<tr style="border-top:1px solid #E8EAEC;border-bottom:1px solid #E8EAEC; padding:12pt 10px 24pt 10px"><td style="font-size:8pt;font-family:Tahoma;border-top:1px solid #E8EAEC;border-bottom:1px solid #E8EAEC; padding:12pt 10px 24pt 10px">Please approve [Lookup to Document Name]</td></tr>
<tr style="border-top:1px solid #E8EAEC;border-bottom:1px solid #9CA3AD;padding:4pt 10px 4pt 10px"><td style="font-size:8pt;font-family:Tahoma;border-top:1px solid #E8EAEC;border-bottom:1px solid #9CA3AD;padding:4pt 10px 4pt 10px">To complete this task:<br><ol><li>Review <a style="color:#003399;text-decoration:none" href="[Lookup to Document URL]">[Lookup to Document Name]</a>.</li><li>Perform the specific activities required for this task.</li><li>Fill out <a style="color:#003399;text-decoration:none" href="[Lookup to Custom Task Form]">this task form</a>, and then click the <b>Complete Task</b> button to mark the task as completed. (If you cannot update this task, you might not have access to it. Click <a style="color:#003399;text-decoration:none" href="[Lookup to Display Form for Document Item]">here</a> to request access.)</li></ol></td></tr></table>
Included in the preceding HTML code sample are seven placeholders for lookups. The placeholders appear in square brackets ([]). After you paste the HTML content into the body of your e-mail message in the Workflow Designer, you must replace the placeholders, including the square brackets that contain them, with the actual lookups. You will find the instructions for creating these lookups in the following six subsections. (One of the placeholders, the one for the document name, is used twice.)
Workflow Name lookup
Use this lookup.
Task Creation Date lookup
Use this lookup.
Document Name lookup (used twice)
Use this lookup.
Document URL lookup
Use this lookup.
Custom Task Form lookup
This lookup is inserted as part of the URL for the custom task form created by the current workflow, as explained in the earlier section If the current item is a custom task form.
The lookup itself looks like this.
And the whole address looks something like this:
Display Form for Document Item lookup
This lookup is inserted as part of the URL for the display form of the task item, as explained in the earlier section If the current item is a list item.
The lookup itself looks like this.
And the whole address looks something like this:
When all of the lookups are in place, the rendered custom task notification looks this.
You can customize this message by adding further instructions or other information, or adjust the look and feel of the message by formatting the text. With the tools you've learned about in this article, you are ready to set up your workflows to send exactly the messages that you want to send.
Identify options that are not supported
The following options are not supported by the current version of the Send an Email action:
-
Specifying an address on the From line. (E-mail messages sent by the workflow always show the e-mail address specified by the server administrator on the From line. Only the server administrator can change this, and it can only be changed for all notifications in the current Web application, not per workflow.)
-
Including a hyperlink to the Workflow Status page. (There is no way to use a workflow lookup to supply the value of the WorkflowInstanceID variable in the query string.)
-
Using an embedded cascading style sheet (CSS) to format message content. (Text can be formatted by using the style attribute, but the <style> tag and CSS classes are not supported.)
-
Using a workflow lookup in either the To or CC box that references a column of the Person or Group type that contains multiple values.
-
Specifying a Bcc (blind carbon copy) recipient for a message. (A developer can modify the .ACTIONS file on the server to include a Bcc field, but this cannot be done in the Workflow Designer.)
-
Including another file with a message as an attachment.
-
Embedding image or graphic files in a message. (You can link to an image — see the earlier section Include an image.)
No comments:
Post a Comment