StackRoleMappings

View as Markdown

StackRoleMappings

A stack role mapping gives the users of a team a set of roles on one stack. The StackRoleMappings class manages these mappings for one team through the Content Management API (CMA). Use this class to

  • list the stacks that a team can reach, with the roles on each
  • give a team roles on a stack
  • change or remove the roles of a team on one stack

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

Instance State

  • Call team.stackRoleMappings() without an API key to work with every mapping of the team, with add and fetchAll.
  • Call team.stackRoleMappings('<API_KEY>') with the API key of a stack to work with the mapping for that stack, with update and delete.
  • Each form has only its own methods. update is undefined on team.stackRoleMappings(), and add is undefined on team.stackRoleMappings('<API_KEY>'), so calling the wrong one throws TypeError.
  • The team object keeps the last API key that you passed. Read the known issue on the stackRoleMappings page before you reuse a team object.

Class-Level Notes

Authentication.

  • Stack role mapping requests belong to an organization. Create the client with an authtoken, as contentstack.client({ authtoken: '<AUTHTOKEN>' }), or call client.login first.

Response shape.

  • Every method resolves to the response body as a plain object. None of them returns StackRoleMappings objects.
  • When the API answers add, fetchAll or update with an empty body, the method resolves to undefined.

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.

Method Index

Work with every mapping of a team. Available on team.stackRoleMappings().

Method NameReturnsDescription
addThe API response, with the new mapping.Gives the team roles on a stack.
fetchAllThe stack role mappings of the team.Lists the mappings of the team.

Work with the mapping for one stack. Available on team.stackRoleMappings('<API_KEY>').

Method NameReturnsDescription
updateThe API response, with the updated mapping.Changes the roles on one stack.
deleteThe API response for the deletion.Removes the mapping for one stack.

Class-Level Snippet

The snippet below gives a team one role on a stack and then lists every mapping of the team.

import contentstack from '@contentstack/management'

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

try {
  await mappings.add({ stackApiKey: '<API_KEY>', roles: ['<ROLE_UID>'] })
  const response = await mappings.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)
}

Methods

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

add

add gives the users of the team a set of roles on one stack.

NameTypeDescription
updateData (required)StackRoleMappingData

Request body with the stack and its roles.

Default: Not applicable
updateData.stackApiKey (required)string

API key of the stack.

Default: Not applicable
updateData.roles (required)string[]

UIDs of the stack roles to give.

Default: Not applicable
paramsobject

Query parameters, sent as given.

Default: {}

Returns: Promise<object>. The API response, with the new mapping.

Validation

  • There is no client-side validation. add sends updateData as given and does not check its keys.
  • add exists only on team.stackRoleMappings(). On team.stackRoleMappings('<API_KEY>') 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}/stack_role_mappings with updateData as the JSON body, as the Add a stack role mapping request in the Content Management API reference describes.
  • Read the stack role UIDs with the Role fetchAll method on that stack.
  • Resolves to the response body as a plain object. The new mapping sits under the stackRoleMapping key.

Example

Basic usage: give a team one role on a stack

import contentstack from '@contentstack/management'

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

try {
  const response = await client.organization('<ORGANIZATION_UID>')
    .teams('<TEAM_UID>')
    .stackRoleMappings()
    .add({ stackApiKey: '<API_KEY>', roles: ['<ROLE_UID>'] })
  console.log(response.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 params = {}

try {
  const response = await client.organization('<ORGANIZATION_UID>')
    .teams('<TEAM_UID>')
    .stackRoleMappings()
    .add({ stackApiKey: '<API_KEY>', roles: ['<ROLE_UID>'] }, params)
  console.log(response.stackRoleMapping)
} catch (error) {
  console.error(error.errorMessage)
}

delete

delete removes the roles of the team on the stack whose API key you passed to team.stackRoleMappings('<API_KEY>').

NameTypeDescription
paramobject

Query parameters, sent as given.

Default: {}

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

Warning A successful delete removes the association between the team users and that stack. To restore it, call add with the same stack and roles.

Validation

  • There is no client-side validation.
  • delete exists only on team.stackRoleMappings('<API_KEY>'). On team.stackRoleMappings() 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}/stack_role_mappings/{stack_api_key} with every key of param as a query parameter, as the Remove a stack role mapping 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 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>')
    .delete()
  console.log(response.status)
} 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>')
    .stackRoleMappings('<API_KEY>')
    .delete(param)
  console.log(response.status)
} catch (error) {
  console.error(error.errorMessage)
}

fetchAll

fetchAll retrieves the stacks that the team can reach, with the roles of the team on each one.

This method takes no parameters.

Returns: Promise<object>. The stack role mappings of the team.

Validation

  • There is no client-side validation.
  • fetchAll exists only on team.stackRoleMappings(). On team.stackRoleMappings('<API_KEY>') 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}/stack_role_mappings, as the Get all stack role mapping request in the Content Management API reference describes.
  • Sends no query parameters. An argument has no effect.
  • Resolves to the response body as a plain object, not to a ContentstackCollection. The mappings sit under the stackRoleMappings key.

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()
  for (const mapping of response.stackRoleMappings) {
    console.log(mapping.stackApiKey, mapping.roles)
  }
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

update

update changes the roles of the team on the stack whose API key you passed to team.stackRoleMappings('<API_KEY>').

NameTypeDescription
updateData (required)StackRoleMappingData

Request body with the new roles.

Default: Not applicable
updateData.roles (required)string[]

UIDs of the stack roles that the team gets.

Default: Not applicable
paramsobject

Query parameters, sent as given.

Default: {}

Returns: Promise<object>. The API response, with the updated mapping.

Validation

  • There is no client-side validation. update sends updateData as given and does not check its keys.
  • update exists only on team.stackRoleMappings('<API_KEY>'). On team.stackRoleMappings() 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}/stack_role_mappings/{stack_api_key} with updateData as the JSON body.
  • The Update a stack role mapping request in the Content Management API reference lists POST for the same path, with the body { roles: [...] }.
  • Resolves to the response body as a plain object. The updated mapping sits under the stackRoleMapping key.

Example

Basic usage: change the role of a team on a 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.roles)
} 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 params = {}

try {
  const response = await client.organization('<ORGANIZATION_UID>')
    .teams('<TEAM_UID>')
    .stackRoleMappings('<API_KEY>')
    .update({ roles: ['<ROLE_UID>'] }, params)
  console.log(response.stackRoleMapping)
} catch (error) {
  console.error(error.errorMessage)
}