Using Comala Workflows for approval of controlled documents

When considering using Confluence to develop and release controlled documents, one of the main concerns many companies have is whether they will be able to approve the documents directly from the application.
This is possible using Comalatech’s Comala Workflows plugin, which allows us to configure your desired approval workflow right into Confluence.
This plugin has the two key components required for FDA CFR 21 Part 11 compliance:

• each approval step can be linked to an electronic signature
• and each approval activity is logged in a dedicated page activity report, creating an audit trail.

This makes it suitable for the controlled document process in organisations that need to adhere to good manufacturing practices (GMP) and other stringent regulatory frameworks. Figure 1 below shows a screenshot of an example report.

Deciding on the approval process

Once the Comala Workflows plugin is installed, you’ll need to decide on the approval process you want to use. Many teams don’t have a formally defined approval process until they decide to manage their controlled documents in Confluence. Until then approval often depends on various people adding their signature to a final draft once it has been reviewed.

In fact the informal review phase leading up to final approval is often very important, making it possible to incorporate the feedback of many stakeholders. Fortunately a variety of collaboration features built into Confluence facilitate this.

Installing the Comala Workflows plugin makes it possible to follow the informal review with a formal review and approval phase, where approval and electronic sign-off are logged on the system. This stage can replace your existing paper or electronic sign-off.

One of the interesting aspects of the plugin is that it makes it possible to apply different review and approval processes to different controlled documents, using a single workflow definition. This is helpful, because some documents by nature demand a more complex approval process than others. Obviously, it’s also possible to define several separate workflow scripts to use in different cases.

Below is an example of the code involved in an approval workflow, which demonstrates many of the features available. First, figure 2 shows a brief overview:

Approval workflow work example

The workflow below is tested for the following configuration:

• Confluence server 5.7.3
• Comalatech workflow 4.8.2

We’ve added a few notes within the script for clarity.

