User defined Object States

Object states let you define stages of your own for content, such as Draft review, Approved or Archived, and let roles and policies decide who may read, edit or move content in each stage, and who may change the stage. States are grouped: an object has exactly one state in every group.

How it works

• A state group holds an ordered list of states. The first state is the default: new objects get it, in every group.
• Every installation has the system group ez_lock (Not locked, Locked), which the kernel uses while content waits in a workflow such as approval.
• States belong to the object, not to a version, a translation or a location. They act on the published content; drafts are not affected.
• In policies, every group becomes a limitation StateGroup_<identifier> of content/read, edit, publish, manage_locations and remove. Changing a state needs state/assign, which can be limited by class, section, owner, subtree, the current state and the new state (NewState).

The administration

Setup > States (/state/groups, policy state/administrate) lists the groups. Open a group to add states, change their order and the default, and translate their names. On a node's page, the States part sets the object's states, optionally for the whole subtree (state/assign).

Commands and settings

# give every object the default state of each group it has no state in (dry run without --apply)
./console exp:adddefaultstates --apply --allow-root-user
# release objects stuck in the Locked state
./console cron:unlock --allow-root-user

A workflow can run when a state changes: add the trigger with workflow.ini [OperationSettings] AvailableOperationList[]=content_updateobjectstate.

An example: a private waste bin

1. Create a group private_wastebin with the states Visible (first, so the default) and In my waste bin.
2. Give the Anonymous role and the other readers content/read limited to StateGroup_private_wastebin = Visible.
3. Give a role for owners content/read and content/edit with the Owner limitation, and state/assign limited to Owner.
4. An owner sets an article to In my waste bin; only the owner can still see it, and it keeps its locations. Setting it back to Visible shows it to everyone again.

Limits

• One state per group per object, for all its translations and locations at once.
• Changing a state does not notify anyone by itself; use a workflow on content_updateobjectstate for that.
• Removing a state moves its objects to the first state that stays in the group; removing a group removes the states from every object. Check what depends on a state (policies, templates) before you remove it.

Related pages

• Object states: stages of your own for content, the full guide with a review workflow, templates, fetches and troubleshooting
• Roles and policies
• Workflows