Syncing the Team Field Between Jira Software and Jira Align

[#1]

The Jira to Jira Align integration syncs the Team field between Jira Align and Jira Software on various work items (Jira Software Issues).  The method of team synchronization depends on work item (issue type) and application setup. 

Work Item (Issue Types):

Feature (Jira Software Epic): The Jira Align feature doesn't have a Team field, since Jira Align features are assigned to programs instead of directly to Agile teams.  This means a team value won't sync from Jira Software to Jira Align at the feature (Jira Software Epic) level.  If a custom team field is required on the Jira Epic Create Screen in Jira Software, the field won't be populated when initial creation occurs in Jira Align.  This would lead to a connector sync error, resulting in the failure to create the issue in Jira Software.  We recommend making any team field on the Jira Software Epic screen not required in Jira, or to manage all creation of Jira Software Epics in Jira Software.

Story: The Jira Align story syncs bi-directionally with the Jira Software story issue type.  The team field on the Jira Align story syncs in one of two ways:

1. Team boards in Jira Software are configured on a one integrated team board per a project basis with a correctly established filter share.
2. Custom team mappings configured under Jira Align Admin > Jira Settings > Manage Custom Fields.

One Integrated Team Board per Project Team Sync:

In Jira Software, projects consist of boards with filter queries to determine which issues will show on a board and filter shares to associate projects and groups to boards.  To facilitate the Team field sync from Jira Software to Jira Align on stories, the Jira Integration will use a single project shared to a board's filter share to populate a project mapping for boards under Jira Align Admin > Jira Management.  When there is only one integrated board for each integrated project between Jira Align and Jira Software, the connector will populate the Jira Align Team field based on this mapping.  If there is more than one integrated board for an Integrated Project or the board has a No Project Found error, the connector won't be able to make this association and custom team mapping must be utilized to sync the Team field between Jira Software and Jira Align.

No Project Found errors will appear next to a board mapping on the Jira Align Admin > Jira Management page for one or more of the following reasons:

1. The connector service account does not have permission to view the board in Jira Software or the board was deleted.
2. The board has a filter share without the parent project in Jira Software.
3. The board has a filter share with multiple projects in Jira Software.

Notes:

• This error will result in stories assigned to the Jira Software Backlog or stories from a Kanban-type board in Jira Software to not receive a team assignment when they're synced with Jira Align.  Stories that are assigned to a sprint in Jira Software that is mapped to a sprint in Jira Align will still have their Team fields populated through the sprint mapping.
• If a project has multiple boards in Jira Software, but only one of the boards is mapped to Jira Align, there won't be an error finding the project as long as the board's filter share is set correctly to its parent project.
• The connector supports mapping both a project and a user group to a board's filter share, but more than one project will lead to the No Project Found error.
• The board's parent project must be included in the filter's Shares permission, not the filter's Edits permission. The latter will cause Team assignment to fail.

Custom Team Field Mapping Team Sync:

Custom Team field mapping is required in scenarios where there is more than one integrated board per a mapped project, or when the board owners don't want to adjust their board's filter share. 

Jira Requirements and Setup for Custom Team Field Mapping:

The Custom Team field mapping requires the Standard Select List (single choice) field type from Jira Software, present on the Create and Edit screens of the Story issue type. 

To create the custom field in Jira, click Jira Administration > Issues > Custom Fields and then click "Add Custom Field" in the upper right corner of the Custom Fields page. 

Once the Custom Field has been created, please make sure the field is added to the Create and Edit screens of the Story Issue Type your Jira Instance. 

NOTE - The Jira Integration does not support plugin or non-standard fields for the implementation of this custom field. 

Jira Align Custom Team Field Mapping Setup:

To set up Custom Team field mapping in Jira Align, please follow the steps below.

Navigate to the Jira Align Administration > Jira Settings > Jira Setup panel:

1. Populate Team custom field: The key for the Jira Software field used for a team. Use the following format: customfield_123.
2. Click Configure next to Team custom field to map Jira and Jira Align teams.
3. Select the Jira Software project to which the Jira Software team that you want to synchronize belongs.
4. Select if the team custom field in Jira Software is a drop-down or a label.
5. Type the custom team field value in the corresponding box. Use the following format: customfield_#####, where ##### is the team custom field ID in Jira Software.
6. Under Sync Jira Team Values with Jira Align Teams, click Add New.
7. In the Jira Team Value box, type the name of the team in Jira Software that you want to synchronize. This must match exactly to the field's value in Jira Software.  The Parent field will be populated with the left value of a Jira Software cascading field and the Child field will be populated with the right value of a Jira Software cascading field.  If a single-select or multi-select drop-down is being used, the Child field should be ignored.
8. From the Jira Align Team drop-down menu, select the team in Jira Align with which you want to synchronize the Jira Software team.
9. Click Update Teams.
10. To add more teams, click Add New and repeat Steps 6–9.

Close the Jira Custom Setup panel and navigate back to Admin > Jira Settings > Jira Setup. Complete the setup by configuring appropriate values for the following additional settings:

• Does story creation in Jira require a team assignment?
  • Select Yes if the Jira Story issue type screen has a required team field.  This setting will require the custom field ID of the Jira custom field utilized for team mappings to be listed on the Team custom field field.
• Is your Jira Team field a cascading select list?
  • Select Yes if the custom Team field in Jira Software is a cascading field and No if the custom Team field in Jira Software is a single- or multi-select field.
• Is your Jira Team field a multiple choice select list?
  
  • Select Yes if the Team field in Jira Software is a multi drop-down and No if it's single-select to help reading and writing the data.

Custom Type Stories: 

Stories with custom types will sync bi-directionally between Jira Software and Jira Align.  The Team field sync for these stories will adhere to the same logic as the Jira Software to Jira Align story Team field sync.

Defect (Jira Bug): 

The Jira Software bug will sync bi-directionally between Jira Software and the Jira Align defect.  The Team field sync will adhere to the same logic as the Jira Software to Jira Align story Team field sync.

[Mark Cruth]

A couple additional insights to share on syncing the team field between Jira and Jira Align:

1. If your organization is using the Component ID field to apply Team Name in Jira, the integration with Jira Align will not be able to map the Team Name. Today Jira Align does not support mapping the Component ID field because it's custom per Jira Project. 
2. If you're not able to create a custom field for Team Name in Jira, you can use Jira Labels. Although not recommended due to the ability to fat finger values in the Labels field, you can map Labels to Teams in Jira Align. The steps are nearly the same as above except...you will leave the Organization field blank, and you will select "Label" as the type associated with the project within the Custom Fields window. 

[Brant Schroeder]

Thanks this was very helpful.

[Rolf Eckardt]

I understand all the steps above and I am just about to configure the additional custom field in JIRA.

However there are a few questions around the master data for teams field in JIRA:

Kira Align stores the defined teams, lets say Team A and Team B. I have configured the teams custom field in JIRA as a select list (multiple choice) with the same values "Team A" and "Team B".

Case 1: someone creates in JIRA Align "Team C"  - do I need to ensure manually that "Team C" is also available in JIRA ?

Case 2: someone creates in Jira "Team D" and it gets assigned to a user story. What is happening in this case when the data gets synced ?

Finally: what is the purpose of the Teams information in JIRA Align? 

[Mark Cruth]

Great questions @Rolf Eckardt ! 

For Case #1, if you are using a team drop-down to associate Jira items with a team (this is applicable if you have one Jira Project with multiple Jira Boards associated with it), you would need to ensure that Team C is in the Jira custom team drop-down. Then you would map the values together in Jira Align (like you did for Team A and B). If you didn't map the values that only work that would show up in Jira Align associated with Team C is work assigned to a Team C sprint (when Jira Align syncs with Jira Boards we pull the sprint information in and can infer a team based on the sprint work lives in...if the work lives in the backlog we're unable to make that association without the team field being mapped). 

For Case #2, if you had a new team created and the value "Team D" doesn't exist in Jira Align, the work item would still sync over to Jira Align (if it's within a sync Jira Project) and the Team field would be blank. If you later added "Team D" to Jira Align you could re-run Jira Integration and the Team field would update automatically to reflect "Team D". Jira Align needs to have that mapping in place to make the appropriate assignment. 

I hope that helps!

[Rolf Eckardt]

Thx for quick answer. So you are saying that we need to control values manually in order to keep values in sync in both systems?

I still dont understand what JIRA Align uses the Team information for? What fails if we do not have this custom field in JIRA like we have it currently in our POC?

[Mark Cruth]

You only need to set these values manually if you use a one Jira Project with multiple Jira Boards setup. If you have a one Jira Project to one Jira Board relationship you don't have to do this mapping (Jira Align infers that if a work items is associate with a Jira Project that it belongs to that Jira Board/Team). If you have to map the team field (because you have the one project, multi-board situation), we recommend it be part of the onboarding process for a new Jira Align teams (that way the mapping isn't missed and it's a rinse and repeat process for each new team). 

In terms of things breaking, the biggest issue that occurs if you don't do the mapping is the work items in the backlog for the team being mapped will not be associated with the team (team field will be unassigned). Without doing the mapping, work items will only be associated with the team if they are assigned to a sprint (when we sync up the Jira Boards to Jira Align Teams we bring over sprints and associate them with teams). Otherwise, the work items will not have a team in Jira Align (the work will still sync over, just without a team assignment). 

[Bonnie Beyer]

Can the team assignment field be a required field in Jira?

[Mark Cruth]

@Bonnie Beyer - sure can! In Jira go to Settings > Issues > View Field Configuration. Once on this page find the custom field you use for team. Once here you can mark the fields as "Required" (see screenshot). 

Hope this helps!

[Bonnie Beyer]

I know how to make the field required in Jira.  But we've been told that you cannot have any required custom fields on Stories or Jira Epics without breaking the synch between Jira and Jira Align.  Is the Jira custom field that maps to the "Team" field in Jira Align the exception?  Can it be a required field in Jira without breaking the Align/Jira synch?

[Mark Cruth]

@Bonnie Beyer - I see what you're asking now :-) Yes, this is one of the exceptions, though you will need to do a couple things. First, in Jira Align Admin > Jira Settings > Jira Setup tab, make sure the option "Story Creation Requires Team" is set to YES (this will make the team field required in Jira Align on Stories, which avoids sync issues if you don't add a team value). Additionally, on the Jira Align Admin > Jira Settings > Manage Projects tab > Manage Custom Fields modal you will need to map the custom  field from Jira for "team" and setup the team mapping (see screenshot). Doing these steps will allow you to make the team field required in Jira and prevent sync issues if stories are created in Jira Align.

[LAXMI ABHINAV REDDY ARAE]

Hello,

 May I please know, how does the users assigned to the project where the custom teams are used in Jira sync/copied over to Jira Align teams automatically?

Thank you.

[Sanwar Mal]

Has anyone seen such error on team field syncing ?

By External System on 4/29/2022 5:36:53 PM
Failed to update JiraID : XXXXXX - Response: 400 BadRequest Json: {"errorMessages":[],"errors":{"Scrum Team(s)":"Specify the value for Scrum Team(s) in an array"}}