Workflows Module

Workflows module allows to build workflows to sort messages, assign them to the right person, send predefined emails and even create SLA-like workflows. Workflows are similar to Gmail filters or rules in other email clients.

Workflows are configured on a per-mailbox basis, so you should look for Workflows under mailbox menu (not in the main top menu).

There are two main types of workflows: Automatic and Manual.

Automatic workflows are running in the background and check conversations for matching conditions and carry out specified actions automatically. If automatic workflow does not contain any date-related conditions (Waiting Since, Date Created, Last User Reply, Last Customer Reply), it is executed when a new message is created or some condition’s value changes (for example, conversation status changes).

A Manual workflow doesn’t do anything until you execute it for a conversation. For example when a customer emails in with a specific question, you can execute a workflow to send a reply, add a tag and assign it to someone on your team.

Workflows consist of Conditions and Actions.

When “Apply to Previous” setting is disabled the workflow does not apply to any conversations created before the workflow’s creation date.

Available Conditions

1) When using OR conditions and “Does not contain” / “Is not equal” be very mindful. Very often when people need AND they are using OR instead and get logical issues.

2) If you need the workflow to trigger when a new email or reply is received you need to add the “New / Reply / Moved” condition:

  • Customer Name
  • Customer Email
  • User Action — replied or added a note
  • Conversation Type — email or phone.
  • Conversation Status — active, pending, closed, spam
  • Assigned to User
  • To — email To field
  • Cc
  • Subject
  • Body — customer message or user note contains specific text
  • Headers — email headers
  • Attachment — contains or not
  • Customer Viewed
  • New / Reply / Moved — is it a new conversation or user’s or customer’s reply.
  • Communication Channel — allows to distinguish messages from Chat, Telegram Integration, Twitter Integration, Facebook Integration, WhatsApp integration or SMS Tickets.
  • Tag(s) — contains specific tags (requires Tags module).
  • Waiting Since — for how many days or hours a customer message is waiting to be replied by a user. This condition triggers the workflow only if the last reply in the conversation is made by a customer and conversation’s status is ACTIVE or PENDING
  • Last User Reply — date of the last user reply.
  • Last Customer Reply — date of the last customer reply
  • Date Created — date when conversation was created
  • Custom Fields — check custom fields values (requires Custom Fields module)

Conditions are case-insensitive. “Waiting Since” and “Last User Reply” are considering replies created by Workflows as support agent replies.

Some conditions allow to use regexes to check values. Tools for testing regexes: Regex Pal or Regex101. Sample regular expression: /^[a-zA-Z0-9]$/

Available Actions

  • Send Email Notification — to current assignee, to the last user to reply or to a specific user.
  • Reply to Conversation — this action sends an email to the customer and includes previous conversation history. %user.*% variables always contain Workflow user data, not the user triggering the workflow, assignee or any other user.
  • Email the Customer — this action sends an email to the customer and does not include previous conversation history. Email subject can not be changed – email has the same subject as the conversation triggering this action. %user.*% variables always contain Workflow user data, not the user triggering the workflow, assignee or any other user. This action does not work for Chat conversations (use “Reply to Conversation” instead).
  • Forward — forward conversation with a custom message to a third party (this action creates a new “forwarded” conversation – this is by design).
  • Disable Auto Reply — do not send an auto reply to the incoming customer email.
  • Add a Note
  • Change Conversation Status — active, pending, closed, or spam
  • Assign to User
  • Move to Mailbox
  • Move to Deleted Folder
  • Delete Forever
  • Add Tag(s) (requires Tags Module).
  • Remove Tag(s) (requires Tags Module)
  • Set Custom Field (requires Custom Fields Module)
  • Trigger Webhook — trigger a custom Webhook (requires API & Webhooks Module). In the action setting enter your custom Webhook event name (example: custom.webhook.event) and after that use this event in the API & Webhooks section to create a Webhook.

If you have Custom Folders module installed, by adding tags to conversations you can move conversations to custom folders.

Workflows are automatically deactivated when some entity in it’s Actions or Conditions does not exist anymore (for example mailbox, user or customer is deleted).

Workflows Examples

Track refund requests

When the subject line or customer message contains “refund”, you want FreeScout to automatically add a tag and send an email to the customer.

Keep track of aging conversations

When a conversation is not replied by a user more than 1 day, add a “overdue” tag and send email notification to the current assignee and specific user. Also using Custom Folders module you by assigning a tag can add conversations to the Overdue folder for example.

Send a follow-up email to the customer after a specific time period

Trigger workflow when conversation moved from another mailbox

By default Workflows are not triggered when conversations are moved. To let the Workflow be triggered when the conversation is moved from another mailbox, you need to have at least one “Conversation moved from another mailbox” item among Conditions.

Permissions

You can allow non-admin users to manage workflows in “Manage » Settings” or in each user’s profile on Permissions page.

Configuration

By default Workflow user’s name is “Workflow”. If you want to change it, add the following parameter to the .env file and clear the cache. Max length is 20 symbols. If you need more flexibility in configuring Workflow user – see this patch.

WORKFLOWS_USER_FULL_NAME=”Robot”

Max Executions and Workflows Infinite Loop

Before it was possible to run each workflow only once per conversations. So we’ve added “Max Executions” parameter to workflows because people wanted to run workflows more than once. But this parameter has to be used with BIG ATTENTION.

If you’ve set a value larger than “1” to workflow “Max Executions” parameter and your workflow goes into infinite loop it means other workflows keep triggering tit. It on other words you’ve configured a Workflows Infinite Loop.

What are the signs of the workflows infinite loop? The obvious sign is when you see something like this in the conversation:

Another sign of Workflows Infinite Loop is the high CPU usage and many “freescout:workflows-process” running processes in the background like in this case.

The solution for Workflows Infinite Loop is to review all your workflows and reconfigure them so that they don’t trigger each other. Try to disable all other workflows and enable them one-by-one to identify the one causing an infinite loop.

If you can’t fix your workflows configuration, to avoid infinite loops just go to the workflow’s settings and set “Max Executions” parameter to “1”.

Troubleshooting

When using OR conditions and “Does not contain” / “Is not equal” be very mindful. Very often when people need AND they are using OR instead and get logical issues.

If after updating FreeScout to a newer version some workflow does not work anymore try to re-update FreeScout manually (see this issue) and make sure that background jobs are running properly.

If you have a Workflow with date-related condition and it runs with some delay (40 minutes or more) – see this.

If you are using Global Mailbox Module you won’t see workflows in the conversations list:

If you need to check if something contains the ” tba ” string for example but spaces are being stripped out by FreeScout when saving the workflows, in this case use  the “Matches the regex pattern” condition: / tba /

Are you running cron jobs every minute? https://github.com/freescout-help-desk/freescout/wiki/Installation-Guide#9-configuring-cron-jobs

Try to manually kill background `queue:work` process and see how it goes: https://github.com/freescout-help-desk/freescout/wiki/Background-Jobs

If your workflow containing Waiting Since condition does not run – see the description of the “Waiting Since” condition above in “Available Conditions” section.

If your workflow containing “Last User Reply” or “Last Customer Reply” conditions does not trigger and you are using “not in the last” operator keep in mind that the conversation should have at least one user reply (for “Last User Reply”) or one customer reply (for “Last Customer Reply”).

If you have a time-related condition and it does not run:

If you assigning a conversation to some user and receiving ERR_TOO_MANY_REDIRECTS error in your browser – see this issue.
Lifetime license for one FreeScout instance
Purchase
Demo
  • Version: 1.0.72
  • Required App Version: 1.8.117
  • License Period: Lifetime
  • Open Source: AGPL-3.0