Learn / eZ Publish / eZ Publish Knowledge Series: Editorial workflow with Object States

eZ Publish Knowledge Series: Editorial workflow with Object States

In this implementation, an object can have multiple object states, but can have only one at a time in any defined object state collection.

Use case

Currently, the workflow engine in eZ Publish does not allow for objects to be edited with fine grained access control while being submitted for a workflow process. An example is the approval workflow currently bundled with eZ Publish: an object is locked and can only be rejected or accepted by the person in charge of approval. No corrections or other editing are possible in this phase with the default approval event provided.

With object states, this can be easily governed by setting correct permissions for the various object states together with policies and roles on the transitions between object states. Let's see how this can be achieved.

Here is the situation: you are managing a team of journalists, which is broken down into several specialized subteams :

  • Bulk editors (Brad is part of this team)
  • Spellcheckers (Stefan)
  • Media enrichers (Mélanie)
  • Translaters (Telma)

Ok, this is simplistic, but stay focused please...

Each subteam should focus on its very task for every generated piece of content, in order to best leverage its skills, and then hand over the piece of content to the subsequent team. To achieve this, you will need to set up two key elements of the process :

  1. An access control mechanism, giving the right to each subteam to do its part of the work ( and only this one ) on a piece of content, preventing any destructive intereference.
  2. A hand-over mechanism, communication channel between subteams.

Say Brad writes an articles about Obama's fresh election as President of the USA. When he is done, Stefan takes his work over, and checks the various grammar and spelling rules. Then Mélanie adds cool pictures of Barack Obama's inauguration, and sends the resulting almost-ready article to Telma, who is in charge of translating it to Spanish.

Here come the object states on stage !

When creating your eZ Publish-based web media application, you will create Object States matching the different phases of your editorial chain. From the administration interface, navigate to Setup, and click the « States » link in the left menu. You can see, listed, the different so-called «Content object state groups», as follows.

Enter the relevant information in the proposed object-state edition screen, in all applicable languages (the object states feature natively supports languages), as follows. Then click the « Create » button.

Then create the various object states, mapped to your editorial chain. In order to do so, you will need to click the «Create New» button under the «Object states in this group» block, from the object states group full view. Note that the first state in a group will be the one applied by default to objects. It should eventually look like this :

Note that the «Ready to go live» state was added, final logical step of our editorial chain.

Creating User groups

Create, from the «User accounts» tab in the administration interface, as many user groups as your editorial chain requires. Then create our main characters in their respective groups (remember, Brad, Stefan, Mélanie, Telma).

Creating Roles

Creating the adequate roles will help satisfy point 1. of the initial key elements :

«An access control mechanism, giving the right to each subteam to do its part of the work ( and only this ) on a piece of content, preventing any destructive interference.»

The first step will be to copy the built-in «Editor» , role, and slightly modify it. It is too permissive in our current use-case. Here is the new “Generic Editor” :

We then assign it to the four user groups used in the web-media application.

On top of the generic edition role, let's create roles controlling the state transitions between each step of our editorial chain, and also enforcing that every user group has the right to only perform the edit action it is allowed for. They are straight-forward, giving among other the right on the 'state' module, its 'assign' function, and narrowing down the allowed action to a specific transition between two steps. Here they are. Each of them is assigned to its eponymous user group.

Bulk Editors

This role is assigned to the «Bulk Editors» group, and allows Brad, once he finished writing the initial text of a piece of news, to push it one step ahead to the Spell Checking phase (Stefan).

Spell Checkers

This role is assigned to the «Spell Checkers» group, and allows Stefan, once he finished reviewing a piece of news, to push it one step ahead to the Media Enrichers (Mélanie).

Media Enrichers

This role is assigned to the «Media Enrichers» group, and allows Mélanie, once she finished adding media elements to a piece of news, to push it one step ahead to the Translaters (Telma).


This role is assigned to the «Translaters» group, and allows Telma, once she finished translating the piece of news into various languages, to push it live ! The content object will then be in the last step of our editorial chain: “Ready to go live”.


The anonymous role, in our simplistic proof of concept, shall be altered to properly reflect the editorial process. Indeed, the built-in Anonymous role gives read access on about any content in the standard section, with absolutely no restriction on the Object States. Hence the need to make sure all content classes involved in the editorial process are only visible when their instances are in the “Ready to go live” state. Here is our modified Anonymous role, assuming that only Article, Article (main-page), Article (sub-page) are used by the editors:

Ok, now the system is properly configured, only “Ready to go live” articles will be surfaced on front pages, and the four different teams are able to collaborate efficiently...but for point 2. of our initial key elements :

“A hand-over mechanism, communication channel between subteams.”

When Brad finished writing the bulk text of an Article, he needs to tell Stefan that there is some spellchecking work to do on this fresh Article. This would traditionally go through a workflow, in the eZ Publish sense of it, catching the state change and notifying the members of the Spell Checkers User Group that a new Article was submitted for spellchecking. This feature is not yet shipped by default in 4.1, but shall soon be, along with more use-cases for Object States. For now, the notification will be manual. Brad will send his new Article's URL to Stefan, right after he changed the state from “Bulk Edition” to “Spellchecking”. And so on.

Rolling out the process

Brads starts up by deciding to write about Barack Obama's fresh election as President of the United States. Logged-in in eZ Publish, he navigates to the suitable location in the content tree to write such an big piece of news, selects the Article class in the drop down list, English as a language, and hits the “Create here” button. History is being written, this is his first editorial workflow based on Object States. We all hope he is enjoying this moment. Once he is satisfied with what he wrote, he publishes the object, and changes its state to “Spellchecking”. In case Brad had chosen front-end editing ( eZ Flow here ), he can totally change the state of his article from there. When viewing the article, click the following button in the toolbar :

He lands on the following screen, where he can pursue his editor's destiny, as shown here :

He then notifies Stefan of this new Article about Obama. Stefan fixes the multiple mistakes ( Brad is bad with grammar .. ), and sets the content object in the “Media Enrichment” state. Once notified by Stefan, Mélanie populates the articles with relevant pictures, videos and interview-podcasts and finally send it to Telma, in “Translation” state. Telma, last person in the editorial process, translates the article to spanish, and sets its state to “Ready to go live”. And guess what ? The article is now online, after having completed this simplistic yet significant, multi-team editorial workflow !


Although the Object States feature shipped with 4.1 is at an early stage of its life, the hereby presented use-case, set up in half an hour, reveals its high potential. This example is a simple use-case for Object States. Yet a vast amount of applications and workflow-like implementations based on this new functionality can be easily implemented without further PHP coding :

  • Document management with “check-in”, “check-out” (or locking) of objects, with possible overrides by a “supervisor” . Also here, an object can be marked as “locked”, while the roles/policies defined at this state to be read-only (the name does not imply the roles/policies, they must be set explicitly).
  • Personal project spaces also benefit a lot, for example to implement a personal “trash-can” in eZ Publish, a dedicated object state can be assigned for this. Of course un-doing this “removed” state is straightforward with the correct roles and policies, both at the state level as well as the transitions between states. An object also retains its node location(s).
  • Integration of external publishing workflows: suppose web content or part of it needs to be exported to a traditional publish/print workflow. Currently triggers can be used to launch additional workflows. In the future, a simpler system with hooks for external processes will be provided, so the need for dedicated modules and/or traditional eZ Publish workflow events can be avoided and possibly fully automated.

More to come in eZ Publish 4.2 and Thanks for reading !