Email-Based Approval

Note: This feature requires the WorkflowFirst v4.2 (or later) release.

WorkflowFirst allows users to action workflow items through email alone, through a simple setting, without even having to access the web interface at all. The user who receives an assignment email can reply to that email with the name of the chosen workflow stage (eg. Approve), and WorkflowFirst can then pick up that email response and process it as if the user went in and clicked the button themselves.

This can be extremely useful for situations where users are traveling and don't have access to their company network, and so cannot access the server directly. It can also be very convenient to simply click "Reply" and type in "approve". It keeps the business processes flowing and allows the business to operate efficiency.

To set this up, there are some important considerations to be aware of:

  • You must connect your WorkflowFirst application to an email server (which must have POP3 enabled) so that it can pick up the replies.
  • The "From" email address of the reply must match the email address of the user.
  • It will only work for workflow stages that have no input fields.
  • You should not enable this feature if security is a major concern, as email is not as secure as actually logging into the system.

Simple Example

Let's say that a user, Bob Smith, received an assignment email for a Purchase Order. He is the Department Manager and needs to approve a purchase that is over $5,000.

Bob is traveling and does not have access to the server as it is not on the Internet. With email-based approval he does not need to click the link and bring up the web page. Instead he can just reply to the email and type in "approve" and send the email. A minute or so later he will receive an email from the system confirming that the action was processed.

If, however, he mistypes the action (eg. "aprove") then the system will respond with another email that tells him the stage wasn't found, and will list the available stages that he can use. If there was an error or warning, he will also be notified of that. He can reply to that new email to provide a new command if necessary.

The originator of the workflow will see the the approval as if it were performed through the regular interface.

Setting Up

In order for WorkflowFirst to be able to access email replies, those replies will have to go to a special inbox that you set up that will be dedicated to receiving such replies for workflow purposes. This can be any kind of inbox, and can even be set up using a commercial email service like GMail.

However, it is important that the mailbox must be accessible through POP3. In some cases this may need to be explicitly enabled. For details on accessing an inbox through POP3, you should contact your email service provider.

The first step is to go to WorkflowFirst Designer, go to the Application record for your application, edit it and set Email-Based Approval to Yes.

After setting this and republishing, it will add several settings on the Configuration tab of your application.

The Email Approval POP3 Server will be the name of the mail server. You can determine this by contacting your email service provider. If your POP3 server requires a secure connection, you should add :tls to the end. For GMail, for example, it would be

The Email Approval POP3 Username, and Password, will be the login name (and password) for the mailbox you want WorkflowFirst to be monitoring. If you are using GMail, then you should prefix the username with recent: (eg. recent:[email protected]) so that it retrieves the most recent entries first.

As well as these settings, you will also have to configure your application so that any emails sent from the system will have a "Reply-To" header set, which will instruct your mail program to send replies to a specific address. That way you can ensure that any replies to assignment emails will go to the mailbox it is monitoring.

To do this, you should change the From EMail setting in the Configuration tab of your application.

Advanced Tip: If you need the "From" email to be different to the "Reply To" email address, then you can put the From EMail first, put a pipe character |, and then put the "Reply To" email after that.

Note: In the WorkflowFirst Cloud system, all emails will come from [email protected] The email address specified in your application's From Email setting will only be used for the Reply-To email, which will only appear when the user clicks Reply in their email program.

Once this is all configured, your application will start checking for email every minute, in the background. It will only retrieve new emails as they appear in the mailbox, and will process each accordingly.

Security Considerations

The email-based approval feature requires that users be able to control workflow from their email, without being fully authenticated in the system. This can impose a security concern because the system will now be authenticating specific action invocations purely from the "From email" of any email received in the mailbox. Because email servers can be compromised, and "from emails" can be faked, by enabling email-based approval you may be compromising the security of your system. If this is a concern for your application, you should not use this feature.

Saying that, WorkflowFirst does ensure that only those actions available to the user can be invoked. For example, the user will have to be the assignee of the record - if they are not the assignee, they will not be able to run any workflow stage. It also only allows visible buttons to be invoked, and only those that do not require any field inputs. For example if a workflow stage had an additional visibility condition that would make it invisible because of a specific state, the user will not be able to invoke that action if it were not visible.

Technical Details

The system parses incoming emails based on specific rules. Firstly, the email subject must contain the word 'Assign". Secondly, the body of the email must contain an anchor link to a WorkflowFirst record. The first such link will be used to determine the record where the action will run. Thirdly, the from address of the email must match an existing user's email address in the system. Fourthly, the first line of the email body will be used to search for an action on that record that the matching user can execute. The action must be an auto-submit action, with no input fields.

So long as the subject contains Assign and the body contains a link, an email will be sent back to the user with the result - either that it processed it successfully, or that it could not find an action with the given name, or cannot match a user.

Next Topic: Workflow Examples