Workflow in Joomla

1. The Basics

1.1 What a Workflow Is

By default, an article has a single state field: it is published, unpublished, archived, or trashed, and any editor with the right permission can flip it. A workflow replaces that single switch with a process you design yourself. Instead of one switch, the article moves through stages you name (for example Draft, In Review, Published), and it moves only through transitions you allow.

Workflow is an optional feature. It is turned off by default, and you turn it on per component. Today, core Joomla ships workflow support for articles (com_content); the system is built so other components can adopt it too.

Without workflow, "publish" is a checkbox. With workflow, "publish" is a door that only certain people can open, and opening it can trigger extra actions.

1.2 The Three Building Blocks

Everything in Workflow is made of just three things. Learn these three words and the whole component makes sense:

1.3 A Picture of the Idea

Think of stages as boxes and transitions as the arrows between them. The arrows are one-way and you decide which ones exist:

  [ Draft ] --submit--> [ In Review ] --approve--> [ Published ]
                              │
                              └--reject--> [ Draft ]

An editor working on an article in the Draft stage sees only the doors that lead out of Draft (here, "submit"). They cannot jump straight to Published, because no transition connects those two stages. That is the whole point: the workflow decides what is possible.

1.4 Where to Find It

Workflow lives in the administrator only. Once it is enabled for articles, a Workflows entry appears in the Content section of the admin menu, opening the screen at index.php?option=com_workflow&view=workflows&extension=com_content.article. There you manage workflows, and inside each workflow you manage its stages and transitions.

3. Stages: The Statuses Your Content Moves Through

A stage is a named status. Designing good stages is the heart of building a workflow, so it pays to think about them clearly.

3.1 One Stage at a Time

Every article that belongs to a workflow sits in exactly one stage. That stage is the article's current position in the process. When you look at the article list with workflow enabled, the Stage column shows where each article stands (Draft, In Review, Published, and so on).

3.2 The Default Stage

Each workflow has exactly one default stage. New articles enter the workflow in that stage. Joomla protects this rule: you cannot delete the default stage, and you cannot unpublish it, because every workflow needs a valid starting point. If you try, Joomla shows an error and refuses.

3.3 Designing Stages

A typical editorial workflow uses three or four stages:

Keep the number of stages small. Each extra stage means more transitions to define and more decisions for your editors. Start with the fewest stages that describe your real process, and add more only when you feel the lack of one.

5. Transition Actions: Publishing, Featuring, and Notification

A transition moves an item between stages, but on its own that is just a label change. The real effects come from workflow plugins, which add actions a transition can run. Joomla ships three of them.

5.1 The Publishing Plugin

The plg_workflow_publishing plugin lets a transition set the article's actual state. In the transition's Options you choose one value:

This is the bridge between your workflow and the article actually appearing on the site. A transition to your "Published" stage normally carries the publishing action "Published"; a transition to "Draft" carries "Unpublished".

5.2 The Featuring Plugin

The plg_workflow_featuring plugin lets a transition mark an article as featured or not, which controls whether it shows in the Featured Articles list. The option is simply Featured (1), Unfeatured (0), or "do not use".

5.3 The Notification Plugin

The plg_workflow_notification plugin sends an email when a transition runs. This is what makes a workflow feel alive: when a writer submits a draft, the editors get a message. In the transition options you set:

• Send email: on or off for this transition.
• Notification text: a custom message to include.
• User groups: which groups to email (for example, all Editors).
• Recipients: specific individual users to email.

Because these are plugins, the action options you see on a transition depend on which workflow plugins are enabled. Disable the notification plugin and the email options disappear from every transition.

7. The Visual Workflow Editor

Since Joomla 6.1 you do not have to build stages and transitions through list screens alone. Each workflow has a visual graph editor that shows the whole process as a diagram you can edit by hand. For a multi-stage workflow it is far easier to reason about than two separate lists.

7.1 Opening the Graph

