AUTOMAIT provides a way for business process owners to implement their own workflow processes using simple drag and drop configuration. 

The purpose of this introduction is to give you a sense of how the automated workflows work so you can start piecing together in your mind the different features you’ll need to configure your workflow.

The End-User Experience

The User Interface works perfectly in the dashboard but it also works equally well in the front-end pages of your site using the shortcode. This allows you to use the styling of your choice and let external users participate in the workflows.

The Flow Designer includes a complete user interface which works out-of-the-box without any configuration beyond assigning appropriate permissions to users. The following sub-menu items include:

  • Inbox: This is where users come to perform their pending tasks such as approval or input.
  • Submit: A central place to publish all your workflow forms. Users select the form they’d like to submit. The administrator can decide which forms to publish on the submit page.
  • Status: The repository for workflow entries. Entries can be filtered by id, form, date and status.
  • Activity: A log of everything that happens and how long it took.

An example of the inbox with a couple of vacation requests pending approval.

An example of the Status page:

See the documentation on permissions to see how to give users access to these pages.

You don’t have to use this built-in admin UI if you don’t want to. Each of these pages is available via a shortcode so you can use them in the front-end. 

See the documentation on using the shortcode for further details.

Workflow Steps

AUTOMAIT processes are built using Workflow Steps. Each Step is responsible for controlling a set of tasks such as approval, user input, sending notifications or integrating with third-party systems such as MailChimp. The following steps are built-in to the Flow Designer:

  • Approval – Read more about configuring a simple approval process.
  • User Input – See an example of a user input step.
  • Notification – Sends any of the Forms notifications.
  • Webhook – Sends data to other systems.

You can add as many steps to your process as you like, and use each step type as many times as you need.

Note

The Flow Designer handles the management of the status for you so you can concentrate on the flow of the process.

Workflow Steps are form-specific, so they are configured in the workflow tab on the form settings page for each form. Here’s an example of a vacation request workflow involving an employee, department managers and the HR department:

The Assignee Field

In some processes it’s not possible to know who should be assigned to a step or an email until the moment the form is submitted. In these cases we have a couple of options. One way to do it is to let the user to decide exactly who should be assigned. The Assignee Field is a field that can be added to a Form which can be used to allow users choose from a list of roles and users. The Assignee Field can then be used in the configuration of the approval or user input steps.

You can find the Assignee Field in the Workflow Fields section of the Form Editor.

The Assignee Field can also be used as the destination for emails in some steps such as the approval and user input steps. 

Conditional Routing

Another way to configure dynamic step assignment is to configure routing. Routing works the same way as routing in Forms Notifications. It looks like this:

In this example, the step is assigned to a different manager (AUTOMAIT user account) depending on the value of the Department field (Dropdown).

Workflow Emails

Workflow Emails are similar to Forms Notifications except they are tied to a step and will be triggered only in that step. The following steps allow emails to be configured for different events:

Approval Step

  • Assignee Email
  • Rejection Email
  • Approval Email

User Input Step

  • Assignee Email

Emails can be sent to:

  • a specific user account.
  • a specific user role. Note the email will be sent to all users in the role so take care to select the correct role.
  • a user or role specified in an Assignee Field.
  • an email address entered in an email field.
  • the user who submitted the form. (Only enabled when the form setting ‘require user to be logged in’ is activated.)
  • conditional routing (see above)

It’s also possible to configure Forms Notifications by using the event setting along with the conditional logic setting. The Flow Designer adds an event for each step type and an event for Workflow Complete:

Next Steps

There are often many ways to implement the same workflow so once you’re aware of each of the features you’ll be able to get more creative with your solution.

When a new workflow is created, the Start and Complete settings will appear at the top and bottom of the step list. They are used to define global settings that apply to the entire workflow and after the workflow is complete.

Note: for workflows created before version 2.5, the Start and Complete steps are not added automatically – they can optionally be added like adding workflow steps.

The Workflow Start Settings

The Start settings, like workflow steps, has a conditional logic setting. However, unlike workflow steps, the conditional logic applies to the entire workflow. If the condition is met, then the workflow will be processed. If the condition is not met, then none of the workflow steps will be processed and the final status will be set to complete.

The Pending Message setting will display a message to the form submitter when the entry is viewed via the status page. This message will not be displayed if the form submitter is an assignee of the current step – use the step instructions instead.

The Default Display Fields setting controls which fields will be displayed to the form submitter when the entry is viewed via the status page. Note that all fields will be displayed if the user has permission to view all entries.

 

The Workflow Complete Settings

The Workflow Complete settings control the behaviour of the entry when the workflow is complete.

The Complete Message will be displayed to the form submitter when the entry is viewed via the status page.

The Default Display Fields setting controls which fields will be displayed to the form submitter when the entry is viewed via the status page. Note that all fields will be displayed if the user has permission to view all entries.

First, create a form that should be used for the approval process. Then in the Form Settings – Workflow tab, define the following settings:

1. Give the step a Name to uniquely identify it in the list of steps.

2. Select ‘Approval’ from the Step setting.

3. Assign the user who should approve the entry in the Select Assignees setting. Click on the user to move it to the list of approvers.

4. Configure the emails for this step. The assignee email will be sent as soon as the step starts to advise the assignee that there’s a pending task waiting in their inbox. The Rejection email will be sent in the case of rejection, and the Approval email will be sent if the entry is approved.

5. Finally, define the next step in the Workflow. In the case of rejection, the default setting is to stop the Workflow. In the case of approval, the default setting is, ‘next step in list’. If there are no more steps in the list, then the Workflow will be considered complete.

The complete step configuration should look something like this. In your case, you will have different user accounts.

Selecting Display Fields

By default all fields will be displayed, but you can use the “Display Fields” setting to specify which fields should be displayed.

Sending Assignee Reminder Emails

The assignee email has a “Send Reminder” setting.

When activated, the assignee email will be sent once more after the specified number of days. Once sent, the reminder email will not be sent again.

Scheduling Steps

All steps can be scheduled to begin after a specific delay, or on a specific date. The entry will be ‘queued’ until it’s time to start the step.

Step Expiration

Approval steps can be scheduled for expiration. Once a step expires, the entry will be sent to the step configured in the Next step setting(s). The Expiration settings in the Approval Step allow for the status to be specified once the step has expired.

Step Due Date

