Jira for Workflows

Your Dynatrace environment can integrate with a Jira Cloud or Server instance. With this integration, you can automate creating, commenting, and assigning Jira issues on the events and schedules defined for your workflows.

Set up Jira integration

To use Jira workflow actions, you first need to install the Jira for Workflows app from Dynatrace Hub.

In Dynatrace Hub , search for Jira for Workflows.
Select the Jira for Workflows app and select Install.
To install Jira for Workflows, you need the app-engine:apps:install permission.

After you install Jira for Workflows, you need to perform some initial steps to set up the connection between Jira and your Dynatrace environment.

Allow Jira for outbound connections

Grant permissions to Workflows

Authorize connection to Jira

Allow Jira for outbound connections

Open the Settings app and go to Preferences > Limit Outbound Connections.
Select Add item and add the domain of your publicly accessible Jira instance. For example, *.atlassian.net can be added if the Jira for Workflows actions should connect to a Jira Cloud instance.
Select Save changes.

This way, you can granularly control the web services to which your Dynatrace environment can connect.

Grant permissions to Workflows

Some permissions are required by Workflows to run actions on your behalf. Other permissions are required by actions that come bundled with Jira for Workflows itself.

To fine-tune permissions granted to Workflows

Open Workflows and go to Settings > Authorization settings.
Make sure the following permissions are selected.
- Permissions needed for Workflows
  - app-engine:functions:run
- Permissions needed for Jira workflow actions:
  - app-settings:objects:read
  - state:app-states:read
  - state:app-states:write
  - state:app-states:delete

Authorize connection to Jira

Get credentials for the Jira instance. The following authentication methods are supported:
- Basic Authentication
  
  We don't recommend using the basic authentication scheme, but it may still be required to authenticate older Jira Server versions that don't support the personal access token.
- Personal Access Token (PAT) recommended
  
  This is the recommended method to use for Jira Server. To learn which versions of Jira Server support personal access tokens and how you can create them, see Using personal access tokens in the Atlassian Jira documentation.
- Jira API Token (Jira Cloud)
  
  When connecting to a Jira Cloud instance, use the Jira API tokens.
Return to Dynatrace, open Settings, and go to Dynatrace apps > Jira Connections.
Select Add item and provide a name, the URL of the Jira instance, and—depending on the type of the credentials—either a username/password or simply a token.
Save your changes.

Additional notes

To improve traceability and audibility, use a Jira service user to access your Jira instance.

To add connection settings, you need the following permissions:

plaintext
ALLOW settings:objects:read, settings:objects:write, settings:schemas:read WHERE settings:schemaId = "app:dynatrace.jira:connection"

For details, see Permissions and access.

Be aware that connections are shared and can be used by all users with app-settings read permissions. This is by design, as workflows enable a simplified ticket lifecycle across projects and entities.

Create Jira issues with workflows

Open Workflows and select to create a new workflow.
In the side panel, select the trigger best suited to your needs.
On the trigger node, select to browse available actions.
In the side panel, search the actions for Jira for Workflows and select Create Issue.
Select a preconfigured Jira connection.
Select a Jira project.
Select an issue type.
Optionally, select values for fields such as priority, assignee, reporter, labels, and components.

Not all fields support workflow expressions and some fields depend on others. For example, the priority cannot be set if the issue type is unknown.
Enter summary text.
Enter a description for the Jira issue.

Format your message using Jira Text Formatting Notation. You can also use workflow expressions as input for the description.
To test your workflow, select Run.

If fields are missing or you are unable to create an issue, see Missing required fields or custom fields in the Troubleshooting section.

Action result

The Create Issue action provides the following result:

Property	Description
`id`	The numeric ID of the newly created Jira issue (for example, `1234567`).
`key`	The Jira issue key of the newly created Jira issue (for example, `XYZ-1234`).
`url`	A URL that links to the newly created Jira issue (for example, `https://<your-jira-instance>.atlassian.net/browse/XYZ-1234`).

This result can be used as inputs for other workflow actions via workflow expressions.

Transition issue

