Workflows

The workflows module enables you to implement and manage different processes and actions, triggered by certain events in the system and taking account of certain conditions. It tracks changes in any system entities and performs certain actions at the same time. The main purpose of workflow configuration and programming is to automate processes and create/modify data records, to save time, minimize human error, and improve collaboration. Absolutely any workflow can be implemented.

The detection of an action occurs on the server side and not on the user interface side. So, the changes are tracked via API.

Concepts

A workflow is a model of a process in your application. For example, you want automatically to set a tag for a product with a price over 200$ or you want to set an error when a price is 0$ or less. All of this and even more can be executed via workflows.

Creating a Workflow

You can configure as many workflows as you wish. More than one workflow can be appended to an entity.

Click on the button Create Workflow to create a new workflow.

To create a new workflow, define the "Name", then choose the "Trigger entity" to align with the workflow and the entity, which is going to be investigated when searching. It indicates which entity he is listening to, for example, Product. Then you will need to identify which action ("Trigger Actions") will trigger the workflow, for example, before create and before update and then indicate a condition ("Conditions Type") for the trigger to happen, for example, if the entity is active. The condition is not mandatory so if you want the action to always trigger the workflow you may set it to be always true.

Trigger Actions

For workflow to work you must set trigger actions. They are the essence. they can be before or after update, create or delete. When one of mentioned actions is achieved then workflow is started. You can choose multiple actions, but at least one is always required. For more advance settings use conditions.

For our example of updating a tag for a product it is better to choose after update and create so that all possible conditions are met and only after the changes are implemented. For the error message the best case would be before update and create so that the changes are not yet implemented. After that we can switch to conditions.

Conditions Type

There are two condition types available - "Basic" and "Script". Their logic basically states: "trigger workflow on trigger action when condition is fulfilled (the results are true)".

Basic

For easier use you can select basic conditions. They follow common logic with AND OR and NOT. These are combined in any shape. Fields are the end results, and their options to look at are the same as for filtering. On the example below you can see a formula where workflow triggers on the trigger action when a field "amount" is empty or brand is Xiaomi.

Here you can see condition for our first example.

Script

Script is more complicated use case but as a result more versatile. It uses twig syntax for formulas. To use it you have to set a formula that results in a default Boolean variable "proceed" ({% set proceed = ... %}). For more detailed twig guidelines and syntax please go to https://twig.symfony.com/doc/.

Please note, conditions use database query to function. They are launched every time Trigger Actions are made. So, not to overload it with multiple queries, please, minimize amount of database queries by using best practices. For example, for twig you can set variables (like {% set brand = entity.brand %}) instead of doing full blown database queries for every field. You can also check if an entity is linked to another (like {% if entity.brand is not empty %}) before setting variables.

Here you can see condition for our second example.

Workflow Actions

If all conditions are met, workflow actions are launched. Workflow actions are the a separate entity. They are the essential for workflows to work. When workflow is triggered ant the condition is met then action is started. You can choose only one action per workflow.

You can also run the workflow actions manually. To do so, visit workflow action page and press 'Execute' button.

The action can be also launched from entity. Usage prescribes placement of the action. It can be used a new custom action from record page or as a custom action from entity page. Display is where this button will be shown.

For our examples we need update and error message actions.

Import Feed

This action allows to launch selected import feed with set payload. For example, in the image below script {"sourceEntitiesIds": {{ sourceEntitiesIds|json_encode|raw}}} states that only selected records are to be executed.

Export Feed

This action allows to launch selected import feed with set payload. For example, here { "where": [ { "type": "in", "attribute": "id", "value": [ "{{ entity.id }}" ] } ] } the payload filters all attributes by ids and transfers to export only the attribute with the id of a triggering record.

Connector

This action allows to launch selected import feed with set payload. The payload is the same structure as in Import Feed or Export Feed actions.

Create

This action can be used to create records with specified fields. Just like other actions, it can be of the Script or Basic type and can be used in conjunction with the Workflow and separately from it.

Upsert

To do bulk create and bulk update records, you can use action Upsert. The system will try to find existing entities based on the identifier or unique fields. If an entity is found, it will be updated, otherwise it will be created by the system.

