How to integrate JIRA with Sapho version 4.3 and greater
Category: Integration Setup
How to set up the JIRA connector in Sapho
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.
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
The amount of data the connector will retrieve from JIRA can be limited by applying a load filter. When you are on "Select Entities to Sync with Sapho" screen in the connector wizard, set the Advanced Features toggle to ON.
You will notice that the default filter for the Tickets entity is set to "Last 12 Weeks". This means the connector will load JIRA tickets created or modified during the last 12 weeks.
You can change the load filter to any of the predefined options or click in the input and write a custom filter, e.g. weeksToLoad=15.
This section will describe a number of possible connectivity blockers and errors that might appear during connector synchronization. Follow the suggested solutions or contact email@example.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.
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.Once 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.)
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.The 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.
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.