Jira integration for Polaris
You can manually export Polaris issues as Jira issues. This requires some setup to help Polaris exchange information with your Jira instance.
Introduction
About the integration- The integration enables Polaris users to manually select Polaris issues and assign them to a Jira project.
- The integration currently supports only one Jira instance per organization.
- Polaris can export one issue at a time to Jira.
- The exporter chooses the issue type, depending on what is available in the associated Jira project.
- Subsequent updates or comments in Polaris are automatically appended to the Jira issue.
Technical requirements
- Classic Jira Cloud instances running the latest Long Term Support release. (Jira Next-Gen is not supported.)
- The Jira instance must be routable over the Internet. Closed networks are not supported at this time.
- A Polaris instance is required.
- Setup requires organization admin access to both Jira and Polaris.
- Exporting issues to Jira requires access to the Polaris project and the associated Jira project.
- Authentication between Jira and Polaris is by OAuth.
Organization setup overview
Here's a high-level view of the steps for setting up Jira for your organization on Polaris.
- Ensure you have the required types of Jira and Polaris instances.
- Verify that your Jira projects expect the appropriate issue types and fields from Polaris.
- Generate an RSA public/private key pair using OpenSSL.
- Use the public key to configure Jira. The client application Polaris is registered as a consumer, by creating an application link (that uses OAuth) in Jira.
- Use the private key to configure Polaris. Go to your Polaris server, click My Organization > Integrations. Integrate Polaris with Jira for your Organization.
Before setting up the integration
- When exporting tasks to Jira, Polaris includes the following Jira fields:
- Summary
- Description
- Reporter name (Exported with an empty value, which Jira sets to the name of the user who configured the Polaris-Jira integration)
- Project id
- Issue type
Create Public and Private RSA Keys
Before connecting Jira with Polaris, you need to create a pair of public and private OAuth keys. If you already have keys, go on to the next section. If not, follow these steps.
1. Open a terminal.
2. Copy and paste the following SSL commands into your terminal one at a time. Most of them create little or no output in the terminal.
2A. Generate a new RSA private key:
openssl genrsa -out jira_privatekey.pem 1024
This example assigns the name jira_privatekey.pem
and a length
of 1024 bits. The .pem file is written to your current
directory and is necessary for the next step.
2B. Create a certificate:
openssl req -newkey rsa:1024 -x509 -key jira_privatekey.pem -out jira_publickey.cer -days 365
After you enter what is above, the terminal will ask you a series of questions that are necessary for the certificate request.
The example generates an X509 certificate.
2C. Extract a PCKS8 private key:
openssl pkcs8 -topk8 -nocrypt -in jira_privatekey.pem -out jira_privatekey.pcks8
This example reads the unencrypted private key and outputs a new key in PKCS8
format with the name specified (jira_privatekey.pcks8
). This is
the private key that you will provide to Polaris later.
2D. Extract the public key:
openssl x509 -pubkey -noout -in jira_publickey.cer > jira_publickey.pem
This example uses the certificate you created to extract the public key file:
jira_publickey.pem
. This is the public key you will provide
to Jira.
Configure Jira with a Public Key
3. In Jira, navigate to Settings > Products.
(Settings is the small, gear-shaped icon at the top right.)
4. Under Integrations, Choose Application Links, then click Create Link and enter the URL of your Polaris instance.
5. Click Continue.
6. If you see a warning that the URL might not be valid, click Continue again.
7. Complete the three required parts of the form.
- Enter an application name (required).
- Under Application type, select generic application
- Check the box next to Create incoming link
8. Click Continue.
9. Complete the next form:
All three fields are required. For the first two fields, you can copy the answers exactly as they appear in the following list.
- Consumer Key: OauthKey
- Consumer Name: Polaris
- Public Key: {your public key}
To use a public key you created: Open the file, copy the contents, and paste the text in the Public Key field of the form.
10. When you return to the Configure Application Links page (where you entered the URL in step 2) you should see Polaris in your list of apps.
Configure Polaris with a Private Key
11. In Polaris go to My organization > Integrations and click the button that says Add Jira Integration.
12. Chose your Jira instance type from the pulldown menu.
13. In the Jira Integration Set Up page, complete the form as follows:
- Jira URL: {Enter the address of your Jira}
- Enter Consumer Key: OauthKey
- Enter Private Key: {Enter your private key}
14. Click Next.
15. In Jira, you should see a new window asking for verification that you want to allow Polaris to connect. Click Allow.
16. Copy the verification code and go back to Polaris.
17. In Polaris, enter the verification code and click Validate.
18. Click Next.
19. Review the information and click Finish.
20. Verify the connection.
Back on the Jira Integrations page (in Polaris), click the Test button next to your new instance to verify that the connection between Jira and Polaris is working. (A checkmark means that it works.)