Open Workflows and select to create a new workflow.
In the side panel, select the trigger best suited to your needs.
On the trigger node, select to browse available actions.
In the side panel, search the actions for Jira for Workflows and select Transition issue.
Set Connection to a preconfigured Jira connection.
Set Project to the appropriate Jira project for the issue to be provided.
Set Issue type to one of the listed issue types for the selected project.
Set Transition status to the status that the issue should have after this transition. You can use workflow expressions as input here.
Set Issue Key to the exact issue key (for example, XYZ-1234).
optional Enter a comment to be added to the issue during the transition operation.
If the destination status requires extra fields to fulfill the transition, enter them in key/value pairs as follows.

Key Value
customfield_10041
A valid URL, such as https://www.example.com/
customfield_10055
A required value as defined by the Jira administrator.
To test your workflow, select Run.

Key	Value
`customfield_10041`	A valid URL, such as `https://www.example.com/`
`customfield_10055`	A required value as defined by the Jira administrator.

Action result

The Transition issue action currently provides no results, but the Input tab shows all IDs associated with the transition and the logs provide some feedback.

The Detail tab shows the State of the operation:

Success if the transition operation passed
Failed (with more information) if the transition failed

Comment on issue

Open Workflows and select to create a new workflow.
In the side panel, select the trigger best suited to your needs.
On the trigger node, select to browse available actions.
In the side panel, search the actions for Jira for Workflows and select Comment on issue.
Select a preconfigured Jira connection.
Provide an issue key (for example, XYZ-1234). It is also possible to use workflow expressions as input.
Provide the comment. Format your message using Jira Text Formatting Notation. You can also use workflow expressions as input.
To test your workflow, select Run.

Action result

The Comment on issue action provides the following result:

Property	Description
`id`	The numeric ID of the comment (for example, `123456`).

This result can be used as inputs for other Workflow actions via workflow expressions.

Change assignee

Open Workflows and select to create a new workflow.
In the side panel, select the trigger best suited to your needs.
On the trigger node, select to browse available actions.
In the side panel, search the actions for Jira for Workflows and select Change assignee.
Select a preconfigured Jira connection.
Provide an issue key (for example, XYZ-1234). It is also possible to use workflow expressions as input.
Select an assignee from the list and optionally search for the user by name.
To test your workflow, select Run.

JQL Search

Open Workflows and select to create a new workflow.
In the side panel, select the trigger best suited to your needs.
On the trigger node, select to browse available actions.
In the side panel, search the actions for Jira for Workflows and select JQL Search.
Select a preconfigured Jira connection.
Set JQL to a valid query to search (for example, PROJECT = CA AND assignee = null).
Set Fields to a comma-separated list of fields returned from the search (for example, key,summary,created). See the onscreen instructions for additional options.
Set Expand to a comma-separated list of entities that you want to be expanded (for example, names, renderedFields). You can optionally leave this empty.
Set Maximum number of results to the maximum number of results you want the search to return (for example, 10).
To test your workflow, select Run.

Action result

The Detail tab shows the State of the operation:
- Success if the JQL search operation passed
- Failed (with more information) if the search failed
The Result tab lists all the records from the search (if the search was successful).

Troubleshooting

The following are solutions to problems some people had with Jira for Workflows actions.

Missing required fields or custom fields

Some fields—such as Project, Issue type, and Summary—are required by the Create Issue workflow action. However, not all required fields for a Jira project are known by the workflow action, so the creation of a Jira issue may fail. Currently, a customized issue creation page is not supported by this workflow action.

Even with all mandatory fields provided, it is still possible for a workflow execution to fail. For example, a connection token could be expired or the result of an expression could result in invalid input.

Invalid connection error

When editing an existing workflow, you may see an Invalid connection message if it has been deleted in the meantime.

To modify your connections, open Settings and go to Dynatrace apps > Jira Connections.

Insufficient permissions error

To run workflows, Workflows needs to be allowed to read app settings on your behalf. Insufficient permissions can lead to an execution error.

To grant this permission, open Workflows , go to Settings > Authorization Settings, and select app-settings:objects:read.