Publishing Workflow Tutorial

The problem

Let's say we are working on a Systems Development Life cycle (SDLC) for a big company. We want people in IT to know the approved policies, procedures, templates and guidelines.

For the SDLC to be updated, there has to be a lot of discussion, but we don't want to interfere with the day to day operations, until they are approved. Only a few people from Project Management, Development and QA are involved in the revisions of the SDLC. After all the discussions, only people from the Project Management Office can approve the changes.

The solution

So what we are going to do is to define two Spaces: one for drafts (DRAFTSDLC) and the public space (SDLC). The discussion and approvals workflow will occur on the drafts space, and once the changes have been approved, they will be published to the public space.

We are also going to need two groups, sdlc-editors and pmo. The DRAFTSDLC space can only be seen and edited by members of the sdlc-editors, and the final changes can only be approved by members of the pmo group.

We are going to use the Content Publishing Plugin and the Approvals Workflow Plugin.

Setting up the Content Publishing Plugin

After the plugin has been installed (either through the [Plugin Repository] or manually) we need to set it up.

First, we need to define who can publish, and what spaces can be published.

From the Administration console, lets go the Content Publishing section:

We want only members of the pmo group to publish, and only the Drafts Space can be published.

We save the changes and we are done with the configuration:

From the Advanced section of the DRAFTSDLC Space, pmo members can publish the space:

The very first time we need to select to what space we are going to publish. In this case we are going to publish to the Systems Development Life cycle (SDLC) space:

Because the SDLC is empty the very first time, we need to publish the whole space at once. So we click the "publish" button:

All pages on the DRAFTSDLC space are copied to the SDLC space:

The latest version of the SDLC is now available to the public:

Defining the Approvals Workflow

To keep the SDLC updated, we need to define a workflow because we don't want to publish the entire space every time there is a change.

Furthermore, the workflow will allow us to enforce a procedure for SDLC updates (defined in the SDLC itself ).

We want any of the members of the sdlc-editors to be able to propose changes to the SLDC. They have to be peer-reviewed and can be only approved by the Project Management Office.

Ee are going to need the Approvals Workflow Plugin to define a couple of approvals and a workflow.

Workflows are defined as a collection of macros. We create the Workflows (WORKFLOWS) Space to define the SDLC workflow.

Approvals Workflow Configuration

After the Approvals Workflow Plugin has been installed and configured, we need to enable workflows (they are disabled by default).

First, we need to enable a couple of macros.

From the Administration console, let's go to the plugins section:

Select the Approvals Workflow Plugin:

Let's enable the workflow macro:

... and the send-email macro:

We need to define where workflows can be defined. We go then to the Approvals Workflow Plugin administration:

By default, no workflows can be defined in any space:

We have created a Workflows Space, which we are going to use to define the SDLC Workflow. We need to configure the plugin so workflows can be defined only in that space:

We are ready now to define our workflow in the Workflows Space:

The SDLC Workflow

We create a SDLC Workflow page in the Workflows space.

The workflow will be used on the DRAFTSDLC space:

{workflow:spaces=DRAFTSDLC}
...

We need two approvals in the workflow. The Review approval and the Publish approval. The Publish approval can be given only by members of the pmo group, after the Review plugin has been given. We also want to make the the Publish approval as final, so we record the version of the pages approved.

{workflow:spaces=DRAFTSDLC}
    {approval:Review}
    {approval:Publish|hasapproval=Review|final=true|group=pmo}
    ...

After a change is made, it has to be peer-reviewed. When the change is reviewed, we want to label the page, set a message, and to notify a member of the pmo group that the page is ready for approval.

{workflow:spaces=DRAFTSDLC}
   ...
    {trigger:pageapproved|approval=Review}
        {set-label:pending_pmo_approval}
        {set-message}Waiting for PMO approval{set-message}
        {send-email:user=roberto|subject=Document waiting for approval}
            The document @page@ has been reviewed by @user@ and is waiting for approval
        {send-email}
    {trigger}
    ...
{workflow}

When the change is given the Publish approval, we want to publish it to the public space. We want also to remove the message and the label we had added.

{workflow:spaces=DRAFTSDLC}
   ...
    {trigger:pageapproved|approval=Publish}
        {set-message}{set-message}
        {remove-label:pending_pmo_approval}
        {publish-page}
    {trigger}

We are done with the workflow. This is the entire workflow we defined:

{workflow:spaces= DRAFTSDLC}
    {approval:Review|weight=10}
    {approval:Publish|hasapproval=Review|final=true|group=pmo|weight=20}
    {trigger:pageapproved|approval=Review}
        {set-label:pending_pmo_approval}
        {set-message}Waiting for PMO approval{set-message}
        {send-email:user=roberto|subject=Document waiting for approval}
            The document @page@ has been reviewed by @user@ and is waiting for approval
        {send-email}
    {trigger}
    {trigger:pageapproved|approval=Publish}
        {set-message}{set-message}
        {remove-label:pending_pmo_approval}
        {publish-page}
    {trigger}
{workflow}

And this is how the workflow page looks:

Updating the SDLC

Now that the workflow is defined, the new approvals are shown in all pages on the DRAFT Systems Development Life cycle space:

Once a change is made and discussed, a peer-reviewer (member of the sdlc-editors group) approves the change:

The page is shown now as approved by the reviewer and the label pending_pmo_approval is added:

We defined in the workflow that an email is to be sent to one of the members of the Project Management Office. They can also use the pending_pmo_approval to identify what pages need approval: