How to create or modify custom team field mappings in Jira Align using API calls
Platform Notice: Cloud and Data Center - This article applies equally to both cloud and data center platforms.
Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
Summary
Using the Jira Align REST API, it is possible to create or modify the team mappings for a custom team field from Jira. This article discusses the API calls needed for such changes.
WARNING
This article refers to using a custom team field in Jira and relates to the original method of synchronizing teams between Jira and Jira Align. The content should not be used to configure the recently introduced, alternative method to synchronize team details using the built-in JIra team field (which makes use of completely different API calls as discussed in Set up Jira connector team mappings with the API 2.0 )
Solution
Create a team mapping using a POST API call to the team mappings endpoint :
POST /rest/align/api/2/Connectors/1/customFields/teams
1
2
3
4
5
6
7
{
"jiraCustomFieldType": "dropdown",
"jiraTeamValue": "Jira Team Name",
"childTeamValue": "",
"projectKey": null,
"teamId": 6023
}Notes:
the number following the word Connectors in the endpoint URL must match the connector being used (for most environments there will be only 1 connector, so this number will often be 1)
setting the projectKey to null creates a default team mapping, specifying a Jira projectKey results in a Project Specific Team Mapping being created
the numeric teamId (in the example above it is 6023) can be found by in the Team list in the Jira Align console (Team > View all teams) or by using a GET API call to the Teams endpoint ( /rest/align/api/2/Teams )
Updating a team mapping using a PATCH API call to the team mappings endpoint
Modifying a team mapping using a PATCH API call to the team mappings endpoint:
In order to modify a team mapping you first need to know the mapping ID of the existing mapping, so first run a GET API call to the customfields/teams endpoint:
/rest/align/api/2/Connectors/1/customfields/teams?filter=contains(projectKey,'PK') Where PK is your Jira project key
then to change Jira Team Name being mapped (as an example) use the PATCH API call
PATCH /rest/align/api/2/Connectors/1/customfields/teams/<mapping id>
1
2
3
4
5
{
"op": "replace",
"path": "jiraTeamValue",
"value": "New Jira Team Name"
}Notes:
the <mapping ID> used in the endpoint URL needs to be set based on the results of the GET call
if using child teams, you can optionally modify the child team name using this method, just set the path to "childTeamValue"
Due to an acknowledged bug, this method currently only works for Project Specific Team Mappings, attempting to change a default team mapping will fail with a 'ProjectKey not found' error. See this bug ticket for more details: API: Unable to modify a custom team mapping with null jira projectKey
Was this helpful?