Example of the script:

[
{
    "entity": "Product",
    "payload": {
        "name": "Apple iPhone 15",
        "sku": "iphone15"
    }
},
{
    "entity": "Product",
    "payload": {
        "id: "2348924928743",
        "name": "Apple iPhone 15 Pro Max",
    }
}
]

Update

There are two types of update actions: Basic and Script. Their principle is the same as for workflow conditions. For both actions, you can set conditions inside the action itself. These conditions will be checked after the workflow conditions have been met.

For basic type you select a record (Target Entity *), select what field would be updated and a filter. For the example above The action updates all empty description fields of an Account entity with "abc".

For script type you select a record (Target Entity *). The script then states what will be updated and with what information. For example, here the script {"releaseDate": "{{ "now"|date('Y-m-d H:i:s') }}"} the Script specifies the data that is transferred to update the entity, in this case the releaseDate field will be updated.

So for the example we can select needed tag. Ypu can see the code in the picture above.

Send Notification

Action of type Send Notification allows you to create templates and send notifications to any users of the system in response to a specific trigger (record modification, changing of the specific field, etc.). You can select a specific user from the list of all system users, as well as select users associated with a specific entity.

Select template for the notification in Transport panel. Here you can also choose whether to send a system notification or an email. To do this, select the appropriate checkbox(es). Templates for notifications are created in the Notification Templates entity. You can choose any of the system templates or create your own.

In the Notification recipients panel, select the users who should receive the notification. In the System Users field, you can select one or more users from the list of all users registered in the system. The list of fields in Entity Users depends on the entity selected in the Source Entity field. All fields of the selected entity that are related to Users (Owner, Assigned User, Followers, etc.) are presented here.

Send Email

The Send Email action can be used to notify users about events related to the selected entity in response to some trigger actions (modification, creation or deletion of a new record, change of a certain field, etc.)

To send emails, you can choose existing templates of the Email Notification entity or create your own template. To create a template for an email, go to Administration / Email Templates and click Create Email Template.

• Name - set the name of the template
• Code - set code of the template if it is needed
• Email To - the recipient's email address
• Email CC - add the recipient to the copy, if necessary
• Subject - set the subject of Email in the Twig field. The template has a separate field for each locale added to the system
• Body - create a body of email in the Twig field. The template has a separate field for each locale added to the system.
• Connection - select the connection of SMTP from the existing ones in the system that will be used to send emails
• Allow attachment - select this checkbox if you want the files contained in the entity to be attached to the email.

Select the desired template when creating an Action in field Email Template.

If you want the email to be sent in response to a specific trigger, create a Workflow with the appropriate condition and add link it with the Action.

Action set

This action allows to launch multiple actions at once. Select actions you want in it. If you want to temporary deactivate action in set you can by disabling "Active in Action Set" checkbox for action.

Error Message

This action allows to set you own error messages. The message shown in text will appear whenever this action will be executed.

So for the example we can write "price should not be 0 or lower".

For it to work better to leave "Display" empty for it not to show as action or button.

Launching Actions not via workflows

You can set workflow actions as custom buttons on entities or records in the entity. To use them so, choose corresponding "Usage" option. Then, you would need to choose a "Display" to select if you want to see the button in dropdown menu or as a separate custom button.

Action selected to be launched from records as a separate custom button looks like this:

Action selected to be launched from records as a dropdown button looks like this:

Action selected to be launched from records can be also added as a mass action.

Action selected to be launched from entity as a separate custom button looks like this:

Action selected to be launched from entity as a dropdown button looks like this:

Action selected to be launched from entity can be applied to only pre-selected records or all records of the entity.

Examples

Update attribute value

You want automatically to ad an attribute with selected value. For our example we will take "Test value".

We will select "After Update" and then check if the selected by id attribute is in the product.

Than we will update the action.

If the status switches to "Done" and no price greater than 10 is specified, we display a message

First we check if the record receives the "Done" status and no price greater than 10.

Than we use message action with custom message.

When the entity receives the "Approved" status, we execute an export feed that creates a record of this entity on the production server

First we check if the record receives the "Approved" status.

Than we execute export action with all needed information. For the example below we export only id.