Document Approvals, someone?

rootUncategorized

Introduction
Are you considering to use JIRA to support an approval process, but you’re not sure how to tackle it?  This page details an implementation we made for one of our customers using a bit of groovy scripting and the unbelievable essential ScriptRunner from Adaptavist.
The environment
This customer is one of these robust financial organizations where every project needs to be documented in full before implementation starts.  They have on average 2 releases per year and this approach proved to be very trustworthy and stable.  The team was looking for a way to formally approve these documents instead of managing these approvals in a manual way.

We proposed to use JIRA, enhanced with the ScriptRunner,  as it contains all functionality to implement the requirements
The customer document approval process has mainly 3 stages:

  • Drafting stage
    During the drafting stage, an author redacts the content of a document and once ready publishes it on JIRA.
  • Level 1 approval stage
    All documents need to be approved by a number of stakeholders in the IT department. Next, to the approvers, a number of people need to be kept up to date when new versions of the document are published.

    • Each approver can either approve or reject a document.  This individual action needs to be logged
    • The project manager can decide to either push the document back into review (because some of the comments need to be addressed) or approve the document and trump any people who have been rejecting the content
    • It must be easy for the stakeholders to express their opinion.  As most of them live their professional life in their email box, all interactions should be email based.
  • Level 2 approval stage
    Once that the level 1 approval has been reached, the document is promoted to the level 2 approval stage where the project management board decides on the final faith of the document.  Either it is approved, pushed back into a review or rejected.

The solution
We decided to use a practical approach to solving this requirement. After a team brainstorm, we came up with the following approach
The user picker custom fields
The user picker (multiple users) is a standard custom field part of JIRA.

image2016-5-6-18_35_5
This is a really nice control as it allows to collect multiple users into a single custom field

To support the approval workflow we created 4 different user pickers.

  • Approvers
    This list contains all users who must provide their approval for a document
  • Has accepted
    Will list all users who approved a document
  • Has declined
    These are the ones that asked to modify the document
  • Readers
    Are the people that need to be kept up to date
  • To Approve
    Are the people who still need to provide their opinion

The workflow
The complete approval workflow can now be implemented by using a script which moves users from one user list to another.

  • When a user approves the document, his/her userid will be moved from ‘To Approve’ to ‘Has Accepted’
  • When a user refuses the document, his/her userid is moved from ‘To Approve’ to ‘Has Declined’
  • When a document is submitted for review, the ‘To Approve’ list is initialized from the ‘Approvers’ List

image2016-5-6-18_30_26

Submitting a document.

The status ‘open’ denotes the drafting stage and it is the first status in the workflow. Once that the author of the document considers the content fit for review, s/he will progress the document issue to the ‘SENT’ status.

image2016-5-6-18_32_36
The author can still add / remove users from the approvers/readers list and press send.
image2016-5-6-18_48_48
The groovy script copies all the users listed in the ‘Approvers’ list to the ‘To Approve’ custom field. The workflow triggers a custom event ‘Document Sent’ which is translated into a notification for all users in the ‘To Approve’ custom field.
To approve or to reject – that’s the question

The workflow has 2 transitions in status ‘Sent’ – Approve or Reject
image2016-5-6-22_24_24
These transitions are only accessible for the users which are in the ‘to approve’ list. Depending on the chosen transition, the userid will be copied from the ‘to approve’ list to either the ‘has approved’ or ‘has declined’ list. A notification is sent to the project manager

Auto transitioning issues

One of the requirements of the customer was that once that all approvers approved the document, it would go automatically to status ‘Approved’. To implement this requirement, we used the ScriptRunner escalation service. This service runs every couple of minutes, triggering an ‘autoApprove’ transition on every issue which matches following jql

issuetype = Document and 'To approve' is empty and 'Has declined' is empty and 'Has accepted' is not empty and status = sent

image2016-5-6-22_29_39
Sending notifications

Given the email orientation of the users, we decided to enhance the notifications such that

  • The notification message contains all attachments related to the document issue
  • The message contains a link to trigger an approval and a trigger to reject the document
    The advantage is that the user now can read the document and click one of both links.

Keeping track of the approval history
One of the requirements was to ensure that the complete approval history would be tracked. Given that comments are also used for providing feedback on the document, we decided to create a custom field ‘Approval Comment’ which is used to collect the history.

Wrapping up
Using the ScriptRunner from Adaptavist, it is possible to create, in a simple way, pretty advanced customizations.
The system is in use by more than 500 users, for a couple of years now. The ROI of the solution was a couple of weeks.

The code behind it all
The whole solution is groovy based. Check out following links for some examples how the logic has been constructed

  • setApprovers.groovy
    The setApprovers.groovy is a simple script which copies the content of the approvers and readers project role to the corresponding approvers and readers user list. This way one can define on a project level the approvers and readers of any document created in the context of that project
  • ApprovalLogic.groovy
    The approval logic is all contained in a single class.  It contains methods for the different use cases such as

    • doAccept – used when the current user accepts a document
    • doDecline – used when the current user declines the document
    • delegateTo – the workflows allows a user to delegate the approval to a colleague.  This method will then rearrange the content of the different user lists
    • changeApprovers – used when the approverslist changes, taking into account past history of approvals
  • SendCustomEmailWithUniqueAttachments.groovy
    This class is an enhanced ‘SendCustomEmail’ script listener, which will filter out duplicate attachments.  The issue is that users tend to upload multiple versions of the same attachment and you want to send only the latest version.
    You need to add it to the right path (ie under your script root …/com/onresolve/scriptrunner/canned/jira/workflow/postfunctions) and restart ScriptRunner. It will be picked up automatically and be available as one of the options on the script listeners

image2016-5-12-9_34_35

Script Plugin

To simplify the deployment of this code we opted to create a script plugin – which is actually like a JIRA add-on but then using the groovy classes as resources. It is straightforward to do and well described on the documentation site: https://scriptrunner.adaptavist.com/latest/jira/creating-a-script-plugin.html

Are you still using multiple issue trackers?

Check out exalate https://www.exalate.com – Exalate is an advanced issue synchronization solution which supports cross organization issue tracking.
Its flexibility comes from the built in groovy scripting capability allowing to implement almost any type of integration.
slide07

Support anyone ?

You can always contact us to help out with the implementation of your use cases, just contact us.