{workflow:name=Controlled document workflow (demo)  1|key=com.radbee.controlleddoc2.demoworkflow.01|label=demoworkflow|stickylabels=controlleddoc}
    {description}
        A controlled document needs to be approved by various stakeholders and by QA person. Optionally- A review cycle may also take place prior to the approval cycle.
    {description}
    {comment}
    *************************************
    ****** workflowparameters
    *************************************
    {comment}
    {comment}
    *************************************
    ****************** workflowparameters: Non editable
    *************************************
    {comment}
    {workflowparameter:Organization options}
        Operations, Research, Quality, Administration
    {workflowparameter}
    {comment}
    *************************************
    ****** workflowparameters: all these are editable (per page)
    *************************************
    {comment}
    {workflowparameter:Document ID|description=Is NA if this is a new document with no ID set.|edit=true}
        NA
    {workflowparameter}
    {workflowparameter:Organization|type=list|options=@Organization options@|edit=true}
        Operations
    {workflowparameter}
    {workflowparameter:Training|type=list|options=Required, Not required|edit=true}
        Required
    {workflowparameter}
    {workflowparameter:Who needs to approve|type=list|options=Only QA, QA and others|edit=true}
        Only QA
    {workflowparameter}
    {workflowparameter:Author|type=user|edit=true}
        @creator@
    {workflowparameter}
    {comment}
    *************************************
    **** Charlie is the default QA approver. It is possible to change the QA approver for specific page through the workflow settings for that page.
    *************************************
    {comment}
    {workflowparameter:QA approver|type=user|edit=true}
        charlie
    {workflowparameter}
    {comment}
    *************************************
    ***************** States
    *************************************
    {comment}
    {state:Draft|approved=In Review}
        {state-selection:states=In Review,In Approval|user=@Author@}
    {state}
    {state:In Review|approved=In Approval}
        {approval:Assigned reviewers|assignable=true}
        {approval:Revert from In Review to Draft|user=@Author@}
    {state}
    {state:In Approval|approved=In QA Approval|updated=Draft}
        {approval:Assigned approvers|assignable=true|credentials=2}
        {approval:Revert from In Approval to Draft|user=@Author@}
    {state}
    {state:In QA Approval|approved=Approved and pending training|updated=Draft}
        {approval:Assigned QA approver|user=@QA approver@|credentials=2}
        {approval:Revert from In QA Approval to Draft|user=@Author@}
    {state}
    {state:Approved and pending training|updated=Draft|expired=Published|taskable=true|duedate=PT2M|changeduedate=true}
    {state}
    {state:Published|final=true|updated=Draft}
    {state}
    {comment}
    *************************************
    ********************** Triggers
    *************************************
    {comment}
    *************************************
    **** the user who cause the page to go into draft mode, is assigned to be the "author" in the workflow.
    **** because of the other constraints in the workflow, an author can change only when a page is published 
    **** and the work on the next version is initiated, not in midst of a review/approval cycle.
    *************************************
    {comment}
    {trigger:statechanged|state=draft}
        {set-metadata:Author}@user@{set-metadata}
    {trigger}
    {comment}
    {comment}
    *************************************
    **** If training is not required, move directly to publishing.
    *************************************
   {comment}
    {trigger:statechanged|state=Approved and pending training|@Training@=!Required}
        {set-state:Published}
    {trigger}
    {comment}
    *************************************
    **** If "only QA" needs to approve, skip the "In Approval" state.
    *************************************
    {comment}
    {trigger:statechanged|state=In Approval|@Who needs to approve@=Only QA}
        {set-state:In QA Approval}
    {trigger}
    {comment}
    *************************************
    **** Publish the page to the "published space". This depends on the Comala Publishing plugin.
    *************************************
    {comment}
    {trigger:statechanged|state=Published}
        {publish-page}
    {trigger}
    {comment}
    *************************************
    **** A bunch of triggers to send emails on approval assignments to the concerned users.
    *************************************
    {comment}
    {trigger:pageapprovalassigned|approval=Assigned reviewers}
        {send-email:user=@assignee@|subject=@content:title@, is pending your review}
        The latest draft can be viewed here: @pagelatest@
        {send-email}
    {trigger}
    {trigger:pageapprovalassigned|approval=Assigned approvers}
        {send-email:user=@assignee@|subject=@content:title@, is pending your approval}
        The latest draft can be viewed here: @pagelatest@
        {send-email}
    {trigger}
    {trigger:statechanged|state=In QA Approval}
        {send-email:user=@QA approver@|subject=@content:title@, is pending your approval}
        The latest draft can be viewed here: @pagelatest@
        {send-email}
    {trigger}
    {comment}
    *************************************
    **** A bunch of triggers to send emails on approval events. 
    **** Note the way that the Full Name of the user is retrieved.
    *************************************
    {comment}
    {trigger:pageapproved|approval=Assigned reviewers}
        {set-metadata:usertmp}@user@{set-metadata}
        {send-email:user=@Author@|subject=@content:title@, review by @workflow:metadata > usertmp > full name@ completed}
        The latest draft can be viewed here: @pagelatest@
        {send-email}
    {trigger}
    {trigger:pageapproved|approval=Assigned approvers}
        {set-metadata:usertmp}@user@{set-metadata}
        {send-email:user=@Author@|subject=@content:title@, approval granted by @workflow:metadata > usertmp > full name@}
        The latest draft can be viewed here: @pagelatest@
        {send-email}
    {trigger}
    {trigger:pageapproved|approval=Assigned QA approver}
        {set-metadata:usertmp}@user@{set-metadata}
        {send-email:user=@Author@|subject=@content:title@, QA approval granted by @workflow:metadata > usertmp > full name@}
        The latest draft can be viewed here: @pagelatest@
        {send-email}
    {trigger}
    {comment}
    *************************************
    **** A bunch of triggers to send emails to author in regards to rejection events.
    *************************************
    {comment}
    {trigger:pagerejected|approval=Assigned reviewers}
        {set-metadata:usertmp}@user@{set-metadata}
        {send-email:user=@Author@|subject=@content:title@, was rejected by @workflow:metadata > usertmp > full name@}
        The latest draft can be viewed here: @pagelatest@
        {send-email}
    {trigger}
    {trigger:pagerejected|approval=Assigned approvers}
        {set-metadata:usertmp}@user@{set-metadata}
        {send-email:user=@Author@|subject=@content:title@, was rejected by @workflow:metadata > usertmp > full name@}
        The latest draft can be viewed here: @pagelatest@
        {send-email}
    {trigger}
    {trigger:pagerejected|approval=Assigned QA approver}
        {set-metadata:usertmp}@user@{set-metadata}
        {send-email:user=@Author@|subject=@content:title@, QA approval rejected by @workflow:metadata > usertmp > full name@}
        The latest draft can be viewed here: @pagelatest@
        {send-email}
    {trigger}
    {comment}
    *************************************
    **** Apply edit restriction on a page during the review andapproval stages.
    *************************************
   {comment}
    {trigger:statechanged|state=In Review}
        {add-restriction:type=Edit|user=@Author@}
    {trigger}
    {trigger:statechanged|state=In Approval}
        {add-restriction:type=Edit|user=@Author@}
    {trigger}
    {trigger:statechanged|state=Published}
        {remove-restriction:type=Edit}
    {trigger}
    {trigger:statechanged|state=Draft}
        {remove-restriction:type=Edit}
    {trigger}
    {comment}
    *************************************
    **** Trigger the move of the page to draft during review/approval stages (as this can only done manually during the review and approval stages).
    *************************************
    {comment}
    {trigger:pageapproved|approval=Revert from In Review to Draft}
        {set-state:Draft}
    {trigger}
    {comment}
    *************************************
    **** Because of the fact that there is a second approval on this state (which allows the author to move the page to draft)
    **** then, in the case that the review is approved we need to proactively trigger the page into the next stage.
    *************************************
    {comment}
    {trigger:pageapproved|approval=Assigned reviewers}
        {set-state:In Approval}
    {trigger}
    {trigger:pageapproved|approval=Revert from In Approval to Draft}
        {set-state:Draft}
    {trigger}
    {trigger:pageapproved|approval=Assigned approvers}
        {set-state:In QA Approval}
    {trigger}
    {trigger:pageapproved|approval=Revert from In QA Approval to Draft}
        {set-state:Draft}
    {trigger}
    {trigger:pageapproved|approval=Assigned QA approver}
        {set-state:Approved and pending training}
    {trigger}
{workflow}

