Important

You are browsing the documentation for version 3.1 of OroCommerce, OroCRM and OroPlatform, which is no longer maintained. Read version 5.1 (the latest LTS version) of the Oro documentation to get up-to-date information.

See our Release Process documentation for more information on the currently supported and upcoming releases.

Workflow Configuration Reference

Configuration of Workflow declares all aspects related to a specific workflow:

  • basic properties of a workflow, like name and entity

  • steps and transitions

  • attributes involved in the workflow

  • entity related to the workflow

The structure of the configuration is declared in class oro\Bundle\WorkflowBundle\Configuration\WorkflowConfiguration.

Configuration File

Configuration must be placed into the Resources/config/oro/workflows.yml. file. For example, src/Acme/DemoWorkflowBundle/Resources/config/oro/workflows.yml.

The configuration file can be split into parts. All included parts must be placed under the imports section. Imports may be used in any part of the workflow configuration.f

Example - workflows.yml

1 imports:
2     - { resource: 'workflows/b2b_flow_lead.yml' }
3     - { resource: 'workflows/b2b_flow_sales.yml' }
4     - { resource: 'workflows/b2b_flow_sales_funnel.yml' }

Example - b2b_flow_lead.yml

 1 imports:
 2     - { resource: 'b2b_flow_lead/steps.yml' }
 3     - { resource: 'b2b_flow_lead/attributes.yml' }
 4     - { resource: 'b2b_flow_lead/transitions.yml' }
 5     - { resource: 'b2b_flow_lead/transition_definitions.yml' }
 6
 7 workflows:
 8     b2b_flow_lead:
 9         entity: Oro\Bundle\SalesBundle\Entity\Lead
10         entity_attribute: lead
11         start_step: new

Workflow Imports

When you need to reuse an existing workflow configuration or its parts, use the workflow import directive.

Import Example (with replace)

1 imports:
2     - { workflow: flow_to_import, as: flow_to_recieve, replace: ['transitions.unneeded_transition_from_other_flow']}
3 workflows:
4     flow_to_recieve:
5         #...

Options (* - required):

  • workflow * (string) - a name of workflow to import

  • as * (string) - a name of workflow that should accept imported workflow config

  • replace * (list) - a list of node paths that should be replaced from imported workflow

  • resource (string) - an optional direct file path to load workflow to import from

The example above shows the import of a different workflow configuration (flow_to_import) into the current one (flow_to_recieve).

The flow_to_import workflow configuration is found across all registered workflows and imported as is (raw configuration without normalization) under node workflows.flow_to_recieve in the current configuration file. Then, it replaces all nodes defined in the replace option to clean all unnecessary segments. After that, flow_to_recieve from the current config file is recursively merged on top of the imported one. The described operation is performed for each import directive. The search for workflow configuration by default is performed across all registered bundles.

Resource Option with Workflow Import

If you need to load your part of the configuration directly from the file, use the resource option for load. This approach can be helpful in two situations:

  1. Resource: Split Parts Reuse

    1 imports:
2     - { resource: 'b2b_flow_lead/steps.yml', worklow: b2b_flow_lead, as: new_workflow, replace: [] }
3 workflows:
4     new_workflow:
5        transitions:
6             #...
7        #other options except steps

    If you need to reuse part of the workflow with split config by files and don not want to perform all other unnecessary nodes to be specified in replace option. For example (as granted above), you are interested in steps only from a different workflow config, and those steps are placed under the ‘b2b_flow_lead/steps.yml’ file. So, now you can load them directly by using the resource option together with the workflow import options (workflow, as). And you will have all steps from the b2b_flow_lead workflow loaded under your new_workflow configuration without any additions.

  2. Resource: Common Template Reuse

    If you are defining several workflows that are similar to each other, but have different use cases (for example: entities to apply to), use the following approach:

    1 imports:
2     - { resource: 'common_flow.yml', workflow: common_flow, as: flow_for_user, replace: [] }
3     - { resource: 'common_flow.yml', workflow: common_flow, as: flow_for_customer, replace: [] }
4 workflows:
5     flow_for_user:
6         entity: User
7
8     flow_for_customer:
9         entity: Customer

    Then you can create a file with a workflow which will serve as a template for others (‘common_flow.yml’). Then, by importing it, you can override its nodes for a particular case (different entity but shared remaining configuration).