Approval steps can have a due date specified. Once a step has passed the due date, the entry will be highlighted with the chosen color on any inboxes.

The due date can also be communicated through the {current_step} merge tag modifiers {current_step:due_date} and {current_step:due_status}.

The Revert Button

The Approval Step has a Revert setting, which will activate a third option in addition to Approve and Reject. The Revert button allows the assignee to send the entry directly to a User Input step without changing the status. Enable this setting to show the ‘Revert’ button next to the ‘Approve’ and ‘Reject’ buttons, and specify the User Input step the entry will be sent to.

The Revert setting will only appear if the workflow has at least one User Input step.

Once enabled, the ‘Revert’ button will appear on the workflow detail page next to the ‘Approve’ and ‘Reject’ buttons.

First, create a form to use for this Workflow. The go to the Form Settings – Workflow tab to configure your User Input Step. Click on the ‘Add New’ button to add a new Workflow Step. Configure the following settings to set up the User Input step.

  1. Give the step a Name to uniquely identify it in the list of steps.
  2. Select ‘User Input‘ from the Step setting.
  3. Assign the entry to the user whose input is required in the Select Assignees setting. Click on the user in the list of users on the left to move it to the list of assignees on the right.
  4. Define which of the fields should be editable by clicking on the field in the list on the left to move it to the list of editable fields on the right.
  5. If any of the fields have conditional logic, then the “Enable field conditional logic” setting will be available. Leave this setting deactivated to override the conditional logic and display all the selected editable fields.
  6. The editable fields will be highlighted if the “Highlight Editable Fields” setting is selected. Options for highlighting are: green triangle and green background.
  7. Select the appropriate assignee policy.
  8. Optionally add instructions to the top of the page for this step.
  9. Select the display fields that should appear on this step.
  10. Select the option for the default status. User Input Steps can be submitted immediately (complete) or saved for later (in progress).
  11. The Workflow note is a special field above the ‘Update’ button. The content of this field is not stored in the entry, it’s added to the timeline. You can choose to make the note required depending on the status.
  12. If the Email setting enabled, an email will be sent to the assignee informing them that there is a task pending in their inbox. Enable the reminder setting to resend the email after a specified number of days.
  13. The expiration setting allows you to set a time limit for this step.
  14. Select the next step in the Workflow once this step is complete. If there are no more steps in the list, then the Workflow will be complete

Example Screenshots of the User Input step

Editable fields highlighted with a green background

Editable fields highlighted with a green triangle

Scheduling Steps

All steps can be scheduled to begin after a specific delay or on a specific date. The entry will be ‘queued’ until it’s time to start the step.

Step Expiration

User Input Steps can be scheduled for expiration. Once a step expires, the entry will be sent to the step configured in the Next Step setting(s). The Expiration settings in the User Input Step allow for the status to be specified once the step has expired.

Step Due Date

User Input steps can have a due date specified. Once a step has passed the due date, the entry will be highlighted with the chosen color on any inboxes. 

The due date can also be communicated through the {current_step} merge tag modifiers {current_step:due_date} and {current_step:due_status}.

Update User Step

The Update User Step is a very powerful step which can update the profile of any user. 

Care must be taken to design workflows that ensure that only authorized users perform updates to user profiles. For example, add an approval step before the Update User step.

The Update User step can update the user account of the form submitter (the created_by field), the current user (e.g. of a User Input step), the selected user in a User field, or the account looked up using the value of an email field.

The following profile properties can be updated: First Name, Last Name, Nickname, Display Name, Email Address, Roles and Custom User meta. 

The Roles setting allows the roles to be replaced completely by a new set of roles or additional roles can be added to the user’s existing roles.

How to setup outgoing webhook steps with response mapping

I is possible map the JSON values sent in the response to field values. This happens before the workflow moves on to the next step so you can define what happens next in the workflow depending on the response of an external API. For example, your webhook may request approval status from an external API, store the result in a field value and send a conditional notification based on the result.

Response Mapping Webhook Examples

APIs are a fundamental part of the open web which allow different web sites / servers to share data. Whether you own/manage an external application or you need to connect with or want to use one of many public APIs to return JSON responses, the possible uses of the response mapping feature of the outgoing webhook step are nearly endless. The examples provided below are meant to help you understand how to implement an outgoing webhook step with response mapping. The particular details of your form and API request/response format will require slight changes to fit your use case.

  • EU VAT Number Validation
  • Automatic Translation of Entry Values
  • Postal Code / Zip Code Lookup
  • Currency Conversion

EU VAT Number Validation

vatlayer.com offers an API for checking that an EU VAT number is valid. They currently offer a free plan which you can use for testing. So, at any point in your workflow after the initial form submission, you can configure an Outgoing Webhook step to check that a VAT number is valid and then populate field values with the registered company name and address.

The following Outgoing Webook step will connect to the vatlayer API and lookup the VAT number in field ID 1.  The {:1} is the merge tag for field ID 1 and the API key for the service is hidden. The Response Field Values will look up the company_name and company_address values in the response and save them in the Company Name and Company Address form fields.

Here’s what the workflow entry detail page looks like after entering Amazon’s VAT number in a User Input step followed by the webhook step:

Automatic Translation of Entry Values

The  deepl.com API provides a translation API so we can use it to translate submitted values. Whereas the vatlayer API provides all of the response data at the top level of the JSON, deepl has a more complex structure so we need to drill down into the response to grab the right values.

Here’s an example response from the deepl API:

    “translations”: [ 

        { “detected_source_language”: “ES”, “text”: “Hello World!” } 

    ] 

}

In order to retrieve the translated text we need to use the key “translations\0\text” – we use the zero because the value for translations is an array and we need to target the first element in that array.

Postal Code / Zip Code Lookup

zippopotam.us offers a free API which lets you lookup full or partial zip codes / postal codes for over 60 countries. It returns multiple data points including the latitude / longitude including USA, Spain and Canada.

Here’s the response from the zippotam.us API:

In order to retrieve the place name we need to use the key “places\0\place name” – we use the zero because the value for places is an array and we need to target the first element in that array.

Our example form ( zippopotam-sample-form2.json – unzip and import the form) uses the {Country:2:value} merge tag for field ID 2 with the value modifier and the {ZipPost:1} merge tag for field ID 1 to build the outgoing URL.

