Jira

Overview

Jira is a proprietary issue tracking product developed by Atlassian which allows bug tracking and agile project management.

Authentication

Step 1: Generate an RSA public/private key pair

In a Terminal window, run the following openssl commands (please run the commands separately):

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

This generates the files jira_privatekey.pcks8, jira_privatekey.pem, jira_publickey.cer and jira_publickey.pem.

Note that on Windows the > jira_publickey.pem last part of the command may not work, in which case you can just use openssl x509 -pubkey -noout -in jira_publickey.cer then copy the terminal output (including the -------BEGIN PUBLIC KEY-------- and -------END PUBLIC KEY-------- lines) and paste it into a file named jira_publickey.pem

Step 2: Configure the client app as a consumer in Jira

Log into your Jira instance and click Jira settings -> Products -> Application links from the sidebar menu:

In the "Enter the URL of the application you want to link" field, enter any URL and then click on Create new link. Ignore any warning about "No response was received from the URL you entered - it may not be valid.", just click on Continue.

On the first screen of the Link applications pop-up window, The Consumer Key and shared secret are user defined. When setting up an application link on the Jira side, you specify what the consumer key and shared secret should be. Then, on the Tray side, you need to put these same values in so that Tray is able to authenticate to Jira. Be sure to select the Create incoming link checkbox.

On the next screen of the Link applications popup window:

Enter the Consumer Key, Consumer Name and the Public key (copy the public key from the file jira_publickey.pem you generated previously). The Consumer Name is user defined, it's just for reference.

Then click on Continue.

You can now create a new authentication in the Tray workflow builder. You will use the following:

• The Jira URL (without / at the end)

• The Private key contained in the file jira_privatekey.pem

• The consumer key specified in the second screen of the Link applications popup window

• The shared secret specified in the first screen of the Link applications popup window

Username/Password Authentication

