TeamUsers

View as Markdown

TeamUsers

A team in an organization groups users so that they share the product role and stack roles of the team. The TeamUsers class manages the users of one team through the Content Management API (CMA). Use this class to

  • list the users of a team
  • add users to a team by email
  • remove one user from a team

Call the teamUsers method of the Teams class to get an object.

Instance State

  • Call team.teamUsers() without a user UID to work with the users of the team, with add and fetchAll.
  • Call team.teamUsers('<USER_UID>') to work with one user, with remove.
  • Each form has only its own methods. remove is undefined on team.teamUsers(), and add is undefined on team.teamUsers('<USER_UID>'), so calling the wrong one throws TypeError.
  • The team object keeps the last user UID that you passed. Read the known issue on the teamUsers page before you reuse a team object.

Class-Level Notes

Authentication and permissions.

  • Team user requests belong to an organization. Create the client with an authtoken, as contentstack.client({ authtoken: '<AUTHTOKEN>' }), or call client.login first.
  • Only the owner or an admin of the organization can add or remove team users. The Add users to team and Remove a user from team requests in the Content Management API reference state this rule.

Headers.

  • This class has no header methods. Its 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
Remove a user from an item that fetchAll returnsNoKnown issue on the fetchAll page. Use team.teamUsers('<USER_UID>').remove()

Method Index

Work with the users of a team. Available on team.teamUsers().

Method NameReturnsDescription
addThe API response, as a TeamUsers object.Adds users to the team.
fetchAllThe users of the team.Lists the users of the team.

Work with one user. Available on team.teamUsers('<USER_UID>').

Method NameReturnsDescription
removeThe API response for the removal.Removes one user from the team.

Class-Level Snippet

The snippet below adds a user to a team by email and then lists the user UIDs of the team.

import contentstack from '@contentstack/management'

const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const users = client.organization('<ORGANIZATION_UID>').teams('<TEAM_UID>').teamUsers()

try {
  await users.add({ emails: ['<COLLABORATOR_EMAIL>'] })
  const result = await users.fetchAll()
  console.log(result.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)
}

Methods

Each method of the TeamUsers class has its own section below, with its parameters, validation rules, behavior, and examples.

add

add sends invitations that add users to the team, by email.

NameTypeDescription
data (required)TeamUserData

Request body with the users to add.

Default: Not applicable
data.emails (required)string[]

Email addresses of the users to add.

Default: Not applicable
paramobject

Query parameters, sent as given.

Default: undefined (sends no extra query parameters)

Returns: Promise<TeamUsers>. The API response, as a TeamUsers object.

Validation

  • There is no client-side validation. add sends data as given and does not check the emails.
  • add exists only on team.teamUsers(). On team.teamUsers('<USER_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/{team_uid}/users with data as the JSON body, as the Add users to team request in the Content Management API reference describes.
  • Resolves to a TeamUsers object that holds the fields of the response body. The object has no organization UID, so its methods have no usable request path. Read its fields only, and call team.teamUsers() again for the next request.

Example

Basic usage: add two users to a team

import contentstack from '@contentstack/management'

const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })

try {
  const result = await client.organization('<ORGANIZATION_UID>')
    .teams('<TEAM_UID>')
    .teamUsers()
    .add({ emails: ['<COLLABORATOR_EMAIL>', '<EMAIL>'] })
  console.log(result)
} 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 result = await client.organization('<ORGANIZATION_UID>')
    .teams('<TEAM_UID>')
    .teamUsers()
    .add({ emails: ['<COLLABORATOR_EMAIL>'] }, param)
  console.log(result)
} catch (error) {
  console.error(error.errorMessage)
}

fetchAll

fetchAll retrieves the users of the team.

NameTypeDescription
paramobject

Query parameters, sent as given.

Default: {}
param.includeUserDetailsboolean

Adds the details of each user.

Default: API default
param.include_countboolean

Adds the total number of users.

Default: API default

Returns: Promise<ContentstackCollection>. The users of the team.

Known issue remove on an item in items fails, because the item has no request path. Call remove on team.teamUsers('<USER_UID>') instead.

Validation

  • There is no client-side validation.
  • fetchAll exists only on team.teamUsers(). On team.teamUsers('<USER_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/{team_uid}/users with every key of param as a query parameter, as the Get all users of team request in the Content Management API reference describes.
  • Resolves to a ContentstackCollection. Its items array holds one TeamUsers object per entry of the users array in the response. The userId property of each item holds that entry as the API returns it.
  • With include_count: true, the collection has a count property.

Example

Basic usage: list the user UIDs 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()
  for (const user of users.items) {
    console.log(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: include user details and a count

import contentstack from '@contentstack/management'

const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })

try {
  const users = await client.organization('<ORGANIZATION_UID>')
    .teams('<TEAM_UID>')
    .teamUsers()
    .fetchAll({ includeUserDetails: true, include_count: true })
  console.log(users.count, users.items.map((user) => user.userId))
} catch (error) {
  console.error(error.errorMessage)
}

remove

remove takes the user whose UID you passed to team.teamUsers('<USER_UID>') out of the team.

NameTypeDescription
paramobject

Query parameters, sent as given.

Default: {}

Returns: Promise<object>. The API response for the removal.

Warning A successful remove takes the user out of the team. To bring the user back, call add again.

Validation

  • There is no client-side validation.
  • remove exists only on team.teamUsers('<USER_UID>'). On team.teamUsers() 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}/users/{user_uid} with every key of param as a query parameter, as the Remove a user from 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: 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) {
  // 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>')
    .teamUsers('<USER_UID>')
    .remove(param)
  console.log(response)
} catch (error) {
  console.error(error.errorMessage)
}