In Content → Workflows, every workflow row has a Graph link, which opens the canvas at index.php?option=com_workflow&view=graph&id=1&extension=com_content.article (with the workflow's own id). On the canvas every stage is a box (a node) and every transition is an arrow (an edge) between two stages, so you see the shape of your process at a glance:

   +---------+   submit    +-----------+   approve   +-------------+
   |  Draft  |----------->|  In Review |----------->|  Published  |
   +---------+            +-----------+             +-------------+
        ^   reject              │
        └----------------------└

7.2 Editing on the Canvas

You build and change the workflow directly on the diagram, with the mouse or the keyboard:

• Add a stage (Alt+N) drops a new stage node onto the canvas.
• Add a transition (Alt+M) draws an arrow from one stage to another.
• Edit a selected node or arrow with E; remove it with Delete.
• Fit view (F) zooms the whole diagram back into view.
• Drag stage boxes to arrange them the way your process reads best.

The editor respects your permissions: it only offers the edit, delete, and run controls you are actually allowed, using the same core.edit, core.delete, and core.execute.transition checks described in section 9.

7.3 Where the Layout Is Stored

When you drag stages around, Joomla remembers their positions. The coordinates of each stage node are saved as JSON in the position column of #__workflow_stages, a column added in Joomla 6.1 for exactly this purpose. The canvas loads its data through small JSON endpoints that return the workflow, its stages, and its transitions, so the picture always matches the underlying tables. The graph is only a friendlier face on the same stages and transitions from sections 3 and 4: whatever you draw here writes the same rows you would create by hand.

9. Permissions and ACL

Workflow is only useful if the right people can do the right moves, so it is tied closely to Joomla's access control.

9.1 The Two Key Actions

9.2 Permission Per Transition

The clever part is that core.execute.transition can be set on a single transition, not just on the whole component. Each transition is its own ACL asset. So you can let the Writers group run "Submit for review" while only the Managers group can run "Approve". The workflow plus the permissions together describe who may push content forward.

Transition "Approve"  → Permissions tab
   ├─ Writers:  Execute Transition = Denied
   └─ Managers: Execute Transition = Allowed

9.3 Stages and Workflows Are Assets Too

Workflows, stages, and transitions each become an ACL asset when saved, nested under the component. This is why the workflow tables carry an asset_id column: it lets you set permissions at every level of the hierarchy, exactly like categories and articles.

11. Under the Hood: The PHP API

Developers rarely touch these tables directly. Joomla provides a small set of classes that do the work safely.

11.1 The Workflow Class

The core class Joomla\CMS\Workflow\Workflow drives transitions. You create it for an extension and call executeTransition() to move items. It reads the transition, fires the events, runs the plugin actions, and updates #__workflow_associations for you:

use Joomla\CMS\Workflow\Workflow;

$workflow = new Workflow('com_content.article');

// Move articles 42 and 43 through transition id 2 ("Approve")
$workflow->executeTransition([42, 43], 2);

Behind that single call, the class checks the transition is valid for each item's current stage, dispatches the before/after events (section 12), lets the publishing and notification plugins act, and finally writes the new stage_id into the associations table.

11.2 How a Component Declares Workflow Support

A component opts into Workflow by implementing WorkflowServiceInterface and using WorkflowServiceTrait. The content component does exactly this. The interface answers questions the workflow engine needs to ask:

use Joomla\CMS\Extension\Component;
use Joomla\CMS\Workflow\WorkflowServiceInterface;
use Joomla\CMS\Workflow\WorkflowServiceTrait;

class ContentComponent extends Component implements WorkflowServiceInterface
{
    use WorkflowServiceTrait;

    // Which features can a transition drive for this component?
    //   'core.state'    => true   (publish / unpublish / archive / trash)
    //   'core.featured' => true   (feature / unfeature)
}

Key methods include isWorkflowActive($context) (is workflow_enabled on and does the model support it?), supportFunctionality($functionality, $context) (does this component offer core.state or core.featured?), and filterTransitions() (which transitions are valid for an item right now). This is the seam other components plug into to gain workflow.

13. Performance and Debugging

Workflow adds a little work when items are saved and a few extra tables to the database, but the cost is small, and those tables make problems easy to trace.

13.1 The Performance Cost Is Small

A workflow lookup is cheap. Finding an item's current stage is a single indexed read on #__workflow_associations by its primary key (item_id, extension). The workflow, stage, and transition tables are tiny next to #__content: a site with one workflow has one workflow row, a handful of stages, and a handful of transitions, no matter how many thousands of articles it holds. The extra work happens when an item is saved or a transition runs, not on every front-end page view, so visitors feel nothing.

13.2 Reading the Tables to Debug

Because the state lives in four small tables, you can see exactly where any item stands with a couple of queries. To find the stage of article 42:

SELECT s.title AS stage
FROM   #__workflow_associations AS a
JOIN   #__workflow_stages AS s ON s.id = a.stage_id
WHERE  a.item_id = 42
AND    a.extension = 'com_content.article';

To list the moves an editor could make from a given stage, read the published transitions whose from_stage_id is that stage or -1 (Any):

SELECT id, title, from_stage_id, to_stage_id
FROM   #__workflow_transitions
WHERE  workflow_id = 1
AND    from_stage_id IN (<current_stage_id>, -1)
AND    published = 1;

13.3 Common Things to Check

When content behaves oddly, the cause is almost always in these tables or in ACL:

• No row in #__workflow_associations for an item means it never entered the workflow. Re-save the item so it receives its default stage.
• A transition that moves the stage but does not publish has an empty publishing value in its options column.
• An item that cannot move on has no published transition out of its stage, or the user lacks core.execute.transition on the transition that would move it.

15. SEO and Metadata

Workflow has no tags of its own in the page head, but it has a real, indirect effect on your SEO because it controls what gets published at all.

15.1 Nothing Half-Finished Goes Live

The most common SEO damage on team sites is half-edited or duplicate drafts slipping onto the live site and getting indexed. A workflow with a review stage stops that: an article reaches the Published state only after someone approves it, so search engines see finished pages, not work in progress.

15.2 Archived Instead of Deleted

An Archived stage (mapped to the archived state) lets you retire old content cleanly. Archived articles leave the main listings but keep their URL, which is far better for SEO than deleting a page and creating a dead link. Pair an "Archive" transition with a redirect strategy for content you truly remove.

15.3 Consistent Publishing Discipline

Because publishing is funneled through transitions, your publish dates and featured flags are set consistently by the workflow rather than ad hoc by each editor. Consistent, deliberate publishing is quietly good for both readers and crawlers.

17. Best Practices

If you remember only a few things from this article, remember these:

• Only enable workflow when you have a team or a process. A solo site rarely benefits and adds clicks for nothing.
• Keep stages few. Three or four named stages cover most editorial needs. Every extra stage multiplies the transitions you must define.
• Map publishing carefully. Make sure the transition into your "live" stage carries the Publishing: Published action, or content will move but never show.
• Use per-transition permissions. This is the real reason to run a workflow: let writers submit but only managers approve, with core.execute.transition.
• Sketch the flow in the graph editor before wiring up actions. Seeing the stages and arrows makes gaps and dead ends obvious.
• Assign workflows per category when only part of the site needs review. Leave the rest on the simple default.
• Test the whole loop on a staging copy before going live: submit, approve, reject, and confirm the emails and the published state all behave.

19. Summary

Joomla Workflow turns the simple "published or not" switch into an editorial process you design. It is off by default and enabled per component, starting with articles:

• For editors: content moves through named stages, and the only moves you see are the transitions allowed from where the item stands.
• For administrators: workflows, stages, and transitions, plus per-transition permissions, decide who can submit, who can approve, and who can publish, and the visual graph editor lets you design the whole flow as a diagram.
• For developers: four small tables, a single Workflow class, the WorkflowServiceInterface, and the before/after transition events expose the whole engine cleanly, and the three core actions are just plugins you can copy.
• For SEO: a review stage keeps unfinished work out of the index, and an archive stage retires old pages without breaking their URLs.

Once you understand the three building blocks, how a transition's publishing action sets the real state, and where the current stage is stored, you can design a process that matches your team and trace exactly why a piece of content is or is not live.

If your editors keep publishing things by accident, or content keeps getting stuck halfway, a well-shaped workflow usually fixes it. It pays to design the stages and permissions deliberately, because a workflow that fits your team turns publishing from a free-for-all into a calm, predictable routine.