In this article:
Introduction to Jira integration
Enabling the Jira integration
Prerequisites for self-managed Jira setup
Configuring the Jira connection
Connecting the Jira connection to an OKR
Examples
Introduction to Jira integration
Integrating Jira with Ally.io allows any updates on linked Jira user stories or epics to automatically track progress on OKRs. in Ally.io. This makes for a powerful setup because it ensures your OKR process is not waiting on manual check-ins and any progress is updated real-time on Ally.io.
Here are a couple of examples where teams see the benefit of the integration with Jira:
A Product Manager links her Objective (‘Ship feature Email Campaigns’) with an epic in Jira. As stories within the epic get done, the objective gets closer to its goal.
One Engineering team resolves to fix 20 bugs in a quarter. They link their objective to an epic under which all bugs get filed, and set the target of their KPI success metric to 20. Ally.io ensure that even when the number of bugs filed under the epic keeps growing, the objective has hit its goal as soon as 20 bugs are closed.
Enabling the Jira integration
Admins can enable this integration, and here’s how it can be done:
From the sidebar, click on Admin > select the Integrations tab.
Against Jira, you will have an option to Enable the integration. If a connection has been made previously or if the integration has been enabled already, you will have the option to Manage the enabled integration.
This integration can also be disabled from the same section by clicking on Change and choosing Disable integration from the dropdown.
Prerequisites for self-managed Jira setup (on-premise)
If your Jira instance is hosted on-premise (self-managed), you should have your IT/Jira administrator,
Setup an application link inside Jira as described here. Please note that the Jira connection for users will fail if the application link is not configured on your Jira instance.
You'll have to whitelist the IP addresses 54.243.192.208, 3.225.237.0, 107.20.38.17, 23.21.1.160 if your Jira installation restricts access by IP address.
If you are facing issues with any of the steps above, please refer to the Ally.io - Jira integration Troubleshooting Guide.
Configuring the Jira connection
After enabling the integration, the first step is to configure a Jira connection.
Select New Connection, and provide a name for the connection.
Add the Server URL of your Jira account.
Select whether your Jira instance is self-managed (on-premise) or hosted on the cloud. If you are not sure of the type of your instance, please check with your IT/Jira administrator.
For self-managed instances, click on the "Sign in with Jira" and follow the instructions in the popup to complete authentication.
Note: If your Jira instance is behind a reverse proxy and if you need to pass the authentication header key and value, click on the "Advanced options" above the "Sign in with Jira" button to send the key/value as part of the header.
For cloud instances, enter the email address and the API token associated with your Jira account. The instructions for generating an API token for your Jira cloud account is described here.
Click on Next to get up and running with this integration. You can edit the saved connection at any time.
While in most cases one connection is enough, Ally.io allows you to connect with multiple Jira instances. Click ‘New connection’ to add another instance. You can add names to your connections to differentiate them. These names are displayed to members when they link their OKRs to Jira stories.
Connecting the Jira connection to an OKR
Once you have configured the connection, the next step is to start linking OKRs to the stories or epics in Jira.
While creating or editing an OKR, click on Connect data source to auto-update progress. From the drop down menu, select Jira.
If you have already created a connection, or if your administrator has shared a connection with you, that connection will be selected automatically. Ally.io will prompt you to create a new connection only if there are no connections created or shared.
Choose the method using which you want to measure the progress of the key result — percent complete or KPI (success metric). If you are choosing KPI, provide a metric, starting value, and target value.
Select a connection, and add a JQL query to match any issues that would relate to the objective or key result. This also means that as more issues in Jira match the query, they keep getting linked to the success of the objective or key result.
A JQL query can be copied from Jira. Search for issues you want to link to your objective using available filters on Jira. Next, click on the ‘Advanced’ option and Jira automatically converts your search to a JQL query. You can copy and paste the query string into your integration with Ally.io.
The JQL query linked to the objective or key result can be edited at any given point in time. This leads to a recalculation of current progress.
Note: If you are using Jira next-gen projects, the support for JQL can behave slightly different compared to classic Jira projects. For example, a Jira next-gen project does not support query based on epic link. Here is an official Jira quote summarising this scenario, "Users should query on next-gen epics using the parent =. If you want to combine Epics from both project types, an example of such a query would be: "Epic Link" = NPC-6 OR parent = NJDP-5. The Parent field can now be selected as a column in the Global Issue Navigator and exported from Jira."
5. Select the metric you want to use to track progress. Refer to the tabular column beneath for more details on the Jira metrics supported.
Track progress by | Percent complete | KPI |
Count of tickets | % of tickets that are marked as done out of the total number of tickets that match the specified JQL configuration. | Number of tickets that match the specified JQL configuration. |
Time spent | % of total hours spent on the completed ticket out of the total number of hours spent on tickets that match the specified JQL configuration. | Total hours spent on tickets that match the specified JQL configuration. |
Original estimate | % of total estimated hours on the completed tickets out of the total number of estimated hours on tickets that match the specified JQL configuration. | Total estimated hours on tickets that match the specified JQL configuration. |
Remaining estimate | N/A | Total remaining estimate on tickets that match the JQL configuration. |
Progress | N/A | Average of the progress metric on tickets that match the JQL configuration. The progress of a ticket in Jira is computed as Time logged / Total time. |
% of story points on the completed tickets out of the total story points on tickets that match the specified JQL configuration. | Number of story points on the completed tickets out of the total story points on tickets that match the specified JQL configuration. | |
Custom fields – these are fields available in your Jira instance. Ally.io will automatically pull all the numeric custom fields in your Jira instance, and you will be able to track the progress by any of the Jira custom fields. | Track the percent complete of the associated numeric custom field in your Jira instance. | Track the total completion number of the associated numeric custom field in your Jira instance. |
Note: For more information on how Jira does time and progress tracking, visit this Jira article.
If you choose to track the progress by KPI, you will have the option to measure progress by the completed tickets only or all tickets by toggling the checkbox.
Note: 'Done' tickets include tickets with all statuses that is associated with the Jira's "Done" workflow status category irrespective of the resolution status of the tickets (reference to Jira article).
Examples
Let’s see a few examples of how the integration would work.
Example 1:
We’ll pick the example mentioned earlier: A Product Manager, Dana, links her objective (‘Ship feature Email Campaigns’) with an epic in Jira. A simple JQL query used to set up the link could be: "Epic Link" = AE-786
If the epic has 10 stories, owned by different designers, engineers and testers in the team, the progress of Dana’s objective would update every time one of the 10 stories gets closed. For instance, when 3 stories get closed in Jira, Ally.io would automatically update the progress of the objective to 30%. If an eleventh story gets added under the Epic, this progress gets re-calculated to 27%.
Example 2:
Consider the objective: “Improve the overall quality of the product”. In this case, you might want to track the number of bugs generated as opposed to the progress of issues, as an indicator of overall quality. You can use the ‘Count of Tickets’ metric in the tracking field to achieve the desired setup: Ally.io will automatically tally up all the tickets generated.
When an objective or key result is linked to Jira, members can see the Jira icon next to the progress bar indicating there is a connection.
The colors of the progress bar indicated the status of the objective.
If the progress is 0 - 25% less than the expected progress at any given point in time, the OKR status is Behind, and the progress bar color will be Orange.
If the progress is over 25% less than the expected progress at any given point in time, the OKR status is At Risk, and the progress bar color will be Red.
Ally.io pulls in new updates from Jira every 60 minutes. However, you can also manually refresh to pull in any new changes.
To learn more about Ally’s other integrations, please visit our Integrations page.