Connectors / Service / Jira Cloud

Jira Cloud

Jira Cloud

Plan, track, and manage your agile and software development projects

Overview

Jira Cloud is a cloud-based platform that allows you to plan, track, and manage your agile and software development projects.

Authentication

IMPORTANT!: Please take note of the following recommendations when authenticating with the Jira Cloud connector.
  • The Jira Cloud site entered on the Tray.io authentication dialog must match the Jira Cloud site selected on the Atlassian grant access web page. This is how Tray.io knows which Jira Cloud site to connect to.

  • A Jira Cloud user may have access to more than one Jira Cloud site. Please make sure to create one authentication per Jira Cloud site, that you wish to access.

  • If you create another authentication for the same Jira Cloud site, then the scopes selected in the most recent authentication will replace those from previous authentications. This may impact existing workflows if scopes have been removed.

When using the Jira Cloud connector, the first thing you will need to do is go to your Tray.io account page, and select the workflow you wish to work on. Once in the workflow builder itself, search and drag the Jira Cloud connector from the connectors panel (on the left hand side) onto your workflow.

With the new Jira Cloud connector step highlighted, in the properties panel on the right, click on 'New Authentication' which is located under the 'Settings' heading.

This will result in a Tray.io authentication pop-up window. The first page will ask you to name your authentication, and state which type of authentication you wish to create ('Personal' or 'Organisational').

As you can see, the next page asks you for your 'Jira Site URL' credentials. This is the URL of the Jira Cloud site that you wish to access.

Once you have added the Jira Cloud site URL and selected the required scopes (all are selected by default) to your Tray.io authentication popup window, click on the 'Create authentication' button.

An Atlassian web page will popup asking you to grant Tray.io access to your Jira Cloud site. Select the Jira Cloud site that you would like to grant access to from the 'Authorise for:' input field. Click on the 'Accept' button to grant access to your Jira Cloud site.

Go back to your settings authentication field (within the workflow builder properties panel), and select the recently added authentication from the dropdown options now available.

Your connector authentication setup should now be complete.

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.

Note on Operations Usage

Accessing API endpoints

API LIMITATIONS: Currently, Atlassian do not grant access to all API endpoints via OAuth 2.0.

As such, the Jira Cloud connector does not support operations related to boards and sprints. If you wish to access those, please use the Jira connector instead.

Jira Cloud triggers & webhooks

While there is no Trigger currently available for Jira Cloud, the Jira Cloud connector can support webhooks. It simply does not support the programmatic creation of them.

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

Please see the Jira vs Jira Cloud: Triggers section below for more details.

Using the Raw HTTP Request ('Universal Operation')

As of version 1.0, you can effectively create your own operations.

This is a very powerful feature which you can put to use when there is an endpoint in Jira Cloud 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 Cloud API documentation v2, to find the exact format that Jira Cloud 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 for Jira Cloud is: https://api.atlassian.com/ex/jira/[cloud_id]/rest/api/2

Note that [cloud_id] is the ID of your Jira Cloud site. The cloud ID can be obtained by querying the https://api.atlassian.com/oauth/token/accessible-resources endpoint, if necessary. The Jira Cloud connector will automatically do this for you unless you override the base functionality.

For example, say that the 'Get issue' operation did not exist in our Jira Cloud connector, and you wanted to use this endpoint, you would use the Jira API docs to find the relevant endpoint - which in this case is a GET request called: /issue/[issueIdOrKey].

More details on this endpoint can be found

here.

As you can see there is also the option to include a query parameter, should you wish to do so. So if you know what your method, endpoint and details of your query parameters are, you can get the Jira issue information with the following settings:

Method: GET

Endpoint: /issue/10001

Body Type : No Value

Final Example outcome being:

https://api.atlassian.com/ex/jira/[cloud_id]/rest/api/2/issue/10001

Example Usage

TRAY POTENTIAL: Tray.io is extremely flexible. By design there is no fixed way of working with it - you can pull whatever data you need from other services and work with it using our core and helper connectors. This demo which follows shows only one possible way of working with Tray.io and the Jira Cloud connector. Once you've finished working through this example please see our Introduction to working with data and jsonpaths page and Data Guide for more details.

Below is an example of a way in which you could potentially use the Jira Cloud connector, to list the issues in a project and get the individual issue details.

The steps will be as follows:

  1. Setup using a manual trigger so that the workflow can be run on demand.
  2. List the issues in a given project.
  3. Iterate through each issue, one at a time, using a Loop connector.
  4. Get the individual issues details.

The final outcome should look like this:

1 - Setup Trigger

Once you have clicked 'Create new workflow' from your main Tray.io dashboard and named it, select the Manual trigger from the trigger options available:

You will then be redirected to the Tray.io workflow dashboard.

2 - List Project Issues

From the connectors panel on the left, add a Jira Cloud connector to your second step. Set the operation to 'List project issues'.

Validate the step with your pre-made Jira Cloud authentication. You can rename the steps to make the workflow more user friendly however this is not mandatory.

Make sure that you provide the Project ID or Key in the properties panel that you wish to retrieve the issues for.

Either click on the 'Run workflow' button in the bottom right corner or hit the refresh option on any previously run flows in the debug panel. Your Input and Output panels will display the relevant JSON data, listing the available issues for the specified project:

3 - Loop through the Project Issues

Next, search for the 'Loop collection' connector within your connector panel, and drag it into your workflow as your next step. Set your operations to 'Loop Issues'.

The Loop Collection connector allows you to iterate through a list of results. In this example, we will use it to iterate through the data found within the previous Jira Cloud connector step.

In order to specify the list you want to loop through, start by using the 'List' mapping icon (found next to the list input field, within the properties panel) to generate the connector-snake.

While hovering over the 'List Project Issues' step (with the tail end of the connector-snake), select issues from the list of output properties displayed. This will auto-populate a jsonpath within your 'List' input field, and update the type selector to jsonpath.

For more clarification on the pathways you have available, open the Debug panel to view your step's Input and Output.

JSONPATHS: For more information on what jsonpaths are and how to use jsonpaths with Tray.io, please see our Intro page and Data Guide for more details.
CONNECTOR-SNAKE: The simplest and easiest way to generate your jsonpaths is to use our feature called the Connector-snake. Please see the main page for more details.

4 - Get Issue Details

Add another Jira Cloud connector onto the square space available in the loop connector's workflow. Set the Operation to 'Get issue', with the Issue ID or Key as $.steps.loop-1.value.key, making sure that the input type for your Issue ID or Key is set to JSON.

This step within the loop, will now retrieve each issues' data. You can see the relevant output when you run the workflow and open the debug panel.

You now have access to the issues' details and can perform further operations as required. Congratulations!

BEST PRACTICES: Whenever you do decide to create your own workflow, please make sure you take a look at our Managing data best practices guide.

Jira vs Jira Cloud: When to use

EMBEDDED USERS: If you choose a method where webhooks need to be copy and pasted, the last screen of the Configuration Wizard (or any other screen you wish to put it on) would simply display a URL that the end-user would copy and paste, along with instructions on where to put it within their Jira account.

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.
PLEASE NOTE: Rest assured, that while there is no trigger automatically available for Jira Cloud users, Jira Cloud does support the use of webhooks, and therefore creating a trigger is possible.

The Jira v3.0 API simply does not support the programmatic creation of them. This is a common complaint, as you can see in Jira support threads here. Webhooks are a modern construct, and not many APIs 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).

All Operations

Latest version:

2.0