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/Bundle/DemoBundle/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.

Workflow Imports 

There are 3 types of imports available:

  • resource file import

  • workflow import

  • workflow import with resource option

Resource File Import 

Resource file import is the simplest import of configuration from the specified resource into the current file. The imported configuration is recursively merged into the existing one. If the imported configuration contains scalar elements with keys that are present in the existing configuration, then they will be overridden by new values. If the imported configuration contains numeric array sections that are present in the existing configuration, then their elements will be appended after the existing one.

Example - workflows.yml

imports:
    - { resource: 'workflows/b2b_flow_lead.yml' }

Example - workflows/b2b_flow_lead.yml

imports:
    - { resource: 'imports/steps_transitions.yml' }
    - { resource: 'imports/transition_definitions.yml' }
    - { resource: 'imports/extra_transition_definitions.yml' }

workflows:
    b2b_flow_lead:
        entity: Oro\Bundle\SalesBundle\Entity\Lead

Example - imports/steps_transitions.yml

workflows:
    b2b_flow_lead:
        steps:
            new:
                allowed_transitions: ['qualify']
            qualified: ~
        transitions:
            qualify: ~

Example - imports/transition_definitions.yml

workflows:
    b2b_flow_lead:
        transition_definitions:
            qualify_definition:
                actions:
                    - '@flash_message': { message: 'Created' }

Example - imports/extra_transition_definitions.yml

workflows:
    b2b_flow_lead:
        transition_definitions:
            qualify_definition:
                actions:
                    - '@flash_message': { message: 'Qualified' }

Example - resulting workflow configuration

workflows:
    b2b_flow_lead:
        entity: Oro\Bundle\SalesBundle\Entity\Lead
        steps:
            new:
                allowed_transitions: ['qualify']
            qualified: ~
        transitions:
            qualify: ~
        transition_definitions:
            qualify_definition:
                actions:
                    - '@flash_message': { message: 'Created' }
                    - '@flash_message': { message: 'Qualified' }

Workflow Import 

When you need to reuse an existing workflow configuration or its parts, use the workflow import directive. Each imported configuration is recursively merged onto the previous one. If the imported configuration contains numeric array sections that are already present, then their elements will be appended. Once all imports are processed, the existing configuration is merged onto the resulting imported configuration, so scalar values in the existing configuration replace values with corresponding keys in the imported configuration, and the numeric arrays’ elements in the existing configuration are appended after the corresponding numeric arrays elements in the imported configuration.

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

Example - workflows.yml

imports:
    - { workflow: b2b_flow_lead, as: b2b_flow_lead_alternative, replace: ['transition_definitions.qualify_definition'] }

workflows:
    b2b_flow_lead_alternative:
        entity: Oro\Bundle\SalesBundle\Entity\AlternativeLead
        steps:
            new:
                allowed_transitions: ['cancel']
            cancelled: ~
        transitions:
            cancel: ~
        transition_definitions:
            qualify_definition:
                actions:
                    - '@flash_message': { message: 'Qualified' }
            cancel_definition:
                actions:
                    - '@flash_message': { message: 'Cancelled' }

Example - resulting workflow configuration

workflows:
    b2b_flow_lead_alternative:
        entity: Oro\Bundle\SalesBundle\Entity\AlternativeLead
        steps:
            new:
                allowed_transitions: ['qualify', 'cancel'] # 'cancel' is appended
            qualified: ~
            cancelled: ~ # step is added
        transitions:
            qualify: ~
            cancel: ~ # transition is added
        transition_definitions:
            qualify_definition: # definition is replaced with the new one
                actions:
                    - '@flash_message': { message: 'Qualified' }
            cancel_definition: # definition is added
                actions:
                    - '@flash_message': { message: 'Cancelled' }

The example above shows the import of a different workflow configuration (b2b_flow_lead) into the current one (b2b_flow_lead_alternative). As a result, you have the configuration from the b2b_flow_lead workflow, but named b2b_flow_lead_alternative and with an additional step, transition, and transition definition for the cancellation flow. At the same time, qualify_definition is completely replaced.

