Joomla Workflows

Basic Workflow contains one stage, Basic Stage, and a set of self-transitions (from Basic Stage back to Basic Stage) named Unpublish, Publish, Trash, Archive, Feature, Unfeature and Publish and Feature. With them a site that enables workflows keeps the familiar behaviour: the toolbar buttons of the article list simply run those transitions. That default is why enabling workflows on a site that does not design its own stages changes very little for editors.

Workflows are off after installation. They are switched on for articles in the options of the component:

Once enabled, Content → Workflows appears in the menu and every article gets a stage. Articles that existed before are placed in the default workflow’s stage, and new articles start in the first stage of the workflow that applies to them. Which workflow applies is decided by the category: the category edit form has a Workflows tab where the category either uses the default workflow, inherits the one of its parent, or selects a specific workflow. Items created in a category without an explicit choice use the workflow marked as Default in the Workflows list.

Workflows are a per-component feature. Joomla ships the integration for articles; any other component can take part by implementing the workflow service interface, and the Workflow Publishing plugin has two options, Allowed and Forbidden lists of component sections, that restrict which sections the plugin acts on. A section in the forbidden list keeps its normal publish buttons even when workflows are enabled for the component as a whole.

The setting is global for the component, and disabling it again is safe for content but not for data: the stage rows stay in the database and the workflow screens simply disappear. Items keep whatever published state their last transition left. Switching workflows on for a site with thousands of articles is quick because the association rows are created in one operation, but test it on a copy first, since a stage must exist for every item.

Content → Workflows lists the workflows. The list has these columns: status (Enabled, Disabled or Trashed), Name, Default, Stages (a button that shows the number of stages and opens the stage list), Transitions (the same for transitions) and ID. A workflow that is not the default is only used by categories that select it.

Opening a Stages list shows each stage and lets you add, edit, publish, unpublish and trash stages. A stage that still holds items cannot be trashed and deleted without first moving them, and the default stage of a workflow cannot be removed. Opening a Transitions list shows, for each transition, its Current Stage and its Target Stage, and the edit form has these tabs:

Two details matter in practice. First, a transition that does not change the published state leaves the article exactly as published as it was: a "Return to draft" transition that only changes the stage on an already published article does not unpublish it, so every transition that should hide content must say so in Publishing State. Second, when workflows are enabled the article list and the article edit form no longer show their normal status controls (see the plugins).

Three plugins of type workflow ship with Joomla, in plugins/workflow. They are enabled by default and appear in System → Plugins when the type filter is set to workflow. Each of them contributes a part of the transition form and reacts to the events that the workflow system dispatches around a transition (onWorkflowBeforeTransition and onWorkflowAfterTransition). Plugin development in general is in Plugin Development and Events.

Because the Publishing and Featuring plugins are what makes a transition publish or feature something, disabling the Workflow - Publishing plugin turns the workflow into labels only: the Publishing State field disappears, and the normal published field comes back. That is a legitimate setup for a site that only wants stages as an editorial checklist, but it makes the permission model weaker, because anyone who may edit state can then publish.

Notifications are delivered as private messages. Whether a recipient also receives an email depends on the message preferences of that user and on the mail settings of the site (see Mail Templates and Email Settings). Test it with a real account before relying on it, since a recipient with no permission to read messages is silently skipped.

Workflows add permissions on top of the ones of articles. The relevant ones are:

A practical rule: give authors the right to run the transitions that leave Draft and no transitions that publish, and give the publishing transitions to a group that only editors belong to. Remember that the Super User group is always allowed to do everything, including Change Stage in a batch, so a Super User can override any workflow. Permission design in general is described in Users, Groups, Access Levels and ACL.

If a transition publishes but the user running it lacks permission to change the state, the action fails while the transition itself still succeeds, which leaves the item in the target stage and unpublished. This is the commonest error in a new workflow: a stage called "Published" containing unpublished items. Always test each transition with an account that has only the intended permissions.

Joomla 6.1 added an interactive diagram of a workflow, announced in the release news as the Visual Workflow Editor. It is a Vue.js-based graph that shows the stages as boxes and the transitions as arrows, so the whole publication process can be seen at once instead of through two lists.

The editor changes nothing about the model. It writes the same rows to #__workflow_stages and #__workflow_transitions, so the transition screens described above still work, and the Permissions of a transition still have to be set there. Older books such as Joomla! 4 Masterclass (2023) describe workflows only through the list and form screens, because the graph did not exist in 4.x.

The Tallpine volunteers write trail reports, and the club wants a Trail Warden to check them before publication. The design uses four stages and the permissions below.

Source: Joomla User Guide: Publishing Workflows

The transitions are created in Content → Workflows → Tallpine Review → Transitions:

The remaining setup is mostly clicking, but the order matters:

A category change moves an article to the first stage of the new category’s workflow only when the article is saved with that new category and the workflow differs; if items end up in the wrong place, use Change Stage in the batch dialog. Custom fields on Tallpine trail reports (distance, elevation gain, difficulty) are not affected by workflows, but a field group assigned to a category is evaluated with the category, see Custom Fields.

The Web Services API of an article exposes the stage as part of the item, and the published state of an item that is under a workflow cannot be set directly through the API for the same reasons as in the administrator: the Publishing plugin refuses state changes outside a transition. A headless client that wants to publish an article therefore has to follow the transitions available to its token user. The API is described in Web Services API.

Workflows add steps, screens and permissions, and every step is a place where an item can get stuck. They are the wrong tool when:

They pay off when different people write, check and publish; when a publish step must be restricted to a group; or when the club must be able to show who approved what. For the Tallpine club the news section does not need them, and the trail reports, where wrong distances or closures cause real problems, do.

Common mistakes to avoid are enabling workflows with no plan for existing articles, forgetting that a transition must set the publishing state explicitly, giving authors a publishing transition, assuming that notifications are emails, and leaving the Workflow - Publishing plugin disabled and then wondering why the status field is back.