You are browsing the documentation for version 4.2 of OroCommerce, OroCRM and OroPlatform, which is no longer maintained. Read version 5.1 (the latest LTS version) of the Oro documentation to get the updated information.
See our Release Process documentation for more information on the currently supported and upcoming releases.
Processes provide the possibility to automate tasks related to entity management. They use the main doctrine events to perform described tasks at the right time. Each process can be performed immediately or after a timeout. Processes use the OroMessageQueue component and the bundle to provide the possibility of delayed execution.
Three entities represent processes:
1. Definition is the primary entity that contains information about a specific process. It contains the most important information: process-related entity type (e.g., user) and what the actions must be performed with this entity (e.g., change the value of a field). Another important option is the execution order that affects the order of processes execution if several processes are subscribed to the same event of the same entity. The process can be enabled or disabled. Other fields of the process definition contain the process name, when this process was created and when it was last updated.
Trigger entity provides information about the trigger used to run the related process when this process is invoked.
There are two types of triggers:
The first parameter is the trigger event - one of
delete. The second parameter defines the entity field name used to listen (used for the
updateevent only) and the process that is invoked only if the value of this field has been changed. The trigger also contains information about when the process should be performed - immediately or with delay (delay interval in the seconds of PHP date interval format). In case of delayed execution, you can also control the execution priority of process jobs.
Allows execution of processes based on cron-definition. The cron definition itself is specified in the
*/1 * * * *). These triggers can be executed only if the system has configured the cron script with the
Each trigger can define only one of these types.
3. Job is an entity that contains information specific to the performing process in case of delayed processing (in this case, JMS job is created). Depending on the event, a job can contain the following data:
createevent - entity identity;
updateevent - entity identity and change set (old and new values);
deleteevent - entity plain fields (without references).
Each job entity also contains a relation to the trigger used to create this job and entity hash (the full class name of the related entity plus the identity of a specific entity). This entity hash is required in order to find all registered jobs for the same entity (e.g., to remove all related jobs).
Each process definition related to an entity type, and each definition can have several triggers.
When a user performs an action with an entity that is related to an enabled process definition, all existing triggers for this process are analyzed, and the appropriate ones are found to be executed.
A trigger can be processed in two ways. The first one is immediate execution; in this case, the process action is executed right after the entity is flushed to the database or by the cron schedule. The second one is delayed execution; it creates a job and sends it to the queue with the specified priority. If an entity has several appropriate process triggers, then all of them are processed in the order defined by definition.
Once a specific entity item is deleted, all job processes related to this entity are also deleted.
Performing the action described in the process definition can provoke triggers of other processes (or even the same process). You should either use an appropriate condition to avoid recursion or use the “exclude_definitions” option.
All processes are described in the configuration. The example below illustrates a simple process configuration that performs an action with the Contact entity.
processes: definitions: # list of definitions contact_definition: # name of process definition label: 'Contact Definition' # label of the process definition enabled: true # this definition is enabled (activated) entity: Oro\Bundle\ContactBundle\Entity\Contact # related entity order: 20 # processing order exclude_definitions: [contact_definition] # during handling those definitions won't trigger preconditions: # List of preconditions to check before scheduling process @equal: [$source.name, 'other'] # Perform process only for entities that have "other" source actions_configuration: # list of actions to perform - '@find_entity': # find existing entity conditions: # action conditions @empty: $assignedTo # if field $assignedTo is empty parameters: # action parameters class: Oro\Bundle\UserBundle\Entity\User # $assignedTo entity full class name attribute: $assignedTo # name of attribute that will store entity where: # where conditions username: 'admin' # username is 'admin' triggers: # list of triggers contact_definition: # name of trigger - event: create # event on which the trigger performed - event: update # event on which the trigger performed field: assignedTo # field name to listen priority: 10 # priority of the job queue queued: true # this process must be executed in queue time_shift: 60 # this process must be executed with 60 seconds delay - cron: */1 * * * * # execute process every 1 minute
This configuration describes the process that relates to the
Contact entity. Every 1 minute, or every time a contact is
created, or the
Assigned To field is changed, the current administrator user is set as the assigned user.
In other words, a contact is assigned to the current administrator.
The described logic is implemented using one definition and two triggers.
The first trigger is processed immediately after the contact is created, and the second one creates a new process job
and sends it to the message queue with priority
10 and time-shift
60, so the job is processed a minute later than
the triggered action.
Assigned To field is updated, then process “contact_definition” is eventually handled, and the
value of the
Assigned To field can be changed. When the “exclude_definitions” option is specified, this process does not
- If you want to test this process configuration in a real application, you can place this configuration into the
Oro/Bundle/WorkflowBundle/Resources/config/oro/processes.ymlfile and reload the definitions using the console command
php bin/console oro:process:configuration:load. After that, you can create a
Contactof the changed assigned user and ensure that the process works.
- Expression $. allows you to access the main data container; for processes, it is an instance of
- Expression $ (shortcut) or $.data allows you to access the current entity; above in example it is
WorkflowBundle provides two following console commands to work with processes.
This command loads processes configuration from .yml configuration files to the database. It is used during application installation and update. The command has two optional options:
- –directories - this option specifies directories used to find configuration files (multiple values allowed)
- –definitions - this option specifies names of the process definitions that should be loaded (multiple values allowed)
You should run this command if process configuration was changed to upload your changes to DB.
This command executes a process trigger with a specified identifier and the process name. The command has two required options:
- –id - the identifier of the ProcessTrigger to handle
- –name - the name of ProcessDefinition. The trigger should belong to this ProcessDefinition
OroWorkflowBundle provides REST API that allows activation and deactivation of processes.
Activation URL attributes:
- parameter: processDefinition - the name of the appropriate process definition
Deactivation URL attributes:
- parameter: processDefinition - the name of the appropriate process definition