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
54
ibexa:
    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
                                user_group: 13
                        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.

If set to draft, applies for new Content (newly created).

If set to published, applies for Content that has already been published (for example, edit after the Content was 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. You can restrict who can review the content item by setting reviewers.user_group to a Location ID of the user group.

To be able to search for users for review, the user must have the content/read Policy without any Limitation, or with a Limitation that allows reading users. This means that, in addition to your own settings for this Policy, you must add the /Users subtree to the Limitation and add Users in the content type Limitation.

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 first editor of the draft 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 locked by another user.

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: ~

Disable Quick Review

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
ibexa:
    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 Ibexa\Workflow\WorkflowTimeline\Value\AbstractEntry. Use an Ibexa\Contracts\Workflow\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
ibexa:
    system:
        default:
            workflows_config:
                timeline_entry_templates:
                    - { template: '@IbexaWorkflow/ibexa_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.

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
28
                    transitions:
                        to_legal:
                            from: [draft]
                            to: [legal]
                            label: To legal
                            color: '#8888ba'
                            icon: '/bundles/ibexaplatformicons/img/all-icons.svg#notice'
                            reviewers:
                                required: true
                                user_group: 13
                            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.