Jira Server steps
Flow Designer has built-in steps to help you integrate Jira Server into your event management and incident response flows.
The following steps are available:
- Create Issue: automatically create a new issue in Jira Server, populating it with information from the alert and any previous steps in the flow.
- Update Issue: automatically update an issue record as information changes.
- Add Comment: automatically add a comment to an issue record, either as an internal comment or as a published comment visible to the customer, adding information from the signal source or previous steps in the flow.
In the example above, the flow creates a Jira Server issue when the "Create Major Incident" response is selected. A Statuspage incident is created with details from the alert and the Jira issue. Information about the alert, the Jira Server issue and the Statuspage incident are all included in a message posted to a Teams channel.
Adding Jira Server steps to your flow
- To add a Jira Server step to your flow, go to the Apps panel in the palette, expand the Jira Server steps and drag the step onto the canvas.
- Connect the step to the previous step in the flow. This lets you access the alert properties and outputs of previous steps when configuring the inputs.
- Double-click the step to edit it, and use the Setup tab to configure the inputs, using plain text, input variables, or a combination of both. See the sections below for detailed information on the inputs for each step, including which are required. Some things to keep in mind:
- Jira Server or your organization might have certain requirements for the fields that are populated by this steps. Your Jira Server configuration might also be customized to allow different options besides those listed here.
- The Jira Server API is case-sensitive (for example, Medium and medium are two different values). If Jira Server requires a specific value, and the input value at runtime doesn't have the same capitalization, Jira Server will return an error.
- On the Run Location tab, set where you want the step to run: on the cloud or on an xMatters Agent installed behind your firewall.
- On the Endpoint tab, select an existing endpoint or create a new endpoint with the following settings:
- Enter the base URL of your Jira Server instance (for example, https://jira.example.com).
- In Authentication, enter the credentials of a user with permission to create and update issues. Make sure Preemptive is selected before saving the endpoint configuration.
Create Issue
Use the Create Issue step to automatically create a new issue in Jira Server. Map outputs from the trigger or previous steps to the inputs; at runtime, the values in the inputs are used to fill in the issue record.
Create Issue inputs and outputs
Inputs
Inputs with an asterisk* are required.
|
Label API mapping |
Description |
|---|---|
|
Project Key* fields.project.key |
The Jira key of the parent project to assign the issue to. If you want to use a project key in multiple steps without hard-coding it, you can store it in a constant. |
|
Issue Type* fields.issuetype.name |
The type of issue to create. This can be Task, Story, Bug, or Epic. You can find the Type in the issue details. If previous steps in the flow don't provide the issue type, you can use a switch step before this one to create different types of issues based on some other piece of information. |
|
Summary* fields.summary |
A brief summary of the issue. This becomes the title of the record in Jira. |
|
Description fields.description |
The detailed description of the issue. |
|
Priority fields.priority.name |
Sets the importance of the issue in relation to other issues. This defaults to Medium if left blank. If previous steps in the flow don't provide a priority value Jira can use, you can use a switch step before this one to create issues with different priorities based on some other piece of information. |
|
Labels fields.labels |
Additional labels to assign to the issue, entered as a comma-separated list. For example, to apply the labels for the Cats and Dogs releases, add "release-Cats, release-Dogs" (or variables that map to the release names). If you try to send a label with spaces (for example, Cats release), Jira Server may return an error. |
|
Assignee Key fields.assignee.name |
The Jira key of the person to assign the issue to (this can't be a group). This defaults to unassigned if left blank. |
|
Reporter Key fields.reporter.name |
The Jira key of the person to record as the reporter of the issue. If left blank, this defaults to the user configured in the endpoint authentication. |
|
Environment fields.environment |
The environment the issue affects (for example, Chrome, iOS, etc.). |
Outputs
These outputs are available as inputs to steps further along the flow.
|
Label API mapping |
Description |
|---|---|
|
Issue ID id |
Unique ID assigned to the issue by Jira Server. |
|
Issue Key key |
The key assigned to the issue by Jira Server. Example: You could use this as part of a channel name in a Create Channel step or a Statuspage name in a Create Statuspage step further down the flow. |
Update Issue
Use the Update Issue step to automatically update an existing issue in Jira Server. Map outputs from the trigger or previous steps to the inputs; at runtime, the values in the inputs are used to update the issue record.
Update Issue inputs and outputs
Inputs
Inputs with an asterisk* are required.
|
Label API mapping |
Description |
|---|---|
|
Issue ID* issueIdOrKey |
The unique ID or Key assigned to the issue in Jira Server. Use the "Issue ID" or "Issue Key" output from the Create Issue step. |
|
Notify Users notifyUsers |
Sets whether a notification email is sent to all watchers (true) or not (false). To accept false, Jira Server requires the authenticating user of the endpoint be an administrator in Jira. |
|
Summary fields.summary |
A brief summary of the issue. This becomes the title of the record in Jira. |
|
Description fields.description |
The detailed description of the issue. |
|
Status fields.status.name |
The status you want to assign to the issue. Leave blank to keep the status as is. The transition from the current status to the target status must be configured in your Jira instance, and there can only be one transition path between the two statuses. For example, if the issue is currently at "To Do" and you want to set the status to "In Progress", To Do > In Progress must be a transition in your instance, and there can only be one path between "To Do" and "In Progress". An error is logged in the Activity panel if there are either no paths between the statuses or there are multiple paths. |
|
Priority fields.priority.name |
Sets the importance of the issue in relation to other issues. If previous steps in the flow don't provide a priority value Jira can use, you can use a switch step before this one to create issues with different priorities based on some other piece of information. |
|
Labels fields.labels |
Labels to assign to the issue, entered as a comma-separated list. This overwrites the existing labels. For example, if the issue has the labels Cats and Dogs, and you populate this field with only Ferrets, the Cats and Dogs labels are removed and the Ferrets label is applied. If you try to send a label with spaces (for example, Cats Release), Jira Server may return an error. To create a copy of the step that adds to the list of labels, see the Knowledgebase article Customize Jira Update Issue steps to add labels for instructions. |
|
Assignee Key fields.assignee.name |
The Jira key of the person to assign the issue to (this can't be a group). |
|
Reporter Key fields.reporter.name |
The Jira key of the person to record as the reporter of the issue. |
|
Environment fields.environment |
The environment the issue affects (for example, Chrome, iOS, etc.). |
Outputs
This step has no outputs.
Add Comment
Use the Add Comment step to add a comment to an existing issue in Jira. Map outputs from previous steps to the inputs; at runtime, the values in the inputs are used to determine the issue to comment on, and the content of the comment.
Add Comment inputs and outputs
Inputs
Inputs with an asterisk* are required.
|
Label API mapping |
Description |
|---|---|
|
Issue ID* issueIdOrKey |
The unique ID or key of the issue that you want to add a comment to. You can map this to the Issue ID from the output of a previous "Create Issue" step. |
|
Comment body |
The text of the comment you want to add. Use outputs from the trigger or previous steps, along with text, to create the comment. |
|
Make Comment Internal properties |
When set to true, the comment is added as an internal comment on the issue, meaning the customer cannot view it and isn't notified. A value of false posts it as a public comment viewable by the customer. This must be true or false. This input only applies to Jira Service Desk project types; for all other project types, it is ignored. |
Outputs
These outputs are available as inputs to steps further along the flow.
|
Label API mapping |
Description |
|---|---|
|
Comment ID id |
Unique ID assigned to the comment in Jira. You can use this to identify the specific comment in another step further down the flow. |