Using the Jira integration

Last updated on May 8, 2025 at 2:51 PM

The Jira integration allows you to connect Dixa conversations with Jira issues, allowing your support and engineering teams to collaborate even closely.

Add a Jira widget to Dixa

Jira must have the following fields configured to work correctly:description, summary and reporter .

You need to be a Dixa system administrator or administrator to configure integrations.

You will find integrations under Settings -> Integrations -> Conversation cards if you have the proper permissions.

Configure the widget

On the Create Jira widget screen, you must fill in the following:

Name
site URL
Authorize with OAuth

The Widget name is for identifying integration in the conversation interface. An example would be just Jira.

The second required field is your instance of Jira's site URL (e.g., https://acme.atlassian.net/).

Once that is added and saved ( via Submit), you will be prompted to authorize the integration.

Clicking the Start authorization button will ask you to log in to Jira.

Your browser must allow pop-ups and be aware that some adblockers can prevent the authorzation window from showing.

Review and accept the permissions required by the Dixa Jira integration:

When the authorisation is done correctly, you will see a green checkbox to the right of the Start Authorization button

It's not always the authorization that works. Below are the different icons you can encounter:

Green checkmark: authorised and connected. All done, the widget should work
Spinner: waiting for the authorization process to be finished. Will timeout after 30 seconds (this is the time the user has in the pop-up window until timeout)
Light red exclamation triangle: connection timeout. As mentioned above, the max time of 30 seconds was reached without any change in the authorisation. Reload the settings page and try again.
Red crossed through circle: connection failed. Something went wrong after the user accepted the pop-up window. Reload the settings page and try again.
Grey circle with an exclamation mark: Not connected. There is no current authorisation for this widget. This is also the initial state.

Important: make sure that you authorise the integration as otherwise you will not receive any data inside the conversation view!

Bringing it all back home

Once the Jira native integration has been configured and issues are linked to conversations, a natural next step would be to be able to react to changes made on Jira's end.

When a Jira issue is marked as done, you can listen to the change and re-open any conversations linked to it.

This can be achieved by creating an inbound webhook on the Dixa platform and configuring it on a Jira project's automations section.

Authorization and access

Dixa’s Jira integration can access content in your Jira account, and depending on which Jira user authenticates the integration, different content will be accessible.

Suppose Jane Doe has a Jira account and can access 2 out of 3 projects as shown in the image below.

Then, Jane logs in to the Dixa platform as an admin and creates a Jira integration in the settings. As part of the integration setup, Jane needs to authorize it so that it can access Jira project data on her behalf. The Dixa integration now has the access rights of Jane Doe’s Jira account.

Once the access has been granted, the Dixa’s Jira integration will be able to access the same data the authorizing user has access to, i.e. Jane Doe’s Jira user access scope.

Important:
Keep in mind what Jira projects you want to allow Dixa’s Jira integration to see and use the appropriate Jira account when authorizing the integration. Since creating and authorizing a Jira integration on the Dixa platform requires the Dixa user to have the admin role, then a Dixa administrator needs to also have a corresponding Jira account with access to all the required projects.
If the user authorizing the Dixa Jira integration leaves your company, the integration will have to be re-authenticated using a Jira account with the same required access as the previous user.

Configuration options

Two options are now configurable:

Remove all links
Enabling this will show a convenient "Remove all links" button on the widget, allowing the agent to quickly remove all connected Jira issues simultaneously.

Show unresolved links to Jira issues
If you link a conversation to a Jira issue that cannot be resolved (aka does not translate to a proper Jira issue link), it will, by default, not be visible in the UI. By toggling ON the Show unresolved links to Jira issues option, you will now also see the un-resolved Jira IDs, allowing you to correct and/or remove them.

Enable the "Create issue" button
If enabled, it will allow agents to create Jira issues directly from Dixa

If you delete the integration all links between Jira tickets and Dixa conversations are also deleted. No data in Jira is edited.

Enable sorting the issue types by label

Sorting is disabled by default

Because Jira's sorting seems quite random, we have introduced the sort option, where we will sort your Jira fields based on name. To use this functionality, you can rename the fields in Jira to appear in your preferred order. Examples include "01 Description", "02 Summary", etc.

Make sure to ensure that the Show the widget in the conversation sidebar option is ON.

Using the integration

Once the Jira integration is configured, you can link to one or more Jira issues in every conversation and view the description and status directly from Dixa.

Search & link issues

To link the conversation to a new Jira issue, paste the Jira link, type its ID or search for the issues you want to link

Backlinks

On the Jira side, once an issue is linked to a conversation, you will find a backlink on the Jira issue pointing to the Dixa conversation.

This will make it easier to identify all customers who need to be notified once a Jira issue is fixed.

Unlinking Jira issues

If you unlink an issue from within Dixa, it automatically removes the backlink from the Jira issue.

Creating new Jira issues

If the "Enable the "Create issue" button" option is enabled, you will be able to create Jira issues directly from Dixa

Currently, the process is as follows:

You select the Jira project in which you want to create the issue
Once that is done, you will be able to select the type of Issue you want to create (that depends on the project you've selected)
When the Issue type is selected, the required fields for that issue type will be available for completion

Note: the displayed fields are loaded from the Jira issue definition - Dixa will display all fields that are marked as required. You can use this to select additional fields to display (you will require Jira admin access for that).

The Jira integration supports the following input types:

Summary
Short text
Paragraph
Reporter
Priority
Dropdown
Checkbox
URL
Number

The integration does not support:

Date
Timestamp
Labels (custom)
Labels (native)
People
Start date
Due date
Dependent dropdown

Once the issue is created, you can see the issue by using the link in Dixa. The Jira ticket will automatically be linked to the current conversation.

FAQ

What does the Authorize with OAuth do?

The Authorize button in the Jira widget settings page starts the authorization process against the Atlassian servers. In this process, the Dixa user needs to use their Atlassian account to give consent to the Jira widget so it can access certain data on behalf of the (Atlassian) user. Once consent is granted, the Partnerships backend service will obtain an access token for accessing data from the Jira account the authorizing user is a member of. In addition, the Partnerships backend service will automatically refresh the access token when it expires (without any intervention of the user required) so the authentication of the widget works transparently for the agent when they are fetching issue data or creating issues.

Why can I Authorize with a user that doesn’t exist in Jira?

When you authorize it is not with your Dixa account but your Atlassian account. You are either logged in on Atlassian on another tab or your browser still has a valid session stored and available for when you access a Atlassian product again. The authorization flow uses the existing session when you click Start authorization in the Jira widget configuration page. You can verify this by accessing Atlassian and logging out, and then trying to re-authorize the Jira widget. When doing so, you should be prompted to log in to Atlassian before being able to see the consent window.

I'm getting an error in the integration called "Downstream_API_Forbidden_Error"

What's happening here is that somehow one of the calls to Jira returns with a "403 - you don't have permission to access this resource". This is due to the the person who authorized the integration has not enough access rights within their Jira instance (because all agents using the Jira integration use the access rights of the person who authorized it). Potentially some access rights has changed on the person since their connected the integration.