Ensure you have completed all steps in Jira integration prerequisites before proceeding.
Note: You can download an Excel spreadsheet of all of the tables in this article here.
Jira projects and boards
1. Create a list of Jira Project Keys and Jira Project Names that you plan to synchronize to Jira Align. Determine to which Program/Release Train each Jira project maps. Please note each Jira Project can only be mapped to one Jira Align Program due to the Jira Align data model which associates Jira Projects to Jira Align Programs.
To find a Jira Project Key:
When logged into Jira, select your project, and then look at the URL. In the URL, you can find the Project Key: https://your_jira_name.net/projects/PROJECTKEY/
|
Project Key |
Project Name |
Program/Release Train Name |
|
(e.g. MDP) |
(e.g. ) Mobile Delivery Platform |
(e.g. Mobile Release Train) |
2. For each project above, create a list of Jira Software Agile Board IDs, which are in the URL for the board, that you plan to synchronize to Jira Align (for example, RapidView=38). Determine to which Program in Jira Align each Jira Software board will map and specify a friendly name for the Team to create.
To find a Jira RapidView ID:
When logged into Jira, select your project, and then go to Board/Backlog/Sprints (or select your board from the board list). Next, look at the URL to find the RapidView ID:
|
Board ID |
Team Name |
Program |
|
(e.g. 123) |
(e.g. Superheroes) |
(e.g. Mobile Release Train) |
3. If you use a filter to determine what issues appear on the Backlog portion of the Jira Software Agile Board, record the field name that does the board assignment (a custom drop-down menu or a label in Jira Software). This might be different for each Jira Software project being mapped.
|
Jira Software Project |
Drop-down menu or Label |
Field Name |
JA Team Name |
Value to set in Jira Software |
|
|
|
|
|
|
|
|
|
4. Run JET (available in the Atlassian Marketplace) for the boards you wish to integrate. Your Jira Align Solutions Architect will assist. JET will help determine how your boards and sprints should be configured and optimized for the integration, as well as provide some useful metrics about the cleanliness of your data in Jira Software.
5. Determine the start date (how far back in time) from which you want to import data. This will determine how many historical Program Increments you need to set up in Jira Align.
| Date to import from: |
Jira custom field IDs and issue type names
1. Record the Issue Type Names for company-managed projects in the table below. This is a word, not a number, see the example screenshot.
2. Record the Issue Type IDs for your company-managed projects in the table below. To find the Issue Type IDs, follow the instructions outlined here: https://confluence.atlassian.com/jirakb/finding-the-id-for-issue-types-646186508.html
|
Jira Issue Type |
Your Issue Type Name (e.g. Task) |
Your Issue Type ID (e.g. 10000) |
Description |
|
Epic |
|
Five-digit issue type ID number and name from Jira for Epic. * If you’re using Jira Software Data Center and can’t find an issue type called Epic, the issue type name may have been changed. |
|
|
Story |
|
Five-digit issue type ID number and name from Jira for Story. | |
|
Sub-Task |
|
Five-digit issue type ID number and name from Jira for Sub-Task (or Task). | |
|
Defect |
|
Five-digit issue type ID number and field name from Jira for Bug/Defect. |
3. Record the Custom Field names and ID numbers in the tables below. The quickest way to collect the Custom Field IDs is to open the Advanced Issue Search in Jira and start typing the field name. This will show you the Custom Field number as shown in the screenshot below.
|
Custom Field Purpose |
Your Custom Field Name (e.g. Points) |
Your Custom Field ID (e.g. customfield_10000) |
Description |
|
Epic Name |
Five-digit custom field ID number and field name from Jira for EpicName. |
||
|
Epic ID Link |
|
Five-digit custom field ID number and field name from Jira for EpicLink or EpicIDLink. | |
|
Story Points |
|
Five-digit custom field ID number and field name from Jira for Story Points. |
|
|
Sprint ID |
Five-digit custom field ID number and field name from Jira for SprintID. | ||
|
Accepted Date |
|
The field name of the value/flag set when a user completes the workflow on an item by clicking the DONE button on the issue screen. * This one can be tricky to find as it is called Accepted, AcceptedDate, ResolutionDate, Resolution, or Resolved depending on the version of Jira being used and any customizations that may have been made. |
|
|
Rank |
|
Five-digit custom field ID number and field name from Jira for Rank. |
| Additional fields for company-managed projects These fields may be used with Jira Align and Jira Software integration if created. |
|||
|
Custom Field Purpose |
Your Custom Field Name (e.g. Points) |
Your Custom Field ID (e.g. customfield_10000) |
Description |
| Feature Points |
Optional: Five-digit custom field ID number and field name from Jira for Feature Points. |
||
| Team | Optional: Five-digit custom field ID number and name from Jira Software for Team. | ||
| Deleted Item Status |
Optional: The Status value from Jira Software which will result in items being permanently deleted from Jira Software. Use the format 12345 when filling in the Custom Field ID. * Do not use this if you want to use the recycle bin (two-stage delete) process in Jira Align. |
||
| MMF | Optional: Five-digit custom field ID number and name from Jira Software for MMF. | ||
| Product | Optional: Five-digit custom field ID number and name from Jira Software for Product for Jira Align features. | ||
|
Feature Portfolio Ask Date |
Optional: Five-digit custom date picker field ID number and name from Jira Software for Portfolio Ask date for Jira Align features. |
||
|
Feature Start / Initiation Date |
Optional: Five-digit custom date picker field ID number and name from Jira Software for Start / Initiation date for Jira Align features. |
||
|
Feature Target Completion Date |
Optional: Five-digit custom date picker field ID number and name from Jira Software for Target Completion date for Jira Align features. |
||
|
Why? Details |
Optional: Five-digit custom field ID number and name from Jira Software for Portfolio Ask date for information from Jira Align's Why panel. Use the following format: customfield_123. This is a PUSH ONLY from Jira Align to Jira Software.The field in Jira Software must be read-only. |
||
| Parent Feature Name |
Optional: Five-digit custom field number and name from Jira Software for a parent item for Jira Align features (either an Jira Align capability or epic). This is a PUSH ONLY from Jira Align to Jira Software. The field in Jira must be non-editable by anyone except admin/Jira Align integration role. |
||
| Jira Align PI |
Optional: Five-digit custom field number and name from Jira Software for Jira Align Program Increment. This is a PUSH ONLY from Jira Align to Jira Software. The field in Jira Software must be non-editable by anyone except admin/Jira Align integration role. |
||
|
T-Shirt |
Optional: Five-digit custom field number and name from Jira Software for T-shirt sizing. This is a PUSH ONLY from Jira Align to Jira Software. The Jira field should be a select list (single option) field. |
||
| Capability Parent |
Optional: Five-digit custom field number and name from Jira Software for a capability’s parent epic, to display on Jira Align features where capabilities are enabled. This is a PUSH ONLY from Jira Align to Jira Software. The field in Jira Software must be non-editable by anyone except admin/Jira Align integration role. |
||
|
Work Code (features only) |
Optional: Five-digit custom field number and name from Jira Software for a work code on Jira Align features. |
||
| Acceptance Criteria | Optional: Five-digit custom field ID number and name from Jira Software for Acceptance Criteria. | ||
4. Create a list of custom issue types (anything that is not an epic, story, or bug) that you want to synchronize to Jira Align in your company-managed projects. Custom issues will synchronize to Jira Align as Stories with a specific type.
|
Custom Issue Type |
Your Issue Type Name (e.g. Spike Story) |
Your Issue Type ID (e.g. 10000) |
Intended Use |
5. Create lists for team-managed projects of the issue type names and IDs in the tables below. The IDs for each issue type are specific to each individual project, so create a separate list for each team-managed project.
You can locate individual issue type IDs for team-managed projects on the project's Project Settings > Issue Types page by hovering over the issue type name on the left-hand sidebar. The ID is the five-digit number at the end of the URL on the lower-left of the page.
|
Jira Issue Type |
Your Issue Type Name (e.g. Task) |
Your Issue Type ID (e.g. 10000) |
Description |
|
Epic |
|
Five-digit issue type ID number and name from Jira for Epic. | |
|
Story |
|
Five-digit issue type ID number and name from Jira for Story. | |
|
Sub-Task |
|
Five-digit issue type ID number and name from Jira for Sub-Task (or Task). | |
|
Defect |
|
Five-digit issue type ID number and field name from Jira for Bug/Defect. |
|
Additional fields for team-managed projects These fields may be used with Jira Align and Jira Software integration if created. |
|||
|
Custom Field Purpose |
Your Custom Field Name (e.g. Points) |
Your Custom Field ID (e.g. customfield_10000) |
Description |
|
Story Points |
Optional: Five-digit custom field ID number and field name from Jira for Story Points. |
||
|
Parent Feature Name |
|
|
Optional: Five-digit custom field number and name from Jira Software for a parent item for Jira Align features (either a Jira Align capability or epic). This is a PUSH ONLY from Jira Align to Jira Software. The field in Jira must be non-editable by anyone except admin/Jira Align integration role. |
| Capability Parent |
|
|
Optional: Five-digit custom field number and name from Jira Software for a capability’s parent epic, to display on Jira Align features where capabilities are enabled. This is a PUSH ONLY from Jira Align to Jira Software. The field in Jira Software must be non-editable by anyone except admin/Jira Align integration role. |
|
Program Increment Text Field |
Optional: Five-digit custom text field number and name from Jira Software for Jira Align Program Increment. This is a PUSH ONLY from Jira Align to Jira Software. The field in Jira Software must be non-editable by anyone except admin/Jira Align integration role. |
||
|
Acceptance Criteria |
|
|
Optional: Five-digit custom field ID number and name from Jira Software for Acceptance Criteria. |
|
Feature Portfolio Ask Date |
|
|
Optional: Five-digit custom date picker field ID number and name from Jira Software for Portfolio Ask date for Jira Align features. |
|
Feature Start / Initiation Date |
|
|
Optional: Five-digit custom date picker field ID number and name from Jira Software for Start / Initiation date for Jira Align features. |
|
Feature Target Completion Date |
|
|
Optional: Five-digit custom date picker field ID number and name from Jira Software for Target Completion date for Jira Align features. |
6. Create a list of Link Actions. Link Actions may be imported from Jira Software and converted into dependencies in Jira Align.
|
Link Name (e.g. Blocked by) |
Issue Link Type ID (e.g. 10000) |
Intended Use |
7. Determine if the following fields are required on work items.
|
Item |
Required on Epic (Yes/No) |
Required on Story (Yes/No) |
Required on Defect (Yes/No) |
| Points on Epic? | N/A | N/A | |
| Is Team required when an item is created? | |||
| Is Reporter required when an item is created? | |||
| Sync State bidirectionally? | |||
| Sync Work Item bidirectionally? | |||
| Sync Rank bidirectionally? | N/A |
Print 
PDF
Join the Atlassian Community!
The Atlassian Community is a unique, highly collaborative space where customers and Atlassians come together. Ask questions and get answers, start discussions, and collaborate with thousands of other Jira Align customers. Visit the Jira Align Community Collection today.
Need to contact Jira Align Support? Please open a support request.