Teams
Teams
A team is a group of users in an organization that share a product role and stack roles. The Teams class manages the teams of one organization through the Content Management API (CMA). Use this class to
- list the teams of an organization, or create one
- read, update or delete one team
- reach the users of a team and the stack roles that the team holds
Call the teams method of the Organization class to get an object.
Instance State
- Call organization.teams() without a UID to work with the collection, with create and fetchAll.
- Call organization.teams('<TEAM_UID>') to work with one team, for example fetch and teamUsers.
- Each form has only its own methods. fetch is undefined on organization.teams(), and create is undefined on organization.teams('<TEAM_UID>'), so calling the wrong one throws TypeError.
- The Teams objects that create, fetch and fetchAll return have the methods of organization.teams('<TEAM_UID>').
- The organization and team objects keep the last UID that you passed to a factory. Read the known issues on the Organization teams page and on the teamUsers and stackRoleMappings pages before you reuse an object.
Class-Level Notes
Authentication.
- Team requests belong to an organization, not to a stack. Create the client with an authtoken, as contentstack.client({ authtoken: '<AUTHTOKEN>' }), or call client.login first.
Headers.
- This class has no header methods. Team requests send only the headers of the client.
Rate limiting and retry.
- This SDK automatically retries on 429 with configurable delay and attempt limits.
Additional Resource For more information on the retry options and their defaults, refer to the Contentstack documentation.
Capability Matrix
| Capability | Supported | Notes / Alternative |
|---|---|---|
| Add or remove one user without sending the whole team | Yes | Use the TeamUsers class |
| Change the roles of a team on one stack | Yes | Use the StackRoleMappings class |
| Search teams with query() | No | Use fetchAll and filter the items |
Method Index
Work with the collection. Available on organization.teams().
| Method Name | Returns | Description |
|---|---|---|
| create | The new team. | Creates a team in the organization. |
| fetchAll | The teams of the organization. | Lists the teams of the organization. |
Work with one team. Available on organization.teams('<TEAM_UID>').
| Method Name | Returns | Description |
|---|---|---|
| fetch | The requested team. | Retrieves one team. |
| update | The updated team, as a plain object. | Changes the details of one team. |
| delete | The API response for the deletion. | Deletes one team. |
Reach the users and stack roles of a team. Available on organization.teams('<TEAM_UID>').
| Method Name | Returns | Description |
|---|---|---|
| teamUsers | A new team users object. | Returns a TeamUsers object. |
| stackRoleMappings | A new stack role mappings object. | Returns a StackRoleMappings object. |
Class-Level Snippet
The snippet below creates a team with one product role and prints the UID of the new team.
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const data = {
name: 'docs-test-editors',
organizationRole: '<ROLE_UID>',
users: [],
stackRoleMapping: []
}
try {
const team = await client.organization('<ORGANIZATION_UID>').teams().create(data)
console.log(team.uid, team.name)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}Methods
Each method of the Teams class has its own section below, with its parameters, validation rules, behavior, and examples.
create
create adds a new team to the organization.
| Name | Type | Description |
|---|---|---|
| data (required) | TeamData | Request body with the team details. |
| data.name (required) | string | Display name of the team. |
| data.organizationRole (required) | string | UID of the product role that members get. |
| data.users | object[] | Members of the team. |
| data.stackRoleMapping | StackRoleMappingData[] | Stack roles of the team, one entry per stack. |
| param | object | Query parameters, sent as given. |
Returns: Promise<Teams>. The new team.
Validation
- There is no client-side validation. create sends data as given and does not check its keys.
- create exists only on organization.teams(). On organization.teams('<TEAM_UID>') it is undefined, and calling it throws TypeError.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends POST /v3/organizations/{organization_uid}/teams with data as the JSON body, as the Create a team request in the Content Management API reference describes.
- The SDK sends data without a wrapper key.
- Each entry of data.stackRoleMapping has the shape { stackApiKey: '<API_KEY>', roles: ['<ROLE_UID>'] }.
- Resolves to a Teams object that holds the fields of the new team, with fetch, update, delete, teamUsers and stackRoleMappings.
Example
Basic usage: create a team with a product role
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
const team = await client.organization('<ORGANIZATION_UID>').teams().create({
name: 'docs-test-editors',
organizationRole: '<ROLE_UID>'
})
console.log(team.uid, team.name)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: create a team with a member and a stack role
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const data = {
name: 'docs-test-blog-team',
organizationRole: '<ROLE_UID>',
users: [{ email: '<COLLABORATOR_EMAIL>' }],
stackRoleMapping: [{ stackApiKey: '<API_KEY>', roles: ['<ROLE_UID>'] }]
}
// Query parameters to send with the request
const param = {}
try {
const team = await client.organization('<ORGANIZATION_UID>').teams().create(data, param)
console.log(team.uid, team.users)
} catch (error) {
console.error(error.errorMessage)
}delete
delete removes the team whose UID you passed to organization.teams('<TEAM_UID>') from the organization.
| Name | Type | Description |
|---|---|---|
| param | object | Query parameters, sent as given. |
Returns: Promise<object>. The API response for the deletion.
Warning A successful delete removes the team with its users and its assigned roles, and you cannot undo it. Call fetch first to keep a copy of its members and roles.
Validation
- There is no client-side validation.
- delete exists only on organization.teams('<TEAM_UID>') and on the Teams objects that create, fetch and fetchAll return. On organization.teams() it is undefined, and calling it throws TypeError.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends DELETE /v3/organizations/{organization_uid}/teams/{team_uid} with every key of param as a query parameter, as the Delete a team request in the Content Management API reference describes.
- Resolves to the response body. When the API answers with an empty body, it resolves to { status, statusText } instead.
Example
Basic usage: delete one team
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
const response = await client.organization('<ORGANIZATION_UID>').teams('<TEAM_UID>').delete()
console.log(response)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: pass query parameters with the request
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
// Query parameters to send with the request
const param = {}
try {
const response = await client.organization('<ORGANIZATION_UID>').teams('<TEAM_UID>').delete(param)
console.log(response)
} catch (error) {
console.error(error.errorMessage)
}fetch
fetch retrieves the team whose UID you passed to organization.teams('<TEAM_UID>').
| Name | Type | Description |
|---|---|---|
| param | object | Query parameters, sent as given. |
Returns: Promise<Teams>. The requested team.
Validation
- There is no client-side validation.
- fetch exists only on organization.teams('<TEAM_UID>') and on the Teams objects that create and fetchAll return. On organization.teams() it is undefined, and calling it throws TypeError.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends GET /v3/organizations/{organization_uid}/teams/{team_uid} with every key of param as a query parameter, as the Get a single team request in the Content Management API reference describes.
- Resolves to a new Teams object that holds the team fields, such as name, users, organizationRole and stackRoleMapping. The object you called fetch on does not change.
Example
Basic usage: read one team
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
const team = await client.organization('<ORGANIZATION_UID>').teams('<TEAM_UID>').fetch()
console.log(team.name, team.users, team.stackRoleMapping)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: pass query parameters with the request
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
// Query parameters to send with the request
const param = {}
try {
const team = await client.organization('<ORGANIZATION_UID>').teams('<TEAM_UID>').fetch(param)
console.log(team.uid)
} catch (error) {
console.error(error.errorMessage)
}fetchAll
fetchAll retrieves the teams of the organization.
| Name | Type | Description |
|---|---|---|
| param | object | Query parameters, sent as given. |
Returns: Promise<ContentstackCollection>. The teams of the organization.
Validation
- There is no client-side validation.
- fetchAll exists only on organization.teams(). On organization.teams('<TEAM_UID>') it is undefined, and calling it throws TypeError.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends GET /v3/organizations/{organization_uid}/teams with the header api_version: 1.1 and every key of param as a query parameter, as the Get all teams request in the Content Management API reference describes.
- Resolves to a ContentstackCollection. Its items array holds one Teams object per entry of the teams array in the response, each with fetch, update, delete, teamUsers and stackRoleMappings.
Example
Basic usage: list the teams of an organization
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
const teams = await client.organization('<ORGANIZATION_UID>').teams().fetchAll()
for (const team of teams.items) {
console.log(team.uid, team.name, team.organizationRole)
}
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: pass query parameters with the request
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
// Query parameters to send with the request
const param = {}
try {
const teams = await client.organization('<ORGANIZATION_UID>').teams().fetchAll(param)
console.log(teams.items.length)
} catch (error) {
console.error(error.errorMessage)
}stackRoleMappings
stackRoleMappings returns a StackRoleMappings object for the stack roles of the team. It sends no request. The following table lists its parameters.
| Name | Type | Description |
|---|---|---|
| stackApiKey | string | API key of one stack. |
Returns: StackRoleMappings. A new stack role mappings object.
Known issue After stackRoleMappings('<API_KEY>'), a later stackRoleMappings() call returns the mapping for that stack instead of the collection, even on another team of the same organization object. Start each chain from a new client.organization('<ORGANIZATION_UID>') call.
Validation
- There is no client-side validation.
- stackRoleMappings exists only on organization.teams('<TEAM_UID>') and on the Teams objects that create, fetch and fetchAll return. On organization.teams() it is undefined, and calling it throws TypeError.
- An invalid value surfaces as a rejected promise from the request method you call next.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Client-side only. stackRoleMappings builds a StackRoleMappings object with the organization UID and the team UID.
- Without stackApiKey, the object has add and fetchAll.
- With stackApiKey, the object has update and delete.
- An empty string counts as no API key and returns the collection form.
Example
Basic usage: list the stack roles of a team
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
const response = await client.organization('<ORGANIZATION_UID>').teams('<TEAM_UID>').stackRoleMappings().fetchAll()
console.log(response.stackRoleMappings)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: change the roles of a team on one stack
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
const response = await client.organization('<ORGANIZATION_UID>')
.teams('<TEAM_UID>')
.stackRoleMappings('<API_KEY>')
.update({ roles: ['<ROLE_UID>'] })
console.log(response.stackRoleMapping)
} catch (error) {
console.error(error.errorMessage)
}teamUsers
teamUsers returns a TeamUsers object for the users of the team. It sends no request. The following table lists its parameters.
| Name | Type | Description |
|---|---|---|
| userId | string | UID of one user of the team. |
Returns: TeamUsers. A new team users object.
Known issue After teamUsers('<USER_UID>'), a later teamUsers() call returns that user instead of the collection, even on another team of the same organization object. Start each chain from a new client.organization('<ORGANIZATION_UID>') call.
Validation
- There is no client-side validation.
- teamUsers exists only on organization.teams('<TEAM_UID>') and on the Teams objects that create, fetch and fetchAll return. On organization.teams() it is undefined, and calling it throws TypeError.
- An invalid value surfaces as a rejected promise from the request method you call next.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Client-side only. teamUsers builds a TeamUsers object with the organization UID and the team UID.
- Without userId, the object has add and fetchAll.
- With userId, the object has remove.
- An empty string counts as no UID and returns the collection form.
Example
Basic usage: list the users of a team
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
const users = await client.organization('<ORGANIZATION_UID>').teams('<TEAM_UID>').teamUsers().fetchAll()
console.log(users.items.map((user) => user.userId))
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: remove one user from a team
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
const response = await client.organization('<ORGANIZATION_UID>')
.teams('<TEAM_UID>')
.teamUsers('<USER_UID>')
.remove()
console.log(response)
} catch (error) {
console.error(error.errorMessage)
}update
update changes the details of the team whose UID you passed to organization.teams('<TEAM_UID>'), such as its name, members, product role and stack roles.
| Name | Type | Description |
|---|---|---|
| updateData (required) | TeamData | Request body with the new team details. |
| updateData.name | string | New display name of the team. |
| updateData.users | object[] | Members of the team. |
| updateData.organizationRole | string | UID of the product role that members get. |
| updateData.stackRoleMapping | StackRoleMappingData[] | Stack roles of the team, one entry per stack. |
Returns: Promise<object>. The updated team, as a plain object.
Validation
- There is no client-side validation. update sends updateData as given and does not check its keys.
- update exists only on organization.teams('<TEAM_UID>') and on the Teams objects that create, fetch and fetchAll return. On organization.teams() it is undefined, and calling it throws TypeError.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends PUT /v3/organizations/{organization_uid}/teams/{team_uid} with updateData as the JSON body, as the Update a team request in the Content Management API reference describes.
- update sends only updateData. It ignores the properties of the object you call it on, so changing team.name and calling update with no argument sends no name.
- Sends no query parameters. A second argument has no effect.
- Resolves to the response body as a plain object, not to a Teams object. When the API answers with an empty body, it resolves to undefined.
Example
Basic usage: rename a team
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
const team = await client.organization('<ORGANIZATION_UID>').teams('<TEAM_UID>').update({
name: 'Blog Editors'
})
console.log(team.uid, team.name)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: change the name, members, product role and stack roles
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const updateData = {
name: 'Blog Editors',
users: [{ email: '<COLLABORATOR_EMAIL>' }],
organizationRole: '<ROLE_UID>',
stackRoleMapping: [{ stackApiKey: '<API_KEY>', roles: ['<ROLE_UID>'] }]
}
try {
const team = await client.organization('<ORGANIZATION_UID>').teams('<TEAM_UID>').update(updateData)
console.log(team.name, team.users)
} catch (error) {
console.error(error.errorMessage)
}