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.
You will find the username on the right side of the Profile page (see below).
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: Finish the creation of the connector
Click Next and finish the creation of the connector. If you'd like to limit the data downloaded by the connector, see the Load Filters section below.
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.
Moreover, you can write any other custom query using the JIRA Query Language (JQL). For more information, consult JQL documentation.
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.)
II. Issues specific to when connecting to JIRA Cloud
Possible issue #1: If Sapho Server runs on premises behind a proxy, it might not be able to connect to JIRA Cloud.
Solution: Configure Sapho to work with your proxy server as described here.
Possible issue #2: JIRA Cloud is down.
Solution: Check if JIRA is down on https://uptime.com/atlassian.com. If yes, all you can do is to wait.
III. Issues specific to when connecting to JIRA Server (on-premises)
Possible issue #1: JIRA Server (on-premises) is using a HTTPS certificate which is not signed by a common certificate authority and, thus, Sapho Server doesn’t trust it and will not connect to JIRA. There is going to be the following exception in the browser console: “sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target”.
Solution: Get the certificate used by your JIRA Server from your system admin or from the browser and add it to the general Java keystore on the server where Sapho is hosted by executing the following command:
sudo keytool -import -alias <nameOfJiraServer> -keystore $JAVA_HOME/jre/lib/security/cacert -file <path to cert>. After installing the certificate, please restart the server.
Possible issue #2: If Sapho Server runs in a private cloud (e.g. AWS) and JIRA Server is behind a corporate firewall, Sapho might not be able to connect to it.
Solution: Whitelist Sapho Server’s IP address in your firewall so it can connect to the JIRA Server.
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.
A similar comment will be added when an end user will assign a ticket to some other JIRA user (also through Sapho). See below.
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.