Teams

View as Markdown

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

CapabilitySupportedNotes / Alternative
Add or remove one user without sending the whole teamYesUse the TeamUsers class
Change the roles of a team on one stackYesUse the StackRoleMappings class
Search teams with query()NoUse fetchAll and filter the items

Method Index

Work with the collection. Available on organization.teams().

Method NameReturnsDescription
createThe new team.Creates a team in the organization.
fetchAllThe teams of the organization.Lists the teams of the organization.

Work with one team. Available on organization.teams('<TEAM_UID>').

Method NameReturnsDescription
fetchThe requested team.Retrieves one team.
updateThe updated team, as a plain object.Changes the details of one team.
deleteThe API response for the deletion.Deletes one team.

Reach the users and stack roles of a team. Available on organization.teams('<TEAM_UID>').

Method NameReturnsDescription
teamUsersA new team users object.Returns a TeamUsers object.
stackRoleMappingsA 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.

NameTypeDescription
data (required)TeamData

Request body with the team details.

Default: Not applicable
data.name (required)string

Display name of the team.

Default: Not applicable
data.organizationRole (required)string

UID of the product role that members get.

Default: Not applicable
data.usersobject[]

Members of the team.

Default: Not applicable
data.stackRoleMappingStackRoleMappingData[]

Stack roles of the team, one entry per stack.

Default: Not applicable
paramobject

Query parameters, sent as given.

Default: undefined (sends no extra query parameters)

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.

NameTypeDescription
paramobject

Query parameters, sent as given.

Default: {}

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>').

NameTypeDescription
paramobject

Query parameters, sent as given.

Default: {}

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.

NameTypeDescription
paramobject

Query parameters, sent as given.

Default: {}

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.

NameTypeDescription
stackApiKeystring

API key of one stack.

Default: null (returns the collection form)

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.

NameTypeDescription
userIdstring

UID of one user of the team.

Default: null (returns the collection form)

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.

NameTypeDescription
updateData (required)TeamData

Request body with the new team details.

Default: Not applicable
updateData.namestring

New display name of the team.

Default: Not applicable
updateData.usersobject[]

Members of the team.

Default: Not applicable
updateData.organizationRolestring

UID of the product role that members get.

Default: Not applicable
updateData.stackRoleMappingStackRoleMappingData[]

Stack roles of the team, one entry per stack.

Default: Not applicable

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)
}