Mail Processor Workflow

From Sense/Net Wiki
Jump to: navigation, search
  •  
  •  
  •  
  •  
  • 100%
  • 6.0.8
  • Enterprise
  • Community
  • Planned

Overview

Mail Processor Workflow
Sense/Net CMS comes with a built-in workflow that is executed for every incoming email. This can be exchanged to a user-defined workflow any time, in the Incoming Email Settings for a Content List, or if a global adjustment is necessary, this built-in workflow can also be modified.

Details

Mail Processor Workflow

Workflow information:

  • type is MailProcessorWorkflow
  • the definition can be found at /Root/System/Workflows/MailProcessorWorkflow.xaml
  • the workflow is a Content Workflow, and the related content is the Content List
Mail Processor Workflow

The workflow consists of the following main parts:

  • 1: an ExchangePoller activity downloads unread email from the Exchange mailbox. The parameter PushNotification accepts a boolean value indicating the usage of push (true) or pull (false) notifications (default is false). If false, the activity connects to the Exchange server and downloads all unread mails. If true, the activity searches for content under the IncomingEmails SystemFolder under the list, and uses the email ids saved on that content to retrieve those emails from the Exchange server. In this latter case the content in the IncomingEmails folder are created by the webservice handling push notifications.
  • For every retrieved email the following blocks are executed:
    • 2: attachments and their container are created according to the GroupAttachments Field value on the Content List
    • 3: an .eml file is created if configured
    • 4: the email is marked as unread in the mailbox.

The following screenshot shows the part of the built-in workflow that is responsible for creating attachments and grouping them under a folder according to the sender's name. If you wish to fine-adjust the functionality of this workflow, or create a custom one, we advise you to read this throught:

Mail Processor Workflow - creating attachments

This section of the workflow consists of the following parts:

  • 1: an If block: attachments and their container is only created if the email has attachments, or the original email is to be saved as an .eml file.
  • 2: a GetNameFromDisplayName activity: the target folder name is generated from the sender's name.
  • 3: a LoadContent activity: the target folder is loaded from the Content Repository. The returned WfContent Id will be 0 if the target folder does not yet exist.
  • 4: an If block: create the container if it does not exist. A CreateContent activity is used for this inside the If.
  • 5: a ForEach block: creates the attachments under the target folder. An ExchangeCreateAttachment activity is used for this inside the cycle.

Receiving emails using POP3 (from version 6.3)

From Sense/Net 6.3 the mail processor workflow is capable of working with emails received through the POP3 protocol. The mail processing mode is set in the settings content as you can read in this article. The POP3 side of the processing workflow looks the same as the Exchange part, it just works with the more generic System.Net.Mail.MailMessage type when processing e-mails.

Mail Processor Workflow - POP3 mode

Workflow Activities for Exchange Integration

When building custom workflows for Exchange integration, you can use the following built-in special workflow activities:

  • ExchangeCreateAttachment: creates an attachment as a File in the Content Repository.
  • ExchangeCreateEml: creates an .eml File in the Content Repository.
  • ExchangeGetMail: returns a Microsoft.Exchange.WebServices.Data.EmailMessage object as retrieved from Exchange Web Services Managed API.
  • ExchangeMarkAsRead: sends a request to the Exchange Server to mark the given email read.
  • ExchangePoller: retrieves all unread emails from the mailbox as defined with the given email address and returns an array of Microsoft.Exchange.WebServices.Data.EmailMessage objects as retrieved from Exchange Web Services Managed API. It's PushNotification boolean parameter defines whether the activity should determine the list of unread mails by connecting to the Exchange server (false - email polling), or by checking persisted content under the IncomingEmails folder that were created by the push notification webservice (true - push notifications).

Workflow Activities for receiving POP3 e-mails (from version 6.3)

When building custom workflows for receiving e-mails from any mail server, you can use the following built-in special workflow activities:

  • CreateAttachment: creates an attachment as a File in the Content Repository.
  • CreateEmail: creates an .eml File in the Content Repository.
  • MailPoller: retrieves all e-mails from the mailbox as defined with the given email address and returns an array of System.Net.Mail.MailMessage objects.

Example/Tutorials

Creating a custom mail processor workflow

In this following example we are going to create a custom mail processor workflow that will create Memo content for every incoming email it receives from the Exchange push notifications. The setup is relatively simple, so instead of doing it step-by-step, here is the workflow you will have to create. Let's call it MailMemoWorkflow.xaml:

Memo creating email workflow

It is pretty straightforward: email is retrieved, a Memo content is created with the subject, and then the email is marked as read. Let's see the parameters for the individual activities!

  • ExchangePoller: gets unread mails from the Exchange server. The result will be stored in the Messages variable.
    • PushNotification: false
    • Result: Messages
  • ForEach<EmailMessage>: iterates through messages
    • TypeArgument: Microsoft.Exchange.WebServices.Data.EmailMessage
    • Values: Messages
  • CreateContent: a Memo content is to be created under the ContentList, the DisplayName of the Memo content will be the subject of the email, it's Body will be the body of the email.
    • ContentDisplayName: Message.Subject
    • ContentTypeName: "Memo"
    • ParentPath: RelatedContentPath
    • Result: EmailContent
    • FieldValues: New Dictionary(Of String, Object) From { {"Body", Message.Body.Text} }
  • ExchangeMarkAsRead: this takes an EmailMessage object as parameter to mark it as read.
    • Message: Message

For the above to work without errors, we need to define some parameters:

Arguments
Name Direction Argument type Default value Description
StateContent In SenseNet.Workflow.WfContent This will be a reference to the workflow instance, and thus it will hold vital information, like the id of the incoming email, that will be used in following email operations.
Variables
Name Variable type Scope Default Description
Messages EmailMessage[] MainFlow This is the result of the first activity, it returns the EmailMessage objects as it resolves the emails from the Exchange server.
EmailContent WfContent MessageFlow This is the created Content in the Content Repository, and the result of the second activity. Comes handy if you would like to further use it later in the workflow (for example to create attachments under it, etc.)
RelatedContentPath String FlowChart StateContent.Reference("RelatedContent").Path This is a shortcut to the Path of the Content stored in the RelatedContent field of the workflow instance. This is the path of the referenced Content List.

Also, you will need to define some namespaces to import, like:

  • Microsoft.Exchange.WebServices.Data
  • SenseNet.ContentRepository
  • SenseNet.Workflow
  • SenseNet.Workflow.Activities

Now let's deploy the workflow!

  • 1.: create a new CTD for this workflow. It will inherit from the MailProcessorWorkflow. Name should be MailMemoWorkflow:
<ContentType name="MailMemoWorkflow" parentType="MailProcessorWorkflow" handler="SenseNet.Workflow.WorkflowHandlerBase" xmlns="http://schemas.sensenet.com/SenseNet/ContentRepository/ContentTypeDefinition">
  <DisplayName>Mail Memo Workflow</DisplayName>
  <Description></Description>
  <Icon>workflow</Icon>
  <Fields></Fields>
</ContentType>?
  • 2.: upload the xaml to /Root/System/Workflows as MailMemoWorkflow.xaml. Note: the name (without the extension) should be equal to the name of the CTD in step 1. The xaml does not need to be set as Content workflow, since the notification subsystem will automatically bind the Content List to its Related Content field.
  • 3.: Go to the Incoming Email Settings of your Memo list, and set this workflow instead of the built-in MailProcessorWorkflow.

We are ready. The next time an email notification is sent by the Exchange server, a Memo will be created with the subject of the email as its name.

Related links

References