Skip to main content

ALM Connection to Jira Software

'How To' connect piplanning.io with Jira Software (Cloud or Data Center)

Updated today

1st: Create a Service User account in Jira

We strongly recommended a Service User account in Jira - with the required CRUD permissions for Jira Projects - to authenticate the ALM Connection.

Note: Make sure that the Jira Service User does not need to login via Single Sign On if such a solution is in place.

Required Permissions for the Jira Service User

The Jira User account used for authenticating the ALM Connection needs to have the following permissions in all Jira Projects you want to synchronize (map) with piplanning.io:

  • BROWSE_PROJECT

  • CREATE_ISSUES

  • DELETE_ISSUES (optional)

  • EDIT_ISSUES

  • LINK_ISSUES

  • SCHEDULE_ISSUES

  • MANAGE_SPRINTS_PERMISSION (optional)

  • MODIFY_REPORTER

2nd: Connect to Jira

  1. Navigate to RTE Cockpit > ALM Connections

  2. Click Add new ALM Connection

  3. Select ALM Tool select Jira.

  4. Click Next

    IF you wish to use the OAuth* authentication method continue here.

    IF you wish to use the Basic Auth authentication method continue here.

Note: *Atlassian advises using OAuth for integration to Jira Cloud. OAuth is therefore preferred for connection to Jira Cloud and Basic Auth only to be used if there are issues with OAuth.

REMINDER

The Jira Service User account, that you use when setting up the OAuth connection, will be used to perform all the C.R.U.D. operations in the real-time sync between Jira (Cloud or Data Center) and piplanning.io. Please make sure that this User has appropriate permissions: create Work Items in the right Jira Projects, and read the Jira Project Workflows and Status (metadata).

OAuth Authentication - Step-by-Step Instructions

  1. On the Jira - Connection page it defaults to the OAuth authentication method.

    1. Enter a Connection Name // Friendly name or alias for the connection

    2. Enter the Instance URL // URL to the instance of Jira we are connecting to

  2. Click Connect to Jira // OAuth dance starts

  3. The Setup OAuth window pops up:

  4. Follow the steps mentioned in the embedded video linked here or follow the step-by-step instructions below.

    In a separate browser tab > login to Jira with the Service User account

  5. Create an Application Link in Jira:

    1. Click Settings > Product > Jira apps.

    2. Navigate to Integrations on the left-side panel menu. Click Application links.

    3. Click Create link button

    4. Create an application link > Connection type

      1. The Connection type, the Direct application link radio button is checked by default.

      2. Enter https://piplanning.io in the Application URL* field

        Jira Software Application Link set up for OAuth.

  6. In the newly opened popup window titled Configure Application URL:

    1. Click the checkbox labeled Use this URL to make it active

    2. Click Continue

      Jira Software Application Link for OAuth.

  7. In the Review link dialogue box complete the following required fields:

    1. Application Name: piplanning.io

    2. IMPORTANT: Next, scroll to the bottom of the form, and click the checkbox labeled Create incoming link

    3. Click Continue

  8. Here the dance starts, and we alternate between Jira and RTE Cockpit browser tabs. From the RTE Cockpit OAuth screen to the screen in Jira:

    1. Copy over the Consumer Key from the RTE Cockpit > Setup OAuth screen.

    2. The Consumer Name value can be an alias or friendly value. We suggest naming it piplanning.io.

    3. Copy over the Public Key from the RTE Cockpit > Setup OAuth screen.

    4. Click Continue

  9. Back in the RTE Cockpit, click Authenticate

  10. A new browser tab will open to finalize the OAuth authentication in Jira. Follow the steps displayed on the Jira page:

    1. Click Allow and the page will redirect. Close that Jira browser tab.

  11. Navigate back to the RTE Cockpit

    1. Click Check & Close on the setup page in piplanning.io

Troubleshooting Jira Software OAuth Setup

If you see an error when you click Authenticate: Open the Browser Dev Tools / JavaScript Console in your browser and check for additional errors.

  • Check for an error like: "oauth_problem=signature_invalid":

  • Make sure that your Jira Data Center instance is properly configured in terms of its Base URL.

    • If you use a proxy to let the piplanning.io access your Jira, OAuth may not work. Contact Us through the In-App Messenger or write to [email protected].

  • The Base URL configured in Jira (System Settings) and in the <JIRA-INSTALL>/conf/server.xml file must exactly match the URL you have entered to connect to Jira in the RTE Cockpit.

  • Additional information can be found on the Atlassian help page: https://confluence.atlassian.com/kb/oauth-error-oauth_problem-signature_invalid-720406720.html

Basic Authentication (Basic Auth) - Step-by-Step Instructions

Prerequisites: You are logged into Jira with the recommended Service User account or a Jira User account with the appropriate permissions.

  1. Click the link Switch to Basic Auth

  2. Add a Connection Name // Friendly name or alias for the connection

  3. Add the Jira Instance URL // URL to the instance of Jira we are connecting to

  4. Add the Username and Password

    1. For Jira Cloud the value to enter into the Password field is an API Token for that Username. See below.

    2. For Jira Data Center the value to enter in the Password field is the Users local Password.

Note: IF want to connect to Jira Cloud - using Basic Auth. - you must generate an API Token for the Jira Service User account that will be used to complete the authentication. You will need to generate an Atlassian Account (Jira Service User) API Token to enter into the Password field for Basic Auth. Please go here to learn more: https://id.atlassian.com/manage-profile/security/api-tokens. For ALM Connections to Jira Cloud the OAuth method is advised.

Re-Authenticate (Reconnect with Service User account)

Have you set up the Jira ALM Connection using your personal Jira User account, and now want to reauthenticate with a Jira Service User accont?

Click the button below and follow the steps in the video to re-authenticate with a new (Jira) Service User account.

Reauthenticating to Jira Software with a Jira Service User Account

Connect to a Jira instance that has an unsigned certificate

You can deactivate the TLS / SSL certificate check in the Advanced Settings page of the ALM configuration.

  • Check the Advanced Settings checkbox on the #1 Connection tab.

  • Uncheck the Verify TLS / SSL certificates

Related Articles
Jira Team Mapping
piplanning.io attributes <> Jira fields
Adding a Webhook to Jira
Jira Software ALM Connection: Discovery + Setup Preparation
Kanban Teams | Jira Kanban Boards
Did this answer your question?