Plugin installation

The Ovyka Advanced Notifer for JIRA plugin is provided as a JAR file.

To install the plugin, go to JIRA Add-ons administration, and select the Manage Add-ons page. On the page, click the Upload add-on button, select the Ovyka Advanced Notifer for JIRA JAR, and click OK.

Once the plugin is installed, a new menu appears in the Add-ons administration page left menu, as shown below (you may have to reload page if plugin was just installed).

Plugin configuration

The configuration of the Ovyka Advanced Notifer for JIRA plugin is divided in five configuration elements :

• Permissions : The Ovyka Advanced Notifer for JIRA plugin adds an email sending form to issue views. This form will only be displayed for users allowed to use the plugin. The Permissions administration screen allows you to select which users are allowed to use the Ovyka Advanced Notifer for JIRA plugin, and which user are allowed to administer the plugin.
• Recipients Lists : Recipients Lists allow you to define lists of email addresses to which notifications will be sent. In a recipeint list, you can define multiple TO, CC and BCC email addresses.
• Contexts : A Context defines which in which issues the Ovyka Advanced Notifer for JIRA email sending form will appear. It contains a list of projects, and a list of issue types. Issues in the selected project and with one of the selected issue types will have the mail sending form displayed.
• History : Notification history allow you to view sent notifications 

Permissions

The permissions screen allows you to see and add allowed users and administrators. The email sending form will be displayed only for users allowed to use the Ovyka Advanced Notifer for JIRA plugin. Allowed users are displayed as shown in screenshot below :

To add a user, just start typing the name of the user you want to add, and a list of matching users will appear, as shown below. Just continue typing to refine the matching users list, until you find the desired user.

That's it. As soon as the user is selected and displayed in Allowed users field, it is saved in the plugin configuration.

To add users to plugin administrators in addition to global administrators, you can add them to Ovyka Advanced Notifier for JIRA allowed administrators.

Recipients Lists

A recipient list is the list of email addresses to which notifications will be sent when this recipient list is selected in the email sending form (more on this later).

In the recipients lists administration screen, configured recipients lists are displayed as shown below.

To add a new recipient list, click the Add Recipient List button. A popup window will appear, as shown in the screenshot below.

In this window, you must enter a title and at least one address (TO, CC or BCC). If you want to enter more than one email address in one of the fields, enter one address per line. 

Please note that recipients lists titles must be unique. You cannot create two recipients lists with the same title.

Groups are not JIRA groups. They are groups of recipient lists. Groups allow to group several recipient lists together.

You can create groups to make sets of recipient lists.

• Enter a new or an existing group during recipient list creation or edition. 
• Recipient list without group are added to default group. 
• Groups must be unique.
• Groups will allow you to quickly send a notification to all recipient lists within that group ("select all" feature)

Once you click the Save button, your recipient list is added to the list.

Contexts

Contexts define for which issues the email sending form will be displayed. To define a context, you must select :

• a list of projects
  • you can select one project, multiple projects, or all projects
• a list of issue types
  • you can select one issue type, multiple issue types or all issue types
• a checkbox to allow or disallow commenting in issue when notifications are sent.

In the Context administration screen, contexts are displayed as shown below.

To add a context, click the Add Context button. A popup window will appear, in which you will be able to enter the context's title, issue types and projects. Please note that context titles must be unique. You cannot create two contexts with the same title.

To select an issue type, just begin typing and a list of matching issue types will be displayed, as shown in the screenshot below. Just continue typing to refine the list of matching issue types until you find the desired issue type.

To select a project, just begin typing and a list of matching projects will be displayed, as shown in the screenshot below. Just continue typing to refine the list of matching projects until you find the desired project.

For issue types and projects, if you want to select all issue types or all projects, do not enter anything in the corresponding field.

For example, in the screenshot below, we are creating a context :

• with title : My New Context
• that applies to issues of type Bug or Task
• that applies to all projects
• that will add a comment in the issue each time a notification is sent

Once saved, it appears in the contexts list as shown below.

Templates

The Templates administration screens allows you to create email templates.

An email template is an email in which you add placeholders that will be replaced by values extracted from the issue you send the mail from when the mail will be generated.

The Templates administration screen is divided in two parts : context and template selection, and template edition/creation.

Context and Template selection

The first part of the screen allows you to select the context to which this email template will be associated to. This means that this template will only be available in issues belonging to the selected context (project and issue type). It appears as shown below.

In the Select context field, a list of configured contexts is displayed. Select one of your contexts.

The Select template field has two usages. Once the context is selected, it will be filled with the list of already configured templates.

To edit an existing template, select it the the dropdown list. To create a new template, leave the Select template field empty.

Template creation

In the screenshot below, you can see the administration screen as it is when a context is selected, and no template is selected. This is the template creation mode.

Template title

Enter a title for your template. Please note templates titles are unique. You cannot create two templates with the same title.

Subject template

The subject template is the template of the mail subject. You can enter a line of text, and include placeholders if necessary (more on placeholders later).

Body template

