Workflow

A workflow in Drupal is a configuration entity of the core Workflows module: a named set of states and the transitions allowed between them.

Learn DrupalDrupal glossary
Edited by Founder and CEO, DXPR Last updated

A Drupal workflow describes a process as stages and the moves allowed between them, for example from Draft to Published. It is stored as configuration. On its own it only describes a process; a workflow type, such as the one from Content Moderation, connects it to something real, such as publishing a page.

How workflows work in Drupal 11

The Workflows module provides an admin interface and an API. The module description says the states come from other modules, for example publication status. The workflow itself is the config entity Drupal\workflows\Entity\Workflow. It exports four keys: id, label, type and type_settings. The collection page is /admin/config/workflow/workflows and it needs the Administer workflows permission.

The type value names a workflow type plugin. The type plugin owns the behavior: it keeps the states and transitions (methods such as addState(), addTransition() and getTransitionsForState() live on WorkflowTypeInterface) and lists the states it requires. The Content Moderation type, with ID content_moderation, requires a draft and a published state.

A transition has a label, one or more states it starts from, and one state it leads to. Modules that use a workflow, like Content Moderation, build their permissions on transitions, so a role can be allowed one move but not another.

Example

This shortened excerpt is from the Editorial workflow that Drupal core ships in the Standard profile. The file is named workflows.workflow.editorial.yml.

id: editorial
        label: Editorial
        type: content_moderation
        type_settings:
          states:
            draft:
              label: Draft
              published: false
              default_revision: false
            published:
              label: Published
              published: true
              default_revision: true
          transitions:
            publish:
              label: Publish
              from:
                - draft
                - published
              to: published
          default_moderation_state: draft

The full file also defines an Archived state and four more transitions.

Common mistakes

  • Enabling Workflows and expecting moderated content. Without a type that is applied to content types, a workflow changes nothing on your pages.
  • Deleting a state that is in use. Drupal refuses while content uses it. It also refuses to delete the last state or one the workflow type requires.
  • Rebuilding the workflow by hand on each environment. It is configuration, so export it and import it where you need it.
  • Forgetting the transition permissions. With Content Moderation, a role can only use the transitions it has been granted.

For marketing and content teams

The workflow is the written process of your team in a form Drupal can enforce. Decide the stages (for example write, review, publish) and which role makes each move, then ask your site builder to set up Content Moderation to match. The individual stages are explained under workflow states.

Sources

Questions about Drupal workflows

Workflows is the core module that lets you define states and transitions, with an admin screen and an API. Content Moderation is a workflow type from another core module that applies such a workflow to content, so the states control publishing. Workflows alone does not moderate anything.

Go to Configuration, then Workflow, then Workflows (/admin/config/workflow/workflows) and choose to add a workflow. Enter a Label and pick the Workflow type. A workflow needs at least one state before it is enabled, so Drupal sends you to the add-state form.

Configuration. A workflow is a config entity that exports its ID, label, type and the type's settings, which hold the states and transitions. You can deploy it with configuration management like any other setting.

Related terms

All Drupal terms from A to Z