Some key points.

The role of ‘Author’ and the review process

‘Author’ is a workflow parameter. When a document is created, the role of Author is assigned to the user who created it, and is reassigned every time someone moves the page back into draft status. So, essentially, any person initiating a change becomes responsible for taking the document through to approval (see lines 81 etc).
The Author can edit a document without causing it to revert to draft. They may also choose to revert a page to draft by manually approving a ‘Revert to draft’ (see lines 201 etc.)
Only the Author has the permission to edit a page while it’s in review (see lines 176 etc).

Note that, for edit restriction to work properly, the configuration parameter of ‘Space Tools > Workflows > Configuration tab > Workflow Activity and Drafts Visibility’ needs to be changed to ‘Anybody’.

Use of workflow parameters to control the review and approval process

1. The identity of the default ‘QA approver’ – the person who needs to approve a document – can be changed for each document using the relevant workflow parameter.
2. Approval by ‘QA approver’ is obligatory, but only certain documents will need additional approval. In order to simplify the approval process where appropriate, you can just change the ‘Who needs to approve’ setting (see line 93 etc).
3. If training is required before a page can be published, you can set a fixed delay within intermediate status, using ‘Approved and pending training’ (see line 66). In the example we’ve set a delay of two minutes, but in reality this can be set to a week or more, as appropriate. Whether the delay happens or not will depend on the workflow parameter ‘Training’, which can be set to ‘Required’/’Not required’ (see the triggers in lines 85 etc).

Email notifications

Emails are sent automatically:

• to participants when their action is required (see lines 110 etc)
• and to the Author when the status of a document changes or when another user approves or rejects one of their documents (see lines 130 etc).

Getting started

For more details you can refer directly to Comala’s helpful guidance on using the plugin or send us an email.
If you would like assistance with implementing a controlled document approval process using Confluence and Comala Workflows, please get in touch.