Configuration Loading

To load the configuration, execute the following command:

1 php bin/console oro:workflow:definitions:load

The command has two options:

  • directories allows to specify which directories will be used to find definitions

  • workflows defines names of definitions required to load

Note

Workflow configuration cannot be merged, it means that you cannot override workflow that is defined in a different bundle. If you declare a workflow and another bundle will declare its own workflow with the same name, the command will trigger exception and data will not be saved. If you want to reuse an already existent configuration, use the import workflow feature.

Translations File

Together with workflows configurations, for almost each section that specified below, there should be defined translation text under corresponded key to display correct UI text. Configuration of translations is implemented in the same way as other translation resources (you might know them by files placed under <YourBundle>/Resources/translation/messages.en.yml or <YourBundle>/Resources/translations/jsmessages.en.yml.

Every workflow must have their own translations file, i.e. - <YourBundle>Resources/translations/workflows.{lang_code}.yml, - where {lang_code} is your preferred language code for the translations that are collected there. Each section that describe workflow configuration part must contain a note provided with a proper Translatable type for the translatable fields. These fields describe the value that can be defined only in the workflows.{lang_code}.yml file, but never in the configuration.

Defining a Workflow

The root element of the configuration is workflows. Workflows can be defined under this element.

A single workflow configuration has the following properties:

  • name - string - A workflow should have a unique name in the scope of all applications. As workflow configuration does not support merging two workflows with the same name, this will lead to throwing an exception during configuration loading.

  • label (translation file field) - Translatable: oro.workflow.{workflow_name}.label. This value will be shown in the UI.

  • entity - string - The class name of workflow a related entity.

    Note

    An entity must either be extended or custom, or it must have fields to contain the workflow item and step.

  • entity_attribute - string - The name of the attribute used to store a related entity.

  • is_system - boolean - The flag that defines whether this definition is system. System definition cannot be edited or removed. All definitions loaded from the .yml files are automatically marked as system.

  • start_step - string - The name of the start step. If a workflow has a start transition, then start_step is optional, otherwise, it is required.

  • steps_display_ordered - boolean - If this flag is true, then the workflow step widget will show all steps according to their order (including not passed) on the entity view page, otherwise, the widget will show only the passed steps.

  • attributes - Contains configuration for attributes.

  • steps - Contains configuration for steps.

  • transitions - Contains configuration for transitions.

  • transition_definitions - Contains configuration for transition definitions.

  • priority - an integer value of the current workflow dominance level in part of automatically performed tasks (ordering, exclusiveness). It is recommended to use high degree integer values to give a scope for 3rd party integrators.

  • exclusive_active_groups - a list of group names for which the current workflow should be active exclusively.

  • exclusive_record_groups - a list of group names for which the current workflow cannot be performed together with other workflows with one of specified groups. E.g., no concurrent transitions are possible among workflows in same exclusive_record_group.

  • entity_restrictions - Contains configuration for workflow restrictions.

  • defaults - node for default workflow configuration values that can be changed in UI later.

  • active - determines if the workflow should be active right after the first load of configuration.

  • applications - a list of web application names for which the workflow should be available (default: all applications match)

  • scopes - a list of scopes configurations used for filtering workflow by scopes

  • datagrids - a list of datagrid names on whose rows currently available transitions should be displayed as buttons.

  • disable_operations - an array of operation names (as keys) and related entities for which the operation should be disabled. See Operations for more details.

Example

 1 workflows:                                                    # Root elements
 2     b2b_flow_sales:                                           # A unique name of workflow
 3         defaults:
 4             active: true                                      # Active by default (when config is loaded)
 5         entity: Oro\Bundle\SalesBundle\Entity\Opportunity  # Workflow will be used for this entity
 6         datagrids:                                            # datagrid names on which rows available transitions from currently started workflow should be displayed
 7             - opportunity_grid
 8         entity_attribute: opportunity                         # Attribute name used to store root entity
 9         is_system: true                                       # Workflow is system, i.e. not editable and not deletable
10         start_step: qualify                                   # Name of start step
11         steps_display_ordered: true                           # Show all steps in step widget
12         priority: 100                                         # Priority level
13         exclusive_active_groups: [b2b_sales]                  # Only one active workflow from 'b2b_sales' group can be active
14         exclusive_record_groups:
15             - sales                                           # Only one workflow from group 'sales' can be started at time for the entity
16         applications: [webshop]                               # list of application names to make the workflow available for
17         scopes:
18             -                                                 # Definition of configuration for one scope
19                 scope_field: 42
20         disable_operations:
21             operation_for_simple_sale: ~                      # disables specified operation in system (can be empty array - [])
22             operation_create_sale: [OrderBundle\Entity\Order] # disables operation for OrderBundle\Entity\Order entity
23         attributes:                                           # configuration for Attributes
24                                                               # ...
25         steps:                                                # configuration for Steps
26                                                               # ...
27         transitions:                                          # configuration for Transitions
28                                                               # ...
29         transition_definitions:                               # configuration for Transition Definitions
30                                                               # ...
31         entity_restrictions:                                  # configuration for Restrictions
32                                                               # ...

Attributes Configuration

Workflow defines the configuration of attributes. When a Workflow Item is created, it can manipulate its own data (Workflow Data) that is mapped by Attributes. Each attribute must have a type and can have options. When a Workflow Item is saved, its data is serialized according to the configuration of attributes. Saving data that is not mapped by any attribute or mismatched with the attribute type is restricted.

A single attribute can be described with the following configuration:

  • unique name - Workflow attributes should have a unique name in scope of Workflow that they belong to. Step configuration references attributes by this value.

  • type - string - Type of an attribute. The following types are supported:

    • boolean

    • bool - alias for boolean

    • integer

    • int - alias for integer

    • float

    • string

    • array - elements of array should be scalars or objects that supports serialize/deserialize

    • object - object should support serialize/deserialize, option “class” is required for this type

    • entity - Doctrine entity, option “class” is required and it must be a Doctrine manageable class

  • label (translation file field) - translatable: oro.workflow.{workflow_name}.attribute.{attribute_name}.label . Label can be shown in the UI

  • entity_acl - Defines an ACL for the specific entity stored in this attribute.

    • update - boolean - Can entity be updated. Default value is true.

    • delete - boolean - Can entity be deleted. Default value is true.

  • property_path - string - Used to work with attribute value by reference and specifies the path to data storage. If the property path is specified, then all other attribute properties except name are optional - they can be automatically guessed based on last element (field) of the property path.

  • options - Options of an attribute. Currently, next options are supported

    • class - string - Fully qualified class name. Allowed only when type either entity or object.

    • multiple - boolean - Indicates whether several entities are supported. Allowed only when type is entity.

    • virtual - boolean - Such attribute will not be saved in the database and available only on current transition. Default value is false.

Note

Attribute configuration does not contain any information about how to render attribute on step forms, it’s responsibility of “Steps configuration”. This makes it possible to render one attribute in different ways on steps.

Browse class Oro\Bundle\WorkflowBundle\Model\AttributeAssembler for more details.

Example

 1 workflows:
 2     b2b_flow_sales:
 3         # ...
 4         new_account:
 5             type: entity
 6             entity_acl:
 7                 delete: false
 8             options:
 9                 class: Oro\Bundle\AccountBundle\Entity\Account
10         send_email:
11             type: checkbox
12             options:
13                 virtual: true
14         new_company_name:
15             type: string
16         opportunity:
17             property_path: sales_funnel.opportunity
18         opportunity_name:
19             property_path: sales_funnel.opportunity.name

Enable Users to Modify Attributes

You can enable a user to modify attributes of the record during transitions. To do this, list attributes that can be modified during any of the workflow’s transitions under the attributes key:

 1# src/Acme/DemoBundle/Resources/config/oro/workflows.yml
 2
 3workflows:
 4    phone_call:
 5        # ...
 6        attributes:
 7                phone_call:                             # The workflow attribute.
 8                type: entity
 9                options:
10                    class: Acme\Bundle\DemoWorkflowBundle\Entity\PhoneCall
11                call_timeout:                           # The workflow attribute.
12                type: integer
13                call_successful:                        # The workflow attribute.
14                type: boolean
15            conversation_successful:
16                type: boolean
17            conversation_comment:
18                type: string
19            conversation_result:
20                type: string
21            conversation:
22                type: entity
23                options:
24                    class: Acme\Bundle\DemoWorkflowBundle\Entity\PhoneConversation

Tip

By default, the attribute data is stored inside the WorkflowItem entity. Consequently, this data can only be accessed in the scope of the specific workflow for an entity.

To automatically store and retrieve attributes data by a property path (i.e. such attributes can be considered as links to an entity’s values), use the property_path option instead:

1workflows:
2    phone_call:
3        # ...
4        attributes:
5            timeout:
6                property_path: entity.call_timeout

The entity part of the property path refers to the underlying entity. You can change the name using the entity_attribute option.

Translations

For attributes, you need to add labels into two places: first, to the list of all attribute labels, second, to the list of labels for attributes of each transition that has them.

oro.workflow.{workflow_name}.attribute.{attribute_name}.label

A default label text for the attribute.

oro.workflow.{workflow_name}.transition.{transition_name}.attribute.{attribute_name}.label

A label text for attribute of the corresponding particular transition.

 
 1    # src/Acme/DemoBundle/Resources/translations/workflows.en.yml
 2
 3    oro:
 4        workflow:
 5        phone_call:
 6            attribute:
 7                    phone_call
 8                                label: 'Phone Call'
 9                call_timeout
10                            label: 'Call Timeout'
11                call_successful
12                    label: 'Call Successful'

 1    # src/Acme/DemoBundle/Resources/translations/workflows.en.yml
 2
 3    oro:
 4        workflow:
 5            phone_call:
 6                transition:
 7                    connected:
 8                        ...
 9                        attribute:
10                            opportunity:
11                                label: 'Call Successful'

Variables Configuration

A workflow can define configuration for variables. Despite their name and unlike attributes, variables are required to have values set when defining them. When a Workflow Item is created, it can manipulate its own data (Workflow Data) mapped by Variables. Each variable must have a type and a value. When Workflow Item is saved, its data is serialized according to the configuration of variables.

A single variable can be described with the following configuration:

  • unique name - Workflow variables should have unique name in scope of Workflow that they belong to. Transition definitions reference variables by this value.

  • type - string - Types of variables. The following types are supported:

    • boolean

    • bool - alias for boolean

    • integer

    • int - alias for integer

    • float

    • string

    • array - elements of array should be scalars or objects that supports serialize/deserialize

    • object - object should support serialize/deserialize, option “class” is required for this type

    • entity - Doctrine entity, option “class” is required and it must be a Doctrine manageable class

  • entity_acl - Defines an ACL for the specific entity stored in this attribute.

    • update - boolean - Can entity be updated. Default value is true.

    • delete - boolean - Can entity be deleted. Default value is true.

  • property_path - string - Used to work with variable value by reference and specifies path to data storage. If property path is specified, then all other attribute properties except name are optional - they can be automatically guessed based on last element (field) of property path.

  • label - translatable: oro.workflow.{workflow_name}.variable.{variable_name}.label. Label can be shown in the UI.

  • options - Options of a variable. Currently the following options are supported:

    • class - string - Fully qualified class name. Allowed only when type is object.

    • form_options - array - Options defined here are passed to the WorkflowVariablesType form type. Browse class Oro\Bundle\WorkflowBundle\Form\Type\WorkflowVariablesType for more details. Constraints may be set to workflow configuration form with the constraints option. All Symfony form constrains are supported.

    • multiple - boolean - Indicates whether several entities are supported. Allowed only when type is entity.

    • identifier - string - Applies to entities only. Class identifier specifies the identity field which will be used to query for the desired entity, in case a default entity needs to be loaded upon workflow assembling. Not specifying it will read the identifier field names from the entity’s metadata. Please note that it is not necessary to use a primary key, any unique key is supporter, as long as it is not a composite key.

Important

Unlike attributes, variable configuration does contain information about how to render variables in the configuration form, with the form_options node under options. Browse class Oro\Bundle\WorkflowBundle\Model\VariableAssembler for more details.

Example

Defining a variable:

 1 workflows:
 2     my_workflow:
 3         variable_definitions:
 4             variables:
 5                admin_user:
 6                     type: 'entity'
 7                     value: 1 # id of the user to be loaded upon variable assembling
 8                     options:
 9                         class: Oro\Bundle\UserBundle\Entity\User
10                         identifier: id
11                         form_options:
12                             tooltip: true
13                             constraints:
14                                 NotBlank: ~

Using a variable:

1 ...
2     preconditions:
3         '@and':
4             ...
5             - '@not':
6                 - '@some_condition': [$entity, $.data.admin_user]

Steps Configuration

Steps are like nodes in the graph of Workflow Transitions. Step must have a unique name and can optionally contain form options, allowed transitions and other options. If Workflow has type wizard user will be able to see in what step Workflow instance is at the moment, possible transitions and form of current step (if it is configured via form options). Step can be connected with attributes via form options. On different step it is possible to attach any attribute with any form options.

Summarizing all above, a step has the following configuration:

  • name - string - A step must have unique name in scope of Workflow

  • label (translation file field) - Translatable: oro.workflow.{workflow_name}.step.{step_name}.label . The label of step, can be shown in UI if Workflow has type wizard

  • order - integer - This value is used in wizard page to sort steps in UI.

  • is_final - boolean - If true, then step will be counted as the workflow final step.

  • entity_acl - Defines an ACL for an entity related to the specified attribute when workflow is in this step.

    • update - boolean - Allows entity be updated. Default value is true.

    • delete - boolean - Allows entity be deleted. Default value is true.

  • allowed_transitions - A optional list of allowed transitions. If no transitions are allowed, it is the same as is_final option set to true.

Example

 1 workflows:
 2     phone_call:
 3         # ...
 4         steps:
 5             start_call:
 6                 allowed_transitions: # list of allowed transitions from this step
 7                     - connected
 8                     - not_answered
 9                 entity_acl:
10                     owner:
11                         update: false
12                         delete: false
13             start_conversation:
14                 allowed_transitions:
15                     - end_conversation
16             end_call:
17                 is_final: true

Transitions Configuration

Transitions change the current step of the Workflow Item when it is performed. It also uses Transition Definition to check if it is allowed and to perform Post Actions.

Transition configuration has the following options:

  • unique name - string - A transition must have unique name in scope of Workflow. Step configuration references transitions by this value.

  • label (translation file field) - Translatable: oro.workflow.{workflow_name}.transition.{transition_name}.label. Label of transition, will be shown in UI.

  • button_label (translation file field) - Translatable: oro.workflow.{workflow_name}.transition.{transition_name}.button_label. Used to define the text of a transition button. A label will be used if not defined.

  • button_title (translation file field) - Translatable: oro.workflow.{workflow_name}.transition.{transition_name}.button_title. Used to define the text of button hint (button hover). A button_label will be used if not defined.

  • step_to - string - Next step name. This is a reference to step that will be set to Workflow Item after transition is performed.

  • transition_definition - A reference to Transition Definition configuration.

  • is_start - boolean - If true, then this transition can be used to start a new workflow. At least one start transition is required if workflow does not have start_step attribute.

  • is_hidden - boolean - Indicates that this transition must be hidden at frontend.

  • is_unavailable_hidden - boolean - Indicates that this transition must be hidden at frontend when the transition is not allowed.

  • acl_resource - string - ACL resource name that will be checked while checking that transition execution is allowed.

  • acl_message - string - Message that will be sown in case acl_resource is not granted.

  • message (translation file field) - Translatable: oro.workflow.{workflow_name}.transition.{transition_name}.warning_message. Notification message that will be shown at frontend before transition execution. This field can be filled only in the translation file.

  • message_parameters - array - List of parameters for translating value from option message.

  • init_routes - array - List of routes where the transition button will be displayed. It is required to start workflow from entities that are not directly related to that workflow.

  • init_entities - array - List of entities where the transition button will be displayed . It is required to start workflow from entities that are not directly related to that workflow.

  • init_datagrids - array - List of datagrid names for whose rows transition button should be displayed. It is required to start workflow from entities that are not directly related to that workflow.

  • init_context_attribute - string - Name of the attribute which contains init context: routeName, entityId, entityClass, referrer, group. Default value - init_context

  • display_type - string - Frontend transition form display type. Possible options are: dialog, page. Display type “page” require “form_options” to be set.

  • destination_page - string - (optional) Parameter used only when display_type equals page. Specified value will be converted to url by entity configuration (see action @resolve_destination_page). In case when @redirect action used in actions of transition definition, effect from that option will be ignored. Allowed values: name or index (index will be converted to name) , view or ~. Default value ~.

  • page_template - string - Custom transition template for transition pages. Should be extended from OroWorkflowBundle:Workflow:transitionForm.html.twig.

  • dialog_template - string - Custom transition template for transition dialogs. Should be extended from OroWorkflowBundle:Widget:widget/transitionForm.html.twig.

  • frontend_options - Can have such frontend options as class (a CSS class applied to transition button), icon (CSS class of icon of transition button).

  • form_options - These options will be passed to form type of transition, they can contain options for form types of attributes that will be shown when user clicks transition button. See more at Transition Forms.

  • transition_definition - string - Name of associated transition definition.

  • triggers - Contains configuration for Workflow Transition Triggers.

To configure transitions, define the following:

  • Which transitions are available (place transition name keys under the transitions key).

  • To which steps they bring an entity record (the step_to key under the transition name key).

  • Which conditions must be satisfied for the transition to be available and what actions must be taken before and after the transition.

  • Which automatic triggers apply if any.

Example

 1 workflows:
 2     phone_call:
 3         # ...
 4         transitions:
 5             start_process:
 6                 is_start: true                              # Start new workflow
 7                 step_to: start_conversation                 # The name of next step that will be set to Workflow Item
 8                 init_context_attribute: my_init_context     # Name of attribute which contains init context
 9                 init_entities:                              # List of entities where will be displayed transition button "start_process"
10                     - 'Oro\Bundle\TaskBundle\Entity\Task'
11                 init_routes:                                # List of routes where will be displayed transition button "start_process"
12                     - 'oro_task_view'
13                 transition_definition: start
14             connected:                                      # Unique name of transition
15                 step_to: start_conversation                 # The name of next step that will be set to Workflow Item
16                                                             # when transition will be performed
17
18                 transition_definition: connected_definition # A reference to Transition Definition configuration
19                 frontend_options:
20                     icon: 'fa-check'                         # add icon to transition button with class "fa-check"
21                     class: 'btn-primary'                    # add css class "btn-primary" to transition button
22                 form_options:
23                     attribute_fields:                       # fields of form that will be shown when transition button is clicked
24                         call_timeout:
25                             form_type: Symfony\Component\Form\Extension\Core\Type\IntegerType
26                             options:
27                                 required: false
28                 display_type: page
29                 destination_page: index
30             not_answered:
31                 step_to: end_call
32                 transition_definition: not_answered_definition
33             end_conversation:
34                 step_to: end_call
35                 transition_definition: end_conversation_definition
36                 triggers:
37                     -
38                         cron: '* * * * *'
39                         filter: "e.someStatus = 'OPEN'"

Note

Attribute label option for attribute_fields in form_options of transition are deprecated now. It was moved to workflows.{lang_code}.yml file as translatable field and has following key to define its text value: oro.workflow.{workflow_name}.transition.{transition_name}.attribute.{attribute_name}.label

Translations

Define how the workflow transition name will appear on the user interface and the warning message:

Field

Description

oro.workflow.{workflow_name}.transition.{transition_name}.label

The transition name.

oro.workflow.{workflow_name}.transition.{transition_name}.warning_message

A notification message text shown before the transition is executed.

 
 1    # src/Acme/DemoBundle/Resources/translations/workflows.en.yml
 2
 3    oro:
 4        workflow:
 5            phone_call:
 6                transition:
 7                    connected:
 8                                label: 'Connected'
 9                            warning_message: 'Connection performed!'
10                not_answered
11                            label: 'Not Answered'
12                end_conversation
13                            label: 'End Conversation'

Transition Definition Configuration

Transition Definition is used by Transition to check Pre Conditions and Conditions, to perform Init Action and Post Actions.

Transition definition configuration has the following options.

  • preactions - Configuration of Pre Actions that must be performed before Pre Conditions check.

  • preconditions - Configuration of Pre Conditions that must satisfy to allow displaying transition.

  • conditions - Configuration of Conditions that must satisfy to allow transition.

  • actions - Configuration of Post Actions that must be performed after transit to next step will be performed.

Example

 1 workflows:
 2     phone_call:
 3         # ...
 4         transition_definitions:
 5             connected_definition: # Try to make call connected
 6                 # Set timeout value
 7                 preactions:
 8                     - @assign_value: [$call_timeout, 120]
 9                     - @increment_value: [$call_attempt]
10                 # Check that timeout is set
11                 conditions:
12                     @not_blank: [$call_timeout]
13                 # Set call_successfull = true
14                 actions:
15                     - @assign_value: [$call_successfull, true]
16             not_answered_definition: # Callee did not answer
17                 # Set timeout value
18                 preactions:
19                     - @assign_value: [$call_timeout, 30]
20                 # Make sure that caller waited at least 60 seconds
21                 conditions: # call_timeout not empty and >= 60
22                     @and:
23                         - @not_blank: [$call_timeout]
24                         - @ge: [$call_timeout, 60]
25                 # Set call_successfull = false
26                 actions:
27                     - @assign_value: [$call_successfull, false]
28             end_conversation_definition:
29                 conditions:
30                     # Check required properties are set
31                     @and:
32                         - @not_blank: [$conversation_result]
33                         - @not_blank: [$conversation_comment]
34                         - @not_blank: [$conversation_successful]
35                 # Create PhoneConversation and set it's properties
36                 # Pass data from workflow to conversation
37                 actions:
38                     - @create_entity: # create PhoneConversation
39                         class: Acme\Bundle\DemoWorkflowBundle\Entity\PhoneConversation
40                         attribute: $conversation
41                         data:
42                             result: $conversation_result
43                             comment: $conversation_comment
44                             successful: $conversation_successful
45                             call: $phone_call

Transition Triggers Configuration

Transition Triggers are used to perform Transition by Event or by cron-definition. Please note that transition can be performed by trigger even if Workflow not started for the entity yet. There are two types of triggers:

Event Trigger

Event trigger configuration has the next options.

  • entity_class - Class of entity that can trigger transition.

  • event - Type of the event, can have the following values: create, update, delete.

  • field - Only for update event - field name that should be updated to handle trigger.

  • queued - [boolean, default = true] Handle trigger in queue (if true), or in realtime (if false)

  • require - String of Symfony Language Expression that should much to handle the trigger. Following aliases in context are available:

    • entity - Entity object that dispatches an event

    • prevEntity - entity copy with fields state before update (like the ‘old’ in lifecycle changeset)

    • mainEntity - Entity object of the workflow

    • wd - Workflow Definition object

    • wi - Workflow Item object

  • relation - Property path to mainEntity relative to entity if they are different.

Example

 1 workflows:
 2     phone_call:
 3         # ...
 4         transitions:
 5             connected:
 6                 ...
 7                 triggers:
 8                     -
 9                         entity_class: Oro\Bundle\SaleBundle\Entity\Quote    # entity class
10                         event: update                                       # event type
11                         field: status                                       # updated field
12                         queued: false                                       # handle trigger not in queue
13                         relation: call                                      # relation to Workflow entity
14                         require: "entity.status = 'pending'"                # expression language condition

Cron Trigger

Cron trigger configuration has the following options.

  • cron - Cron definition.

  • queue - [boolean, default = true] Handle trigger in queue (if true), or in realtime (if false)

  • filter - String of Symfony Language Expression that should much to handle the trigger. Following aliases are available:

    • e - Entity

    • wd - Workflow Definition

    • wi - Workflow Item

    • ws - Current Workflow Step

Example

 1 workflows:
 2     phone_call:
 3         # ...
 4         transitions:
 5             connected:
 6                 ...
 7                 triggers:
 8                     -
 9                         cron: '* * * * *'                                   # cron definition
10                         filter: "e.someStatus = 'OPEN'"                     # dql-filter

Conditions Configuration

Conditions configuration is a part of Transition Definition Configuration. It declares a tree structure of conditions that are applied on the Workflow Item to check if the Transition could be performed. Single condition configuration contains alias - a unique name of condition and options.

Optionally each condition can have a constraint message. All messages of not passed conditions will be shown to user when transition could not be performed.

There are two types of conditions - preconditions and actual transit conditions. Preconditions are used to check whether the transition should be allowed to start, and actual conditions are used to check whether the transition can be done. A good example of usage is transition forms: preconditions are restrictions to show a button that opens the transition form the dialog, and actual transitions are used to validate the form content after submitting.

Alias of condition starts from the “@” symbol and must refer to a registered condition. For example, “@or” refers to the logical OR condition.

Options can refer to values of Workflow Data using the $ prefix. For example, $call_timeout refers to value of the call_timeout attribute of Workflow Item that is processed in condition.

Also it is possible to refer to any property of Workflow Item using “$.” prefix. For example, to refer to the date/time when the Workflow Item was created, string $.created can be used.

Example

 1 workflows:
 2     phone_call:
 3         # ...
 4         transition_definitions:
 5             # some transition definition
 6             qualify_call:
 7                 preconditions:
 8                     @equal: [$status, "in_progress"]
 9                 conditions:
10                     # empty($call_timeout) || (($call_timeout >= 60 && $call_timeout < 100) || ($call_timeout > 0 && $call_timeout <= 30))
11                     @or:
12                         - @blank: [$call_timeout]
13                         - @or:
14                             - @and:
15                                 message: Call timeout must be between 60 and 100
16                                 parameters:
17                                     - @greater_or_equal: [$call_timeout, 60]
18                                     - @less: [$call_timeout, 100]
19                             - @and:
20                                 message: Call timeout must be between 0 and 30
21                                 parameters:
22                                     - @less_or_equal: [$call_timeout, 30]
23                                     - @greater: [$call_timeout, 0]

Pre, Post and Init Actions

Pre Action, Post Actions, and Init Action configuration complements Transition Definition configuration. Pre Actions are performed BEFORE the Pre Conditions are qualified.

Post Actions are performed during transition AFTER conditions are qualified, and the current Step of Workflow Item is changed to the corresponding one (step_to option) in the Transition.

Init Actions can be performed before the transition. One of the possible init actions usage scenario is to fill Workflow Item with default values, which will be used by Transition form if it exists.

Action configuration consists of alias of Action (which is a unique name of Action) and options (if such are required).

Similarly to Conditions, alias of Action starts from “@” symbol and must refer to registered Action. For example, “@create_entity” refers to the Action that creates entity.

Example

 1 workflows:
 2     phone_call:
 3         # ...
 4         transition_definitions:
 5             # some transition definition
 6                 preactions:
 7                     - @assign_value: [$call_attempt, 1]
 8                 actions:
 9                     - @create_entity: # create an entity PhoneConversation
10                         class: Acme\Bundle\DemoWorkflowBundle\Entity\PhoneConversation
11                         attribute: $conversation
12                         data: # Fill values of freshly created PhoneConversation with data from current WorkflowItem
13                             result: $conversation_result
14                             comment: $conversation_comment
15                             successful: $conversation_successful
16                             call: $phone_call

Entity Restrictions Configuration

Entity Restrictions add validation rules for configured attributes fields. They do not permit to edit these fields on the attributes’ edit or create form, on the attributes’ grids via inline editing, via API or performing an import.

Single entity restriction can be described with the following configuration:

  • unique name - string - A restriction must have unique name in scope of Workflow.

  • attribute - string - This is reference to workflow attribute (attribute must be of type ‘entity’).

  • field - string - Field name of attribute class for which restriction will be applied.

  • mode - enum - Restriction mode. Allowed values for this option are ‘full’, ‘disallow’, ‘allow’. Default value is ‘full’

    • ‘full’ mode means that field will be completely disabled for editing. This is default value for this option.

    • ‘disallow’ mode does not permit to fill field with values listed in ‘values’ option.

    • ‘allow’ mode does not permit to fill field with values except listed in ‘values’ option.

  • values - array - Optional list of field values which will be used for restriction with ‘allow’ and ‘disallow’ modes.

  • step - string - This is reference to workflow step. Restriction will be applied only when workflow is in this step. If no step is provided, restriction will be applied for attribute creation.

Example

 1 workflows:
 2     opportunity_flow:
 3         # ...
 4         entity_restrictions:
 5             opportunity_status_creation:           # unique restriction name in scope of this Workflow
 6                 attribute: opportunity             # attribute's reference links to attribute(attribute must be of type 'entity')
 7                 field: status                      # field name of attribute class
 8                 mode: disallow                     # restriction mode (default is 'full')
 9                 values:                            # disallowed values for this field
10                     - 'won'
11                     - 'lost'
12             opportunity_close_reason_creation:
13                 attribute: opportunity
14                 field: closeReason
15             opportunity_status_open:
16                 attribute: opportunity
17                 field: status
18                 step: open                        # restriction will be applied only When workflow is in this step.
19                 mode: disallow
20                 values:
21                     - 'won'
22                     - 'lost'
23             opportunity_close_reason_open:
24                 attribute: opportunity
25                 field: closeReason
26                 step: open