Jira CloudPlan, track, and manage your agile and software development projects
Jira Cloud is a cloud-based platform that allows you to plan, track, and manage your agile and software development projects.
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.
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
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 theJira 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:
[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:
More details on this endpoint can be foundhere.
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:
Body Type : No Value
Final Example outcome being:https://api.atlassian.com/ex/jira/[cloud_id]/rest/api/2/issue/10001
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:
- Setup using a manual trigger so that the workflow can be run on demand.
- List the issues in a given project.
- Iterate through each issue, one at a time, using a Loop connector.
- 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.
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!
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
- 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
- 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.
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 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:
- Select the Webhook trigger and choose Jira Cloud from the dropdown options available. Enable the workflow.
- Paste in the Jira site url, and when the popup model appears approve and login.
- Within the workflow settings, copy the workflow's public URL (aka webhook URL).
- 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
- 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).
- 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).