Configuring the Jira Add-On¶
Technical Requirements¶
Prerequisites¶
This procedure requires a Jira instance administrator to configure the iObeya application in Jira by creating an incoming link in the Application links.
After creating the dedicated Application link, you will have access to the OAuth 2.0 credentials required to configure the Jira connector in iObeya. For more info, see Configure an incoming link.
Supported Platforms¶
- Jira Server (Core, Software, Service Desk)
- Jira Server 8.22 and above
- Jira Server 9 (with iObeya 4.14 and above)
- Jira Data Center
- Jira Data Center 8.22 and above
- Jira Data Center 9 (with iObeya 4.14 and above)
- Jira Cloud
Latest stable version supported
Since Jira Cloud automatically updates itself, we cannot certify a single version as being fully certified for running with the Jira add-on. If you face any issues while running the Jira add-on with Jira Cloud, do not hesitate to contact us.
Supported configurations¶
- Jira Cloud and iObeya Cloud
- Supported with the standard configuration procedure.
- Jira Cloud and iObeya On-Prem
- Depends on the firewall configuration. Jira and iObeya need to talk to each other over HTTPS.
- Jira Server or Data Center and iObeya Cloud
Depends on the firewall configuration. Jira and iObeya need to talk to each other over HTTPS.
Tip
A static IP address can be provided for iObeya Cloud allowing the configuration of firewall policies between Jira and iObeya. Please contact our Support team (support@iobeya.com).
- Jira Server or Data Center and iObeya On-Prem
- Depends on the network configuration. Jira and iObeya need to talk to each other over HTTPS.
Configuring Jira connector with OAuth 1¶
This procedure can be used for Jira Cloud, Jira Server and Jira Data Center.
Generating an RSA Public/Private Key Pair¶
OAuth 1 configuration between iObeya and Jira requires a private/public key pair.
Open your terminal.
Move to the folder where you want to generate your keys.
Run the following openssl commands:
openssl genrsa -out jira_privatekey.pem 1024 openssl req -newkey rsa:1024 -x509 -key jira_privatekey.pem -out jira_publickey.cer -days 365 openssl pkcs8 -topk8 -nocrypt -in jira_privatekey.pem -out jira_privatekey.pcks8 openssl x509 -pubkey -noout -in jira_publickey.cer > jira_publickey.pem
Note
This generates a 1024-bit private key, creates an X509 certificate, and extracts the private key (PKCS8 format) to the
jira_privatekey.pcks8
file. It then extracts the public key from the certificate to thejira_publickey.pem
file.Open your private key (pcks8 format) with a text editor.
Remove each line break from the key.
Open your public key (pem format) with a text editor.
Remove each line break from the key.
Your key pair is ready to use.
Warning
---BEGIN KEY---
and ---END KEY---
are not part of the key. Do not
include it when you copy the key.
Adding a new Application type in iObeya¶
To configure iObeya to access external applications as an OAuth 1 client, you have to configure these external applications in the administration interface of iObeya.
- From the administration platform, go to Settings ‣ Accessible applications in iObeya.
- Click Add a new Application type.
- Fill in:
- Application type: jira (in lowercase),
- Description.
- Click Add the new Application type.
Adding an instance in iObeya¶
To allow iObeya to access external applications as an OAuth 1 client, you need to configure the external applications from iObeya administration platform.
Go to SETTINGS ‣ Accessible applications in iObeya.
Mouseover the jira line, and click on your Jira instances.
Click Add application instance.
Select in which iObeya domain you want to add an application instance.
Fill in or select:
- Name: The Jira instance name (e.g.: My Jira),
- OAuth version: select OAuth 1,
- URL: your Jira instance’s URL (e.g.: https://jira.mydomain.net),
- Request URL: your Jira instance’s URL followed by /plugins/servlet/oauth/request-token (e.g.: https://jira.mydomain.net/plugins/servlet/oauth/request-token),
- Authorize URL: your Jira instance’s URL followed by /plugins/servlet/oauth/authorize (e.g.: https://jira.mydomain.net/plugins/servlet/oauth/authorize),
- Token URL: your Jira instance’s URL followed by /plugins/servlet/oauth/access-token (e.g.: https://jira.mydomain.net/plugins/servlet/oauth/access-token),
- Access token validity: 604800 (default value is 7 days in seconds),
- Consumer key: must be unique for each instance (e.g.: iObeyaJira1)
- Consumer secret: leave empty (not used for Jira),
- Allow offline API call…: do not select,
- Private key: paste the Private key generated earlier.
Click Add instance.
Mouseover the Jira application and click Display configuration.
Copy the Redirect URL.
Note
The Redirect URL is a callback URL generated when you create a new application instance in iObeya. You need this URL to configure the access to iObeya from the external application Jira.
Configuring iObeya in Jira¶
Go to Settings ‣ Products ‣ Integrations ‣ Application links.
Click Create link.
Select Atlassian product.
In Application URL, enter your iObeya URL.
Click Continue.
Configure a new application link for iObeya using your iObeya url.
Select Use this URL and delete the New URL.
Note
New URL appears as a mandatory field but is only mandatory if Use this URL is not checked.
Click Continue.
Fill in Application Name (e.g.: iObeya).
Click Continue.
From the Application links page, edit your new application link.
In the Incoming Authentication section, fill in:
- Consumer key: the same used in the previous section,
- Consumer name: e.g. iObeya,
- Description: can be anything,
- Public key: your Public key in pem format,
- Callback URL: enter the Redirect URL retrieved in iObeya.
Warning
In the case of Jira, at the end of the “Consumer Callback URL”, you must add the ‘?’ character, otherwise the redirection will fail. This error is due to the fact that Jira automatically adds the “/” character at the end of the Callback URL while saving the configuration.
Here is a Callback URL example (with “?” character at the end) to use in the Jira configuration: http://localhost:8080/iObeya/admin/oauth/applicationInstance/cb8db5e0-2d37-426a-8943-b7b467089723/oauth-callback.action?
Click Update.
Save changes.
Testing the Jira connector in iObeya¶
- From iObeya, create or connect to a room in which you are room administrator.
- From Room settings ‣ Utilities, activate the Jira connector.
- Click Configure the utility ‣ Add an instance.
- Select your Jira instance and save.
- From a board, click the Jira utility ‣ Bulk import.
- Select an instance.
- Click the instance link to initiate the OAuth 1 authentication process.
- In the Jira window, click Allow.
- Return to iObeya to Refresh connections and select the instance you want to use.
Configuring Jira connector with OAuth 2.0¶
This procedure can be used for Jira Server and Jira Data Center.
Configuring iObeya in Jira¶
Create an incoming link¶
- Connect to the administration console of your Jira instance.
- Click Create link.
- In Application type, select External application.
- In Direction, select Incoming.
- Click Continue.
Configure the incoming link¶
Fill in:
- Name: the application name (e.g. iObeya),
- Redirect URL: you can use <your-iobeya-instance-URL>/callback as a temporary value (e.g. https://mycompany.iobeya.com/callback).
In Permission, select Admin.
Note
iObeya needs the Admin scope to list workflows available in Jira when creating a Kanban table.
Even if you grant higher permissions, iObeya will not be able to do more than the user authorizing it.
You can find detailed information regarding the permissions required by the Jira connector in this section: Necessary permissions in Jira to perform actions.
Click Save.
In the Credentials page, copy the Client ID and the Client secret.
Note
You have to provide the Client Id and Client secret in iObeya administration platform to configure the Jira connector.
Adding an Jira instance in iObeya¶
To allow iObeya to access external applications as an OAuth 2.0 client, you need to configure the external applications from iObeya administration platform.
Go to SETTINGS ‣ Accessible applications in iObeya.
Mouseover the jira line, and click on your Jira instances.
Click Add application instance.
Select in which iObeya domain you want to add an application instance.
Fill in/ select:
- Name: The Jira instance name (e.g.: My Jira),
- OAuth version: select OAuth 2,
- URL: your Jira instance’s URL (e.g.: https://jira.mydomain.net),
- Authorize URL: your Jira instance’s URL followed by /rest/oauth2/latest/authorize (e.g.: https://jira.mydomain.net/rest/oauth2/latest/authorize),
- Token URL: your Jira instance’s URL followed by /rest/oauth2/latest/token (e.g.: https://jira.mydomain.net/rest/oauth2/latest/token),
- Client ID: paste the Client ID retrieved from the Jira Credentials page,
- Client Secret: paste the Client Secret retrieved from the Jira Credentials page,
- Code challenge method: select plain,
- Ressources: leave empty.
Click Add instance.
Mouseover the Jira application and click Display configuration.
Copy the Redirect URL.
Note
The Redirect URL is a callback URL generated when you create a new application instance in iObeya. You need this URL to configure the access to iObeya from the external application Jira.
Finalizing configuration of application links in Jira¶
- Connect to the administration console of your Jira instance.
- From Application links, click the pen icon to edit your iObeya link configuration.
- Replace the temporary Redirect URL with the one retrieved in iObeya.
- Click Save.
Testing the Jira connector in iObeya¶
- From iObeya platform, create or connect to a room in which you are room administrator.
- From Room settings ‣ Utilities, activate the Jira connector.
- Click Configure the utility ‣ Add an instance.
- Select your Jira instance and save.
- From a board, click the Jira utility ‣ Bulk import.
- Select an instance.
- Click the instance link to initiate the OAuth 2.0 authentication process.
- In the Jira window, click Allow.
- Return to iObeya to Refresh connections and select the instance you want to use.
Jira Card Configuration¶
The card configuration is done by iObeya users, but if a field used in Jira is not available in iObeya check this documentation.
Necessary permissions in Jira to perform actions¶
Actions | Permissions in Jira |
---|---|
Configure the Jira card tool | Browse project, Create issue |
Edit a Jira card | Browse project, Edit issues, Link issues + option Issue linking actived in Jira |
Change assignee on a Jira card | Browse project, Edit issue, Assign issue, Link issues + option Issue linking actived |
Add a new issue | Browse project, Create issue |
Create a new issue | Browse project, Create issue |
Bulk import Jira cards | Browse project, Create issue |
Convert a card or note into a Jira card | Browse project, Create issue |
Convert a story card with story points mapped on estimation field | Browse project, Create issue, Edit issue |
Pushing updates in Jira | Browse project, Schedule issues |
Add a Kanban table | Browse project, Administer project |
Add a Sprint table | Browse project |
Add a Free table | Browse project |
Use Configure links display feature | option Issue linking activated in Jira |
Display the links | Link issues + option Issue linking activated in Jira |