The body template is the template of the mail body. Note that this is an HTML template. You can enter HTML code, or just plain text, but the mail that will be sent will have the text/html mime type. You can include as many placeholders as desired.

Issue to use for preview

Subject and body templates can be previewed, to allow you to see how the sent mail will look like. If placeholders are included, they will not be replaced in the generated preview.

If you want a more accurate preview of the mail that will be sent, you can select an issue in this field, and ask for a preview (more on this later). In the generated preview, placeholders will be replaced with values from the selected issue.

To select an issue, just begin typing, and a list of matching issues will be displayed. Just continue typing to refine the list of matching issues until you find the desired issue.

Template edtion

To edit an existing template, once the context is selected, select a template in the Select template field. In the lower part of the screen, the template title, subject and body will be displayed. You can then edit them and save your modification.

Template preview

Under subject and body template fields, a preview icon is displayed :  If you click this icon, the template will be replaced by its preview (this is the preview mode), and the icon will become like this : . Click the icon again to return to edition mode.

As an example, the screenshot below shows an html body template, in edition mode.

If you click the preview button, the template switches to preview mode, as shown in the screenshot below.

As you can see, the html code as been converted to an html page, which reflects how the mail body will look like.

Placeholders were not replaced, because we did not select any issue for preview. In screenshot below, you can see the same preview, with a preview issue selected.

As you can see, placeholders were replaced by values extracted from the selected issue.

Placeholders

Placeholders are predefined tags that can be added in templates, and that will be replaced in the generated emails by values from the issue the email is based on.

To get help about existing placeholders, click the question mark icon below the body template text area : . This will show the popup as displayed below.

The available placeholders are the following ones :

• [summary]
  • Replaced by the issue summary
• [description]
  
  • Replaced by the issue description
• [last-comment]
  
  • Replaced by the last issue comment
• [custom-field-XXX]
  
  • Replaced by the value of the custom field identified by its id (XXX must be replaced by the custom field value) in the processed issue.
  • If the field contains a date, the default format will be used : yyyy-MM-dd HH:mm:ss
• [custom-text]
  
  • Adds the custom text entered in the email sending form.
• [custom-field-XXX|yyyy-MM-dd HH:mm:ss]
  • Same placeholder as above, but with a date/time format. If the custom field contains a date, it will be displayed using the provided format.
• [issue.XXX]
  • Allows to include any issue field value. XXX must be replaced by the name of the field to extract. For example, to extract the issue creation date, the placeholder must be : [issue.created]
  • If the field contains a date, the default format will be used : yyyy-MM-dd HH:mm:ss
  • Available issue fields :
    • reporter : the issue reporter
    • assignee : the issue assignee
    • reporterId : the reporter username
    • assigneeId : the assignee username
    • created : the issue creation date
    • updated : the issue update date
    • resolution : the issue resolution status
    • status : the issue workflow status
    • priority : the issue priority
    • issueType : the issue type
    • votes : the number of votes of this issue
    • watches : the number of watchers for this issue
    • resolutionDate : the issue resolution date
    • dueDate : the issue due date
    • summary : the issue summary
    • description : the issue description
    • key : the issue key (for example DEMO-1)
    • affectedVersion : the list of affected version for this issue
    • fixVersions : the list of fix versions for this issue
• [issue.XXX|yyyy-MM-dd HH:mm:ss]
  
  • Same placeholder as above, but with a date/time format. If the issue field contains a date, it will be displayed using the provided format.

History

History allow you to consult sent notifications

• Date: date, time of the notification
• Sent By: user who sent the notification
• Issue: issue from which notification was raised
• Recipients Lists: the recipient(s) list(s) used
•  Context: the context used
• Template: the template used
• View: allow you to view the send notification

You can order the notification ascending or descending with following parameters: 

• Date
• Sender
• Context
• Template

Two icons can be displayed next to elements in the history :

•  : This element was deleted since notification was sent
•  : This element was renamed since notification was sent. You can move your mouse over the pen to see the new name, like this :

View sent notification

• Clic on the view button to see the notification detail
• The notification is also shown as a comment in the issue

Plugin usage

For tickets belonging to users not allowed to use the Ovyka Advanced Notifer for JIRA plugin or not belonging to one of the defined contexts, nothing special will appear in issue view.

For tickets belonging to a defined context and to one of the allowed plugin users , a new form will appear in issue view, as shown below.

As shown in the above screenshot, an allowed user can choose:

• a recipient list group
• one or several recipient list in this group (a list of email addresses to which the notification emails will be sent)
• the template of the notification (an email subject and body model to send to selected recipient list)

He can also add: 

• some custom recipients if needed in BCC (a list of email addresses separated by spaces to add to the configured email recipients)
• a custom text which will be add to the generated email if the [custom-text] placeholder is added into the template.

When you hit the Prepare email button, a popup opens with a preview of the email that will be sent, as shown below.

This preview shows the email that will be sent if you click the Send button. Once you click it, the mail is sent to all the addresses configured in the selected recipient list.