Skip to content

Workflow

The workflow functionality passes a Content item version through a series of stages.

For example, an editorial workflow can pass a Content item from draft stage through design and proofreading.

By default, Ibexa DXP comes pre-configured with a Quick Review workflow. You can disable the default workflow and define different workflows in configuration. Workflows are permission-aware.

Workflow configuration

Each workflow consists of stages and transitions between them.

The following example configuration defines a workflow where you can optionally pass a draft to be checked by the legal team.

Diagram of custom workflow

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
ezplatform:
    system:
        default:
            workflows:
                custom_workflow:
                    name: Custom Workflow
                    matchers:
                        content_type: [article, folder]
                        content_status: [draft]
                    stages:
                        draft:
                            label: Draft
                            color: '#f15a10'
                        legal:
                            label: Legal
                            color: '#5a10f1'
                            actions:
                                notify_reviewer: ~
                        done:
                            label: Done
                            color: '#301203'
                            last_stage: true
                    initial_stage: draft
                    transitions:
                        to_legal:
                            from: [draft]
                            to: [legal]
                            label: To legal
                            color: '#8888ba'
                            icon: '/bundles/ibexaplatformicons/img/all-icons.svg#notice'
                            reviewers:
                                required: true
                        back_to_draft:
                            reverse: to_legal
                            label: Back to draft
                            color: '#cb8888'
                            icon: '/bundles/ibexaplatformicons/img/all-icons.svg#back'
                        approved_by_legal:
                            from: [legal]
                            to: [done]
                            label: Approved by legal
                            color: '#88ad88'
                            icon: '/bundles/ibexaplatformicons/img/all-icons.svg#checkbox'
                            actions:
                                publish: ~
                        done:
                            from: [draft]
                            to: [done]
                            label: Done
                            color: '#88ad88'
                            icon: '/bundles/ibexaplatformicons/img/all-icons.svg#checkbox'
                            actions:
                                publish: ~

Matchers

Matchers define when the workflow is used. Their configuration is optional.

content_type contains an array of Content Type identifiers that use this workflow.

content_status lists the statuses of Content items which fall under this workflow. The available values are: draft and published.

1
2
3
                    matchers:
                        content_type: [article, folder]
                        content_status: [draft]

Stages

Each stage in the workflow has an identifier and can have a label and a color.

The optional last_stage key indicates that content in this stage does not appear on the dashboard or in Review Queue.

One stage, listed under initial_stage, is the one that the workflow starts with.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
                    stages:
                        draft:
                            label: Draft
                            color: '#f15a10'
                        legal:
                            label: Legal
                            color: '#5a10f1'
                            actions:
                                notify_reviewer: ~
                        done:
                            label: Done
                            color: '#301203'
                            last_stage: true
                    initial_stage: draft

Transitions

Each transition has an identifier and can have a label, a color, and an icon.

A transition must state between which stages it transitions (lines 3-4), or be reverse to a different transition (line 9).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
                    transitions:
                        to_legal:
                            from: [draft]
                            to: [legal]
                            label: To legal
                            color: '#8888ba'
                            icon: '/bundles/ibexaplatformicons/img/all-icons.svg#notice'
                        back_to_draft:
                            reverse: to_legal
                            label: Back to draft
                            color: '#cb8888'
                            icon: '/bundles/ibexaplatformicons/img/all-icons.svg#back'

Reviewers

When moving a Content item through a transition, the user can select a reviewer. Assigning a reviewer is mandatory if you set reviewers.required to true for this transition.

1
2
3
4
5
6
7
8
9
                    transitions:
                        to_legal:
                            from: [draft]
                            to: [legal]
                            label: To legal
                            color: '#8888ba'
                            icon: '/bundles/ibexaplatformicons/img/all-icons.svg#notice'
                            reviewers:
                                required: true

Notifications

To ensure that the assigned reviewers get a notification of a transition, configure the actions.notify_reviewer action for a stage.

1
2
3
4
5
                        legal:
                            label: Legal
                            color: '#5a10f1'
                            actions:
                                notify_reviewer: ~

The notification is displayed in the user menu:

Notification about content to review

Draft locking

