Driving JSM Approvals

Owned by Phil Evans
Last updated: Jan 26, 2022
7 min read

The example provided in Use Directive Sets | Managing an issue workflow. Was considered before JSD Approvals were created.

It is possible to create a custom template based on the current JSM Approval notification as of JEMH version 2.7.0.

 

Prerequisites

Ensure that your JSM Project is setup/contains an issue type with a workflow that implements JSM Approvals.

Software

JEMH Profile

Documentation

Shared Setup

Creating the Directive Sets for Approved and Rejected links.

Note that the status with Jira Service Desk Approvals in this example is called “waiting for approval” the status may be different depending on which status you have configured to have JSM approvals.

The directives involved in the approval transitions are:

  • @jsd.approval=waiting for approval - The workflow status where the target approval is configured to.

    • @jsd.approval.decision=rejected - Reject Decision

    • @jsd.approval.decision=approved - Approve Decision

To create your Approved Directive Set go to JEMH> Notifications >Directive Sets and select Create Directive Set and enter the directives shown in the screenshots below. 


Select Create.  You will now see your approval directive set.  Let's set another one up for the reject link:
Once the step below is complete move onto Adding links to Velocity Script Section

Ensure the correct custom field is set for your approvers.

Click the configure Link next to the Add Approval checkbox.

Add a pop up should appear similar to the one as shown below:

Ensure that the correct User Picker custom field is set.

JSM Approvals Custom Issue Event for Multiple User Picker.

In this section we will explore how to handle a multi-user approvals. Please ensure that you have done the prerequisites for this section namely configuring your JEMH Issue Event Notification as documented in Send notifications for Issue Events.

Step 1: Go through prerequsite setup.

Follow the aforementioned documentation: Driving JSM Approvals | Shared Setup

Step 2: Determine if a Custom Event is Necessary.

Firstly you will need to determine whether you need a custom event or modifying an existing issue event template set.

Issue Event.

If your Approval is configured to fire on the initial status during Issue Creation and ensure that approvals are configured correctly as shown below.

then you will need to create a custom Issue Created Event Template Set to replace your default Issue Creation.

Custom Event setup.

If your approval resides in a status without a fixed event then you will have to create a new Custom Event. JEMH can then create notifications based on this new Custom Event being fired.

Go to Administration > System > Events and Add a new custom event.

Edit your custom event as shown above. Add the event to the Notification Scheme related to your Project (which can be viewed/edited in Administration > Issues > Notification Scheme and click Notifications). Configured in JEMH Configuration > Notifications > Jira user notification Project Mapping > Notification Scheme

Go to to Administration > Issues > Custom Fields. Add your custom field containing the user entities required to recieve approvals to the Custom Event Notification Scheme (in this example the custom event is called “Second Approval”). Ensure that these are configured as a “User Picker (multiple users)” field you can do this by going

Please note that you should only add the custom field that contains users who are responsible for authorising approval requests. As by default the every user configured will receive the approval notifications.

Go to Project Setting > Issue Types > (Your Issue type with approvals configured) > Edit click on the status with approvals and Configure the Post functions of the transition before the status with approvals:


On the Post Function screen set the Event to be your Custom event to replace the Generic Event in this example.

To your custom event (Second Approval in this example).

Step 3: Create a Custom Template Set to the related Events.

Create a custom template based on event determined in Step 2

As per previous step: Driving JSM Approvals | Step 2: Determine if a Custom Event is Necessary. As shown below create a new Template Set based on the Event you wish to add the approval buttons to.

After you click the Create button then you must add your velocity link as described in Use Directive Sets | Adding links to Velocity Script .

Create the Velocity Snippet to render Approval Links.

Setup the user ID variable

The run as user key id will be the recipient user as the appropriate users will be notified as we set up previously.

In your template set HTML section you will the following velocity snippet to retrieve the current recipient key and use the user key as the run as user.

#set ($userKeyId = "$recipientUser.getKey()")

For information on how to use Template Sets please refer to prerequisites in the beginning of the document.

Use the generateDirectiveSetLink Macro to render links

In your velocity you need to replace your run as user id with the variable above (the snippet below is an example please refer to Use Directive Sets | Adding links to Velocity Script on how to set up your link)

#rowWrapperNormal("#generateDirectiveSetLink('Approve', $userKeyId ,1, 3) ")

Ensure that only approvers will recieve the Approve/Reject link.

Ensure that the code is wrapped with a condition such that only approvers can see the links

##Check if recipient is a jira user #set($recipientUser = $jemhUtils.getUserByEmail($recipientAddress)) #if($recipientUser != $null) #set($myApproversCustomField = $customFieldManager.getCustomFieldObject("customfield_10122").getValue($issue)) ##Check if jira user is an approver #if($myApproversCustomField.contains($recipientUser)) #rowWrapperNormal("#generateDirectiveSetLink('Approve', $userKeyId, 1, 3)") #rowWrapperNormal("#generateDirectiveSetLink('Reject', $userKeyId, 2, 3)") #end #end

Then in JEMH Configuration > Notifications > Jira user notification Project Mapping > Event Template Selection set the template to be your custom template set.

Step 4: Validate the email was created.

Run a test case (more information here: Use a TestCase for quick testing) to validate that approval links are being generated.

JSM Approvals via Post Function (Not Suitable for multiple approver users).

Please note that If the custom field containing the approvers is a multi user picker then using Post Functions to drive JSD approvals isn’t the best way. The reason is currently JEMH Post Function messages do not send a unique email to each recipient like the JEMH Issue Event Notifications but instead adds each recipient to a single email. In this case It is best to use custom event in conjunction with JEMH Notifications as described in this section.

Step 1: Go through prerequsite setup.

Follow the aforementioned documentation: Driving JSM Approvals | Shared Setup

Step 2: Create the Directive Sets for Approved and Rejected links.

Please follow the previous section which sets up the directive sets to be used in your template set or custom velocity context. Ensure that the transition where the post function is set is a transition leading to the Approval Status as shown in the example below:

In this example the approval status is called the “Waiting for approval”. The transition we are focusing on in this example is the “Create Issue” transition where the Post Functions will be set.

Step 3: Create a velocity snippet to add Directive Set links to your Adhoc Template Set.

Ensure that only one recipient is present which the approver user picker customer field. This ensures that only the intended user receives the approval.

For a post function adding to the Custom Content or selecting an Adhoc template set containing the following velocity snippet: