By Lance Robinson, /n software,
Requirements: /n software SharePoint Workflow Extensions

Contents

1. Introduction
2. Default Actions
3. Workflow Configuration
4. Customizing Actions

Introduction

SharePoint administrators who manage lists and document libraries may wish to configure specific lists or libraries to automatically send out emails when items are added or updated.  Administrators can quickly and easily configure a workflow to handle this automatically by utilizing the /n software SharePoint Workflow Extensions activities.  In this article, I will walk through the process of using the Microsoft Office SharePoint Designer to create a workflow that does exactly this - sends an email whenever a list or library item changes.

The Email Activity that is included in the /n software SharePoint Workflow Extensions package has dozens of action parameters that can be set in order to achieve advanced functionality not available with other email activities, for example: 

• SMTP authentication (LOGIN, CRAM-MD5, NTLM, APOP, SASL/PLAIN).
• SSL connection support and certificate handling settings.
• Firewall detection, navigation, and authentication (HTTP Tunneling, Socks4/5).
• Delivery and read receipts.
• Automatic, configurable attachment delivery.
• Advanced Logging.
• Configurable server host/ip and port parameters.
• Configurable from and reply-to parameters.

The /n software SharePoint Workflow Extensions package includes many dynamic and easily configurable workflow activities for sending emails, uploading files to remote FTP servers, uploading files to Amazon S3, sending SMS messages, instant messaging, zipping up files, and more! The activities can be used for creating workflows in Microsoft Office SharePoint Developer or Microsoft Visual Studio.  For a complete list of activities included with /n software SharePoint Workflow Extensions, please check www.nsoftware.com.

Default Actions

The /n software SharePoint Workflow Extensions can automatically install and deploy the activities to SharePoint server, after which it is necessary to activate the activities via SharePoint's Central Administration page (for detailed installation instructions, please see the documentation included in the download of the product).  After that, the workflow activities are ready to use.  During the install process, if the option to install the sample actions was checked (true by default), several default .ACTIONS files will have been installed to %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\1033\Workflow\.

These default .ACTIONS files each include a working example action, as well as another commented out example that shows how to use all the available parameters of the activity.  For example, the "nsoftware.email.ACTIONS" file includes a working action with the following rule designer definition:

<RuleDesigner Sentence="Email item to %1 from %2 with %3 using %4.">
  <FieldBind Id="1" Field="SendTo" Text="this address" DesignerType="TextArea" />
  <FieldBind Id="2" Field="From" Text="this address" DesignerType="TextArea" />
  <FieldBind Id="3" Field="Subject" Text="this subject" DesignerType="TextArea" />
  <FieldBind Id="4" Field="SMTPServer" Text="this server" DesignerType="TextArea" />
</RuleDesigner> 

When this action is in use, the sentence looks like:

"Email item to this address from this address with this subject using this server."
The other .ACTIONS files installed here look similar, all pointing to a different activity.  Later in this tutorial I'll show how to customize these .ACTIONS files to suit more advanced needs, but for now I'll continue on go to the next step and configure a workflow using this default action.

Workflow Configuration

To start, load Office SharePoint Designer and open a SharePoint site.  Start creating a new workflow by clicking File -> New... -> Workflow...  When the Workflow Designer wizard starts, enter a name for the new workflow, attach it to a list, choose how/when the workflow should start (include "manually started" for the purposes of this tutorial), and click Next. 

On the next page, choose any conditions (I will leave this blank for this first example), and under Actions, choose the "Email Send Sample" action.  This is the default /n software email action similar to the one shown above (to see a list of all available actions, click on "More Actions", and notice the "/n software SharePoint Extensions" category).   This action will send an email using the parameter values given to it (in the workflow sentence).  Click on the "this address", "this subject", and other parameter fields and enter the values the workflow should , and click "Finish" to finalize the workflow.

The new workflow will now appear in the list of workflows in SharePoint Designer.  To use it, browse to the SharePoint site and go to the list the workflow is attached to.  To test the workflow, I can start it manually on a specific item (since I included "manually started" when defining the workflow) by clicking on an item or bringing up its context menu and clicking on "Workflows".  This will show a list of all the workflows that are attached to the list, and clicking on the new workflow will start it for the selected item.  This will result in sending an email to and from the email addresses specified in the workflow.

But what if more functionality is desired, like adding attachments or sending the email to a different recipient depending on who the contact is?  For that, the .ACTIONS file can be customized to make a more advanced workflow.

