What Are Contexts?
Contexts connect various configurations and settings to a Scope. The scope of a Context may be composed of:
- A project (optional)
- An Issue Type (optional)
- JQL filter (optional)
The scope determines which issues the Context is applicable for; these are displayed in the Contexts menu in an expandable list.
To create a new Context, click on the Add button:
Context Attributes
Context attributes have four main aspects:
- the scope for which the context is set (project/issue type/JQL)
- the content that is applicable to the scope
- Email This Issue notifications applicable to the scope
- additional settings within the scope
Context scope
The scope maps all the context settings to a certain project/issue type/JQL or a combination of these.
| Attribute | Description |
|---|---|
| Project | Defines the project to which the context is applied. Applied to all projects if left empty. |
| Issue Type | Defines the issue type to which the context is applied. Applied to all issue types if left empty. |
| JQL Filter | Defines a JQL condition to match the set of issues the context may be applied to. JQL Filter with combination of Project and Issue Type selected is used to determine if the Context is applicable to an Issue being sent in an email. |
| Description | A description of the Context. |
| Order | Defines the order in which the Contexts configured with the same combination of Project and Issue Type are evaluated (see Examples further below). |
Content and Notifications
The content of a context specifies templates and canned responses to be used when sending manual emails.
| Attribute | Description |
|---|---|
| Template | Defines the default Email Templates JETI will use when emails are sent. The template selected here is not visible on the email screen's editor, it can be thought of as a 'frame' for your emails. |
| Mail Body Initializer Template | A template used to initialize email subject and body on the email screen that opens via the Email button. How to use Mail Body Initializer Templates. |
| Template Categories | Categories are groups of Email Templates that are made available in the email screen to choose from. Once selected here, users are able to choose a template from the given category on the email screen's dropdown list. |
| Notification | Defines issue Event Notifications for the context. This may work alongside Jira Notification Schemes but it allows you to fully customize notifications. |
Either a Template or a Notification is mandatory. You cannot create "empty" contexts without one of these.
Additional Settings
Additional content settings allow you to further configure options for your outgoing emails.
| Attribute | Description |
|---|---|
| Field for External Watchers | Text custom field where non-Jira user email addresses will be saved if the "Add recipients to watchers" options is enabled. |
| Sender Name Pattern | Velocity markup pattern to format a sender name in outgoing emails. E.g. if you don't want to show the name of real users as the sender of emails, you can include the project name or the value of a custom field. |
| From Address Pattern | Velocity markup pattern to format the From Address in outgoing emails. E.g. if you don't want to show the name of real users as the sender of emails, you can include the project name or value of a custom field. |
| Reply-To Address Pattern | Velocity markup pattern to format the Reply-to Email Address in outgoing emails. This is very useful if your IMAP and SMTP server addresses are different. |
| Bcc Address | A single email address, if specified, will be added as a Bcc recipient in all emails sent via this Context. |
| Email Details in Comments | Option to set whether comments should include the email details (such as To:, From:, Attachments in the email etc.). |
| Send Individual Emails | Enable this if you want each recipient to receive a separate email instead of sending a single email to all recipients. |
| SMTP Connection | Select the SMTP connection to be used to deliver emails via this Context. Default is Jira's outgoing mail setting.SINCE 7.1.1.17 |
| Email Headers | Custom Email headers of outgoing emails may be set using this attribute. The field should contain email headers in the format of headername:headervalue, multiple headers should be entered one per line. Find more details on how email headers are set in outgoing emails. SINCE 8.0.6
|
Context Resolution Algorithm
There may be multiple contexts applicable for an issue. The best-matching context is selected for each issue to determine the email template or notification rules that apply to that issue.
Contexts are resolved from the strongest to the weakest match. Here are the steps performed:
- Find all Contexts that are configured with a project and an issue type, and iterate through each of them in the order of the Order attribute (see above):
- if the Context that is being evaluated has a JQL filter, check if the Issue matches it. If so, we stop processing and use the Context.
- If the Context that is being evaluated does not have a JQL filter, we stop processing and use the Context.
- If no Context has been found in the previous step, find all Contexts that are configured with an Issue Type but not with a Project, and iterate through each of them in the order of the Order attribute (see above):
- if the Context that is being evaluated has a JQL filter, check if the Issue matches it. If so, we stop processing and use the Context.
- If the Context that is being evaluated does not have a JQL filter, we stop processing and use the Context.
- If no Context has been found in the previous step, find all Contexts that are configured with an Project but not with an Issue Type, and iterate through each of them in the order of the Order attribute (see above):
- if the Context that is being evaluated has a JQL filter, check if the Issue matches it. If so, we stop processing and use the Context.
- If the Context that is being evaluated does not have a JQL filter, we stop processing and use the Context.
- If no Context has been found in the previous step, find all Contexts that are not configured with an Issue Type or a Project, and iterate through each of them in the order of the Order attribute (see above):
- if the Context that is being evaluated has a JQL filter, check if the Issue matches it. If so, we stop processing and use the Context.
- If the Context that is being evaluated does not have a JQL filter, we stop processing and use the Context.
- If no Context has been found in the previous steps, use an implicit default Context.
Context Examples
Some examples of Contexts:
| Project | Issue type | JQL Filter | |
|---|---|---|---|
| 1 | Project1 | Bug | resolution IS EMPTY |
| 2 | Project1 | Bug | priority = Blocker |
| 3 | Project1 | (empty, i.e. applies to all types) | priority = Critical |
| 4 | Project1 | (empty, i.e. applies to all types) | |
| 5 | (empty, i.e. applies to all projects) | New Feature | |
| 6 | (empty, i.e. applies to all projects) | (empty, i.e. applies to all types) | priority = Critical |
| 7 | (empty, i.e. applies to all projects) | (empty, i.e. applies to all types) |
Some examples of contexts are evaluated for an issue:
| Issue | Matching Context | Explanation |
|---|---|---|
Issue attributes:
| 1 | All attriubutes are directly matching the Context's settings |
Issue attributes:
| 4 | Context 1 is not matching the issue as it is resolved. Context 2 is not matching the issue as it is of Normal priority. Context 3 is not matching the issue as it is of Normal priority. Context 4 is matching the issue. |
Issue attributes:
| 6 | Context 1-4 is not matching the issue as it is in Project2 not Project 1. Context 5 is not matching the issue as it is a Bug not a New Feature. Context 6 is matching the issue as it is of Critical priority. |
Issue attributes:
| 7 | Context 1-6 is not matching the issue as it is not fulfilling the Context attributes. Context 7 is matching the issue as the Context does not have any restriction |
Examples of how Contexts are resolved:
- for an issue that is a Bug in project P1, the first context is selected
- for an issue that is a Bug in some other project P2, the second context is selected
- for an issue that is an Improvement (non-Bug) in project P1, the third context is selected
- for an issue that is an Improvement (non-Bug) in some other project P2, the fourth context is selected