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: 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
This section will describe a number of possible connectivity blockers. Follow the suggested solutions or contact email@example.com.
I. 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.
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. General Issues
Possible issue #1: 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.)
Possible issue #2: After a few consecutive failed login attempts, the CAPTCHA was triggered. CAPTCHA requires the user to interpret a distorted picture of a word and type that word into a text field with each subsequent log in attempt. If CAPTCHA has been triggered, you cannot use JIRA's REST API to authenticate with the JIRA site. There is going to be the following exception in the browser console: X-Seraph-LoginReason = AUTHENTICATION_DENIED or AUTHENTICATED_FAILED.
Solution: Go to your JIRA instance and log in manually with the dedicated user, solve the CAPTCHA and then retry to create the JIRA connector in Sapho.
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.