Email to Workflow

Plugin Documentation
 

Overview

Introduction

The Email To Workflow plugin allows you to build advanced workflows that interact using workflows. While workflows have always been able to send email, with this new plugin, they can also be started from a workflow as well as be updated from a workflow.

In the first use case, an incoming email can be setup to start a new workflow. This passes on information like the sender, subject and message body. Your workflow will take this information and process based on your organization’s need.

The second use case is a bit different. You can also configure a new email to update an existing workflow. When the ‘Enable Active Workflow Match’ feature is enabled, the plugin will look for a Workflow Id in the subject line (prefixed with a # sign). If one is found, the plugin will call the activity named ‘Incoming Message’ (the name must be an exact match or a new workflow will be created) of the workflow and the defined attributes will be added as Activity Attributes. Also, if the specific workflow has already completed, it will re-enable that workflow. If no Workflow Id can be found in the subject line, then a new workflow will be created.

Warning

This plugin requires knowledge of DNS and basic mail settings in order to be implemented.

Usage

After Rock restarts you’ll find a new Defined Type called ‘Email To Workflow’ under ‘Admin Tools > General Settings > Defined Types’.  This defined type allows you to create rules for launching workflows. The defined value settings for this include:

NameDescription
ValueThis is the to address that should be considered for the match. In general, we recommend that you create a new to address for each type of workflow, but as you’ll see, you can share an address if you wish.
DescriptionA short description of the purpose of the rule and what this workflow is configured to do.
Subject ExpressionRegular expression to use to match the value of the subject line. For instance, to match the keyword ‘Welcome ….’ you could use the expression ‘welcom.*’ (without the quotes). Note that the search string is not case-sensitive.Leaving this field blank has the effect of matching any value in the subject line.
Body ExpressionAssuming that there wasn’t a match on the subject line, you can also provide a regular expression for searching the contents of the message body.
Workflow TypeThe type of workflow to launch.
Workflow Name Template A Lava formatted string to use as the workflow name. See the listing below of available Lava merge fields.Example:Request From {{ FromPerson.FullName }} ({{ Email.Subject }})
Workflow AttributesKey/value list of workflow attributes to set with the given Lava merge template. A reminder of the available options can be found in the defined type’s help text. We’ve also provided them below

Available Lava Merge Fields

  • Email [Object]
    • An object representing the components of the email message. See the documentation for this object below.
  • FromPerson [Text]
    • The plugin also does a match using the From Email to lookup the first person with that email assigned (sorting by family role (adult before child) and then by Gender (Male before Female). You don’t have to use this attribute, but it saves you from having to do a similar lookup.
  • ReceivedDate [Text]
    • The date the message was received.
  • RecievedTime [Text]
    • The time the message was received.
  • MessageBody [Text or Memo]
    • The plain text message that was received.

Email Object Reference

  • Subject
    • The subject line of the message.
  • From
    • This is a MailAddress object with the following properties:
      • Address
      • DisplayName
      • Host
      • User
  • To
    • This property is the email address that received the message. This will normally be the email address you configured in Mailgun/SendGrid to relay the message to the webhook. This is a MailAddress object with the following properties
      • Address
      • DisplayName
      • Host
      • User
  • MessageTo
    • This is a bit different than the To property above. This property represents the To recipients of the original message. For instance, the message may have been to 3 people with a CC to the Mailgun/SendGrid address. You may want to check who was on the original list of recipients. In that case this is the property you want. It is a list of MailAdress objects. Each object has the following properties:
      • Address
      • DisplayName
      • Host
      • User
  • BodyPlainText
    • This is the message’s plain text body.
  • BodyPlainTextStripped
    • This is the message’s plain text body where an attempt was made to remove the signature line and previous message conversations. The processing of removing the signature and previous conversations is a best attempt and often times can’t be completed.
  • BodyHtml
    • The HTML body of the message.
  • BodyHtmlStripped
    • The HTML body where the signature and previous conversations have been removed.

Attachments

The plugin also supports adding email attachments to your workflow. To do this, add workflow attributes (or activity attributes, in the case of Active Workflow Matching) with the Field Type of File and the attribute key of Attachment1, Attachment2, etc. You can configure as many attributes as you’d like. Keep in mind most emails on an email (even those that make up the signature) will be considered attachments. When adding attachments, the attachment with the largest file size will be added first.

Workflow Configuration

Once the workflow is launched, the ball is in your court. Below are a few things you should know about configuring your workflows.

Responding

It’s up to you to send a response back using the ‘Send Email’ workflow action.

Getting the Sender Into Your Workflow

While you could always query for the owner of the email address that sent the message via the ‘Run SQL’ action, we’ve simplified it by doing the heavy-lifting for you. You might be tempted to also use the {{ FromPerson }} merge field. That will work well if all you want is their name in a text attribute of your workflow. If you’d like to have a full blown Person Attribute, you must load the workflow initiator into your workflow attribute using the ‘Set Attribute to Initiator’ action.

Below is a sample of the settings of this action.

Using Mailgun

To setup Mailgun for use with the Email To Workflow plugin follow these steps:

  • Configure a new domain that will be used for the incoming email.
  • Be sure to configure the proper MX records in your DNS. The on-screen instructions in Mailgun will provide all of the information you’ll need and allow you to test your settings when complete.
  • Next, you’ll need to create a new ‘Route’ in Mailgun. This basically sends (or ‘routes’) the email to the incoming webhook in Rock. The settings for this route should be:
    • Priority: 0
    • Expression Type: Catch All
    • Actions: Forward -> http://your.publicaddress.com/webhooks/EmailToWorkflowMailgun.ashx

The Mailgun supports the stripping off of attachments and previous conversations in the email message. While it uses an advanced machine learning algorithm, it’s not always able to strip this information successfully. So much for SkyNet…

Using SendGrid

To setup SendGrid for use with the Email To Workflow plugin follow these steps:

  • Configure a new domain that will be used for the incoming email.
  • Be sure to configure the proper MX records in your DNS. The on-screen instructions in SendGrid will provide all of the information you’ll need and allow you to test your settings when complete.
  • Next, setup an ‘Inbound Parse’ rule to forward mail to the Rock webhook. The settings for this rule should be:
    • Subdomain and domain – These are the host information that you want to use for the incoming mail and should match the new domain you just configured (e.g. subdomain: workflow, domain: mydomain.com)
    • Destination URL: http://your.publicaddress.com/webhooks/EmailToWorkflowMailgun.ashx
    • Do NOT enable the ‘POST the raw, full MIME message’.

Note: SendGrid does not support any stripping of signatures or previous conversations.

Using CloudMailin

If you already use Mailgun or SendGrid for sending mail it’s a natural fit to also use them for your incoming email -> webhook needs also. If, however, you don’t already use these services, you might consider ClouldMailin as an option. One nice aspect to this service is that it provisions an email account for you so you don’t need to work about setting up all the DNS MX records. You can simply forward an address from our current mail system to the address they provide and wallah you’re done! They also have a free account that gives you 200 emails per month (max email size is also 100K).

To setup their service follow these quick steps:

  • Set the URL to http://your.publicaddress.com/webhooks/EmailToWorkflowCloudMailin.ashx
  • Set the POST format to “Multipart (recommended)”.
  • Boom, you’re done!

Email Address Strategies

In order for your emails to be processed, you’ll need to configure a new email domain (something like @workflows.mydomain.com). This domain’s MX record will then be pointed to your email service’s (Mailgun or SendGrid) incoming webhook.

If this address will be used by the public, you can always setup a new email address on your public domain that forwards messages to this new domain.

it@mydomain.com -> it@workflows.mydomain.com