Jira Add-On

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 9.12 LTS (with iObeya 4.14 and above)

Jira Data Center

• Jira Data Center 9.12 LTS

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 at support@iobeya.com.

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.

1. Open your terminal.

2. Move to the folder where you want to generate your keys.

3. 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 the jira_publickey.pem file.

4. Open your private key (pcks8 format) with a text editor.

5. Remove each line break from the key.

6. Open your public key (pem format) with a text editor.

7. Remove each line break from the key.

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

1. From the administration platform, go to Settings ‣ Accessible applications in iObeya.
2. Click Add a new Application type.
3. Fill in:
   • Application type: jira (in lowercase),
   • Description.
4. 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.

1. Go to SETTINGS ‣ Accessible applications in iObeya.

2. Mouseover the jira line, and click on your Jira instances.

3. Click Add application instance.

4. Select in which iObeya domain you want to add an application instance.

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

6. Click Add instance.

7. Mouseover the Jira application and click Display configuration.

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

1. Go to Settings ‣ Products ‣ Integrations ‣ Application links.

2. Click Create link.

3. Select Atlassian product.

4. In Application URL, enter your iObeya URL.

5. Click Continue.

6. Configure a new application link for iObeya using your iObeya url.

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

8. Click Continue.

9. Fill in Application Name (e.g.: iObeya).

10. Click Continue.

11. From the Application links page, edit your new application link.

12. 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?

13. Click Update.

14. Save changes.

Testing the Jira connector in iObeya

1. From iObeya, create or connect to a room in which you are room administrator.
2. From Room settings ‣ Utilities, activate the Jira connector.
3. Click Configure the utility ‣ Add an instance.
4. Select your Jira instance and save.
5. From a board, click the Jira utility ‣ Bulk import.
6. Select an instance.
7. Click the instance link to initiate the OAuth 1 authentication process.
8. In the Jira window, click Allow.
9. 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.

Warning

If you are using a Jira Data Center in a cluster, we recommend to use the OAuth 1 protocol to configure the application link with iObeya. See the procedure.

Configuring iObeya in Jira

Create an incoming link

1. Connect to the administration console of your Jira instance.
2. Click Create link.
3. In Application type, select External application.
4. In Direction, select Incoming.
5. Click Continue.

Configure the incoming link

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

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

3. Click Save.

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

1. Go to SETTINGS ‣ Accessible applications in iObeya.

2. Mouseover the jira line, and click on your Jira instances.

3. Click Add application instance.

4. Select in which iObeya domain you want to add an application instance.

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

6. Click Add instance.

7. Mouseover the Jira application and click Display configuration.

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

1. Connect to the administration console of your Jira instance.
2. From Application links, click the pen icon to edit your iObeya link configuration.
3. Replace the temporary Redirect URL with the one retrieved in iObeya.
4. Click Save.

Testing the Jira connector in iObeya

1. From iObeya platform, create or connect to a room in which you are room administrator.
2. From Room settings ‣ Utilities, activate the Jira connector.
3. Click Configure the utility ‣ Add an instance.
4. Select your Jira instance and save.
5. From a board, click the Jira utility ‣ Bulk import.
6. Select an instance.
7. Click the instance link to initiate the OAuth 2.0 authentication process.
8. In the Jira window, click Allow.
9. 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 the Atlassian 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