The b2b_flow_lead workflow configuration is found across all registered workflows and imported as is (raw configuration without normalization) under node workflows.b2b_flow_lead_alternative in the current configuration file. Then, it replaces all nodes defined in the replace option to clean all unnecessary segments. After that, b2b_flow_lead_alternative 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

    imports:
        - { resource: 'imports/steps_transitions.yml', workflow: b2b_flow_lead, as: b2b_flow_lead_alternative, replace: [] }
        - { resource: 'imports/transition_definitions.yml', workflow: b2b_flow_lead, as: b2b_flow_lead_alternative, replace: [] }
    
    workflows:
        b2b_flow_lead_alternative:
            entity: Oro\Bundle\SalesBundle\Entity\AlternativeLead
            steps:
                new:
                    allowed_transitions: ['cancel']
                cancelled: ~
            transitions:
                cancel: ~
            transition_definitions:
                cancel_definition:
                    actions:
                        - '@flash_message': { message: 'Cancelled' }
    

    If you need to reuse part of the workflow with split config by files and do not want to replace all other unnecessary nodes via the replace option. Suppose you are interested in basic steps and transitions only from a different workflow config, and those configs are placed under the ‘imports/steps_transitions.yml’ file. You can load them directly using the resource option and the workflow import options (workflow, as). You will have all steps from the b2b_flow_lead workflow loaded under your b2b_flow_lead_alternative configuration without any additions. As a result, you have the basic parts of the b2b_flow_lead workflow configuration, but named b2b_flow_lead_alternative and with an additional step, transition, and transition definition for the cancellation flow, while qualify_definition is reused as is.

    Example - resulting workflow configuration

    workflows:
        b2b_flow_lead_alternative:
            entity: Oro\Bundle\SalesBundle\Entity\AlternativeLead
            steps:
                new:
                    allowed_transitions: ['qualify', 'cancel'] # 'cancel' is appended
                qualified: ~
                cancelled: ~ # step is added
            transitions:
                qualify: ~
                cancel: ~ # transition is added
            transition_definitions:
                qualify_definition: # definition is reused
                    actions:
                        - '@flash_message': { message: 'Qualified' }
                cancel_definition: # definition is added
                    actions:
                        - '@flash_message': { message: 'Cancelled' }
    
  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:

    imports:
        - { resource: 'workflows/b2b_flow_lead.yml', workflow: b2b_flow_lead, as: b2b_flow_lead_alternative, replace: [] }
        - { resource: 'workflows/b2b_flow_lead.yml', workflow: b2b_flow_lead, as: b2b_flow_lead_priority, replace: [] }
    
    workflows:
        b2b_flow_lead_alternative:
            entity: Oro\Bundle\SalesBundle\Entity\AlternativeLead
    
        b2b_flow_lead_priority:
            entity: Oro\Bundle\SalesBundle\Entity\PriorityLead
    

    When importing the file with a workflow that serves as the basis for others (‘workflows/b2b_flow_lead.yml’), you can override its nodes for a particular case (different entity but shared remaining configuration).

Imports With Conditions 

The import_condition option enables you to import resources or workflows when certain conditions are met. If this option is available, the expression is checked early in the import process. If the conditions are not met, the import is ignored.

import_condition uses Expression Language syntax like the Symfony DI component. It also has the parameter_or_null function, which works like parameter but returns null if the parameter does not exist.

imports:
    - { resource: 'workflows/external_entity_flow.yml', import_condition: 'parameter_or_null("acme_demo.enable_external_entity_support") === true' }

Configuration Loading 

To load workflow definitions to the database, execute the following command:

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 an exception and data will not be saved. If you want to reuse an existing configuration, use the import workflow feature.

Translations File 

Together with workflow configurations, for almost every section specified below, translation text should be defined under the corresponding key to display the 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 describes the 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 a system one. 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 (optional) - Contains YAML 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 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 the specified groups. E.g., no concurrent transitions are possible among workflows in the 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.

  • metadata - array - additional metadata associated with the workflow.

  • 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

workflows:                                                    # Root elements
    b2b_flow_sales:                                           # A unique name of workflow
        defaults:
            active: true                                      # Active by default (when config is loaded)
        entity: Oro\Bundle\SalesBundle\Entity\Opportunity  # Workflow will be used for this entity
        datagrids:                                            # datagrid names on which rows available transitions from currently started workflow should be displayed
            - opportunity_grid
        entity_attribute: opportunity                         # Attribute name used to store root entity
        is_system: true                                       # Workflow is system, i.e. not editable and not deletable
        start_step: qualify                                   # Name of start step
        steps_display_ordered: true                           # Show all steps in step widget
        priority: 100                                         # Priority level
        exclusive_active_groups: [b2b_sales]                  # Only one active workflow from 'b2b_sales' group can be active
        exclusive_record_groups:
            - sales                                           # Only one workflow from group 'sales' can be started at time for the entity
        applications: [webshop]                               # list of application names to make the workflow available for
        scopes:
            -                                                 # Definition of configuration for one scope
                scope_field: 42
        disable_operations:
            operation_for_simple_sale: ~                      # disables specified operation in system (can be empty array - [])
            operation_create_sale: [OrderBundle\Entity\Order] # disables operation for OrderBundle\Entity\Order entity
        attributes:                                           # configuration for Attributes
                                                              # ...
        steps:                                                # configuration for Steps
                                                              # ...
        transitions:                                          # configuration for Transitions
                                                              # ...
        transition_definitions:                               # configuration for Transition Definitions
                                                              # ...
        entity_restrictions:                                  # configuration for Restrictions
                                                              # ...

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 the scope of the 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 an array should be scalars or objects that support 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

  • default - Default value of an attribute. This value should correspond to the attribute type.

  • label (translation file field) - translatable: oro.workflow.{workflow_name}.attribute.{attribute_name}.label . The 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. The default value is true.

    • delete - boolean - Can entity be deleted. The 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 the name are optional - they can be automatically guessed based on the last element (field) of the property path.

  • options - Options of an attribute. Currently, the following 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 the current transition. The default value is false.

