Use Directive Sets
- Mike Harrison
- Ryan Clifton
- Andy Brook [Plugin People]
@since 1.9.32
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
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.
The notification recipient clicks on a Directive Set link in the email
The link sends a secure token to a JEMH REST endpoint that validates the token
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
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.
Directive Sets use Directives, so make sure you understand how they work before attempting to use this feature. If changes aren't applied:
Check the JEMH Auditing > Report does not show any problems
Validate the Profile referred actually has Directives enabled, and the appropriate Field Processor for the body format used, e.g. AtPrefix (the example used on this page)
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
Setting Name | Description |
|---|---|
Status | The status that the Directive Set will be saved in. If set to "disabled", subsequent links generated for the Directive Set will not be processed (but also not consumed). |
Name | The name of the Directive Set. This field is required, in order to help differentiate from others. |
Description | A description for the Directive Set can be added. This allows other administrators to understand its function. |
To Address | Enter the address which the directives should be sent to in order to be processed. This should usually be a "catch email address" on the target profile. |
Response TemplateSet | Allows selection of a template that will be used to render the response screen that a user is shown when they click on a directive set link. Information on creating these templates. |
Directive(s) | The directive content to be executed. It is recommended to enable the @prefix field processor, and use the respective format. An example is given when creating each Directive Set. |
The Directive Set link will redirect to the issue since 4.2.11 | If checked, the Directive Set link forwards the user to the related issue. Otherwise, if unchecked, the Directive Set link will forward the user to the Directive Set Response. |
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:
Example Variable | Example Value | Description |
|---|---|---|
$jemhDefaultDirectiveSetGroupId | 8f5f485b-7496-4f4b-a0fc-3e37269704bc | This is an id that is used to relate a set of links, such that when one link is used, the others are inherently expired/voided. An email may have several groups of links. |
$runAsUserKey | andy | This is the |
its the issue from the event, $issue | The Issue object the event is about, if you're in a post-function, you'll have to get a reference to start with. The $issue may vary over links. | |
10 | This integer value must refer a known ID value shown in the Directive Set section of the Notifications page. It refers to the set of Directives that will be applied. | |
5 | This integer value must refer a known profile ID value shown in the JEMH Profiles page. It will be the profile that will be used for processing the Directive Set defined in $directiveSetId, as the $runAsUserKey on the $issue |
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:
Parameter | Type | Description |
|---|---|---|
LABEL | String | The text that will show for the hyperlink in the notification. |
RUN AS USER KEY | String | This is Key of a Jira user that the Directives will be sent by. This needs to be a user who is allowed to perform the issue actions that the directive is for. Here you can use |
DIRECTIVE SET ID | Integer | The ID number of the Directive Set that this link is to be associated with. You can find this ID number by going to the Notifications>Directive Sets section and viewing the ID's in the first column. |
PROFILE ID | Integer | The ID number of the target profile that will process the directives in the Directive Set. The profile must be configured to have directives enabled, and the @prefix field processed enabled (if using the directive format in these examples). |
Here is an example macro call with the relevant values
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:
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 custom notification template.
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:
For this example we are using the following:
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:
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 HTML Template Set as follows:
The field customfield_10301 is just an example - be sure to use the actual custom field ID of the field you are using to store non-Jira user addresses.
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 HTML TemplateSet as follows:
Combining the pieces of HTML and dynamically deciding which piece to use
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.
Use Template Set previews to generate test links that can be used to validate behaviour on the 'Preview Context' issue.
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:
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):
Parameter Name | Description |
|---|---|
LABEL | This parameter is the text that will show for the hyperlink in the notification. |
RUN AS USER | This is the username of the Jira user that the Directives will be sent by. This needs to be a user who is allowed to perform the issue actions that the directive is for. In later versions of JEMH this will need to be the user key instead of the username you can retrieve the user key by the velocity context for example using the |
DIRECTIVE SET ID | This needs to be the ID number of the Directive Set that this link is to be associated with. You can find this ID number by going to the Notifications>Directive Sets section and viewing the ID's in the first column. |
PROFILE ID | This needs to be the ID number of the target profile that will process the directives in the Directive Set. The profile must be configured to have directives enabled, and the @prefix field processed enabled (if using the directive format in these examples). |
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:
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:
Reopening a closed issue - “The Directive Set link will redirect to the issue” example SINCE 4.2.11
The purpose of this example is to demonstrate the new “The Directive Set link will redirect to the issue” checkbox. By ticking the checkbox, email notifications containing DirectiveSet Links will redirect to the issue that the email notifications relates to, instead of your configured DirectiveSet Response TemplateSet.
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 DirectiveSet Link to Notification
Go to JEMH>Template Sets. Here, we will edit an existing custom template for the "Generic Event" issue event by selecting the edit action for the template.
The velocity macro is #generateDirectiveSetLink. The macro needs 4 parameters in order to work, and the parameters must always be in the same order:
For this example we are using the following:
We are going to add the link in a row wrapper, so the DirectiveSet link is styled correctly. We, also, will add an if statement that checks the status of the issue is “Resolved”.
Submit your changes to the template by pressing the "save" button. Then, select the template for the corresponding event in the Notification Project Mapping, and save changes:
Validate configuration
We will now check that we have configured the DirectiveSetLink correctly.
Template set preview (when status of the issue is not resolved):
We can use the preview in Template Sets > Issue Event > Edit to verify whether the Directive Set Link will redirect. In the below instance, the issue LIL-112 is set to “resolved”, so “Reopen ticket” does appear.
By clicking the “Reopened ticket” link, if configured correctly, the DirectiveSet will redirect us to the associated issue. For example:
Template set preview (when status of the issue is resolved):
In this instance, in the preview inside Template Sets > Issue Event > Edit, the issue LIL-112 is not set to “Resolved”, so the Directive Set Link does not appear which is the expected outcome.
Email notification in email inbox sent by JEMH:
Similar to the template set preview, clicking “Reopen ticket” in an email notification will redirect us to the issue in Jira and apply the directive “@workflow=In Progress”.
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:
Which can be invoked with (here, when status is In Progress)
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
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:
So, the template script looks something like:
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!)
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.
Some explanatory screenshots:
The defined Directive Sets in my example:
The notification with the styled button
The mailto link
The mail received by JEMH
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 - Since 4.1.10
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:
Enabling Filter
Go to Profile > Message Filters
Scroll until you see Directive Set Reply Filter and then change the toggle to Enabled
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.