Introduction

Directive Sets are groups of one or more pre-defined Directives that can be triggered by clicking a secure one-time link rendered in an email notification.

This allows simple and safe issue changes to be made by notification recipients without the need to write a reply.  These changes can be anything from simple custom field value changes, to more complex workflow manipulation.

The links generated only contain a security token.  No other parameters are present, meaning that the links can only be used for the intended purpose, one link per action.  A single notification email can have many of these links, allowing a choice of field values or actions to be made by the end user.

How it works

1. An Issue Event occurs, rendering a custom Template Set (selected in the Notification Mapping).  As part of that template, unique links are rendered (see below for more information) for a specific Directive Set.  The notification is then sent to the recipient.

2. The notification recipient clicks on a Directive Set link in the email

3. The link sends a secure token to a JEMH REST endpoint that validates the token

4. If the token is valid, the corresponding set of directives are sent as a Test Case to the configured To: address and profile for processing

5. Once the processing has completed, a result screen to the user indicating if execution was successful or not. This result screen can be customized by creating and setting a Directive Set Render Result Template Set.

Terminology

Directive Sets

Allow users to perform defined Issue Directives by just clicking a link (called a Directive Set Link) generated in an email notification.  Directive Set's can be enabled or disabled - links will only be consumed if the parent Directive Set is enabled.

Directive Set Links

These are the hyperlinks that are associated with a Directive Set and are validated using single-use tokens, meaning that only recipients of the notification will be able to use the Directive Set.

Each link in a single outbound notification is put in a Link Group which is unique to that recipient.  Once a link has been processed by JEMH, it (and others in that link group) will expire.  If 30 days pass without a link from an individual notification being processed, then this will also cause all related links to expire.

Create Directive Set

This is where you specific the Directives that will be used to update the fields you require. This is found within the Notifications tab in JEMH.  You should see a section called Directive Sets.  Select Create.  You will then be taken to the creation screen:

Configuration Options

Notification templates