You can configure draft assignment in a way that when a user sends a draft to review, only the assigned reviewer can either edit the draft or unlock it for editing, and no other user can take it over.

Use the Version Lock Limitation, set to "Assigned only", together with the content/edit and content/unlock Policies to prevent users from editing and unlocking drafts that are assigned to other users.

Content publishing

You can automatically publish a Content item once it goes through a specific transition. To do so, configure the publish action for the transition:

1
2
3
4
5
6
7
8
                        done:
                            from: [draft]
                            to: [done]
                            label: Done
                            color: '#88ad88'
                            icon: '/bundles/ibexaplatformicons/img/all-icons.svg#checkbox'
                            actions:
                                publish: ~

Quick Review disabling

You can disable the default workflow, for example, if your project does not use workflows, or Quick Review entries clog your database:

1
2
3
4
5
6
7
8
ezplatform:
    system:
        default:
            workflows:
                quick_review:
                    name: Quick Review
                    matchers:
                        content_type: []

Custom actions

Besides the built-in actions of publishing content and notifying the reviewers, you can also create custom workflow actions.

Workflow event timeline

Workflow event timeline displays workflow transitions.

You can also use it to render custom entries in the timeline, for example system alerts on workflows.

Custom entry type

To add a custom entry type, create a custom class extending EzSystems\EzPlatformWorkflow\WorkflowTimeline\Value\AbstractEntry. Use an EzSystems\EzPlatformWorkflow\Event\TimelineEvents::COLLECT_ENTRIES event to add your entries to the timeline.

Custom templates

To provide custom templates for new event timeline entries, use the following configuration:

1
2
3
4
5
6
ezplatform:
    system:
        default:
            workflows_config:
                timeline_entry_templates:
                    - { template: '@EzPlatformWorkflow/ezplatform_workflow/timeline/entries.html.twig', priority: 10 }

The template has to provide a block named ez_workflow_timeline_entry_{ENTRY_IDENTIFIER}.

Permissions

You can limit access to workflows at stage and transition level.

The workflow/change_stage Policy grants permission to change stages in a specific workflow.

You can limit this Policy with the Workflow Transition Limitation to only allow sending content in the selected transition.

For example, by using the example above, a workflow/change_stage Policy with WorkflowTransitionLimitation set to Approved by legal allows a legal team to send content forward after they are done with their review.

You can also use the Workflow Stage Limitation together with the content/edit and content/publish Policies to limit the ability to edit content in specific stages. For example, you can use it to only allow a legal team to edit content in the legal stage.

Workflow service

Workflow uses the Symfony Workflow Component, extended in the workflow service.

The service implements the following methods:

  • start - places a Content item in a workflow
  • apply - performs a transition
  • can - checks if a transition is possible

The methods apply and can are the same as in Symfony Workflow, but the implementation in workflow service extends them, for example by providing messages.

For examples of using the Workflow Service, see PHP API documentation.

Validation

Validate form before workflow transition

By default, sending content to the next stage of the workflow does not validate the form in UI, so with the publish action, the form is not verified for errors in UI. However, during the publish action, the sent form is validated in the service.

Therefore, if there are any errors in the form, you return to the edit page but errors aren't triggered, which can be confusing when you have two or more tabs.

To enable form validation in UI before sending it to the next stage of the workflow, add validate: true to the transitions of the stage. In the example below the form is validated in two stages:to_legal and done:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
                    transitions:
                        to_legal:
                            from: [draft]
                            to: [legal]
                            label: To legal
                            color: '#8888ba'
                            icon: '/bundles/ibexaplatformicons/img/all-icons.svg#notice'
                            reviewers:
                                required: true
                            actions:
                                legal_transition_action:
                                    data:
                                        message: "Sent to the legal department"
                            validate: true
                        back_to_draft:
                            reverse: to_legal
                            label: Back to draft
                            color: '#cb8888'
                            icon: '/bundles/ibexaplatformicons/img/all-icons.svg#back'
                            from: [draft]
                            to: [done]
                            label: Done
                            color: '#88ad88'
                            icon: '/bundles/ibexaplatformicons/img/all-icons.svg#checkbox'
                            actions:
                                publish: ~
                            validate: true

You can check validation for a particular stage of the workflow even if the stage doesn't have any actions.