How to configure Atlassian JIRA for integration with Service-Flow


Communications

Inbound to Service-Flow

For a tool to send messages to Service-Flow, the tool must have access to Service-Flow's IP addresses. Communication is only allowed over HTTPS and the endpoint must have a valid trusted certificate in use.

Outbound from Service-Flow

For Service-Flow to send messages to the integrated tool, tools interface must be reachable from Service-Flow's IP addresses. The preferred communication way is HTTPS with a trusted valid certificate. In test environment, self-signed certificates and HTTP can be used as well.


See also Securely connecting ITSM tool with Service-Flow to get guidance how to create a secure connection.

Sending from JIRA to Service-flow

  1. JIRA sends messages using 'webhooks'. These messages are authenticated using a unique identifier Token which Service-Flow provides. 

  2. JIRA Webhooks don't support BASIC authentication, Token based authentication is used instead. Service-Flow will provide the authentication token.

  3. Configure the JIRA webhook as shown in table:

Webhook configuration

Field
Value
Example
NameCase specific.Send all changes to Service-Flow
URL

Test: https://rest-receiver-test.service-flow.com/api?issue.key=${issue.key}&project.key=${project.key}&auth_token=[CUSTOMER_SPECIFIC_TOKEN]

Production: https://rest-receiver.service-flow.com/api?issue.key=${issue.key}&project.key=${project.key}&auth_token=[CUSTOMER_SPECIFIC_TOKEN]

https://rest-receiver.service-flow.com/api?auth_token=foobarxxx
Exclude detailsoff
JQLPossibly limit webhook by project and issue type. Leave more complex logic to S-F mappingsproject = "PROJECT1" AND issuetype = Fault
EventsCheck all relevant events. Only Issue related events can currently be handled in Service-FlowIssue: created, updated, worklog changed

There is no need to add postfunction triggers to the workflow.

Sending from Service-flow to JIRA

Requirements

  1. JIRA user with privileges to create and edit issues. If JIRA Service Desk is used, user needs to be an agent.
    • Username and password for the JIRA user
  2. Url to JIRA instance.

  3. A custom field in JIRA instance for storing external id, the ticket id from the integrated system.
  4. Issue type(s) in JIRA
  5. Any date fields integrated
    • If non-default date format pattern is used, it is needed
  6. Key of the project in JIRA

System fields in JIRA

List of system fields available in default JIRA installation.  List taken from Atlassian Q&A article. NOTE: List may not include all fields. Please feel free to add any missing ones.

Display nameElement to map as targetMandatoryDescription
Issue IDkey(in update)The id of the issue
Projectfields.project.keyxProject key that the issue belongs to.
Issue Typefields.issuetype.idxwhether the issue is a bug, story, improvement, etc. You can add more issue types from the Issue Types admin screen.
Summaryfields.summary(in create)Summary of the issue.
Descriptionfields.description
the main text field for describing the issue
Component/sfields.components.name
a component picker, which references Project Components that you create on the project admin screen. (e.g. UI, Database). Components can have a person who is the Component Lead, who gets auto-assigned any issues with that component set.
Labelsfields.labels
labels are short text strings for grouping issues into categories. Similar to Components except that users can put any arbitrary value in there.
Due Datefields.duedate
a date picker for when the issue should be fixed by
Commentupdate.comment.add.body 
a text field for commenting on an issue
Priorityfields.priority.name
Values: Highest, High, Medium, Low, Lowest
Reporterfields.reporter
a user picker that contains the user that created the issue.
Resolutionfields.resolution
how the issue was resolved (fixed, duplicate, Won't Fix, etc). You can configure these from the Resolutions admin screen.
Custom fieldsfields.customfield_12345
Any custom field
Transitiontransition.key
Used with SetTransition message type. Value to be used is the id if the transition.

See also