Jira and Jira Align Integration: Validating Data After Configuration

[#1]

Purpose:

Integrating Jira with Jira Align is a multi-phase process.  Establishing the connectivity, checking the health of the projects and boards to be integrated, and configuring the connector are the phases that precede the activities in this article.  The next step is to confirm that the Jira connector is properly configured and syncing data as expected.  The data to be validated and how to do this will be covered in this article.

Data Validation

Have all items synced?

One basic validation to perform is simply that all of the issues have synced from Jira to Jira Align.  This can be done by project and issue type.  Information to keep in mind:

• Issues are brought into Jira Align by project and not board
• Jira projects map to Jira Align programs
• Jira boards map to Jira Align teams

Validation steps for 1:1 ratio of project to program for Jira epics (features):

1.  In Jira, select the project and click on All Issues

2.  Click on Advanced Search

3.  If in JQL view, click on Switch to basic

4.  Make sure the following are selected:

• Project = Integrated project
• Type = Epic
• Status = Canceled
• Created Date = Date used in JQL to bring in data (check with Jira Align Admin for date if unknown)
• Updated Date = Date used in JQL to bring in data (check with Jira Align Admin for date if unknown)

5.  Select Switch to JQL

6.  Change the following and then click Search:

• Status "=" to "!="
• The "AND" between the dates to "OR"
• Add parentheses around the created and updated dates

7.  Confirm appropriate results are returned and the number of issues returned

8.  In Jira Align, select the associated program for the project in the top config bar and make sure there is no PI selected

9.  Select Program and Features (Jira Epics) from the left hand navigation menu

• Note:  "Features" may be called something different if it was renamed in your Jira Align instance

10.  Confirm the number of items returned matches the number of issues returned in step 7

Validation steps for multiple:1 ratio of projects to program for Jira epics (features):

11.  Follow steps 1 - 9 above

12.  On the Features Grid, click Apply Filters

13.  Select "JIRA Projects" from the dropdown

14.  Select the Jira project used in step 1 above

15.  Click Filter

16.  Pick up with step 10 above

17.  These steps need to be done for each Jira project that contains epics (features)

Validation steps for stories, bugs and sub-tasks:

1.  Use the same steps listed above according to configuration of ratio of project/s to program with modifying the following steps

• 4.  Select Type as Story, Bug, Sub-task
• 9.  Select Team and then Stories, Defects or Tasks (Sub-tasks) from the left hand navigation according to the Type that was selected in step 4

2.  If counts are off, will need to start drilling down to board as opposed to project in Jira and Team as opposed to Program in the top configuration bar in Jira Align

• Things to keep in mind with stories if counts are off:
  • If there have been any custom issue types mapped, these sync over as stories
    • For example, Tasks from Jira would become a story in Jira Align with story Type listed as "Task"
    • In this case, issue type of "Task" would need to be included in the Jira query

Troubleshooting:

Things to check if counts don't match:

• Have issues with canceled status been filtered out?
• Are there issue types in the query in Jira that are not being synced over to Jira Align?
• Are there custom required fields on the issue in Jira that don't sync to Jira Align?
• If a certain issue type is not syncing over that is expected, was it properly configured in the connector settings?

Are the fields between the issues properly syncing?

There are certain fields that will sync by issue type between Jira and Jira Align.  These can be referenced in Jira Data Synchronization.  It is important to confirm on the various issue types that the data has properly synced.  It is best to spot check issues by project for this validation.

1.  Confirm data from the initial sync by issue type

2.  Update data in fields in Jira by issue type

3.  Confirm updates made properly sync to Jira Align

4.  Update data in fields in Jira Align by issue type

5.  Confirm updates made properly sync to Jira

Note:  In Jira Align, there are separate boxes to add acceptance criteria individually for work items.  This is NOT supported by the connector.  All acceptance criteria needs to be added to the first box only.

Troubleshooting:

Things to check if fields don't match:

• Has the State Mapping been properly mapped?
• Has the field been made visible in Jira Align in the Details Panels Settings?
• If updated in Jira Align, does the API Service Account have the appropriate permissions?
• If updated in Jira Align, are the appropriate fields present on the create/edit screens?

When a new item is created, is it properly syncing to the other tool?

It is possible when creating a new work item for the sync to be successful one way and not the other.  It can also vary at the different levels meaning an epic could sync from Jira to Jira Align but something could be preventing a story from syncing from Jira to Jira Align.  It is all possible for sync errors occur by project.  Due to this, it is important to confirm syncing of all items both directions by project.

Validation steps by project:

1.  Create an issue type of epic in Jira and confirm it syncs to Jira Align

2.  Create a feature (Jira epic) in Jira Align and confirm it syncs to Jira

3.  Repeat steps 1 and 2 for all issue types being synced

• This includes any custom issue types that have been mapped

Troubleshooting:

Things to check if the newly created item is not syncing to the other tool:

• If created in Jira Align, was the Jira project selected on the work item?
• If created in Jira Align, does the API Service Account have the appropriate permissions?
• If created in Jira Align, are the appropriate fields present on the create/edit screens?

Is the state/process step/status properly updating?

State mapping in the Jira connector can be complicated depending on how many Jira workflows there are, how complex those workflows are and if bi-directional syncing of Jira Align process steps are being used.  Because this mapping is done at the various levels (epic/feature, story, bug and sub-task) as well as by project, it is necessary to confirm these items are properly updating both ways as expected for each project.

Note:  If this validation is being performed by someone other than the Jira Align Admin, the Admin should provide that person with the expected mapping.  The name of the status in Jira may map to a different named state or process step in Jira Align and vice versa.  It's according to what has been configured in the connector settings.

Validation steps by issue type AND project if only using state mapping for an issue type:

1.  Start with an epic in Jira in the first status of the workflow

2.  Confirm the state of the feature in Jira Align matches the status of the Jira epic

3. Update the Jira epic to the next status in the workflow

4.  Confirm the state of the feature in Jira Align updated as expected

5.  Continue with steps 3 and 4 until all statuses have been selected

6.  Start with a feature in Jira Align in the first state

7.  Confirm the status of the epic in Jira matches the state of the Jira Align feature

8.  Update the Jira Align feature to the next state

9.  Confirm the status of the epic in Jira updated as expected

10.  Continue with steps 8 and 9 until all states have been selected

11.  Repeat steps 1 - 10 for stories (bugs, if applicable)

12.  Repeat steps 1 - 5 for sub-tasks (if applicable)

• Status only syncs from Jira to Jira Align for sub-tasks and therefore steps 6 - 10 do not apply

Troubleshooting:

Things to check if status/states are not updating as expected:

• If updating status in Jira, check the State Mapping tab in the connector to confirm the correct Jira status is mapped to the correct Jira Align state
• If updating state in Jira Align, check the State Mapping link for the project in the connector to confirm Jira Align state is mapped to the correct Jira status
• Next Gen projects can created duplicate statuses.  In this case, the ID of the status needs to be confirmed.

Validation steps by issue type AND project if only using bi-direction process step mapping for an issue type (only available for Jira epics (features) and stories:

1.  Start with an epic in Jira in the first status of the workflow

2.  Confirm the process step of the feature in Jira Align matches the status of the Jira epic

• Full Details must be selected on the work item in Jira Align to view the process step

3. Update the Jira epic to the next status in the workflow

4.  Confirm the process step of the feature in Jira Align updated as expected

5.  Continue with steps 3 and 4 until all statuses have been selected

6.  Start with a feature in Jira Align in the first process step

7.  Confirm the status of the epic in Jira matches the state of the Jira Align feature

8.  Update the Jira Align feature to the next process step

9.  Confirm the status of the epic in Jira updated as expected

10.  Continue with steps 8 and 9 until all process steps have been selected

11.  Repeat steps 1 - 10 for stories

Troubleshooting:

Things to check if status/states are not updating as expected:

• If updating status in Jira, check the process step mapping in Manage Custom Fields in the connector to confirm the correct Jira status is mapped to the correct Jira Align process step
• If updating process step in Jira Align, check the Process Step tab in the State Mapping link for the project in the connector to confirm Jira Align process step is mapped to the correct Jira status
  • Also confirm that nothing on the State tab is mapped except for "Canceled"
• Next Gen projects can created duplicate statuses.  In this case, the ID of the status needs to be confirmed.

[Richard Wilson _Jarow Digital_]

Thanks Rae great to share all the extra details. I got caught on a Next Gen Security recently. 
Appreciate you connecting to https://community.atlassian.com/t5/Jira-Align-articles/Jira-Align-and-Jira-Integration-Best-Practices-and-FAQ-Table-of/ba-p/1253497 as my goto page in the community.