Note

Attribute configuration does not contain any information about how to render attributes on step forms, it is the 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

workflows:
    b2b_flow_sales:
        # ...
        new_account:
            type: entity
            entity_acl:
                delete: false
            options:
                class: Oro\Bundle\AccountBundle\Entity\Account
        send_email:
            type: boolean
            options:
                virtual: true
        new_company_name:
            type: string
        opportunity:
            property_path: entity.opportunity
        opportunity_name:
            property_path: entity.opportunity.name

Enable Users to Modify Attributes 

You can enable a user to modify the 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:

src/Acme/Bundle/DemoBundle/Resources/config/oro/workflows.yml 
 workflows:
     phone_call:
         # ...
         attributes:
             phone_call:                             # The workflow attribute.
                 type: entity
                 options:
                     class: Acme\Bundle\DemoBundle\Entity\PhoneCall
             call_timeout:                           # The workflow attribute.
                 type: integer
             call_successful:                        # The workflow attribute.
                 type: boolean
             conversation_successful:
                 type: boolean
             conversation_comment:
                 type: string
             conversation_result:
                 type: string
             conversation:
                 type: entity
                 options:
                     class: Acme\Bundle\DemoBundle\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:

workflows:
    phone_call:
        # ...
        attributes:
            timeout:
                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 in 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.

src/Acme/Bundle/DemoBundle/Resources/translations/workflows.en.yml 
    oro:
        workflow:
        phone_call:
            attribute:
                    phone_call
                                label: 'Phone Call'
                call_timeout
                            label: 'Call Timeout'
                call_successful
                    label: 'Call Successful'
src/Acme/Bundle/DemoBundle/Resources/translations/workflows.en.yml 
oro:
    workflow:
        phone_call:
            transition:
                connected:
                    # ...
                    attribute:
                        opportunity:
                            label: 'Call Successful'

Variables Configuration 

A workflow can define the 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 the 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 a unique name in the scope of the 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 an array should be scalars or objects that support 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. The default value is true.

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

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

  • label - translatable: oro.workflow.{workflow_name}.variable.{variable_name}.label. The 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 constraints 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 a 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:

workflows:
    my_workflow:
        variable_definitions:
            variables:
               admin_user:
                    type: 'entity'
                    value: 1 # id of the user to be loaded upon variable assembling
                    options:
                        class: Oro\Bundle\UserBundle\Entity\User
                        identifier: id
                        form_options:
                            tooltip: true
                            constraints:
                                NotBlank: ~

Using a variable:

# ...
    preconditions:
        '@and':
            ...
            - '@not':
                - '@some_condition': [$entity, $.data.admin_user]

Steps Configuration 

Steps are like nodes in the graph of Workflow Transitions. The step must have a unique name and can optionally contain form options, allowed transitions, and other options. If Workflow has a type wizard user will be able to see in what step the Workflow instance is at the moment, possible transitions, and the form of the current step (if it is configured via form options). The 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 the above, a step has the following configuration:

  • name - string - A step must have a unique name in the scope of the 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 the wizard page to sort steps in UI.

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

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

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

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

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

Example

workflows:
    phone_call:
        # ...
        steps:
            start_call:
                allowed_transitions: # list of allowed transitions from this step
                    - connected
                    - not_answered
                entity_acl:
                    owner:
                        update: false
                        delete: false
            start_conversation:
                allowed_transitions:
                    - end_conversation
            end_call:
                is_final: true

Transitions Configuration 

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

The Transition Service allows you to define all transition logic in a PHP class, which is preferable for complex logic. Transition Service should be used for complex logic and YAML for simpler configurations, allowing a balance between flexibility and accessibility.