The result lets you reduce the amount of data your customers have to enter without sacrificing on the key information you need to make business decisions. The result should be increased engagement in your form/workflow and a better business process that saves you time and money.

As you can see all this is configured with zero custom code.

Currency Conversion

Currency exchange APIs could be integrated to your workflow to allow you to store near real-time exchange rates at the time a form or step was completed. This example ( form currency-conversion-api.json  – unzip and import the form) shows how you can use merge tags within the response field key to dynamically select certain elements from the JSON response.

Here’s the response from currencylayer.com API. Notice that the key for the quotes require both the source and destination currency identifier.

If your form has the needed currency identifiers as field values you can use the merge tag to define which specific quote you would like to store.

When the webhook step is run the exchange rate is stored into a field for later calculations. Using this snippet would also let you make calculations at the end of the webhook step for subsequent notifications to display.

The Incoming Webhook can be used in two ways:

  1. After form submission at any point in the workflow, to hold entries on a step until a trigger is received from an external system.
  2. To create an entry in a form from an external system. This will trigger the workflow automatically. 

See the links the bottom of this page for further information.

Incoming Webhook – Workflow Step

The Incoming Webhook Step is a feature of the Incoming Webhook which allows workflows to wait until receiving the input of an external system.

Adding an Incoming Webhook Step

  1. Select Incoming Webhook as the step type.
  2. Enter a name for your application. This is just informational.
  3. Enter a unique API Key or accept the default value. The API key is used to authenticate each request. This value should generally not be changed after saving. Warning: if there are any entries on this step then changing this setting will result in the entries getting stuck in the workflow and unable to proceed.
  4. Enter a unique API Secret which will be used to authenticate the request. It’s good practice to change this secret periodically.
  5. Determine if you want the step to map any values from the incoming request into field values in the entry.

Once an entry hits an Incoming Webhook step it waits until an authenticated request is received.

Request Field Mapping 

The step settings include an option for Field Mapping which opens up many more potential integration options for the Flow Designer. If you are familiar with the Outgoing Webhook step setup, you will find this new setting very familiar.

  • The default (None), will process the workflow onto the next step as soon as a valid request is received. This is valuable when your entry workflow only needs to know that a 3rd party system (or other form using an Outgoing webhook step) has completed a task before proceeding.
  • The new setting (Select Fields) lets you define a field mapping between a request key and entry field. When a valid request is received containing data in the body as either form-data or application/json, the mapped field values will attempt to be stored into the entry. This enables 3rd party systems which have updated data for the entry to pass the data in via the incoming webhook step.

Incoming Webhook – Create an Entry

Incoming Webhooks are a feature of the Incoming Webhook, and allow entries to be created for forms by external systems.

If your workflow starts with a form submitted by a user, then you will not need this feature. You can use the Incoming Webhook Workflow Step instead to pause the workflow until an external system sends a request. See the link at the bottom of this page for further detail.

How to Set Up an Incoming Webhook to Create an Entry

An Incoming Webhook will create an entry in a form when a POST request is received at an endpoint that is defined in the feed.

An incoming Webhook can be created from the form settings page. Multiple webhooks can be added which will allow multiple systems to create entries for the same form.

Webhook URL: This is a read-only field which displays the URL for the Webhook. It contains the ID of the webhook plus the key. Copy and paste this URL into your external system.

Webhook name: Name this webhook so you can identify it in the list of webhooks for this form.

Key: Define a unique key for this webhook. This will make the URL difficult to guess and help to keep your webhook secure. If someone gets hold of this URL they would be able to create entries. However, if this is not secure enough for your use case then you should consider adding some custom code to verify the authenticity of the request. See the Helpscout example below for further details.

Field Values: Map the keys of the values in the request to fields on the form. See the link at the bottom of this page for further details on the field mapping.

Example: Helpscout Webhooks

The following example will create an entry an entry when a rating is received in HelpScout.

Once you have the Incoming Webhook URL you can add it to the Callback Url setting in your Helpscout Webhook app like this:

Every time you receive a rating in Helpscout, the webhook request will be sent to your Incoming Webhook URL and an entry will be created.

Once the entry has been created by the webhook, then the workflow will be triggered automatically. For example, you could add a notification step which sends an email if the rating is not “good”, and a Slack step which sends all the “good” ratings to your support team Slack channel.

Download the sample form: helpscout-ratings-webook.json

Helpscout includes a security feature for their webhooks so that you can verify the authenticity of the request by checking the hash. Here’s a snippet which will verify the request. You’ll need to add the HELPSCOUT_WEBHOOK_SECRET_KEY constant to your wp-config.php file and edit the feed ID.

Importing and Exporting

Incoming Webhooks are exported and imported automatically with the form when the form is exported and imported.

Incoming WebHook – Field Mapping

Request Type

The system which is sending data to the incoming webhook in one of 3 formats:

     – POST with form-data in the body of the request

     – POST with form-data in the body of the request with a Content-Type header = application/json

     – POST with raw JSON in the body of the request with a Content-Type header = application/json

Request Sanitization not Request Validation

All incoming request values are sanitized based on their field type regardless of whether you use version 1 or 2 of the Gravity Forms Web/REST API. This prevents script injections and other technically bad data from being submitted through the incoming webhook field mapping to your form entries. However, it does not validate the request values submit for required status or format. 

What does that mean exactly? 

If you have a dropdown field type set as required with options of A, B, C, D or E, mapping that field for a request it:  

     – WOULD prevent “<script>alert(‘Doing bad things’)</script>” from being stored to DB in a bad format. 

     – WOULD NOT prevent “Banana” from being stored. 

Choice and Complex Field Types

Some field types that can have multiple selections (ex. checkboxes), or have sub-fields (ex. address), can have request values mapped to the entire field or individual data elements. The following settings field values and JSON show how they could be set as part of a raw JSON request. 

Unavailable Field Types

