How to filter users by their team information when using the Jira Align REST API
Summary
This article shows how to use the $filter query parameter to find users based on the team information (such as Id/name/roleId) they are member of.
Environment
Jira Align
Solution
The examples in this article come from a test environment
Assume you have a team with a configuration similar to the following
{
"id": 2063,
"name": "FXP Portfolio Team",
"ownerId": "661802",
"regionId": 16,
"programId": 1179,
"type": 5,
"isActive": 1,
"description": "FXP Portfolio team",
"sprintPrefix": "FXP",
"shortName": "FXP",
"trackBy": 1,
"maxAllocation": null,
"allowTaskDeletion": 0,
"allowTeamToRunStandup": 0,
"isKanbanTeam": null,
[..]
"self": "https://-------.jiraalign.com/rest/align/api/2/teams/2063"
}and would like to find all the users that are members of this team.
The users endpoint will give you a collection (array) of teams fields under each user such as:
{
"id": 661838,
"uid": "661838",
"firstName": "FrancoisGmail4",
"lastName": "PANAGETGmail4",
"fullName": "FrancoisGmail4 PANAGETGmail4",
"email": "---------",
"userStartDate": "2022-10-19T00:00:00Z",
[...]
"isLocked": 0,
"status": "Active",
"regionId": 17,
"title": "SUPER TITLEzz11",
"roleId": 91,
"cityId": 32,
"divisionId": 65,
"costCenterId": 1,
"holidayRegionId": 17,
"holidayCityId": 32,
[...]
"enterpriseHierarchy": null,
"teams": [
{
"teamId": 2063,
"teamName": "FXP Portfolio Team",
"teamType": 5,
"roleId": 12,
"roleName": "TeamOfTeam"
},
{
"teamId": 5983,
"teamName": "FxPTigerK",
"teamType": 1,
"roleId": 8,
"roleName": "Architect"
},
[...]
{
"teamId": 6293,
"teamName": "FXPProgram 3 Team",
"teamType": 2,
"roleId": 9,
"roleName": "Stakeholder"
}
],
"self": "https://-------.jiraalign.com/rest/align/api/2/users/661838"
}
]Although the documentation does not explicitly say the filtering on a collection (array) is supported by the users endpoint you can query on the ‘teams’ collection (array), for example for the teamId, with the following syntax (where 2063 is the numeric ID of the team):
/users ?$filter=teams/any(t:t/teamId eq 2063)
Using the Postman application this would the result in an output similar to the below (noting that in the example 'select' has also been used to reduce the displayed fields):