Customizing Actions

Sending Attachments

By modifying the .ACTIONS file, an extensive selection of parameters can be added to the workflow sentence.  Each of the /n software SharePoint Extensions activities have dozens of parameters that can be used to specify firewall settings, ssl connectivity settings, attachments, etc.  Please see the help file for a full list of properties of each activity.  The default .ACTIONS file also shows how to use all of these properties in the RuleDesigner, but I will go over that here as well.

Sending attachments with the email is easy - because the /n software Email activity will handle it for you automatically!  If the current item of the workflow is a library document or a list item with attachments, the attachment(s) will be automatically sent along with the email.  However, sometimes attachments need to be retrieved from other items or even other lists, which can be done with a small modification.

There are two steps needed to accomplish this:  first modify the .ACTIONS file to include an attachment selection in the sentence, and then modify the workflow itself to specify the attachment(s) to add.

To add an attachment in the .ACTIONS file, open the file and go to the RuleDesigner element. Modify the "Sentence" attribute to include words prompting an attachment, and add another FieldBind that points to the __ListId and __ListItem fields.  This new FieldBind will use the ChooseListItem designer type, which tells SharePoint Designer to show the list item chooser wizard to the workflow designer.  For example:

<RuleDesigner Sentence="Email item to %1 from %2 with %3 using %4, attachment %5."> 
  <FieldBind Id="1" Field="SendTo" Text="this address" DesignerType="TextArea" /> 
  <FieldBind Id="2" Field="From" Text="this address" DesignerType="TextArea" /> 
  <FieldBind Id="3" Field="Subject" Text="this subject" DesignerType="TextArea" /> 
  <FieldBind Id="4" Field="SMTPServer" Text="this server" DesignerType="TextArea" />
  <FieldBind Id="5" Field="__ListId,__ListItem" Text="attach" 
             DesignerType="ChooseListItem" />
</RuleDesigner>

In the above action, I added a bit to the "sentence":   , attachment %5.  %5 is the place holder for the fieldbind element with an Id equal to "5".  I also added a new FieldBind element with an Id equal to "5":  <FieldBind Id="5" Field="__ListId,__ListItem" Text="attach" DesignerType="ChooseListItem" />.  The Field attribute tells SharePoint Designer which parameters of the activity to bind with.

In the default .ACTIONS file, all of the available parameters of the /n software Email activity are listed.  Any of those parameters can be added to the RuleDesigner in the same way.  As an exercise, a good one to add to build on this demo is the MessageHTML parameter, which is used to specify the actual body of the email to be sent.

After making these changes, save the .ACTIONS file and restart IIS.  The updated action will now be available for use in workflows. Go back to SharePoint Designer and reopen the workflow, and the action sentence in the workflow will have been updated to reflect the .ACTIONS file changes. Click on the "__List" link and select the place from which to get attachments. Choose the list/library from which the attachment is to be retrieved, and match a field value in the that list to some other value or field value. This is a bit confusing, and outside of the scope of this article, but it is the same as saying: go to this other list and get the attachments from the item there that has this field equal to this value.

Dynamic Recipients

There are several ways to dynamically choose the recipient address (or any of the other activity properties), none of which require any change to the .ACTIONS file. I'll mention a few ways.

First, a static value may be used, as shown earlier in this example:  just hard-code the recipient right there in the action sentence, ie "Email item to person@server.com".

Another option is to use conditions (which I left blank previously) inside the workflow - if condition 1 send to a, if condition 2 send to b. An example of the condition might be "If the Last Name equals Johnson".  If the workflow were operating on a custom list with a custom "Manager" field that held the name of the manager of each person in the list, the condition might be "If Manager equals John Smith".  The latter example might be used if an email was to be sent to the manager of each person in the list.

Also, a workflow lookup can be used to get the recipient address from a field value of the current item or any other list item.

Conclusion

This article showed how to add automatic email sending capabilities to a SharePoint workflow. The /nsoftware SharePoint Extensions activities can be used to accomplish this any many other Internet communications tasks. Here we talked about the basics that you need to get started, but we recommend that you also take a look at the documentation of the /nsoftware SharePoint Extensions that comes installed with the product, as it goes into details about all available parameters of each activity, including many that were not discussed here.

Read more information about the products mentioned above: /n software SharePoint Workflow Extensions.