Jira Integration #
With the Jira Integration, Project Managers create a connection between Jira and LiquidPlanner, which pulls Jira Projects into the Scheduled Collection for prioritization, forecasting, and scenario modeling. The scheduling algorithm uses the Jira Time Remaining field to calculate start and finish dates in LiquidPlanner. Once the schedule has been calculated, the integration returns the most up-to-date project planning information to Jira through a manual sync.
| 1 | Start the integration from Scheduled Portfolio View |
To pull in a project with the Jira Integration, navigate to Projects in the left-side navigation. This takes you to Portfolio View in the Scheduled Collection. Projects are added to Packages in this view. Use the toggle to expand a Package.
Select the Add Project field to activate the Add Jira Project button. Project Manager access or above is needed in order to create projects through the integration. The Add Jira Project button opens the integration window where you establish the connection between LiquidPlanner and any of your Jira instances.
| 2 | Jira Issues become Tasks |
| Jira Attribute | LiquidPlanner Property |
|---|---|
| Issue Name | Task Name |
| Assignee | Assignee |
| Description | Notes |
| Issue Key | Custom Task Data Field |
| Project Name | Custom Task Data Field |
| Issue Type | Custom Task Data Field |
| Priority | Custom Task Data Field |
| Epic | Custom Task Data Field |
Through the course of the integration, you’ll be prompted to customize the project set up through filtering and field mapping. When that is completed, each of the incoming issues will be transformed into LiquidPlanner tasks with default attributes applied.
Additionally, the project folder in LiquidPlanner will have a custom project data field for Project Lead that maps to the corresponding field on the Jira Project.
The assignee in Jira will map to a Member or Resource in LiquidPlanner. Resources will be created on your behalf for all Assignable Users in the Jira project if they don’t already exist in LiquidPlanner.
Visit Administration in the left-side navigation to view the number of Resources available and make sure you have enough to complete the project integration. Use the Support & Feedback link in the user menu to request more Resources.
| 3 | Connect to Jira Using OAuth |
At the Instance and Credentials step, you have the option to add a new instance or connect to one that you had previously selected. You will always need to provide an email address to pull a project in from Jira.
- +New Instance: Connect to your Jira account and choose a new instance. An authorization window will open requesting access to your Atlassian account. Choose your account and select Accept.
- Email Provided: Choose the email address that established the connection.
- Available Jira Instance: If you have previously integrated then those instances will be listed here.
| 4 | Project & Issues Filter |
After connecting to the Jira instance, you are ready to choose a project from the Jira Project drop-down menu. The menu includes all of the projects that you have access to in the connected Jira instance. After you have selected the project, you can set up the following filters:
- Issue Type: Select the Issue Type you want to pull in: Task, Story, Bug, and Epic, or Select All. A task is created for selected Issue Types. Pull in hierarchical issues as tasks to capture estimates or the time tracked for those tasks.
- Issue Status: Select the status of the Issue Type you want to pull in. The available statuses depend on the configuration of your Jira project.
- Include issues created after: Choose a date to include only issues created after that date.
Depending on the filters that you choose, the Issue Count and User Count will update accordingly. The Issue Count in the lower left corner tells you the number of Jira issues that will come in as LiquidPlanner tasks when set up is complete. The User Count shows you a count of how many new users will be pulled in when set up is complete.
Use the “Next” button to save the filters and move to the next step.
| 5 | Sync Settings |
In Sync Settings, you can choose how you want to pull hierarchies and work logs into LiquidPlanner. The following settings are available:
Reorder Jira Issues by LiquidPlanner Priority
This setting will reorder the tasks in your Jira project to reflect the priority order of your tasks in LiquidPlanner. Remember that in LiquidPlanner, tasks are prioritized from top to bottom, with the top being the highest priority and the bottom being the lowest. The setting is enabled by default. Deselect the check box if you do not want to send LiquidPlanner priority order to Jira.
Subfolder Organization
This setting determines how tasks are displayed when you pull them in. Tasks are displayed as a flat list if no Epics or custom hierarchy levels exist. The following options are available:
- Flat list: Pulls tasks in a flat list in the project. Tasks are not sorted into folders.
- Epic-Based Sub-folders: Creates a sub-folder for each Epic (level 1) with their issue (child) tasks inside the folder. If an issue does not belong to an Epic then it resides at the top level (the same level as the folders).
- Hierarchical Sub-folders: Creates a sub-folder for each custom hierarchical issue type. An example would be for level 1 and above, such as for an Initiative, Feature, and Epic, with child items nested within the corresponding type. This option will only display if the instance you have selected is on a Jira Premium or Enterprise subscription.
Important: The subfolder organization is a one-way process after you set up the integration. After integration, you can change a flat list to Epic-Based and change Epic-Based to Hierarchical, but you cannot revert an option to the previous one. To change the subfolder organization, select the Integration button in your project and then select Modify Setup. There, you can modify your selection and save your changes, which take effect the next time you sync.
Pull Worklogs
The following options are available and will vary depending on your instance:
- Do Not Pull any Worklogs: No Worklogs (Time Entries) are pulled into LiquidPlanner.
- Pull from Jira: Pull Worklogs (Time Entries) from Jira into LiquidPlanner.
- Pull from Tempo Timesheets: Pull Tempo Timesheet entries into LiquidPlanner. This option only displays if Tempo Timesheets is installed on your instance.
- Cost Code: Select a cost code that is applied to Jira time entries in the selected project. This option only displays after you select to pull from either Jira or Tempo Timesheets. Note: After you select a cost code and complete the integration, you cannot change the cost code.
| 6 | Field Mapping |
In addition to the attributes that are applied automatically through the integration process there are optional fields that can be mapped through this step.
Select +Jira Field to add additional Jira fields that you would like to map to LiquidPlanner. Select +LiquidPlanner Field to add additional LiquidPlanner fields that you would like to map to LiquidPlanner.
If you choose to pull the issue Due Date from Jira, it can be mapped to either a custom date field that you have created, or to the Target Finish date, which is the deadline in LiquidPlanner. The benefit of mapping to Target Finish is that you will be alerted if you are at risk of missing the Jira Due Date. Learn more about Target Dates and alerting in the Academy. You can also select Enable Two-Way Sync to create a two-way sync between the Jira Due Date and the LiquidPlanner Finish Date.
The remaining options are LiquidPlanner system fields that can be pushed back into Jira custom fields. They can be mapped to existing fields in your project, or you can create new ones for this integration.
- Target Finish is the deadline date in LiquidPlanner. Work can Keep Scheduling past this date or Stop Scheduling. When the Expected Finish is after a Target Finish, schedule bars turn red and alerts identify work that has Schedule Risk.
- Target Start is the date you would like to begin. It could start later, based on the status of higher priority work.
- Expected Start: when you are most likely to begin, based on the status of higher priority work (calculated by the scheduling engine).
- Expected Finish: the date you’re working toward, the likely finish date (calculated by the scheduling engine).
- Latest Finish:how long it could take if worst-case estimates come into play (calculated by the scheduling engine).
- Item Link: the link you get from using the Copy Link button in the Item Panel.
- Work Limit: when you set a Work Limit you cap the number of hours to work on an item.
- Custom Fields, including Text, Multi Picklist, Single Picklist, and Numbers.
When mapping is complete, Next will take you to Remaining Estimates where you will establish the formula for converting Jira’s Time Remaining field into a ranged estimate for the scheduling algorithm.
| 7 | Remaining Estimates |
Time Remaining
Choose the Estimation Type called Time Remaining to use ranged estimates to statistically calculate your project schedule. Ranged estimates provide a natural way to account for the uncertainty and incorporate it into your plans for a more realistic forecast. In this step you’ll provide a percentage value which will be used to calculate the low and high estimate from the Jira “Time remaining” field.
For example, if “Time remaining” is 100h, 20% would set the range at 80h – 120h.
Learn more in the Remaining Estimate video in the Academy.
Story Points
You can also select the Estimation Type drop-down to estimate using Story Points. There are three options for mapping story points:
- Create a new scheme
- Copy an existing scheme
- Use the default scheme
Learn more about Story Points.
| 8 | Launch |
At this last step, Launch closes the integration window and creates a new project instantly, with tasks generated shortly after the sync completes. You may navigate away from the project while the sync is in progress.
| 9 | Sync and Modify Setup |
Example of Integration Organized by Flat List
When a project has been pulled in from Jira, it can be synced and modified through the drop-down menu under the Jira Integration button.
- Sync Both Ways: Pull in the latest Jira updates, including new issues, and send LiquidPlanner schedule data back into the Jira Project. Specific updates that can be sent back to Jira include a task status change, re-assignments from one person to another, task priority position (overrides Jira issue rank) and Priority custom fields.
- One Way Sync From Jira: Select to only pull in data from Jira. This sync is recommended if you want to work with the latest data from Jira in LiquidPlanner without sending anything back to your Jira project.
- Modify Setup: this link takes you back to integration setup window where you can edit filters, mapping and remaining estimate calculations. Changes take effect the next time you sync.
- Alerts: You will be alerted when there are sync errors. A few of the more common errors are listed below.
- The workspace doesn’t have enough Resources for Assignable Users in Jira.
- The issue was deleted in Jira, and a task still exists in LiquidPlanner.
- Authentication failed due to invalid credentials.
Important: After you log work in LiquidPlanner and perform a two-way sync, you may experience your Latest Finish dates changing for some tasks on each sync. This behavior is expected because time tracking and estimate data are always a one-way pull from Jira into LP.
By selecting a task on the list and visiting the Properties, you can view additional data that was pulled in from Jira. You can view the Issue Key and select it to open the issue directly in Jira. Additional information includes the Project Name, Issue Type, Priority, and Epic fields.
Delete Folders or Tasks
You can also delete folders or tasks that have populated in LiquidPlanner. Deleting items in LiquidPlanner does not delete them in Jira and vice-versa. On your next sync, deleted items are re-created in LiquidPlanner if they match the filter criteria. Select the three-dot icon next to a Folder or Task and select Delete Sub-Folder or Task. Re-sync to make these items re-appear on your list.
