Overview

The Jira data connector for WorkBoard allows the user to pull progress based on “Done” user stories within specified projects. Stories and status can also be specified by JQL. Key Result in WorkBoard will be updated on the next data pull specified by the update cadence, or can be done in real time. 

Configuring a Data Connector

Prior to setting up a new Key Result data connector, your organization’s IT Administrator may need to approve the connector if there is an approval configuration. Once enabled, any user can have their Key Results measure progress from that specific connector. 

1. Create a new Key Result by selecting the kebab menu (3 dots) next to the applicable Objective.
   • If the Objective hasn't been created, simply select Create > Team Objective or Personal Objective, then enter your Key Result name.
2. Select Edit Settings from the dropdown. 
3. Click Add another key result and enter your Key Result name.
4. Select Advanced options, then Pull data from external applications. 
5. Choose the applicable data source from one of the options:
6. Log in to the application by inputting your credentials. 
   • Please note that for some applications, you will also need to create an API key or provide OAuth2 information. This information is Read Only. 
7. Once enabled, your Key Results will automatically update based on the update cadence specified in the Key Result's configuration.
8. If you need to manually sync an update, use the Sync Integration Data option from the kebab menu (three dots) in the upper right-hand corner of the Key Result details page.

Setting up a Key Result from Jira

When you create your first key result sourced from Jira, you'll be asked to provide a Jira access token. To get your token:

1. Log in to your Jira account using this link.
2. Select Create API Token.
3. Enter a name and select Create.
   
4. Copy the token.
   
5. Paste it into the WorkBoard Jira Connector login pop-up.
   
6. Select Sign in.
7. Once logged in you will be able to pull data from Jira using one of three methods -- Query Builder, Advanced JQL, or Search By Epic. Select how to retrieve issue completion data from Jira:
   • Query Builder: The query builder provides search and filter fields to select Project, Issue Type, and Statuses to filter down to.
     
   • Advanced JQL: Utilize the Advanced JQL field, which stands for Jira Query Language, to access more advanced filtering options and define content subsets.
     • To easily create JQL, navigate to Advanced Issue Search by selecting the search field > View all issues. From this screen, you can use the Jira UI to add any custom filters you need. Select Switch to JQL and the JQL is automatically generated. Copy and paste the JQL into the JQL field in WorkBoard.
       • For more information on JQL see Atlassian’s documentation on JQL.
         
   • Search by Epic: use this option if your organization uses epics. Epics are large bodies of work that can be broken down into a number of smaller tasks. You can search for your Jira Epic by entering the Epic ID and pressing Enter.
     
8. For real-time validation of data before connecting, select Preview results.
9. Enter the remaining Key Result details, then select an Update Cadence to determine how often WorkBoard will sync to pull the latest value for your Key Result.
   Note: Update cadence has the same options you would find for Key Results updated by a person (i.e., Daily, Weekly, Monthly, and Quarterly).
10. When finished, select Save to lock in the settings for your Key Result, then Done to apply these changes to your Objective.

Advanced JQL Query Tips

Using the advanced JQL Query option, you can define a query to dynamically pull any set of issues from JIRA, and define which subset of those issues are considered done in your particular workflow.

In the first field, you should pull all issues that the team needs to complete that you would like to track.

1. Project = K2-Web AND sprint = 42

The second field should be a subset of the first set and represent the specific issues that you consider completed in the larger set.

1. Project = K2-Web AND sprint = 42 AND Resolution = Done

How Should Progress Be Calculated

When selecting how progress should be calculated there are two options: issue count and story points. Selecting issue count will return a direct count of all issues to be included. Selecting story points will use the Story Points field in Jira and return a sum of all story points from issues included in your query or JQL. Any null values will be counted as zero. 

Synchronize Data from Jira

WorkBoard will effortlessly sync Key Result updates directly from the data connector based on the specified update cadence. You can manually sync Key Result updates, if needed, in two ways:

Force a Sync on a Single Key Result:

1. Select Key Result to navigate to the Key Results Details page.
2. Click the kebab menu (3 dots) in the upper right-hand corner of the page.
3. Select Sync Integration Data.
   

Force a Sync for all Key Result Integrations:

1. From the My Objectives Page, select the kebab menu in the upper right-hand corner.
2. Select Sync Integration Data.

Frequently Asked Questions

What if I have an on premise instance of Jira?

We suggest you use the WorkBoard Plugin for Jira. It is possible to pull data from your Jira instance using the Jira Cloud connector in WorkBoard, but only if your organization allows that data to be exposed outside your firewall or exposed to the internet. 

What are the scopes of access that WorkBoard receives when I integrate a Key Result connector?

The scope of access is Read Only, which is bounded by the user integrating with the service.

Will the Key Result connector pull in historic updates?

No, the connector does not have the automated ability to post historic updates to Key Results. The update always goes to the present interval due for the Key Result.

• Please note that KPI integrations will only deliver updates that are currently due, meaning data pulled in Month X will have the timestamp 'Month X'.
  • As a workaround, multi-target KRs can divide a Key Result into distinct named intervals such as 'August', 'September', 'October', etc. The 'July' interval, for instance, would encompass the start/end dates for data collection (August 1st - August 31st). Despite being named 'July', the data collection would actually occur within the timeframe of August.
  • 

When will the connector update my Key Result?

The integration will update based on the update frequency set up for the Key Result (e.g. weekly updates weekly, daily updates daily, etc.). The integration scheduler operates on a twice-daily basis, offering two opportunities for updates to ensure data accuracy. To optimize efficiency, the scheduler skips updates for Key Results (KRs) that are not due for updates, to prevent redundant data updates and maintaining a streamlined process.

When does Jira Cloud update?

12:45am PST and 12:45pm PST.