Workflows¶

Translations¶

Together with workflows configurations, for almost each sections that specified below there should be defined translation messages under corresponded key to display correct UI text. Configuration of translations are 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). For workflows there should be created their’s own translations file <YourBundle>Resources/translations/workflows.{lang_code}.yml Where {lang_code} is your preferable language code for translations that gathered there. Further in each section that describe workflow configuration part would be note provided with a proper translation key for translatable fields that can be used in configuration section.

General information¶

Under the workflows key each workflow is created by adding a key that is its name and is used to identify workflows. The following example configures a workflow that defines the process of calling a customer:

1
2
3
4
5
6
7
8

# src/Acme/DemoBundle/Resources/config/oro/workflows.yml
workflows:
    phone_call:
        entity: Acme\Bundle\DemoBundle\Entity\PhoneCall
        start_step: start_call
        defaults:
            active: true
        priority: 10

The basic configuration contains a name that is displayed in the UI, the entity the workflow will be applied to and the initial step that is applied when initializing the workflow for an entity.

Defining the Workflow Steps¶

Next, you need to define the states an entity can have when the workflow is applied:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

workflows:
    phone_call:
        # ...
        steps:
            start_call:
                allowed_transitions:
                    - connected
                    - not_answered
            start_conversation:
                allowed_transitions:
                    - end_conversation
            end_call:
                is_final: true

In this example, the entity can have three states: start_call (which was configured as the start step above), start_conversation and end_call. The end_call step is marked as final which means that the workflow terminates when this step is reached. The final flag does not mean that there cannot be any further transitions, but it is used internally for additional data manipulation (for example, report entities whose workflow is in a final step).

The allowed_transitions defines which transitions can be applied in a step.

1
2
3
4
5
6

oro.workflows:
    phone_call:
        step:
            start_call.label: 'Start Phone Call'
            start_conversation.label: 'Call Phone Conversation'
            end_call.label: 'End Phone Call'

Workflow Attributes¶

During the transition from one step to another step, the user can modify attributes of the underlying entity. All attributes that can be modified in any of the transitions must be enabled with the attributes option:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

workflows:
    phone_call:
        # ...
        attributes:
            phone_call:
                type: entity
                options:
                    class: Acme\Bundle\DemoWorkflowBundle\Entity\PhoneCall
            call_timeout:
                type: integer
            call_successful:
                type: boolean
            conversation_successful:
                type: boolean
            conversation_comment:
                type: string
            conversation_result:
                type: string
            conversation:
                type: entity
                options:
                    class: Acme\Bundle\DemoWorkflowBundle\Entity\PhoneConversation

1
2
3
4
5
6

workflows:
    phone_call:
        # ...
        attributes:
            timeout:
                property_path: entity.call_timeout

1
2
3
4
5
6
7

    oro.workflows:
        phone_call:
            attribute:
                phone_call.label: Phone Call
                call_timeout.label: Call Timeout
                call_successful.label: 'Call Successful'
    #... and on

Configuring the Transitions¶

Then, you need to define which transitions are available, to which step they transform the entity and which attributes can be modified when applying a transition:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

workflows:
    phone_call:
        # ...
        transitions:
            connected:
                label: 'Connected'
                step_to: start_conversation
                transition_definition: connected_definition
            not_answered:
                label: "Not answered"
                step_to: end_call
                transition_definition: not_answered_definition
            end_conversation:
                label: 'End conversation'
                step_to: end_call
                transition_definition: end_conversation_definition
                triggers:
                    -
                        cron: '* * * * *'
                        filter: "e.someStatus = 'OPEN'"

1
2
3
4
5
6
7
8
9

        oro.workflows:
            phone_call:
                transition:
                    connected:
                        label: Connected
                        warning_message: Connection performed
                    not_answered.label: Not answered
                    end_conversation.label: End conversation
        #... and on

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 2 types of triggers:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

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

Transition Definition Configuration¶

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

Transition definition configuration has next options.