Transition configuration has the following options:

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

  • label (translation file field) - Translatable: oro.workflow.{workflow_name}.transition.{transition_name}.label. The label of transition will be shown in the 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 the step that will be set to Workflow Item after the transition is performed.

  • conditional_steps_to (optional) - array - A list of step names (key) and reachability conditions (value). This configuration can be used to define additional target condition-based steps for the transition.

  • transition_definition (optional) - A reference to Transition Definition configuration. Either transition_definition or transition_service should be used.

  • transition_service (optional) - string - An id of the DIC service that is used to handle transition logic.

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

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

  • is_unavailable_hidden - boolean - Indicates that this transition must be hidden in the 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 a workflow from entities not directly related to that workflow.

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

  • init_datagrids - array - List of datagrid names for whose rows the transition button should be displayed. It is required to start a workflow from entities 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 and page. Display type “page” requires “form_options” to be set.

  • destination_page - string - (optional) Parameter used only when display_type equals page. The specified value will be converted to url by entity configuration (see action @resolve_destination_page). In case the @redirect action is used in the actions of the transition definition, the 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 @OroWorkflow/Workflow/transitionForm.html.twig.

  • dialog_template - string - Custom transition template for transition dialogs. Should be extended from @OroWorkflow/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 the form type of transition, they can contain options for form types of attributes that will be shown when the user clicks the 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

workflows:
    phone_call:
        # ...
        transitions:
            start_process:
                is_start: true                              # Start new workflow
                step_to: start_conversation                 # The name of next step that will be set to Workflow Item
                init_context_attribute: my_init_context     # Name of attribute which contains init context
                init_entities:                              # List of entities where will be displayed transition button "start_process"
                    - 'Oro\Bundle\TaskBundle\Entity\Task'
                init_routes:                                # List of routes where will be displayed transition button "start_process"
                    - 'oro_task_view'
                transition_definition: start
            connected:                                      # Unique name of transition
                step_to: start_conversation                 # The name of next step that will be set to Workflow Item
                                                            # when transition will be performed

                transition_service: acme.phone_call.workflow.transition.connected # An ID of the transition service
                frontend_options:
                    icon: 'fa-check'                         # add icon to transition button with class "fa-check"
                    class: 'btn-primary'                    # add css class "btn-primary" to transition button
                form_options:
                    attribute_fields:                       # fields of form that will be shown when transition button is clicked
                        call_timeout:
                            form_type: Symfony\Component\Form\Extension\Core\Type\IntegerType
                            options:
                                required: false
                display_type: page
                destination_page: index
            not_answered:
                step_to: end_call
                conditional_steps_to:
                    ask_details:                            # If there are open questions transit workflow to start_call step. Otherwise transit to default step_to (end_call step)
                        conditions:
                            '@not_empty': $unresolved_questions
                transition_definition: not_answered_definition # A reference to Transition Definition configuration
            end_conversation:
                step_to: end_call
                transition_definition: end_conversation_definition
                triggers:
                    -
                        cron: '* * * * *'
                        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.

src/Acme/Bundle/DemoBundle/Resources/translations/workflows.en.yml 
oro:
    workflow:
        phone_call:
            transition:
                connected:
                            label: 'Connected'
                        warning_message: 'Connection performed!'
            not_answered
                        label: 'Not Answered'
            end_conversation
                        label: 'End Conversation'

Transition Definition Configuration 

Transition logic may be implemented either by a Transition Service or defined as Transition Definition Configuration. Transition Definition is used by transition to check conditions and perform actions.

The 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 be satisfied to allow displaying the transition button.

  • conditions - Configuration of Conditions that must be satisfied to allow performing an action.

  • actions - Configuration of Actions that are performed after conditions are successfully qualified.

Example

