BetterWorks JIRA Integration Overview
Time to Implement: 5 Minutes
The BetterWorks JIRA integration captures data from JIRA and automatically updates progress of your key results or milestones in BetterWorks every 30 minutes. Any JIRA issue can be supported in BetterWorks JIRA Integration, including including stories and epics.
The JIRA integration can track the progress of individual issues or large projects. Linking these items to a key result in BetterWorks via the integration can be accomplished in two ways:
- Manually adding issues via a basic search or JQL query
- Setting up a JQL query to capture all the issues matching the string
Anyone who uses JIRA to track tasks, features or projects in their workflow can benefit from this integration. For instance, engineers use it to show bugs that they have to squash and product managers use it to track the shipment of features by setting up a JQL query to capture overall progress.
To add the JIRA integration to BetterWorks, you need to connect a JIRA user in the BetterWorks integration page.
- Create a JIRA user with the appropriate set of permissions for BetterWorks users. Read-only permissions are sufficient.
Users within BetterWorks will be able to see the JIRA issue, name, and resolution for every project that is available to that JIRA user. No other details from the JIRA instance are captured by BetterWorks.
For more information on creating JIRA users, read JIRA’s documentation.
- Navigate to the BetterWorks Integrations page by going to Admin > Integrations.
- In the JIRA integration section, click Set Up.
- If your JIRA installation is hosted by Atlassian (in the cloud): Enter the JIRA user’s login info and the JIRA server URL. The user password is automatically encrypted.
Note: Do not include your company's domain when entering the username. Instead of "email@example.com", enter only "john".
If your company hosts your JIRA instance (on premise): Enter the JIRA user’s login info and the target URL of your JIRA instance. The user password is automatically encrypted.
If your instance is behind a firewall, your IT department must determine a port to use and open it to allow BetterWorks access to your JIRA instance. Include the port number at the end of the URL (for example, http://JIRA.yourcompany.com:1234).
Alternatively, you can add the BetterWorks IP or URL address to your firewall’s whitelist, or whitelist proxy.betterworks.com. Contact our support team to learn how.
- Click Save.
- If you want to connect multiple JIRA instances, click Add another instance.
- When adding multiple instances, you can optionally enter names for each instance. The names will be used to allow users to select which instance to point to when setting up their milestones. If you do not enter names the for the instance, the domain of each instance will be used.
- Follow steps 1-6 for each additional instance.
That's it! The JIRA integration is ready to go. Just log out of BetterWorks and log back in to use it.
Important: In order to see the JIRA integration at work, you need to log out of your BetterWorks instance and log back in. The integration will not appear until you've logged out and logged back in.
If you have any questions regarding connecting BetterWorks to your JIRA instance, please reach out to our Customer Success team.
If you know what issues you want to link to the objective, you can manually add these via a basic search. Start by naming your key result in the creation stage, then click the JIRA icon in the integration option panel. This will bring up a search bar where you can perform a basic search of your JIRA instance. BetterWorks provides issues that match the search, which you can then click to add to your key result:
Often when you set up your objectives and key results, not all of the issues in JIRA have been established. Examples include fixing bugs over the course of the quarter or all of the issues linked to an epic. You can choose to continuously populate key results with query results in these instances.
Switch from a basic search to a JQL query and utilize JQL to match any issue that would be relevant to the key result you are linking to. Even if you are less comfortable with writing JQL, you can always convert a search in JIRA to JQL and copy that query when configuring your integration in BetterWorks.
After inputting the JQL query, check Continuously populate key result with query results. When this box is checked, BetterWorks will automatically add any new JIRA issues that match the criteria of your JIRA query.
Here are some basic sample JQL strings to get you started:
- Issues assigned to me: assignee=”User Name”
- All issues that relate to a certain epic: “Epic Link” = XYZ-123
- Issues with certain labels (example of two): labels in (label1, label2)
- Issue that are overdue: due <= “0”
For a more in depth review of JQL, please visit JIRA’s website.
Track custom fields in JIRA
BetterWorks gives you the flexibility to use Custom Fields you have defined in JIRA to track the value of each issue in ways that are optimized for your organization. Instead of counting the number of issues solved, measure the impact of a key result by measuring your progress using Story Points, Opportunity Value, or any other custom fields that may be set. Simply pick from the Choose how you would like to measure your progress drop-down to see all the fields defined in your JIRA instance.
One great use case for this is for an engineer to track bugs that they have to squash. In the following example, Damon is tasked with fixing 25 bugs over the course of the quarter. The JQL query in this case will have the assignee set to Damon, a label string that captures the issue as a bug and the resolution as unresolved. Combining these elements in a JQL string will automatically keep track of this objective without needing to manually update the BetterWorks system:
Product managers can also get a lot of value out of using JQL to track the work being done to deliver a new feature. By setting up a JQL to track a specific Epic in JIRA, all tickets matching the query are automatically linked to the key result in BetterWorks. As issues are created that match the query, they are linked to key result to be tracked for progress. Using this integration gives you and others in the organization a way to track how development is going on the features you’re looking to ship - simply have each contributor use a JQL string to identify issues in the epic which are assigned to them to get visibility into overall progress.
Can I update a JIRA ticket from BetterWorks?
No. The JIRA integration can only pull information from JIRA. Users are not able to push data back to JIRA.
My JIRA integrated item isn't updating - how do I get it to work?
JIRA-based milestones do not update after the goal's due date. To sync these key results or milestones, choose the Sync option in the milestone's Actions menu.
If that doesn't work, you'll want to contact your BetterWorks administrator so they can check to see if the credentials for the JIRA integration are up-to-date. If you're still seeing issues syncing, check to see if the JIRA ticket still exists or if your JQL string is complete and correct.
Can I use the JIRA integration for a select group of users?
No. When the JIRA integration is activated, all users will have the opportunity to link JIRA issues in BetterWorks.
Can I see the full details of a JIRA ticket through BetterWorks?
No. We only access three standard items via the JIRA integration: Issue ID, Issue Title, Issue Resolution (issue open/closed). Additionally, our integration is able to pull data from any custom fields you've set up in order to more accurately inform progress on the integrated key results. Note: users can not see any other ticket data (such as description) from within BetterWorks.
If you have any questions on how to configure or optimize your JIRA integration, please reach out to us at firstname.lastname@example.org.