Create a Service User account in Jira
Not mandatory, but strongly recommended!
A Service User is not mandatory, but strongly recommended. Create a Service User (e.g. name piplanning.io) in your Jira instance. The email address is not relevant. Make sure that the Service User does not need to login via Single Sign On if such a solution is in place.
When using a Service User account to configure the integration, the changes made in Jira via piplanning.io will then be recorded as this Service User.
These updates will appear in the Jira Issue > Activity > History Log, and they will be recorded as that Service User account.
When this happens it will be clear and obvious to any viewer reading the History Log what create, update, or delete actions were completed by piplanning.io vs. normal Users.
Required [Service] User Permissions in Jira
In both cases, whether using a Service User or a normal User account, keep in mind that this User needs to have the following permissions in all Jira Projects you want to synchronize with piplanning.io:
BROWSE_PROJECT
CREATE_ISSUES
DELETE_ISSUES (optional)
EDIT_ISSUES
LINK_ISSUES
SCHEDULE_ISSUES
MANAGE_SPRINTS_PERMISSION (optional)
MODIFY_REPORTER
Add new ALM Connection (Jira)
Navigate to RTE Cockpit > ALM Connections
Click Add new ALM Connection
Select ALM Tool select Jira Add New ALM Connection
Field Name | Description |
Connection Name | Friendly name or alias for the connection; generally a name used internally to identify the Jira instance. |
Instance URL | URL to the instance of Jira we are connecting to. Use http or https as schema. |
Create an Application Link
Jira Software Cloud only supports OAuth. You will need to generate an OAuth Token go here to learn more: https://id.atlassian.com/manage-profile/security/api-tokens
In either case, connecting via OAuth or Basic Auth, we recommend creating a Service User account upfront and using this account to authenticate the integration. Please create the Service User account first and then continue.
Connect Jira using OAuth
Login to your Jira instance with the Service User account. Note: Ensure this user has the right permissions as stated above.
In a separate browser tab; login to piplanning.io as an Admin User who has also the permissions of a Jira Administrator
Add a Connection Name
Add the Jira Instance URL
To start the OAuth dance click Connect to Jira
The Setup OAuth window (see below) will pop up, follow the steps mentioned in the embedded video. Alternatively written instructions are provided here in a step-by-step guide Setup OAuth for authentication with Jira.
Reminder: The User that you are currently logged in to Jira with (recommended that to be the Service User) while setting up the OAuth connection, will be used to perform all the operations in the real-time sync between Jira and piplanning.io. Please make sure that this User has appropriate permissions.
Setting up OAuth connection step by step
Setting up OAuth connection step by step
Login to Jira with the [Service] User account that has the appropriate permissions
1st Step is to create an Application link:
Click-path Settings > Product > [INTEGRATIONS] Application links
Click Create link button
The Direct application link radio button is checked by default. Enter https://piplanning.io in the Application URL* field
In the newly opened popup window titled Configure Application URL:
Click the checkbox labeled Use this URL to make it active
Click Continue
In the Review link dialogue box complete the following required fields:
Application Name: piplanning.io
IMPORTANT Click the checkbox at the bottom labeled Create incoming link
Click Continue
***Here the 'dance' starts, and we alternate between the Jira and RTE Cockpit browser tabs. On the new screen in Jira:
Copy over the Consumer Key from the RTE Cockpit > Setup OAuth screen.
The Consumer Name value can be an alias or friendly value. We suggest naming it piplanning.io.
Copy over the Public Key from the RTE Cockpit > Setup OAuth screen.
Click Continue
Back in the RTE Cockpit, click Authenticate
A new browser tab will open to finalize the OAuth authentication in Jira. Follow the steps displayed on the Jira page:
Click Allow and the page will redirect. Close that Jira browser tab.
Navigate back to the RTE Cockpit
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 JavaScript Console in your browser and check for additional errors.
Check for an error like: "oauth_problem=signature_invalid":
Make sure that your Jira 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.
The Base URL configured in Jira (System Settings) and in the <JIRA-INSTALL>/
conf/server.xmlfile 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
Connect Jira using Basic Authentication (Basic Auth)
Connect Jira using Basic Authentication (Basic Auth)
Note: Basic Auth is only applicable for Jira Software Server or Jira Software Datacenter Server
Prerequisites: You are logged into Jira with the recommended Service User account or a Jira User account with the appropriate permissions (above)
Navigate to RTE Cockpit > ALM Connections
Click Add new ALM Connection > Select ALM Tool = Jira
Click the link Switch to Basic Auth
Add a Connection Name
Add the Jira Instance URL
Add the Username and Password (preferably the Service User)
Re-Authenticate (i.e. when you want to connect with a service user)
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.