Publication Workflow Application

Last modified by Anca Luca on 2024/04/15 00:11

cogSimple publication workflow implementation that allows to push a document through various validation states until it is published.
Developed by

Anca Luca, Thomas Delafosse, Raluca Stavro, slauriere

Active Installs92
1 Votes
LicenseGNU Lesser General Public License 2.1


Installable with the Extension Manager



This extension uses 2 important concepts:

  • the draft document
  • the published document (the target document, from the point of view of a draft),
    and functions in the following way: the contributors edit the draft document, demand moderation and validation on it, and once it's published it is copied to the published document. So there are always 2 documents, the draft and the published document. When a workflow is initiated on a document, the current document will be the draft and the user will need to fill in the target document. The published documents should never be edited directly, only published from a draft document.

In order to use this extension, add the PublicationWorkflow.PublicationWorkflowPanel to the spaces of your choice (should be the space where the draft documents reside and the space where the published documents reside, so that the draft can be accessed from the published document and edited) and use the commands available in this panel. The same UI can be achieved by using the {{publicationworkflow /}} macro in the context of the draft and published document.


The workflow "New Workflow" has been created using the template provider on the PublicationWorkflow space (the groups for contributors, moderators and publishers have been created using the wiki administration).

In order to define a workflow, just create a new document using the  PublicationWorkflowConfigTemplate template (which has a template provider available in the space PublicationWorkflow, see the first image above) and fill in the 3 groups: contributors, moderators and publishers (webmasters). By default workflows work with 2 levels of validation: the contributors start the workflow and edit the documents then submit to moderation. Moderators can edit further and then submit of validation or refuse and send the doc back to contribution. Then, the publishers can edit further and validate and publish or refuse and send back to moderation. If, in the configuration, the moderators group is missing then there will only be one level of moderation, done by the publishers. Once published, a document can be archived (passed to hidden) or unpublished (the published document is removed and the content is copied to the draft).

The panel PublicationWorkflow.PublicationWorkflowPanel has been added on the left column for the Draft space in the example above (using the space administration section).

We have created a new document inside the Draft space and we would like to publish it in the Main space using the "New Workflow" workflow.

The button "Start workflow" will send the document to the "Draft" status (draft).

The button "Submit to moderation" will send the document to the "In moderation" status (moderation).

The button "Validate" will send the document to the "Validation" status. The document can be either validated or refused by the a member of the publishers group (webmasters).

The button "Publish" will open a modal box to confirm the publishing of the document. In this state,the document can be validated without being published or refused.

The user needs to confirm if the document is published.

The published document is copied to the "Main" space which was initially selected.

Note that on the draft document the rights are handled automatically by the workflow application (between contributors, moderators and publishers) but for the published documents the rights fall in the responsibility of the wiki administrator, which should make sure that no one can edit the published documents directly (usually it means setting the rights on a space).

Mails are being sent in the following cases:

  • when a document is submitted to moderation - mail is sent to the users of the moderators group if any, or to validators otherwise
  • when a document is submitted to validation - mail is sent to validators
  • when a document is refused by moderators - mail is sent to the contributors
  • when a document is refused by validators - mail is sent to the users of the moderators group if any, or to contributors otherwise
  • when a published document is unpublished - mail is sent to validators

Check the workflow diagram for the complete list of statuses and transitions :


The list of drafts documents is available on the page PublicationWorkflow.Overview:


Publication Workflow macro

The macro publicationworkflow is a standalone macro that allows to control the workflow state of the current document.

allowWorkflowInitializationIf the current document does not have an initialized workflow, display options to initialize it.2.2true


The following options are available when configuring a publication workflow :

NameDescriptionSinceDefault value
Default target spaceDefine an indicative space for the target of a given workflow document2.1N/A
Set drafts to hiddenWill force a draft to be marked as a hidden document when set to true1.9Yes
Move strategy

Will define the actions to be taken by the application when a page under workflow is moved. The application can either :

  • Do nothing : the application will not try to move the equivalent page of the workflow
  • Move drafts : when moving the target document, attempt to also move each draft linked to this target
  • Move target : when moving a draft document, attempt to also move the target linked to this draft (if it exists)
  • Move target if unpublished : when moving a draft document, check if a target exists. If a target does not exist yet (the first publication has not happened yet), then update the target property of the draft document to try to match the move that happened on the draft
  • Move all :¬†when any page under workflow is moved, try to update the equivalent page(s) according to the move that was performed

Note that there are some conditions where the application will not be able to compute a new location for the equivalent document of the document being moved. For example : when trying to move a document MySpace.Draft to MySpace.SomeOtherName, with the target MySpace.Target ; the publication workflow will not be able to compute the new name of the corresponding target, as the rename action did not happened on a part of the page reference that was common to the draft and the target document. In that case, a warning is sent in the move / rename logs, indicating that the equivalent page could not be moved.

In XWiki 12.5-RC1+, you will need to set refactoring.rename.useAtomicRename to false in in order for the move strategy to work properly.


1.10Do nothing
Allow custom publication commentAdd the possibility for editors to define a publication comment that will be used in the history of the target document.2.0No
XWiki 2.3+ Skip draft rights update on workflow transition

By default the workflow transitions update the rights of the draft document, to make the actions available to the various groups of the workflow based on the state (contributors, moderators, validators).

Thus option allows to skip these rights settings and leave the draft rights as they are.


Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.

You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:

  1. Log in the wiki with a user having Administration rights
  2. Go to the Administration page and select the Import category
  3. Follow the on-screen instructions to upload the downloaded XAR
  4. Click on the uploaded XAR and follow the instructions
  5. You'll also need to install all dependent Extensions that are not already installed in your wiki

Note: if this extension is installed on a version of XWiki lower than 4.3, mailsender plugin needs to be replaced with the 4.3 version, so that workflow notification mails are sent.

Release Notes








Added the possibility to move the documents under workflow in sync. See the property Move strategy in the workflow configuration.













Dependencies for this extension (org.xwiki.contrib.workflow-publication:xwiki-workflow-publication-application 2.3.2):

  • org.xwiki.contrib.workflow-publication:xwiki-workflow-publication-api 2.3.2

Get Connected