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.

  1. Ensure you have the required types of Jira and Polaris instances.
  2. Verify that your Jira projects expect the appropriate issue types and fields from Polaris.
  3. Generate an RSA public/private key pair using OpenSSL.
  4. 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.
  5. 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

CAUTION: Before setting up Jira, check your issue types and fields.
  • When exporting tasks to Jira, Polaris includes the following Jira fields:
    • Summary
    • Description
    And the following Jira attributes:
    • 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
    If other fields or attributes are required by the Jira project, the export will fail.

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.

The certificate will expire in 365 days – you can change the final value in this line to reflect a different number of days. After the interval passes, a new certificate is needed.
Warning:
Certificates will expire after a period of time. Schedule periodic rotation of certificates. When updating the certificates, you must repeat this procedure from start to finish, with the exception that you are updating the record rather than creating it.

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.


A screenshot that shows the first pop-up form in Jira.
  • Enter an application name (required).
  • Under Application type, select generic application
  • Check the box next to Create incoming link
Note: Enter text only in the Application Name and Application Type fields. If you enter text or place the cursor in the other fields, the form will not be accepted.

8. Click Continue.

9. Complete the next form:


A screenshot that shows the second pop-up form in Jira.

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.


The button for adding a Jira instance.

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}
Note: Turn off any pop-up blockers or ad blockers to ensure that you receive the verification code.

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.)



Note: The connection between Polaris and Jira is complete, but users cannot export issues to Jira until a Jira project is chosen within their Polaris project. See Set up Jira in an individual Project for more information.