You can easily create a Username/Password authentication with Jira by using the 1.x version of the connector and specifying the username, password and your Jira URL (e.g. https://myjiradomain.atlassian.net).

Available Operations

The examples below show one or two of the available connector operations in use.

Please see the Full Operations Reference at the end of this page for details on all available operations for this connector.

Notes on operations usage

The Jira connector supports two authentication methods: Username/Password and OAuth1. The Username/Password authentication is the simplest way to authenticate to your Jira instance, however it is less secure than OAuth1. On the other hand, OAuth1 requires some additional steps which are explained in the above paragraphs.

If you want to use a Username/Password authentication, then use the connector version 1.x

If you want to use a OAuth1 authentication, then use the connector version 2.x

Using the Universal Operation ('Raw HTTP request')

As of version 2.3 it is now possible to effectively create your own operations.

This is a very powerful feature which you can put to use when there is an endpoint in Jira which is not used by any of our operations.

To use this you will first of all need to research the endpoint in the Jira API documentation , to find the exact format that Jira will be expecting the endpoint to be passed in.

Note that you will only need to add the suffix to the endpoint, as the base url will be automatically set (the base url is picked up from the value you entered when you created your authentication).

The base url is in the format of https://your-domain.atlassian.net/rest/api/2/

For example say that the Get issue operation did not exist in our Jira connector and you wanted to use this endpoint, you would use the Jira API docs to find that the get issue endpoint is a get request at the following url:

So if you know that an issue key is 'DCP-165' you can get this issue with the following settings:

As another example, if you wanted to return the system and custom issue fields available in your Jira instance, the API docs tell you that this is a get request at the following endpoint:

So you can get this information just using the following setting:

Note: If you are using DELETE you will have to set the content type to 'application/json' if body type is none (which it will be in most cases)

Example usage - setting up a JIRA bot in Slack

Here in the Tray.io docs department we have a JIRA bot set up to send Slack notifications about documentation which has been put on hold or is ready to be published. These serve as reminders to make sure that nothing 'slips through the cracks'.

This is managed with a very simple workflow:

This workflow does the following:

1. A scheduled trigger runs once a week

2. Using JQL (Jira Query Language) a check is made for any docs tickets with a status of 'On Hold' or 'Ready to Publish'

3. A loop connector goes through these tickets one-by-one

4. The relevant 'docs-notifications' Slack channel is notified of each ticket

And the final output in Slack looks like this:

Step 1 - set the scheduled trigger

First the trigger is set to run at a certain time every week:

Step 2 - set the query to filter tickets by project and status

Next we can use the Search Issues (JQL) operation to build a filter using the Jira Query Language (JQL) :

Step 3 - loop through the filtered tickets

Now we can use the loop connector and a $.steps.jira-1.issues jsonpath to pick up the results which match the query and loop through each of them one-by-one:

Step 4 - compose the Slack message for each ticket

Finally we can use interpolated mode to compose the Slack message using the jsonpaths which extract the relevant ticket metadata from each ticket in the loop step:

You can see that the message box corresponds with the messages that are then output to Slack:

Note that for the Slack Send message operation you can set Username and Icon url:

Jira vs Jira Cloud: When to use

We currently have two Jira connectors which are able to reach cloud-hosted Jira instances - Jira and Jira Cloud.

Depending on their use case, users may find that one Jira instance is more appropriate than the other. Users need to take the authentication process into serious consideration regarding their end users, during the selection process. As well as trigger set up should they require one.

There are essentially two options:

Option 1: Jira

1. Leverage the Jira connector (along with its prebuilt trigger if necessary), and ask your end users to use the OAuth 1 version of the service. This will require them to use the terminal, while gathering their OAuth 1 authentication parameters.

Option 2: Jira Cloud

1. Leverage the Jira Cloud connector, which allows your end users to authenticate with just their Jira site URL and username/ password. If a trigger is required, than separate setup will be necessary which will require them to copy/ paste a webhook URL into their Jira account.

While the OAuth 1 process and creating a Jira Cloud trigger may seem intimidating, both are rather straightforward and well documented on our site.

See below headers for more details.

OAuth 1 vs OAuth 2

OAuth 1 (used by the the Jira connector) is slightly more complex than OAuth 2 (which is used by Jira Cloud).

The Jira OAuth 1 process requires users to be comfortable with using the terminal.

This is because when setting up their authentication, they will need to generate a private key using terminal commands.

This process is employed by many of our users as it is relatively simple and very well documented in the Authenticaition section above.

However less technically able users may still find this process intimidating so please take this into account for your end users.

The Jira Cloud OAuth 2 process only requires an end user to input their Jira site url and username/ password credentials.

Triggers

The API version used when setting up either of the Jira instances dictated whether or not a trigger was able to be programmatically created.

• Jira comes with a ready made Tray.io trigger.

• Jira Cloud DOES NOT come with a prebuilt Tray.io trigger.

The Jira v3.0 API simply does not support the programmatic creation of then, which is the version Jira Cloud has been built on. This is a common complaint, as you can see in Jira support threads here. Webhooks are a modern construct, and many APIs do not allow you to create them programmatically simply because more development work is required by the service provider to enable this.

However with the help of the Webhook trigger, Tray.io users can set up an instance of their own Jira Cloud trigger relatively easily:

1. Select the Webhook trigger and choose Jira Cloud from the dropdown options available. Enable the workflow.

2. Paste in the Jira site url, and when the popup model appears approve and login.

3. Within the workflow settings, copy the workflow's public URL (aka webhook URL).

4. Head to your Jira account and sdd the URL to your 'System webhooks'. This should be under: 'Settings' -> 'Systems' -> 'Advanced' -> 'Webhooks'.

List of key differences

Jira

• Hosts a service connector.

• Hosts a trigger.

• Leverages v2.0 of the Jira API.

• Uses OAuth 1 authentication process (which in this case requires users to be comfortable working with the terminal).

Jira Cloud

• Hosts a service connector.

• No trigger available, however the Jira Cloud connector can support webhooks. See our note on Jira vs Jira Cloud: Triggers for more details.

• Leverages v3.0 of the Jira API.

• Uses OAuth 2 authentication process (which in this case only requires a username and password).