Teams Management Service

overview the teams api enables developers to manage team operations including creation, retrieval, updates, and deactivation the api offers operations for team creation, retrieval, updates, and deactivation it provides functionality to customize team properties such as operational hours and types, and allows managing team statuses how to use? supported operations the teams api offers the following operations createteam create a new team by providing the necessary details such as team name, team code, owner, operating hours, and team type updateteam modify the properties of an existing team, including the team name, owner, operating hours, and operating days listteams retrieve a list of all teams, with options for pagination, sorting, and filtering based on specific criteria getteam fetch the details of a specific team by providing its unique identifier updateteamstate perform state transitions to change the state of a team, such as activating or deactivating it getteamstate retrieve the current state of a team, indicating whether it is active or inactive filterteams obtain aggregate counts of teams based on specified filters and criteria state transitions teams can transition between the states the following table lists the allowed state transitions from state to state onboarding\ onboarding active\ active active\ active inactive\ inactiveactive\ deboardactive\ pause active\ pause active\ active active\ deboard active\ activeinactive\ inactive inactive\ inactive active\ active inactive\ terminal no further transitions note for more information on how the transition these states, refer to the update state team section implementation of apis use the teams api to create and manage teams the implementation include the following process create a team using the createteam endpoint with required parameters ( teamcode and teamname ) after team creation, you can add users and facilities using respective apis update team properties manage team states (activate/deactivate) retrieve team information manage team properties and states as needed examples 1\ creating a team to create a team, call the createteam endpoint use the below curl command to create a team curl curl location '{domain}/app/api/v2/teams' \\ \ header 'x coreos tid v2fpa19' \\ \ header 'x coreos access {{accesstoken}}' \\ \ header 'x coreos userinfo {"name" "admin","id" "123"}' \\ \ header 'content type application/json' \\ \ data '{ "teamname" "test", "teamcode" "testing", "teamtype" "support", "callback" { "url" "https //example requestcatcher com/test", "metadata" { "a" "b" } } }' body parameters parameter description teamcode the unique id for the team teamname the team name minlength 1 maxlength 128 teamownerid the unique id for the owner of the team teamtype defines the team type acceptable values operational support starttime the time at which the team starts operations on a given day operatinghours the hours for which the team is operational from the start time operatingdays the days of the week on which the team is operational list \[ "mon", "tue", "wed", "thu", "fri", "sat", "sun" ] callback callback configuration callback url callback url callback metadata callback metadata note parameters marked with an asterisk ( ) are required sample request { "teamcode" "team001", "teamname" "my dispatch team", "teamownerid" "user123", "teamtype" "operations", "starttime" "09 00", "operatinghours" "8", "operatingdays" \[ "mon", "tue", "wed", "thu", "fri" ], "callback" { "url" "https //example com/callback", "metadata" {} } } sample response if successful, the response will include a data object containing the team id in the example, the id c5d4b3a2 1f9e 4d8c b7a6 9c8d7e6f5a4b ,which will always contain prefix ' teams ' { "error" { "code" "", "description" "", "additionalinfo" {} }, "request" { "uri" "/teams", "requestid" "f3c8d6a2 8c7d 4a5b 9e1d 8f5c3b2a1d9f", "querystring" "", "body" {}, "method" "post" }, "data" { "id" "teams\ c5d4b3a2 1f9e 4d8c b7a6 9c8d7e6f5a4b" } } 2\ add users and facilities to a team once a team is created using the teams api, developers can add users and facilities using the user and facility apis this is done by associating them with the desired team through the appropriate api calls and providing the necessary information, such as the team id and the details of the users or facilities in your api calls, include the team id (from the team you created) the details of users or facilities you want to add for more information on how to use the user and facility apis, refer to their respective documentation 3\ listing teams the listteams endpoint to retrieve teams based on various query parameters the api supports pagination, allowing you to specify the number of teams per page and the page number you can also filter teams using the query parameter to sort the results based on specific criteria query parameters for listing teams parameter description size number of items in a page minimum 1 maximum 100 default 20 page page number to return (starting from 1) minimum 1 maximum 10000 select specifies list of attributes to be included in response (id is always included in response) if not specified, all attributes are included in response for example properties homefacilityid query query criteria refer to the api reference for the supported query syntax sortby the sorting order enum \["desc", "asc"] default "desc" sortkey the key to be used for sorting data additionalinfo toggle fetching of additional info enum \[true, false] membercount toggle fetching the number of members of a designation in a team enum \[true, false] sample request curl x get \\ 'https //{domain}/app/api/v2/teams?size=10\&page=1\&sortby=desc\&sortkey=createdat\&additionalinfo=true' \\ h 'x coreos tid {tenantid}' \\ h 'x coreos access {access token}'\\ h 'x coreos userinfo {"name" "admin","id" "123"}' sample response { "error" { "code" "", "description" "", "additionalinfo" {} }, "data" { "meta" { "totalelements" 2 }, "participants" \[ { "id" "teams\ c5d4b3a2 1f9e 4d8c b7a6 9c8d7e6f5a4b", "state" "active\ active", "participanttype" "teams", "name" "super team", "owner" "tenants\ a1b2c3d4 e5f6 g7h8 i9j0 k1l2m3n4o5p6", "uniquecode" "team001", "properties" { "starttime" "09 00", "operatinghours" "8", "operatingdays" \["mon", "tue", "wed", "thu", "fri"] }, "createdat" 1621500000, "createdby" { "id" "7", "name" "john doe" }, "updatedat" 1621500000, "updatedby" { "id" "7", "name" "john doe" } }, { "id" "teams\ f8e7d6c5 b4a3 2190 e8d7 c6b5a4931082", "state" "active\ active", "participanttype" "teams", "name" "awesome team", "owner" "tenants\ p6o5n4m3 l2k1 j0i9 h8g7 f6e5d4c3b2a1", "uniquecode" "team002", "properties" { "starttime" "10 00", "operatinghours" "6", "operatingdays" \["mon", "wed", "fri"] }, "createdat" 1621600000, "createdby" { "id" "8", "name" "jane smith" }, "updatedat" 1621600000, "updatedby" { "id" "8", "name" "jane smith" } } ] }, "request" { "uri" "/teams", "requestid" "a1b2c3d4 e5f6 g7h8 i9j0 k1l2m3n4o5p6", "querystring" "size=10\&page=1\&sortby=desc\&sortkey=createdat\&additionalinfo=true", "body" {}, "method" "get" } } the example response includes teams is array containing the team objects each team object includes various attributes such as id , state , name , owner , properties , creation and update timestamps, and associated user information 4\ get teams by id the getteam endpoint allows you to retrieve a specific team using its unique identifier or external reference path parameters parameter description teamid the unique id of the team sample request curl x get \\ 'https //{domain}/app/api/v2/teams/teams\ c5d4b3a2 1f9e 4d8c b7a6 9c8d7e6f5a4b' \\ h 'x coreos tid {tenantid}' \\ h 'x coreos access {access token}'\\ h 'x coreos userinfo {"name" "admin","id" "123"}' sample response { "error" { "code" "", "description" "", "additionalinfo" {} }, "data" { "id" "teams\ c5d4b3a2 1f9e 4d8c b7a6 9c8d7e6f5a4b", "state" "active\ active", "participanttype" "teams", "name" "my dispatch team", "owner" "tenants\ a1b2c3d4 e5f6 g7h8 i9j0 k1l2m3n4o5p6", "uniquecode" "team001", "properties" { "starttime" "09 00", "operatinghours" "8", "operatingdays" \["mon", "tue", "wed", "thu", "fri"] }, "createdat" 1621500000, "createdby" { "id" "7", "name" "john doe" }, "updatedat" 1621500000, "updatedby" { "id" "7", "name" "john doe" } }, "request" { "uri" "/teams/teams\ c5d4b3a2 1f9e 4d8c b7a6 9c8d7e6f5a4b", "requestid" "a1b2c3d4 e5f6 g7h8 i9j0 k1l2m3n4o5p6", "querystring" "", "body" {}, "method" "get" } } the response includes various attributes such as id , state , participanttype , owner , properties , and creation/update timestamps 5\ update team the updateteam endpoint allows to modify the details of an existing team with the updated team information in the request body you can update parameters such as the name, owner, start time, operating hours, and operating days the teamid parameter in the url path represents the id of the team you want to update note uniquecode is non editable body parameters parameter description teamname the team name teamownerid the unique id for the owner of the team teamtype defines the team type acceptable values operational support starttime the time at which the team starts operations on a given day operatinghours the hours for which the team is operational from the start time operatingdays the days of the week on which the team is operational list \[ "mon", "tue", "wed", "thu", "fri", "sat", "sun" ] callback callback configuration callback url callback url callback metadata callback metadata sample request the following request updates the following parameters teamname starttime opaerationhours operatingdays updateteam { "teamname" "my updated dispatch team", "starttime" "10 00", "operatinghours" "6", "operatingdays" \[ "mon", "wed", "fri" ] } sample response if the team is updated successfully, the api will respond with a 202 accepted status code and a success response object similar to the createteam response 6\ update team state the updateteamstate endpoint to update the state of a team with the desired state transition details in the request body you can change the team's state, such as activating or deactivating the team the teamid parameter in the url path represents the id of the team whose state you want to update state transitions the following table lists the allowed state transitions from state to state onboarding\ onboarding active\ active active\ active inactive\ inactiveactive\ deboardactive\ pause active\ pause active\ active active\ deboard active\ activeinactive\ inactive inactive\ inactive active\ active inactive\ terminal sample request the following request set's the team to an inactive state updatestate { "tostate" "inactive\ inactive", "reasoncode" "r 123", "data" {}, "callback" { "url" "https //example com/callback", "metadata" {} } } sample response if the team state is updated successfully, the api will respond with a 202 accepted status code and a success response object similar to the createteam response 7\ get team state the getteamstate endpoint to retrieve the current state of a specific team the teamid parameter in the url path represents the id of the team whose state you want to retrieve sample request curl x get \\ 'https //{domain}/app/api/v2/teams/teams\ c5d4b3a2 1f9e 4d8c b7a6 9c8d7e6f5a4b/state' \\ h 'x coreos tid {tenantid}' \\ h 'x coreos access {access token}'\\ h 'x coreos userinfo {"name" "admin","id" "123"}' sample response if the request is successful, the api will respond with a 200 ok status code and a json object containing the team's state information in the following format { "error" { "code" "", "description" "", "additionalinfo" {} }, "data" { "state" "active\ active", "id" "teams\ c5d4b3a2 1f9e 4d8c b7a6 9c8d7e6f5a4b" }, "request" { "uri" "/teams/teams\ c5d4b3a2 1f9e 4d8c b7a6 9c8d7e6f5a4b/state", "requestid" "a1b2c3d4 e5f6 g7h8 i9j0 k1l2m3n4o5p6", "querystring" "", "body" {}, "method" "get" } } the response includes the current state of the team and its id 8\ filter team the filterteams endpoint allows you to retrieve aggregate counts of teams based on specified filters by calling filterteam with the appropriate query parameters, you can retrieve the count of teams that match the specified criteria query parameters parameter description aggregatequery aggregate query for retrieving count of teams based on specified criteria example \[{"name" "state count","field" "state keyword","aggregation" "terms"}] query query criteria for filtering teams the arr field is an array of query conditions nd the op field specifies the logical operator to combine the conditions (e g , "and" for all conditions to be true) example {"arr" \[{"term" {"properties teamtype keyword" "operations"}}],"op" "and"} sample request filterteam curl x get \\ 'https //{domain}/app/api/v2/teams/filter?aggregatequery=\[{"name" "state count","field" "state keyword","aggregation" "terms"}]\&query={"arr" \[{"term" {"properties teamtype keyword" "operations"}}],"op" "and"}' \\ h 'x coreos tid {tenantid}' \\ h 'x coreos access {access token}'\\ h 'x coreos userinfo {"name" "admin","id" "123"}' sample response if the request is successful, the api will respond with a 200 ok status code and a json object containing the aggregate count results in the following format { "data" { "data" { "aggregateresult" { "state count" { "doc count error upper bound" 0, "sum other doc count" 0, "buckets" \[ { "key" "active\ active", "doc count" 5 }, { "key" "inactive\ inactive", "doc count" 2 } ] } } } }, "request" { "uri" "/teams/filter", "requestid" "a1b2c3d4 e5f6 g7h8 i9j0 k1l2m3n4o5p6", "querystring" "aggregatequery=\[{\\"name\\" \\"state count\\",\\"field\\" \\"state keyword\\",\\"aggregation\\" \\"terms\\"}]\&query={\\"arr\\" \[{\\"term\\" {\\"properties teamtype keyword\\" \\"operations\\"}}],\\"op\\" \\"and\\"}", "body" {}, "method" "get" } } the response includes the aggregate count results based on the specified filters in this example, it shows the count of teams in different states (active and inactive) for teams with the "operations" team type