The DirectiveSetManager can be interacted with as $jemhDirectiveSetLinkManager below, to call createDirectiveSetLink (this comes pre-built into JEMH's global macros, the below code does not need to be added):

## DirectiveSetLink support
#set ($jemhDefaultDirectiveSetGroupId = $jemhDirectiveSetLinkManager.getDirectiveSetLinkGroupId())
#macro(generateDirectiveSetLink $label $runAsUserKey $directiveSetId $profileId)
  #set ($jemhDirectiveSetRestApiUrl= $jemhDirectiveSetLinkManager.createDirectiveSetLink($jemhDefaultDirectiveSetGroupId, $runAsUserKey, $issue, $directiveSetId, $profileId) )
  <A href="$jemhDirectiveSetRestApiUrl">$label</A>
#end

The Parameters to this are as follows:

$jemhDefaultDirectiveSetGroupId

$runAsUserKey

$issue

$directiveSetId

$profileId

Adding Link to Notification

Go to JEMH>Template Sets.  Here, you will edit the Template to include the macro call for #generateDirectiveSetLink which will add the Directive set link to notifications. This Macro needs 4 parameters in order to work, and the parameters must always be in the following order:

#generateDirectiveSetLink(LABEL,RUN AS USER Key,DIRECTIVE SET ID,PROFILE ID)

Here is an example macro call with the relevant values

#generateDirectiveSetLink('test',$userManager.getUserByName('admin').getKey(),1,16)

If your template is based off the built in JIRA style, you will most likely want to add the links within a "row wrapper" in order for the notification styling to not be broken:

#rowWrapperNormal("#generateDirectiveSetLink('test',$userManager.getUserByName('admin').getKey(),1,16)")

Example Scenarios

As a Directive Set can be configured with any valid Directive there are many ways that this feature can be used, here are just a few example scenarios:

Changing an issue Assignee

Lets say that you want a nice link in a notification that assigns the issue to the user Big Bob.

Create Directive Set

Go to the Notifications tab in JEMH.  You should see a section called Directive Sets.  Select Create.  You will then be taken to the creation screen:

Here we will set up our Directive Set as follows:

Select Create.  You will then be brought back to the main Notifications page where you should see your new Directive Set:

Add Link to Notification

Now we are going to add the link generating velocity macro to a /wiki/spaces/JEMH/pages/2850840.

Go to JEMH>Template Sets.  Here, we will edit an existing custom template for the "Issue Created" issue event by selecting the edit action for the template.

The velocity macro that will be called is #generateDirectiveSetLink.  It needs 4 parameters in order to work, and the parameters must always be in the same order:

#generateDirectiveSetLink(LABEL,RUN AS USER KEY,DIRECTIVE SET ID,PROFILE ID

For this example we are using the following:

#generateDirectiveSetLink('Assign To Bob','admin',41,26)

We are going to add the link in a row wrapper in this case, in order for the link to sit in the JIRA styled layout correctly.

Submit your changes to the template by pressing the "Submit" button.  Then, select the template for the corresponding event in the Notification Project Mapping, and save changes:

Validate Configuration

Now, when an issue is created, the notification recipients will get a notification with the Directive Set Link that we added to the template:

The recipient then clicks the link, and is taken to a page where they are given a response:

If you now check the issue, you will see that the assignee has been changed to the username defined in the Directive Set's assignee directive:

Implementing a Customer Satisfaction feature

If you have Jira Service Desk and want to get its built-in customer satisfaction feature working with JEMH notifications, see how to add customer satisfaction feedback to a service desk notification template.

For those who do not have Service Desk installed, a similar thing can be achieved using JEMH. In this scenario, we just show how to set a select custom field value, which will be done 'as' the user who is receiving the notification, whilst only one directive is shown, more could be added if needed.

Using a Select custom field, with values UNHAPPY, OK and HAPPY, we can create 3 Directive Sets, here using the AtPrefix Directive format:

Create Directive Set

This field has an ID of 10200, so can be selected as follows:

Apply Unhappy	Apply OK	Apply Happy

After creating, they are listed:

Setting up the template

Under Template Sets >User Macros, the following example velocity macro can be defined that in this case uses images stored on the Plugin People CDN:

##
## example #generateCSAT('admin', 1, 1,2,3)
## arg1: userkey, arg2: profileID, arg3: unhappyDsId, arg4: okDsId, arg5: happyDsId
##
#macro(generateCSAT $runAsUserKey, $profileId, $unhappySetId, $okSetId, $happySetId)
<div>
    <B style="vertical-align:bottom;">How did we do?</b>&nbsp;
    #set ($jemhCSATDirectiveSetGroupId = $jemhDirectiveSetLinkManager.getDirectiveSetLinkGroupId())
    <A HREF="$jemhDirectiveSetLinkManager.createDirectiveSetLink($jemhCSATDirectiveSetGroupId, $runAsUserKey, $issue, $unhappySetId, $profileId)"><img src="http://cdn.thepluginpeople.com/prod/images/system/template/smiley_unhappy.png" title="Unhappy" style="width:32px;height:32px;"></img></a>
    <A HREF="$jemhDirectiveSetLinkManager.createDirectiveSetLink($jemhCSATDirectiveSetGroupId, $runAsUserKey, $issue, $okSetId, $profileId)"><img src="http://cdn.thepluginpeople.com/prod/images/system/template/smiley_meh.png" title="ok" style="width:32px;height:32px;"></img></a>
    <A HREF="$jemhDirectiveSetLinkManager.createDirectiveSetLink($jemhCSATDirectiveSetGroupId, $runAsUserKey, $issue, $happySetId, $profileId)"><img src="http://cdn.thepluginpeople.com/prod/images/system/template/smiley_happy.png" title="Happy" style="width:32px;height:32px;"></img></a>
</div>
#end

Template HTML for non Jira-users

This implementation of the above generateCSAT macro will only generate the customer satisfaction feature on the notification sent to the issue creator and can be invoked in a /wiki/spaces/JEMH/pages/2850840 as follows:

#if ($!recipientEmail && $recipientEmail == $issue.getCustomFieldValue("customfield_10301"))
    #set ($runAsUserKey = $issue.getAssignee().getKey())
    #set ($profileId = 2)
    #set ($unhappySetId = 2)
    #set ($okSetId = 3)
    #set ($happySetId = 4)
    #set ($csatBody="#generateCSAT($runAsUserKey, $profileId, $unhappySetId, $okSetId, $happySetId)")
    #rowWrapperNormal($csatBody) 
#end

Template HTML for JIRA users

This implementation of the above generateCSAT macro will only generate the customer satisfaction feature on the notification sent to the issue reporter and can be invoked in a /wiki/spaces/JEMH/pages/2850840 as follows:

#if ($!recipientUser && $recipientUser.getKey() == $issue.getReporter().getKey())
    #set ($runAsUserKey = $recipientUser.getKey())
    #set ($profileId = 2)
    #set ($unhappySetId = 2)
    #set ($okSetId = 3)
    #set ($happySetId = 4)
    #set ($csatBody="#generateCSAT($runAsUserKey, $profileId, $unhappySetId, $okSetId, $happySetId)")
    #rowWrapperNormal($csatBody)
#end

Combining the pieces of HTML and dynamically deciding which piece to use

#if ($issue.getCustomFieldValue("customfield_10301") != $null)
    #if ($!recipientEmail && $recipientEmail == $issue.getCustomFieldValue("customfield_10301"))
        #set ($runAsUserKey = $issue.getAssignee().getKey())
        #set ($profileId = 2)
        #set ($unhappySetId = 2)
        #set ($okSetId = 3)
        #set ($happySetId = 4)
        #set ($csatBody="#generateCSAT($runAsUserKey, $profileId, $unhappySetId, $okSetId, $happySetId)")
        #rowWrapperNormal($csatBody) 
    #end
#else
    #if ($!recipientUser && $recipientUser.getKey() == $issue.getReporter().getKey())
        #set ($runAsUserKey = $recipientUser.getKey())
        #set ($profileId = 2)
        #set ($unhappySetId = 2)
        #set ($okSetId = 3)
        #set ($happySetId = 4)
        #set ($csatBody="#generateCSAT($runAsUserKey, $profileId, $unhappySetId, $okSetId, $happySetId)")
        #rowWrapperNormal($csatBody)
    #end
#end

The two pieces of HTML can be placed inside an IF statement that checks whether the custom field used to store the sender email address of a non-Jira user is null. If the field is found NOT to be null, then the template will execute the non Jira user HTML. Otherwise, if the field is found to be null then the Jira user HTML will be executed.

Here is an Issue Resolved Template Set with the macro call:

The preview (in context of Issue TEST-2), shows the section added:

Validate configuration

The hyperlink that is present on the notification should be similar to this format:

http://jira.example.com/rest/jemh/latest/public/directiveset/invoke?token=6e1e9d8fb70649fc81cd1c70ba1e33cc3db62add794146068ee83b17d435b9d6

When the link is opened, a simple success page should be shown:

Reviewing the issue screen, the field has been set, which now allows Dashboard Pie Charts widgets to be driven from this value:

Managing an issue workflow

This scenario shows how the Directive Sets feature can be used to make managing issue workflows with JEMH quicker and easier.  Check out the workflow below.  This could be a workflow for approval of user requests that require approval from 2 different people.  The issue might be assigned to a 1st line manager when it is first created.  That assignee will then either reject the request or approve it, assigning it to the 2nd manager for final approval:

We can make the task simpler by providing 2 hyperlinks in the notification that the manager receives - Approve or Reject.  We will focus on the "1st approval" to begin with.  We will first need to set up our directive sets, including workflow directives where appropriate:

Go to JEMH>Notifications>Directive Sets and select Create Directive Set.  Set the status to enabled, add a name, description and add your directives.  The template set can be left as it is for now, we will show how these are added later in this guide.

Select Create.  You will now see your approval directive set.  Let's set another one up for the reject link:

Again, click Create to save the directive set.

Next step is Adding Links to the Velocity Script.

Adding links to Velocity Script

Now, we add the velocity script to our "Issue Created" template set that provides the 2 links:

Go to JEMH>Template Sets and edit/create the template.  The velocity script needed is of the following format (note that this is for generating 2 links):

#generateDirectiveSetLink(LABEL,RUN AS USER,DIRECTIVESET ID,PROFILE ID)

If your template is based off the built in JIRA style, you will most likely want to add the links within a "row wrapper" in order for them to not break the notification styling:

#rowWrapperNormal("#generateDirectiveSetLink('Approve','admin',45,26)   |   #generateDirectiveSetLink('Reject','admin',46,26)")

Submit your changes to the template.  Make sure that the custom template is selected for desired event.  In this example scenario we have chosen the "Issue Created" event.

Testing

On issue creation the assignee gets a notification with generated links:

In this example scenario, the manager was not keen on the giraffe being brought to the office.  On clicking Reject they are shown a response screen (below, default response template is used):

If we take a look at the issue, we can see that the directive has been successfully processed and the issue has been transitioned to the "Rejected" status:

JSD Approvals

This scenario Driving JSM Approvals. shows how the Directive Sets feature can be used to drive Jira Service Desk Approvals. Read more about Jira Service Desk Approvals here.

Customizing the link presentation

Use Atlassian’s UI library to render buttons instead of links

Links can be replaced with other elements, such as buttons. See the Atlassian User Interface documentation for more information. As an example:

#macro(generateDirectiveSetButton $label $runAsUserKey $directiveSetId $profileId, $isPrimary)
  #set ($jemhDirectiveSetRestApiUrl= $jemhDirectiveSetLinkManager.createDirectiveSetLink($jemhDefaultDirectiveSetGroupId, $runAsUserKey, $issue, $directiveSetId, $profileId) )
    <A href="$jemhDirectiveSetRestApiUrl"><button class='aui-button #if ($isPrimary==true)aui-button-primary#end'>$label</button></A>
#end

Which can be invoked with (here, when status is In Progress)

#if ($issue.getStatusObject().getName()=='In Progress')
    #set ($approveDeclineBody="#generateDirectiveSetButton('Approve (resolve issue)', $issue.getReporterId(), 3,9, true)    #generateDirectiveSetButton('Reject (stop progress)',  $issue.getReporterId(), 4,9, false)")
    #rowWrapperNormal($approveDeclineBody)
#end

When rendered, looks like:

Use in workflow

Combining the button example above, Here is a simple HTML template that could be used as the basis of a JEMH Workflow drive approval request

<html>
<body>
<h3>Approval Required</h3>
<p>Your action is require to approve or decline $issue.getKey(), the last comment was:</p>
<div>
<quote>
$wikiRenderer.render($comment.getBody(), null)
</quote>
</div>
<BR/>
<div>
#if ($issue.getStatusObject().getName()=='In Progress')
    #set ($approveDeclineBody="#generateDirectiveSetButton('Approve (resolve issue)', $issue.getReporterId(), 3,9, true) &nbsp;&nbsp; #generateDirectiveSetButton('Reject (stop progress)',  $issue.getReporterId(), 4,9, false)")
    #rowWrapperNormal($approveDeclineBody)
#end
</div>
</body>
</html>

Such a notification would look like:

Adding a custom response template

By default, JEMH will use its own built in template.  A custom template can be created, by going to JEMH>Template Sets and clicking the Directive Set Response tab.  Then, click the + add button to create a new template.  Click the pen icon  to edit the template.

Once a Template is created, you will then need to select that template within the relevant Directive Set:

Enabling Directive Sets for recipients without direct Jira network access

 Since JEMH 3.0.0, 2.7.16+

When recipients don't have direct network access to Jira, the Directive Set approach above clearly won't work (it uses full URL's). So, in this variation we change how this works:

• we generate mailto: links instead of direct http: links in the initial outbound email, to reply the required Token in the subject of the email

• we add some detection code in the Script Field Processor, identify such email and extract the token.  Then, we invoke the REST URL 'anonymously' jsut as if the remote user had clicked on it directly.

Use mailto links

In the outbound notification, use a mailto: instead of using a direct http URL, with a modified macro:

    #macro(generateDirectiveSetButton $label $runAsUserKey $directiveSetId $profileId, $isPrimary)
    #set ($jemhDirectiveSetRestApiUrl= $jemhDirectiveSetLinkManager.createDirectiveSetLink($jemhDefaultDirectiveSetGroupId, $runAsUserKey, $issue, $directiveSetId, $profileId) )
    #set ($subIdx = $jemhDirectiveSetRestApiUrl.indexOf('token=')+6)
    #set ($mailTo = "blah@blah.com?subject=JEMH Automation - "+$label+" - JEMH_TOKEN=$jemhDirectiveSetRestApiUrl.substring($subIdx)")
        <A id="jemh-ds-$directiveSetId" href="mailto:$mailTo"><button class='aui-button #if ($isPrimary==true)aui-button-primary#end'>$label</button></A>
    #end

So, the template script looks something like:

#generateDirectiveSetButton('test',$userManager.getUserByName('admin').getKey(),1,16)

The recipient user will now be able to click approve/decline links which send the token in the subject back to Jira - it goes without saying that the mailbox must be processed by JEMH, leading into the next part.  The email text is shown here for illustration (end users wont see this!)

MIME-Version: 1.0
Received: by 10.223.112.12 with HTTP; Sat, 18 Jun 2011 22:42:26 -0700 (PDT)
Date: Sun, 19 Jun 2011 17:42:26 +1200
Message-ID: <BANLkTinB1mfSh+GwOXGNWoL4SyDvOpdBoQ@mail.gmail.com>
Subject: JEMH Automation - JEMH_TOKEN=dc99e9064ff9416ea33082c7dc4283d9529565e1261b4dfda3b9981bbcf70ee6
From: reporter@test.com
To: changeme@thiswontwork.com
Content-Type: text/plain; charset=UTF-8

this text will be ignored (currently)

Process using a custom Script within the Script Field Processor

Here we will scan the email for the required token prefix, and if found extract, and actually invoke the URL locally via jemhUtils.invokeLocalRest('/rest/....').  If it all works out, we will also indicate that the mock email that JEMH is currently processing can be dropped silently, as it would otherwise create issues for no reason.

print('hello world, below you can see some of the variables available in the rule context');

print('message obj is '+message);

print('subject is '+subject);

if (subject.indexOf('JEMH_TOKEN=')!=-1)
{
	resultMap.put("FORCE_JEMH_SCRIPTFP", true); //force the Script Field Processor to 'own' this message

    print('token bearing email found');
    var token=subject.substring(subject.indexOf('JEMH_TOKEN=')+11);
    var path = '/rest/jemh/latest/public/directiveset/invoke?json=true&token='+token; 
    var response = jemhUtils.invokeLocalAnonRest(path);
    if (response.has("success") && response.get("success").equals("true"))
    {
        print('DirectiveSet processing success');
        print('--\n'+response+'\n--\n');
        
        if (response.has('issue'))
        {
            print('issueKey: \n'+response.get('issueKey'));
        }
        if (response.has('name'))
        {
            print('directiveSet Name: '+response.get('name'));
        }
        if (response.has('description'))
        {
            print('directiveSet Desc: '+response.get('description'));
        }
        if (response.has('directives'))
        {
            print('directives: \n'+response.get('directives'));
        }

        jemhUtils.dropMessage('DirectiveSet mail automatically consumed'); // JEMH should not process the message, the message should be deleted silently from the mailbox
    }
    else if (response.has('jemhError'))
    {
        print('failed: '+response.get('jemhError'));
        jemhUtils.forwardMessage('DirectiveSet mail failed to be consumed due to error: '+response.get('jemhError')); // JEMH should not process the message, send to the 'forward' address, and delete the message from the mailbox
    }
    else
    {
        print('unknown response:\n'+response);
        jemhUtils.forwardMessage('DirectiveSet mail failed to be consumed, unknown reason'); // JEMH should not process the message, send to the 'forward' address, and delete the message from the mailbox
    }
}

Some explanatory screenshots:

The defined Directive Sets in my example:

The notification with the styled button

The mailto link

The mail received by JEMH

MIME-Version: 1.0
Received: by 10.223.112.12 with HTTP; Sat, 18 Jun 2011 22:42:26 -0700 (PDT)
Date: Sun, 19 Jun 2011 17:42:26 +1200
Message-ID: <BANLkTinB1mfSh+GwOXGNWoL4SyDvOpdBoQ@mail.gmail.com>
Subject: JEMH Automation - JEMH_TOKEN=6b014e4fffd24906b8436fe53e23a853e1449aee5d4446ebb9a3ea438ab6b9c4
From: doesntmatter@test.com
To: changeme@thiswontwork.com
Content-Type: text/plain; charset=UTF-8

Some example text

Test Issue prior to Directive Set

Test Issue post Directive Set execution

Showing the outcome of running the Directive Set to update the issue:

And if you do some testing within the Script field prod dynamic evaluator against a Test Case

If the Directive Set key cannot be found (e.g. its used/expired) you'll see:

Process email using Directive Set Message Filter -

As of JEMH 4.1.10+ you will be able to enable a message Filter that will auto detect if the subject of a incoming mail contains a Directive Set token and will then trigger this inbound mail to be dropped and will run and process the corresponding Directive Set email.

The emails that match on this Message Filter must contain “JEMH_TOKEN=DirectiveSetToken” within the subject. For example the following email:

MIME-Version: 1.0
Received: by 10.223.112.12 with HTTP; Sat, 18 Jun 2011 22:42:26 -0700 (PDT)
Date: Sun, 19 Jun 2011 17:42:26 +1200
Message-ID: <BANLkTinB1mfSh+GwOXGNWoL4SyDvOpdBoQ@mail.gmail.com>
Subject: JEMH Automation - test - JEMH_TOKEN=dc31cfa19d2f4b7c8decd5c4be2fc4c252ab4e040b9d4380a819950553fc6bc6
From: admin@localhost
To: mailbox@localhost
Content-Type: text/plain; charset=UTF-8

Transition Issue.

Enabling Filter

1. Go to Profile > Message Filters

2. Scroll until you see Directive Set Reply Filter and then change the toggle to Enabled

3. Then press Save

What happens when matched

When an incoming matches this Filter it will trigger that incoming mail to be dropped and the relevant Directive Set Link email to be triggered which will then update the issue.

This means that within JEMH auditing you will see that a mail was dropped/filtered and another email was then processed.

Within the Report of the dropped mail you will see that it was filtered by the Directive Set Filter.

Within the newly processed email you will see that it was matched by the Field Processor and updated the values defined in the Directive Set.

Related Articles