@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

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 `ApplicationUser.getKey()` value, e.g. $issue.getReporter().getKey() , the user will be the security context for the execution of the Directives. An email may have links with different context users.
`$issue`	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.
`$directiveSetId`	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.
`$profileId`	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:

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

Parameter	Type	Description

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 `$userManager.getUserByName('admin').getKey()` to get the key for a specific user.
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).

Use Directive Sets