How to integrate JIRA with Sapho version 3.9 - 4.2

 

How to set up the JIRA connector in Sapho

Important Note
We recommend connecting to JIRA with a dedicated user account (for example, sapho@company.com) that was given "Browse Projects" access to the JIRA project(s) you would like to manage through Sapho. How to create a new user account in JIRA is described here, and how to add a user to a permission scheme for a JIRA project is indicated here. This will be particularly useful for audit logs.

This tutorial assumes that:

  • you are logged in Sapho Builder (Admin)
  • you have started Add JIRA Connector or Add JIRA Micro App wizard
  • you are on “What is the connection information?” screen.

Step 1: Enter the URL of your JIRA instance

If you are using JIRA Cloud, the format of the URL will be the following - https://companyname.atlassian.net.

If you are using JIRA Server (on-premises), please insert the root URL of your JIRA Server (i.e. the path you use to access JIRA in your browser).

Step 2: Enter the username of the dedicated JIRA account

This is the Username you entered when creating the dedicated JIRA user account.

In case you are using an already existing account, please note that the username is not the email of the account. To locate the username of an account, log in with that user in your JIRA instance. Click the profile thumbnail in the top right corner of the JIRA UI and then click on Profile. 

jira1.png

You will find the username on the right side of the Profile page (see below).jira2.png

Step 3: Enter the password of the dedicated JIRA account

This is the Password you entered when creating the dedicated JIRA user account.

Note that you can request the reset of the account password by logging out of JIRA and then clicking on “Having trouble logging in?”. Enter the email of the account, solve the CAPTCHA and click the Send button. When you get the email from Atlassian, click the link for resetting your password.

Step 4: Set the number of days of issues to retrieve
Enter a number for how many days of JIRA issues you would like the connector to retrieve. The default is 90 days. If left as it is, the connector will load JIRA issues created or modified during the last 90 days.

Step 5: Finish the creation of the JIRA connector

 

Troubleshooting

This section will describe a number of possible connectivity blockers and errors that might appear during connector synchronization. Follow the suggested solutions or contact support@sapho.com.

I. General Issues

Possible issue #1: You get an error saying "No users could be retrieved. The account used for connecting to JIRA might not have enough permissions to read all the data. Please refer to JIRA Help Page."

Solution: Log in your JIRA instance as an admin. Click the cogwheel at the top right and then User management. Search for the dedicated user account with which you are trying to connect JIRA to Sapho. Note down the groups to which the dedicated user account belongs to.j20.png

Click the cogwheel at the top right again and then System. On the left side, click Global Permissions. Check the groups to which the Browse Users permission was granted to. You'll notice that none of the groups associated with the dedicated account have this permission. At the bottom of the page, grant this permission to one of the groups the user is belonging to.j21.pngOnce you made this update, retry to synchronize the JIRA connector in Sapho.

 

Possible issue #2: You get an "Forbidden (403)" error. This might happen when CAPTCHA has been triggered and the account used to connecting to JIRA became invalid.

Solution: Log in your JIRA instance with the credentials of the dedicated user account. Solve the CAPTCHA and retry to synchronize the JIRA connector in Sapho.

 

Possible issue #3: You are using JIRA Cloud or JIRA Server with a version lower than 7.0 and accepting REST API calls is disabled.

Solution: Go to JIRA System settings and check whether “Accept Remote API calls” is set to ON. (Note: this setting is visible only in versions lower than JIRA 7.0. Starting with JIRA 7.0 the remote API calls are always enabled.

 

Audit Trail

Once you have created a separate user in JIRA and set up the connector in Sapho using that user account, you will be able to ensure transparency in your audit logs.
For example, when an end user will use Sapho to move a JIRA ticket to a new status, Sapho will add a comment to the ticket as shown in the example below.jira3.pngThe email of the actual end user (2) who made the change will be available in the body of the comment. JIRA will show that the comment was added by the dedicated user account (1) which was used to set up the connector in Sapho.

 

A similar comment will be added when an end user will assign a ticket to some other JIRA user (also through Sapho). See below.jira4.png

When a user will add a comment to JIRA through Sapho, their comment will be followed by their email address (see below). This will enable other JIRA users to distinguish between the actual author of the comment and the dedicated user account through which Sapho can do writebacks to JIRA.jira5.png