This app integrates with Jira and adds the possibility to link, comment and view issue information from Jira. If enabled, issues may also be created in Jira from this app.
The integration between Jira and Pureservice requires technical configuration in both ends.
Setup in Pureservice
General
- Enabled: enable or disable the app
- Name: Here you can give the app a unique name of your choosing. This name is used as title for the widget available for agents in the widget sidebar on tickets.
- API version: The Jira API version that is supported
- Webhook URL: URL to Pureservice that needs to be set in Jira. This field will only be available after the information is saved.
Options
This is where you setup the connection details. Fields marked with a star are mandatory fields.
- Server URL: Jira URL
- Customfield (for ID): «Custom Field» created in Jira for Pureservice ticket numbers. Example: “customfield_10807”
- Customfield (for URL): «Custom Field» created in Jira for link to the Pureservice ticket. If more than one ticket is connected, the ticket that was connected last will be shown. Example: “customfield_10808”
- Metadata JQL filter: JQL (Jira Query Language) filter that is used for filtering metadata. It is possible to filtrate on specific projects and/or types in Jira. The result decides what is possible to choose in the «New Jira» dialogue.
- Username and password: This must be a user that at least has access to the relevant project(s) in Jira and access to “Assign Issues” if you want this option in Pureservice.
The password needed here is an API-key. More information on how to create API-keys are found here
Creation of issues in Jira from Pureservice
- Allow: If enabled, agents are allowed to create new issues in Jira from Pureservice.
- Allow attachments: If enabled, agents are allowed to attach attachments to the new Jira issue from Pureservice.
- Allow assignment: If enabled, agents are allowed to assign the new Jira issue to an agent.
Display issues from Jira in Pureservice
- Allow comments: If enabled, agents are allowed to read existing and create new comments in the Jira issue.
- Show link to Jira: If enabled, agents are able to see the URL to the Jira issue. If the Pureservice agents don’t have access to Jira, this can be turned off.
- Show assignee: If enabled, agents can see who the Jira issue is assigned to.
Setup in Jira
User and rights
The Jira app in Pureservice requires authentication with a user account with at least access to the relevant project(s).
Access to “Assign Issues” is required as well if you enable this option in Pureservice.
We recommend creating a service account specifically used for this (for example named “Pureservice 3”).
CustomFields
One (mandatory) or two (optional) custom fields must be created in Jira that Pureservice populates with the Pureservice ticket ID(s) (mandatory) and the Pureservice URL (optional).
The Pureservice ID field needs to have Text Field (single line) type, and the Pureservice URL a URL Field type.
These values are needed before you can finish the app setup in Pureservice.
Jira -> Pureservice WebHook
A webhook that triggers on Issue updated is needed, and you may create several using the same Pureservice webhook for different actions.
This is done in the Jira Settings under System -> Advanced -> WebHooks.
URL
The URL is where you define what will happen when the issue is updated.
Following is a table containing some of the available parameters that can be used with the Pureservice webhook.
| Name | Value | Explanation | Required |
|---|---|---|---|
| id | ${issue.id} | Yes | |
| key | ${issue.key} | Yes | |
| summary | Text (URL formated) | Subject of notification and/or email in Pureservice | No |
| details | Text (URL formated) | Body of notification and/or email in Pureservice | No |
| note | Text | Body of Internal Note in Pureservice | No |
| notify | 1 / 0 | Notification will be sent if “1” to the case owner | No |
| 1 / 0 | Email will be sent if “1” to the case owner | No | |
| emailEndUser | 1 / 0 | Email will be sent if “1” to the end user | No |
Following is a table of Jira variables (also known as code words) that can be used.
| Variable | Explanation |
| {{issue.key}} | Issue key |
| {{issue.id}} | Issue ID |
| {{issue.fields.summary}} | Issue summary |
| {{issue.fields.priority.name}} | Issue priority |
| {{issue.fields.status.name}} | Issue status |
| {{issue.fields.issuetype.name}} | Issue type |
| {{issue.fields.assignee.name}} | Issue assignee name |
| {{issue.fields.assignee.displayName}} | Issue assignee display name |
| {{issue.fields.reporter.name}} | Issue reporter name |
| {{issue.fields.reporter.displayName}} | Issue reporter display name |
| {{issue.fields.resolution.name}} | Issue reolution name |
| {{issue.fields.resolution.description}} | Issue resolution description |
| {{user.name}} | Change caused by name |
| {{user.displayName}} | Change caused by display name |
| If comment added event | |
| {{comment.body}} | Comment body |
| {{comment.author.name}} | Comment author name |
| {{comment.author.displayName}} | Comment author display name |
| {{comment.updateAuthor.name}} | Comment update author name |
| {{comment.updateAuthor.displayName}} | Comment update author display name |
| If issue change event | |
| {{changelog.items}} (use with #each) | Array of changed |
| field | Field that was changed |
| fromString | Original field string value |
| toString | Current field string value |
Following is a few examples of how the parameters of the URL may look (must be URL encoded!):
Notify agent when Priority in Jira has changed:
?id=${issue.id}&key=${issue.key}&summary=Priority+changed+in+Jira&details=Priority+changed+to+%7B%7Bissue.fields.priority.name%7D%7D+in+Jira.¬ify=1
Notify and Email agent when Priority in Jira has changed:
?id=${issue.id}&key=${issue.key}&summary=Priority+changed+in+Jira&details=Priority+changed+to+%7B%7Bissue.fields.priority.name%7D%7D+in+Jira.¬ify=1&email=1
Create Internal Note when Priority in Jira has changed:
?id=${issue.id}&key=${issue.key}¬e=Priority+changed+to+%7B%7Bissue.fields.priority.name%7D%7D+in+Jira+by+%7B%7Buser.displayName%7D%7D
Event filter (JQL query)
The JQL (Jira Query Language) query in this section, right below the URL, is how to specify what issues the webhook will affect. A generally good idea is to limit it to issues with the relevant customfield and is written “cf[customfieldID] is not EMPTY” where “customfieldID” would be the correct customfield ID in your environment.
Please refer to Jira’s documentation for more advanced setups.
Need more help with this?
Ta kontakt med oss for videre spørsmål her!