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
To locate the username of an account, log in with that account 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).
Step 3: Enter the password of the dedicated JIRA account
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
Possible blocker #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 blocker #2: Sapho Server is running in a private cloud (e.g. AWS) and it cannot connect to the JIRA Server which is behind a firewall.
Solution: Whitelist Sapho Server’s IP address in your firewall so it can connect to the JIRA Server.
Possible blocker #3: You are using JIRA Cloud or JIRA Server with a version lower than 7.0 and “Accept Remote API calls” is set to OFF.
Solution: Check whether “Accept Remote API calls” is set to ON in JIRA System settings. (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.
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.