workflows:
    phone_call:
        # ...
        transition_definitions:
            connected_definition: # Try to make call connected
                  # Set timeout value
                  preactions:
                    - '@assign_value': [$call_timeout, 120]
                    - '@increment_value': [$call_attempt]
                  # Check that timeout is set
                conditions:
                    @not_blank: [$call_timeout]
                # Set call_successfull = true
                actions:
                    - '@assign_value': [$call_successfull, true]
            not_answered_definition: # Callee did not answer
                # Set timeout value
                preactions:
                    - '@assign_value': [$call_timeout, 30]
                # Make sure that caller waited at least 60 seconds
                conditions: # call_timeout not empty and >= 60
                    @and:
                        - '@not_blank': [$call_timeout]
                        - '@ge': [$call_timeout, 60]
                # Set call_successfull = false
                actions:
                    - '@assign_value': [$call_successfull, false]
            end_conversation_definition:
                conditions:
                    # Check required properties are set
                    @and:
                        - '@not_blank': [$conversation_result]
                        - '@not_blank': [$conversation_comment]
                        - '@not_blank': [$conversation_successful]
                # Create PhoneConversation and set it's properties
                # Pass data from workflow to conversation
                actions:
                    - '@create_entity': # create PhoneConversation
                        class: Acme\Bundle\DemoBundle\Entity\PhoneConversation
                        attribute: $conversation
                        data:
                            result: $conversation_result
                            comment: $conversation_comment
                            successful: $conversation_successful
                            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 the transition.

  • event - The 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 the queue (if true), or in real time (if false)

  • require - String of Symfony Language Expression that should much to handle the trigger. The 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

workflows:
    phone_call:
        # ...
        transitions:
            connected:
                ...
                triggers:
                    -
                        entity_class: Oro\Bundle\SaleBundle\Entity\Quote    # entity class
                        event: update                                       # event type
                        field: status                                       # updated field
                        queued: false                                       # handle trigger not in queue
                        relation: call                                      # relation to Workflow entity
                        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 the queue (if true), or in real time (if false)

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

    • e - Entity

    • wd - Workflow Definition

    • wi - Workflow Item

    • ws - Current Workflow Step

Example

workflows:
    phone_call:
        # ...
        transitions:
            connected:
                ...
                triggers:
                    -
                        cron: '* * * * *'                                   # cron definition
                        filter: "e.someStatus = 'OPEN'"                     # dql-filter

Conditions Configuration 

Conditions configuration is part of Transition Definition Configuration. It declares a tree structure of conditions that are applied to the Workflow Item to check if the Transition can be performed. Single condition configuration contains an 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 the 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 submission.

Alias of the 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.

It is also 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

workflows:
    phone_call:
        # ...
        transition_definitions:
            # some transition definition
            qualify_call:
                preconditions:
                    @equal: [$status, "in_progress"]
                conditions:
                    # empty($call_timeout) || (($call_timeout >= 60 && $call_timeout < 100) || ($call_timeout > 0 && $call_timeout <= 30))
                    @or:
                        - '@blank': [$call_timeout]
                        - '@or':
                            - '@and':
                                message: Call timeout must be between 60 and 100
                                parameters:
                                    - '@greater_or_equal': [$call_timeout, 60]
                                    - '@less': [$call_timeout, 100]
                            - '@and':
                                message: Call timeout must be between 0 and 30
                                parameters:
                                    - '@less_or_equal': [$call_timeout, 30]
                                    - '@greater': [$call_timeout, 0]

Pre-Actions and Regular Actions 

Pre-action and Regular Action configuration complements Transition Definition configuration. Pre-actions are performed BEFORE the preconditions are qualified.

Regular actions are performed during the transition AFTER conditions are qualified, and the current step of workflow item is changed to the corresponding one (step_to option) in the Transition.

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

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

Example

workflows:
    phone_call:
        # ...
        transition_definitions:
            # some transition definition
                preactions:
                    - '@assign_value': [$call_attempt, 1]
                actions:
                    - '@create_entity': # create an entity PhoneConversation
                        class: Acme\Bundle\DemoBundle\Entity\PhoneConversation
                        attribute: $conversation
                        data: # Fill values of freshly created PhoneConversation with data from current WorkflowItem
                            result: $conversation_result
                            comment: $conversation_comment
                            successful: $conversation_successful
                            call: $phone_call

Entity Restrictions Configuration 

Entity Restrictions add validation rules for configured attribute 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 a unique name in the scope of the Workflow.

  • attribute - string - This is a reference to the 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’, and ‘allow’. The default value is ‘full’

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

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

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

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

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

Example

workflows:
    opportunity_flow:
        # ...
        entity_restrictions:
            opportunity_status_creation:           # unique restriction name in scope of this Workflow
                attribute: opportunity             # attribute's reference links to attribute(attribute must be of type 'entity')
                field: status                      # field name of attribute class
                mode: disallow                     # restriction mode (default is 'full')
                values:                            # disallowed values for this field
                    - 'won'
                    - 'lost'
            opportunity_close_reason_creation:
                attribute: opportunity
                field: closeReason
            opportunity_status_open:
                attribute: opportunity
                field: status
                step: open                        # restriction will be applied only When workflow is in this step.
                mode: disallow
                values:
                    - 'won'
                    - 'lost'
            opportunity_close_reason_open:
                attribute: opportunity
                field: closeReason
                step: open