The majority of field types in the standard, advanced and workflow sections of the form editor are available for request mapping. A few, listed below, are not available at this time. Please contact AUTOMAIT Support if you have a use case that would benefit from them being added to a future release of the add-on. 

     – File Uploads 

     – Any Post Fields (Title, Content, Excerpt, Tags, Category, Images, Custom Field) 

     – Any Pricing Fields (Product, Quantity, Options, Shipping, Total 

Mapping array values and complex objects

Values inside arrays or complex objects can be mapped to fields by using a backslash to drill down into the structure. For example, people\0\name would map “Steve” to the field if the following JSON is received:

{people: [ “Steve”, “Jamie” ] }

E-Signature Workflow Step

Administrators can add workflow steps at any point in the process to collect legally binding document signatures using the E-Signature functionality.

E-Signature Form (Feed) Settings

Add an E-Signature feed from the E-Signature forms settings tab. It will look something like this:

Test the form by submitting an entry for signature.

The E-Signature Step Settings

Once all the above is installed, configured and working then you’re ready to add your workflow step. You can add a signature step at any point in the workflow. For example, you might want to collect the signature in the middle of a workflow after some user input and approval steps and then end the process perhaps with a PayPal payment step.

When you select the E-Signature step type, the settings will appear below. The settings allow you to select the assignees, configure an assignee email, display instructions, select the display fields and select the next step just as you would for any workflow step.

The settings will look something like this:

The E-Signature Workflow Step – Entry Detail

When the assignee opens the entry detail page from the inbox, he/she will see the invitation status in the workflow box and the “Review & Sign” button. The button will open a new window with the standalone document ready to sign. The step will complete immediately after the document is signed.

The “Review & Sign” button will only appear if the email address of the step assignee is the same as the email address of the document signer defined by the Signer E-mail setting in the E-Signature feed settings (see above). 

If the email address of the assignee is different than the document signer email address, then the ‘Preview’ button will be displayed. The Preview button will open the standalone document, but it will not be possible to sign the document. This allows users to be assigned to the step in order to oversee the signing process. For example, a sales person can be assigned to the step along with the client. The client will be able to sign the document and the salesperson will see the entry in the inbox, check the status of the signature and resend the invitation (requires permissions to open the WP E-Signature plugin settings).

Email Notifications

There are three places where email notifications can be configured, and choosing the best option can be confusing. This guide will help you choose the right approach for each step in your workflow.

Assignee Emails

Some steps have built-in email notification settings which help to keep the step configuration in one place. The Approval and User Input steps have email settings which, when enabled, will notify assignees when they are assigned to the step. The Approval step also has ‘Approval’ and ‘Rejection’ email settings. These email notification settings should be sufficient for most workflows.

Notification Steps

You may find that the email configuration in the step settings don’t offer you sufficient flexibility – perhaps you need to send to additional recipients or in certain situations, following special conditional logic. In these cases you may need to add a Workflow Notification Step. The notification step allows you to send notifications that were created in the Forms Notifications tab. Select the notifications you’d like to send in this step. The notification does not have to be active in the Forms notifications tab in order to send, but the conditional logic will be processed.

The Workflow Notification step also contains a ‘workflow notification’ setting which allows you to configure another email notification. This setting might seem like unnecessary duplication given that notifications can be created in the Forms Notifications tab however, there is one important difference. The ‘workflow notification’ setting allows you to send emails to your AUTOMAIT users, all the users in a role, all the assignees in an assignee field and the entry creator.

The Form Designer Notifications

Forms notifications are configured in the Notifications tab of the Form Settings. if you’ve not configured Forms notifications before, then you should start by reading this introduction in the Form Designer article on configuring Notifications. You may find that the previous two options are not sufficient, perhaps you’d like to send to a specific email address that is not contained in one of the fields. In this case you can configure a Forms notification to fire on a workflow event.

The Flow Designer adds a number of events to the notification event setting:

  1. Workflow: Approved or Rejected
  2. Workflow: User Input
  3. Workflow: Complete

The Workflow: Approved or Rejected event will fire whenever a an entry is approved or rejected regardless of the step and regardless of the status. Use the conditional logic setting to target either the ‘approved’ or ‘rejected’ status of a specific step. You may also need to specify the ‘Workflow Step’ to prevent the notification from sending at later steps.

The Workflow: User Input event fires whenever a user updates an entry in a User Input step, regardless of the step and regardless of whether the step was marked as complete or ‘in progress’. You can target specific conditions using the conditional logic.

The Workflow: Complete event fires whenever a workflow is complete regardless of final status. You can target specific conditions using the conditional logic.

Changing the order of steps

You can change the order of steps at any time by dragging the step in the step list to the desired slot.

The Workflow Fields

You can find the Workflow Fields in the Form Editor toolbox:

When you add a Workflow Field to the form you can use it in the configuration of a Workflow step. For example, you can assign a step to the select user in the User Field. Or send an approval email to all the users in the role selected in the Role field.

The User Field

The User Field is a Drop Down field that displays a list of all the User accounts on your  AUTOMAIT platform. The User Field supports conditional logic so you can show or hide other fields based on the value selected in the User Field. It has the same options as a Drop Down Field.

Note: When setting the default value via dynamic population or the merge tag, User Field expects a numeric ID

The Multi-User Field

The Multi-User field works like the standard Multi-Select field and shares the same options as the single User field. It allows multiple users to be selected from the list of users. The Multi-User fields can be selected as an assignee in the Step Settings and the selected users are treated as if they were selected in the step settings. This means that the assignee policy applies to all the selected users. So, if the assignee policy is set to “all assignees must complete the step”, then all the users selected in the Multi-User field must complete the step in addition to any other assignees selected in the step settings.

The User field and the Multi-User field support the “enhanced UI” setting. When activated on the Multi-User field, the field will look like this in the form:

The Role Field

The Role Field is a Drop Down field that displays a list of all the Roles on your AUTOMAIT platform. The Role Field supports conditional logic so you can show or hide other fields based on the value selected in the Role Field. It has the same options as a Drop Down Field.

Note : When setting the default value via dynamic population or the merge tag, Role Field expects a ‘role name’.

The Assignee Field

The Assignee Field is an advanced workflow field that can be added to a Form and can be used to allow users to choose between Users, Roles and other Assignee fields. The Assignee Field does not support conditional logic, but it can be very useful in custom development where you may want to offer different types of assignees.

The User and Role fields support conditional logic whereas the the Assignee field supports multiple assignee types. 

When you add an Assignee field to the form, it will look like a standard dropdown field but it will have all the Users and Roles in the list ready to be selected.

Note: This field is a bit more complex, it expects the type plus the ID, e.g user_id|2 or role|administrator or email|test@test.com.

Configuring the field in a Workflow Step

After you’ve added the Workflow Field to the form, you’ll need to use it in the configuration of a Workflow Step. For example, assign an approval step to the user selected in the Assignee Field.

You can also select the Assignee Field for the destination of the approval and rejection emails.

The Discussion Field

It’s already possible to use the Notes field to add comments to the timeline, however, the timeline can get a bit crowded, and sometimes it’s useful to manage conversations within the entry or add multiple conversations. The Discussion Field provides a way for users to maintain a conversation inside a form field itself, which means it can be used in merge tags, conditional logic and exported along with the rest of the entry values.

Adding a Discussion Field to a Form

Drag the Discussion Field from the Workflow Fields Toolbox to your form.

The Field Settings are identical to the Paragraph Field:

This means that the form submitter can initiate a discussion. If you hide the field using the Visibility setting (admin only), then it will not be available on the front-end form, but it will be visible in all the workflow steps. The field also supports conditional logic. Note: If you use conditional logic you’ll probably want to enable ‘Field Conditional Logic’ in the User Input step settings.

Discussion Fields in a Workflow

Discussion fields can only be updated in a User Input step. So, if you want users to contribute to the discussion, they need to be assigned to a User Input step. An Approval step will simply display the discussion, it is not currently possible to add a comment to the discussion on an Approval step.

When an assignee opens the entry detail page, the Discussion Field in a User Input will look like this:

If you set up a loop between User Input steps you can get a conversation going.

Tip: Assign conditional logic to one of the steps to allow the loop to end based on the value of another field.

Here’s what it’ll look like at the end of the workflow:

When discussions are longer than 10 messages a View more/less button will appear to toggle the display of the older messages. 

Merge Tags

The Merge Tag for the discussion field supports two modifiers: Latest and Limit. Examples:

{my discussion field:3} – displays the entire discussion.

{my discussion field:3: latest } – displays the latest message in the discussion. This is great if you want to send only the latest message in an email to another assignee.

{my discussion field:3: limit=4 } – displays the latest 4 messages in the discussion.

The Simple E-signature Field

You can add a Signature field to your form. Add a User Input workflow step and make sure the Signature field is editable.

When the assignee opens the entry, the signature field will be ready to sign.

Workflow Management

The Status Page

The Status page is the place to find all your submitted Workflows. By default users will only see their own forms. Administrators will see all forms.

The following screenshot show the status page in the WordPress admin UI. The appearance of the status shortcode on the front-end of your site will vary according to your theme.

You can filter by Status, ID, Workflow Form, or Date. Sort the columns by clicking on the column header. Sorting is not supported for the Workflow Form column.

The number of entries per page can be changed in the screen options:

When you filter by form you’ll see additional information for pending workflows. For steps with multiple assignees, person icons will be used to give a quick glance at the status. Click on the icons for further details.

Filter by form and step to display columns for all the assignees.

Exporting the status list

The status list can be exported by clicking on the export button below the table in the admin UI. When you click on the export button, a CSV file will be generated for you based on the current filter. When it’s ready you’ll be able to download it and save it to your computer. You can open the CSV file in any spreadsheet application. In some software, you may need to convert the text to columns – please consult your spreadsheet application for details.

Inbox, workflow details – Restarting or cancelling a workflow

Administrators can cancel the Workflow for an entry or restart the Step, or entire Workflow.

On the Workflow detail page, administrators will see a box with the available admin tasks for the current entry. If a Step or Workflow is restarted, then all emails will get resent just as if the step was starting for the first time.

Users without Administrator capabilities will not see the box with the admin task options.

The Submit Page

The Submit page displays a convenient list of all the available workflow forms to logged in users. Users can initiate workflows by submitting forms from this page just as they can from any page on the site. This is what it looks like in the Admin UI:

This page is mostly useful for sites that use only the Admin UI and don’t use the shortcode in the front-end. However, there is a shortcode which provides a way to display the submit page on any WordPress page. See the link to the shortcode documentation at the bottom of this page.

Note that the Submit page menu item will only appear when an administrator has published at least one workflow form in the Workflow Settings page.

The Shortcode

The shortcode displays the Workflow UI in any WordPress page. Use the page attribute to display either the inbox, the status page, the reports page or the submit page. Example:

OR

OR

OR

Important: the shortcodes are intended to be used on different pages – not on the same page.

Once you’ve added the inbox shortcode to a page, the logged-in users will see their pending tasks and they’ll be able to click through to the workflow detail page to perform the task.

Example of the user input step in a page with a sidebar.

Here’s what the inbox looks like in a Desktop browser with two pending tasks:

This is what it looks like in a smaller screen for example in a mobile device:

When the user clicks through to the workflow detail on an approval step, the page looks like this:

And on a smaller screen…

The Status page looks like this:

And on smaller screens it looks like this:

Advanced Shortcode Attributes

The shortcode supports the following attributes for the inbox and status pages:

id_column – show or hide the ID column in the inbox and status pages. For example, hide the ID column:

submitter_column – show or hide the submitter column in the inbox and status pages. For example, hide the submitter column:

step_column – show or hide the step column in the inbox and status pages. For example, hide the step column:

form – constrain the entries to the specified form ID. For example, constrain the entries to the form ID 1:

title – specify a title that will appear on the both the inbox/status list and the entry detail page. For example:  

timeline – show or hide the timeline. Default = true. Example:

step_status – show or hide the step status on the entry detail page. Default = true. Example

workflow_info – show or hide the workflow info. Default = true. Example:

sidebar – Use two columns or one. Default = true. Use false to use just one column. Example

actions_column – show or hide the approval actions column in the inbox page. For example:

due_date – show or hide the due date column. Default = false. Example:

back_link – show or hide the ‘Return to List’ link at top of main column of entry detail view. Example

back_link_text – Customize the text to display when the back_link parameter is set to true. Example

back_link_url – Customize the url to return users to from entry detail page when the back_link parameter is set to true. Example . Very useful if you have pages with Gravity Views included.

The following shortcode attributes require security settings to be enabled in the Workflow->Settings page.

fields – display value values. This is only supported when the form attribute is set, and when the shortcode security setting is enabled in the Workflow->Settings page. 

For example, display columns for fields 1 and 2 from form 1: . Multi-input fields can be added, but you’ll need to know the ID of each input (Gravity Flow Support can help you with that). An example for a name field with the field ID of 6 would be:

display_all – override the capabilities for the current user and display all the entries in the status page. This is only supported when the page attribute is set to “status”. For example:

allow_anonymous – override the capabilities for the current user and display entries to all visitors to the site. For example:

Advanced Shortcode Attributes for the Reports shortcode

When specifying shortcode supports the following attributes :

  • form – Define what form (id) the report should be pre-set to display based upon.
    Example:
  • range – Define what range of entries the report should be pre-set to display: last 3, 6 or 12 months.
    The attribute value would be last-3-months, last-6-months, last-12-months respectively.
    Example:
  • category – Define what category of report should be pre-set to display. The attribute value would be month, assignee or step.
    Example:
  • step_id – Define which step (id) the report should be pre-set to display.
    The form attribute must also be set.
    Example:
  • assignee Define which assignee the report should be pre-set to display.
    To verify syntax:
    • Specify assignee=”user_id|15″ to limit results to user ID 15
    • Specify assignee=”role|administrator” to limit results to assignee based on role type of administrator
    • Specify assignee=”email|john@example.com” to limit results to entries assigned to an email field.

Due Date

The Approval and User Input steps can be configured to have a due date either after a specified delay, or on a specific date.

The Due Date setting in the User Input step looks like this:

Note: If the form has a date field, then the date field option will be available as shown in the screenshot above. This allows steps to expire before or after the date specified in the value of a date field.

The color option allows you to define if the step should be highlighted on Inbox views when the entry is past its due date.

The due date for an active step will show up in the Workflow Info box on the Entry Details screen.

Additional display options for due date details

  • Notifications: via modifiers of the {current_step} merge tag {current_step:due_date} will show the month, day and year {current_step:due_status} will show whether the entry is ‘Pending’ or ‘Overdue’ which is very useful for reminder notifications
  • Inbox shortcode column: Add the due date to your inbox shortcodes:
  • Status shortcode column: Add the due date to your status shortcodes:

Scheduling a step

All steps can be scheduled by activating the Schedule setting. Scheduling can be useful when two steps are being triggered too close together, or when you need to perform a step on specific date.

This feature is particularly useful for so-called “content-dripping” where a series of notification steps are triggered over a number of days or weeks. For example, a customer has signed up for a course that should be delivered by email every day over the course of a week. You’d create 7 steps, each with a delay of 1 day.

Steps can be scheduled to begin after a specified delay in minutes, hours, days or weeks.

Please bear in mind that these delay settings are not exact. There could be an additional delay of up to 15 minutes before the step is actually triggered.

Steps can be also scheduled to begin on a specific date. For example, for an event.

 If you choose to use this feature for email list automation like an ‘auto-responder’, bear in mind that you should include a one-click cancel link in the emails.

Finally, steps can be scheduled to start on, before or after the date in a date field.

Conditional Routing

The “Assign To” setting has two options. The default option is “Select” which allows multiple assignees to be assigned to the step. For example, this allows multiple assignees to approve or edit an entry in parallel, however, the list of assignees is fixed – the assignees will always be the same regardless of the field values.

The second option of the “Assign To”, “Conditional Routing”, also allows multiple assignees to be assigned to the step, however, the list of assignees is generated dynamically depending on the field values.

For example, in a job application process, the assignee of an approval step will depend on the position applied for, so the rules may be set up like this:

  • If the position applied for is ‘Developer’ the IT Manger must approve.
  • If the position applied for is ‘Designer’ Marketing Manager must approve.
  • If the position applied for is ‘Controller’ the Finance Manager must approve.

With Conditional Routing, the “Assign to” setting will look like as shown below :

This example could also be set up using conditional logic on the step (see the link to the article on workflow branches below) however, it’s a little faster this way.

If the condition matches, the assignee will with be added to the step. If no condition matches, then the step will be skipped. If more than one condition matches, then each match will be added.

Engaging Leads through Partial Entries

Partial Entries can be used to create a sequence of emails that is triggered after a form submission has been abandoned. Enable the workflow setting in the Partial Entries Form settings.

This will trigger the workflow when a partial entry is created. It’s generally recommended to delay the workflow until a reasonable amount of time has passed. Use the schedule setting on the Start step to delay the workflow. For example, the following settings will prevent the workflow from starting until 3 hours after the last update of the partial entry, and ensure that the workflow only starts if the email address field has been entered.

When the workflow setting is enabled for the Partial Entries Add-On, then a new step type is available called the Partial Entry Submission step. This step will wait for the final submission of the form. 

If you’d like to send an email to the email address in a field on the form, then assign the step to the email field.

Use the assignee email to send an email with a link to resume the form submission. The {workflow_resume_partial_entry_link} and {workflow_resume_partial_entry_url} merge tags will output a link to the form. Select the page with the form – the link will take the user to this page and pre-populate all the values with the values they had entered when they were completing the form.

The merge tags support the following modifiers: page_id, text, token, assignee, step.

  • page_id:
    Displays partial entry from the specified page id
    Example: {workflow_resume_partial_entry_link:page_id=”2″}
    Note that this will take precedence over the Submission Page step setting.
  • text:
    Displays the text to display for the partial entry
    Example: {workflow_resume_partial_entry_link:text=”Continue your request”}
  • token:
    Enable or disable token access. It is false by default.
  • assignee:
    Reassign the partial entry to other users
    Example: {workflow_resume_partial_entry_link:assignee=”user_id|42″} or {workflow_resume_partial_entry_link:assignee=”role|developer”}
  • step:
    Display the partial entry for the specified step
    Example: {workflow_resume_partial_entry_link:step=”45″}

Put a space between multiple modifiers if needed.

{workflow_resume_partial_entry_link:page_id=”87″ text=”Continue your request”}

If you’d like to send another, different email the next day for example, then define the expiration settings and add another Partial Entry Submission step next in the list.

Also note: Partial Entries won’t have a value for the created_by as the entry is saved via a separate background process in which the user is not logged in. The value created_by will be set when the partial entry is updated when a multi-page form is paged using the next or previous buttons or when it is submitted.

Process Performance Management and Metrics

Reporting

The reports page displays a variety of charts for completed workflows and average duration by month, step, and assignee to help you identify potential bottle-necks in your processes – in real time.

Reports can be filtered by timeframe, form, step and assignee.

Example of a report filtered by form and grouped by month:

Example of a report filtered by form and grouped by assignee – in this case there is only one assignee:

Example of a report filtered by form and grouped by step:

Example of a report filtered by form and by step, and grouped by assignee:

Example of a report filtered by form, by step and by assignee, and grouped by month:

Approve/Cancel Workflows Through Links

One-click approval links

One-click approval links and tokens allow approvers to approve or reject an entry directly from an email without having to open the Workflow detail page.

Links to the admin UI require authentication, whereas links to a page on the front-end with the inbox shortcode do not require authentication. See link below for further information about the shortcode.

Insert the {workflow_approve_link} and {workflow_reject_link} merge tags in the assignee email. The links will expire after 48 hours, but this can be adjusted using the  gravityflow_email_token_expiration_days filter.

Approval links are available only in the approval step assignee email. They’re not available in any other steps, any other emails or Gravity Forms notifications.

Add approval links either by typing the merge tag manually or selecting them from the merge tag list.

If you’re using the inbox shortcode, you’ll need to add the page_id attribute to the merge tag like this:

{workflow_approve_link:page_id=[ID]}

{workflow_reject_link:page_id=[ID]}

e.g. {workflow_reject_link:page_id=5}

You can find the page ID in the URL of the page when you’re editing the page. The page ID is the ‘post’ parameter in the URL.

You can construct your own links by using the URL equivalents:

{workflow_approve_url:page_id=[ID]}

{workflow_reject_url:page_id=[ID]}

Security

One-click approval links that point to the admin UI require authentication. When an assignee clicks on the link they need to log in to the WordPress dashboard. If the assignee already has the authentication cookie on his or her computer then the password prompt will not appear.

However, one-click approval links that point to the front-end inbox shortcode do not require authentication, meaning the assignee will not be prompted to log in to approve or reject an entry. In this case, the the assignee receives a unique URL with a token which allow the assignee to perform the action encoded inside the token. Be aware that anybody who has access to the link can use it to perform the action, so the assignees should be aware of the implications of sharing/forwarding the links.

One-click cancel links

The one-click cancel merge tags allow assignees to cancel the workflow for the entry by clicking on a link in an email. They can be added to any of the workflow messages. The inbox shortcode must be on a page.

{workflow_cancel_link}

You’ll need to set the default inbox page in the settings or add the page_id attribute to the merge tag like this:

{workflow_cancel_link:page_id=[ID]} e.g. {workflow_cancel_link:page_id=5}

You can find the page ID in the URL of the page when you’re editing the WordPress page. The page_id is the ‘post_id’ parameter in the URL.

You can construct your own links by using the URL equivalents:

{workflow_cancel_url:page_id=[ID]}

Adjust the text in the link using the text attribute:

{workflow_cancel_url:page_id=[ID] text=”Unsubscribe”}

Assigning steps to non-users via the email field

Steps can be assigned to the email address value of an email field allowing users without an AUTOMAIT user account to participate in a workflow.

IMPORTANT: Assigning steps to email fields is not as secure as assigning steps to AUTOMAIT users. If you decide to assign steps to email fields, it’s strongly recommended that you don’t expose highly sensitive data.

When a form has email fields, they will appear in the ‘Fields’ section of the list of assignees that can be selected.

As email field assignees can’t login, they can’t use the admin UI, so you’ll need to add the inbox shortcode to a page and use the {workflow_entry_link} or {workflow_entry_url} merge tag in the assignee email to send them a unique URL which they will use to access the workflow. Use the page_id to specify the ID of the WordPress page containing the inbox shortcode. You can find the ID of the page in the URL when you open the page for editing (it’s the post_id parameter). The text attribute is optional.

The unique URL includes a secure access token which authenticates the user using a cookie stored on their computer for as long as their browser is open. Once the browser is closed, the user will need to click on their unique URL again in order to access the entry.

The unique URLs are valid for a duration of 30 days. This can be modified using the gravityflow_email_token_expiration_days filter.

The purpose of the email field is to allow people without user accounts to participate in workflows as assignees. It doesn’t look up the user account with that email address which means that you have to be careful testing – if you’re logged in you’ll see the tasks assigned to your user account.

Adding Direct Links to Workflow Entries for Easy Access

Linking to the workflow entry

You can include links to the workflow entry in assignee and approval notifications by adding the {workflow_entry_link} or {workflow_entry_url} merge tag. By default, this will link through to the workflow entry detail page in the admin UI. 

If you need to link to a page with the inbox shortcode, you’ll need to specify the ID of the page like this:

{workflow_entry_link: page_id=[ID of your page] }

Example:

{workflow_entry_link: page_id=24 }

You can find the page ID in the URL when you’re editing the page with the inbox shortcode (look for &post=XXX where XXX is the ID). You can also specify the link text by using the text attribute:

{workflow_entry_link: page_id=24 text = “View your application form” }

If you need more flexibility with the construction of the URL, you can use the {workflow_entry_url} merge tag which also takes the page_id attribute.

{workflow_entry_url}

OR

{workflow_entry_url: page_id=234}

Email Field Assignees

If the step is assigned to an Email field, then the page_id attribute is required because the assignee won’t be able to access the admin UI. In this case, the link will automatically include a special token which will identify the assignee. It’s important that these URLs are not shared because anyone who receives the URL can use it to participate in the workflow.

Entry Link Tokens for AUTOMAIT Users

By default, entry URLs and links sent to AUTOMAIT users will not include a token and will require the user to log in. However, there are situations in which it might be useful, and sufficiently secure, to allow WordPress users to participate in the workflow without logging in. It’s important to bear in mind that the token is not as secure as logging in, so use this feature with caution. To force the entry link merge tag to add an authentication token to the entry url and link merge tags just add the token attribute and make sure the page_id attribute is set. e.g.

{workflow_entry_url: page_id=234 token=”true”}

Merge Tags

The Flow Designer uses merge tags to allow you to dynamically populate submitted field values and other dynamic information in notification emails, field mappings, content templates and other areas.

A merge tag uses curly braces and looks like this: {workflow_entry_link}. The complete list of merge tags available to each context can be found by clicking the merge tag icon to the right of the text box.

The {created_by:[property]} merge tags

In addition to the merge tags available in the list, there’s another merge tag which can be used to display information for the user account of the entry submitter.

The {created_by:[property]} merge tags will lookup the user account in the created_by field of the current entry and display the specified property. Please note that this is different from the Forms {user:[property]} merge tag which looks up the user account for the current user.

  • :display_nameDisplays the Display Name of the submitting user.  {created_by:display_name}
  • :user_emailDisplays the email of the submitting user.  {created_by:user_email}
  • :user_loginDisplays the user login of the submitting user.  {created_by:user_login}
  • :IDDisplays the ID of the submitting user.  {created_by:ID}

The {assignees} merge tag

The {assignees} merge tags will output the details of the current step’s assignees. The assignee display name, email, and status are displayed by default. The following modifiers can be used to prevent them being displayed

  • :display_nameDisplays the Display Name of the assignee.  {assignees:display_name=false}
  • :user_emailDisplays the email of the assignee.  {assignees:user_email=false}
  • :statusDisplays the assignee status.   {assignees:status=false}

The above modifiers can also be used together  {assignees:display_name=true user_email=false status=true}

The {workflow_note} merge tag

The note merge tag will display the most recent user submitted note. The following modifiers can be used to customize the behaviour of the merge tag.

  • step_idDisplays all the user submitted notes for the specified step, including previous occurrences of the step   {workflow_note:step_id=5}. The step name can also be used instead of the ID.
  • display_nameDisplays the name of the user who submitted the note  {workflow_note:display_name=true}
  • display_dateDisplays the date and time the note was submitted  {workflow_note:display_date=true}
  • history
    Controls whether notes from previous occurrences of the step are displayed.  {workflow_note:step_id=5 history=true}

The above modifiers can also be used together  {workflow_note:step_id=5 display_name=true display_date=true}

The {workflow_timeline} merge tag

The timeline will display the date, user, step and notes from the timeline in a simple, compact list.

{current_step}

The current step supports the following modifiers: duration (time), expiration (date/time), ID, name (default), schedule (date/time), start (date/time) and type.

Examples:

  • {current_step:duration}
  • {current_step:expiration}
  • {current_step:ID}
  • {current_step:name}
  • {current_step:schedule}
  • {current_step:start}
  • {current_step:type}
  • {current_step:due_date} – When a step due date has been specified, this will return the due date.
  • {current_step:due_status} – This will return “Pending” or “Overdue” when compared to the due date if it has been set.

The {workflow_fields} Merge Tag

The {workflow_fields} merge tag supports the following identifiers : empty, value, admin, editable, display. All these modifiers take Boolean values.

Examples :

  • {workflow_fields:empty = false} // Output empty fields.
  • {workflow_fields:value = false} // Output choice values.
  • {workflow_fields:admin = false} // Output admin labels.
  • {workflow_fields:editable = true} // Output the steps editable fields.
  • {workflow_fields:display = true} // Output the steps display fields.

Note: workflow_fields is just a wrapper for the all_fields merge tag. It filters out any field which isn’t set as display only or editable on the current step. Only then their behavior can be modified by using {workflow_fields} identifiers.

The Flow Designer uses merge tags to allow you to dynamically populate submitted field values and other dynamic information in notification emails, field mappings, content templates and other areas.

A merge tag uses curly braces and looks like this: {workflow_entry_link}. The complete list of merge tags available to each context can be found by clicking the merge tag icon to the right of the text box.

The {created_by:[property]} merge tags

In addition to the merge tags available in the list, there’s another merge tag which can be used to display information for the user account of the entry submitter.

The {created_by:[property]} merge tags will lookup the user account in the created_by field of the current entry and display the specified property. Please note that this is different from the Forms {user:[property]} merge tag which looks up the user account for the current user.

  • :display_nameDisplays the Display Name of the submitting user.  {created_by:display_name}
  • :user_emailDisplays the email of the submitting user.  {created_by:user_email}
  • :user_loginDisplays the user login of the submitting user.  {created_by:user_login}
  • :IDDisplays the ID of the submitting user.  {created_by:ID}

The {assignees} merge tag

The {assignees} merge tags will output the details of the current step’s assignees. The assignee display name, email, and status are displayed by default. The following modifiers can be used to prevent them being displayed

  • :display_nameDisplays the Display Name of the assignee.  {assignees:display_name=false}
  • :user_emailDisplays the email of the assignee.  {assignees:user_email=false}
  • :statusDisplays the assignee status.   {assignees:status=false}

The above modifiers can also be used together  {assignees:display_name=true user_email=false status=true}

The {workflow_note} merge tag

The note merge tag will display the most recent user submitted note. The following modifiers can be used to customize the behaviour of the merge tag.

  • step_idDisplays all the user submitted notes for the specified step, including previous occurrences of the step   {workflow_note:step_id=5}. The step name can also be used instead of the ID.
  • display_nameDisplays the name of the user who submitted the note  {workflow_note:display_name=true}
  • display_dateDisplays the date and time the note was submitted  {workflow_note:display_date=true}
  • history
    Controls whether notes from previous occurrences of the step are displayed.  {workflow_note:step_id=5 history=true}

The above modifiers can also be used together  {workflow_note:step_id=5 display_name=true display_date=true}

The {workflow_timeline} merge tag

The timeline will display the date, user, step and notes from the timeline in a simple, compact list.

{current_step}

The current step supports the following modifiers: duration (time), expiration (date/time), ID, name (default), schedule (date/time), start (date/time) and type.

Examples:

  • {current_step:duration}
  • {current_step:expiration}
  • {current_step:ID}
  • {current_step:name}
  • {current_step:schedule}
  • {current_step:start}
  • {current_step:type}
  • {current_step:due_date} – When a step due date has been specified, this will return the due date.
  • {current_step:due_status} – This will return “Pending” or “Overdue” when compared to the due date if it has been set.

The {workflow_fields} Merge Tag

The {workflow_fields} merge tag supports the following identifiers : empty, value, admin, editable, display. All these modifiers take Boolean values.

Examples :

  • {workflow_fields:empty = false} // Output empty fields.
  • {workflow_fields:value = false} // Output choice values.
  • {workflow_fields:admin = false} // Output admin labels.
  • {workflow_fields:editable = true} // Output the steps editable fields.
  • {workflow_fields:display = true} // Output the steps display fields.

Note: workflow_fields is just a wrapper for the all_fields merge tag. It filters out any field which isn’t set as display only or editable on the current step. Only then their behavior can be modified by using {workflow_fields} identifiers.