- What does it do?
- Manually Adding Projects
- Linking Issues Using JQL
- Adding Items to Key Results Using Basic Search
- Use Case Example
- FAQs and Troubleshooting
What does it do?
The betterworks JIRA integration captures data from JIRA and automatically updates your milestone's progress. By no means are these the only use cases for the JIRA integration in betterworks: we recommend testing to see how you can make the JIRA integration work best for you.
You can use the JIRA integration to track the progress of individual issues or large projects. Linking these items to a milestone via the integration can be completed 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
Manually Adding Projects
If you know what issues you want to link to the milestone, you can manually add these via a basic search. Start by naming your milestone, then click "+ Add an integration". This will bring up a search bar where you can perform a basic search that will search your JIRA instance. We will provide issues that match the search, which you can then click to add to your milestone.
In this example, four issues were chosen. After clicking “save” the completion of these issues will automatically be tracked in betterworks. I can add comments on my progress if I want provide any status updates, but the completed work will automatically be captured. As I complete these issues in JIRA, they will automatically be updated in betterworks.
Linking Issues Using JQL
Often when you setup your goals, 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 use our “Continuously populate milestone 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 pertinent to the milestone you are linking to. After inputting the JQL query be sure to check "Continuously populate milestone with query results". When this box is checked, betterworks will automatically add any new JIRA issues that match the criteria of your JIRA query. For example, if I get assigned a new bug to fix, that issue will automatically be added to my milestone for tracking.
If you are well versed in JQL, that is great! Feel free to search directly in betterworks like you would in JIRA using JQL. If you could use a bit more practice on JQL, no problem! Any basic search in JIRA can be converted to a JQL by clicking "Advanced" within JIRA. You can then copy this string and paste it into our search bar as a JQL query.
The betterworks JIRA integration allows you to search for and pull data in from JIRA by writing a basic search or creating a JQL query.
Below are a few samples of JQL queries that you can leverage when creating your OKRs.
- Sample JQL for “Work assigned to me”
- assignee=”[name]" AND updated>[quarter_beg] AND labels=OKR
- Sample JQL for “Epics for my team”
- issuetype=Epic and project in ([project_team_name]) AND "Planned \"Done\" Date”>[quarter_beg] AND "Planned \"Done\" Date”<[quarter_end]
- Sample JQL for “Epics for my initiatives”
- issuetype=Epic AND Initiative in ([initiative_name]) AND "Planned \"Done\" Date”>[quarter_beg] AND "Planned \"Done\" Date”<[quarter_end]
- Sample JQL for “Epics I have written”
- issuetype=Epic AND reporter=”[name]" AND "Planned \"Done\" Date”>[quarter_beg] AND "Planned \"Done\" Date”<[quarter_end]
For a more in depth review of JQL, please visit JIRA's website.
Adding Items to Key Results Using Basic Search
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:
Use Case Example
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.
FAQs and Troubleshooting
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?
There's 2 immediate things to check.
First, see if the milestones due date has already passed. If so, Jira based milestones don't update after the due date. You will need to manually sync the milestone by clicking additional actions and then sync.
Another possibility is that the Jira ticket is either not Done and resolved or your Jira instance might be using a custom field to mark tickets Done.
If necessary, you can also 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 additional questions about this integration, please feel free to reach out to firstname.lastname@example.org.
Can SSO be used to turn on the Jira Integration?
No. It's not possible to use SSO to turn on the Jira integration. We recommend either using a non-sso account or looking into an official JIRA sanctioned way of managing this.