Workflow

View as Markdown

Workflow

A workflow is a set of stages that an entry moves through before you publish it, such as review and approval. The Workflow class manages workflows through the Content Management API (CMA). Use this class to

  • create a workflow with its stages, or change the stages of a workflow
  • list the workflows of a stack, or read one workflow
  • turn a workflow on or off, or delete it
  • reach the publish rules of the stack, and read the publish rules of one content type

Call the workflow method of the Stack class to get an object.

Instance State

  • Call stack.workflow() without a UID to work with the collection, for example create and publishRule.
  • Call stack.workflow('<WORKFLOW_UID>') to work with one workflow, for example fetch and disable.
  • Each form has only its own methods. A method of the other form is undefined, and the SDK throws TypeError when you call it. For example, stack.workflow('<WORKFLOW_UID>').publishRule() throws, because publish rules belong to the stack, not to one workflow.

The Method Index below lists the full set for each form.

Warning stack.workflow('') returns the collection form, because the SDK treats an empty string as no UID. Check the UID before you build the object.

Class-Level Notes

Workflow objects from responses.

Branch scope.

  • A workflow applies to the branches in its branches key. Set it in the body of create, or change it with update.

Headers.

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
Filter workflows with query()NoPass limit, skip and include_count to fetchAll.
Move an entry to a workflow stageNoUse the setWorkflowStage method of the Entry class.

Method Index

Work with the workflow collection. Available on stack.workflow().

Method NameReturnsDescription
createThe new workflow.Creates a workflow.
fetchAllThe workflows of the stack.Lists the workflows of the stack.
publishRuleA new publish rule object.Returns an object for publish rules.
contentTypeAn object with the getPublishRules method.Returns an object for one content type.

Read the publish rules of a content type. Available on the object that stack.workflow().contentType('<CONTENT_TYPE_UID>') returns.

Method NameReturnsDescription
getPublishRulesThe publish rules that apply to the content type.Reads the publish rules of a content type.

Work with one workflow. Available on stack.workflow('<WORKFLOW_UID>').

Method NameReturnsDescription
fetchThe requested workflow.Reads one workflow.
updateThe updated workflow.Saves changes to the workflow.
enableThe API response with a notice.Turns the workflow on.
disableThe API response with a notice.Turns the workflow off.
deleteThe API response with a notice.Deletes the workflow.

Set request headers. Available on both forms.

Method NameReturnsDescription
addHeaderThe same workflow object, for chaining.Adds one request header.
addHeaderDictThe same workflow object, for chaining.Adds several request headers.
removeHeaderThe same workflow object, for chaining.Removes one request header.

Class-Level Snippet

The snippet below lists the workflows of a stack, then disables the first one that is on.

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const workflows = await stack.workflow().fetchAll()
  const active = workflows.items.find((workflow) => workflow.enabled)

  if (active) {
    const response = await active.disable()
    console.log(active.name, response.notice)
  }
} 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 Workflow class has its own section below, with its parameters, validation rules, behavior, and examples.

addHeader

addHeader adds one header to the requests that this workflow object sends. The following table lists its parameters.

NameTypeDescription
key (required)string

Header name, for example x-request-id.

Default: Not applicable
value (required)string

Header value to send.

Default: Not applicable

Returns: Workflow. The same workflow object, for chaining.

Validation

  • There is no client-side validation. A null or undefined key leaves the headers unchanged, and addHeader returns the same object.
  • An invalid value surfaces as a rejected promise from the request method you call next.

Behavior

  • Client-side only. addHeader sends no request.
  • The first header change on this object copies the headers that it inherited. The change then applies to this object only, not to the stack or to other objects that the same stack creates.
  • Every request method of this object sends its headers.
  • Objects that this workflow object creates afterwards start with its headers. These include the publish rule object from publishRule and the object from contentType.
  • A key that the object already holds gets the new value.

Example

Basic usage: tag the requests of one workflow object

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

const target = stack.workflow('<WORKFLOW_UID>').addHeader('x-request-id', 'docs-123')
console.log(target.stackHeaders['x-request-id'])

addHeaderDict

addHeaderDict adds several headers at once to the requests that this workflow object sends. The following table lists its parameters.

NameTypeDescription
headerDict (required)object

Header names and values to add.

Default: Not applicable

Returns: Workflow. The same workflow object, for chaining.

Validation

  • There is no client-side validation. A null value, or a value that is not an object, leaves the headers unchanged, and addHeaderDict returns the same object.
  • An invalid value surfaces as a rejected promise from the request method you call next.

Behavior

  • Client-side only. addHeaderDict sends no request.
  • addHeaderDict copies every key of headerDict into the header map of this object. A key that the object already holds gets the new value.
  • The first header change on this object copies the headers that it inherited. The change then applies to this object only, not to the stack or to other objects that the same stack creates.
  • Every request method of this object sends its headers.
  • Objects that this workflow object creates afterwards start with its headers. These include the publish rule object from publishRule and the object from contentType.

Example

Basic usage: add a request ID and a trace ID

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

const target = stack.workflow('<WORKFLOW_UID>').addHeaderDict({ 'x-request-id': 'docs-123', 'x-trace-id': 'trace-456' })
console.log(target.stackHeaders['x-request-id'], target.stackHeaders['x-trace-id'])

contentType

contentType returns an object that reads the publish rules of one content type, through its getPublishRules method. The following table lists its parameters.

NameTypeDescription
contentTypeUID (required)string

UID of the content type whose publish rules you read.

Default: Not applicable

Returns: object. An object with the getPublishRules method.

Validation

  • There is no client-side validation.
  • contentType exists only on stack.workflow(). On stack.workflow('<WORKFLOW_UID>') it is undefined, and calling it throws TypeError.
  • When you omit contentTypeUID, or pass an empty string, contentType returns undefined. Calling getPublishRules on it then 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

  • contentType sends no request.
  • The returned object is a plain object, not a class instance. It holds getPublishRules and a copy of the headers of the workflow object. It has no addHeader, addHeaderDict or removeHeader methods.
  • To send a custom header with getPublishRules, add it to the workflow object before you call contentType.

Example

Basic usage: read the publish rules of one content type

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const rules = await stack.workflow().contentType('<CONTENT_TYPE_UID>').getPublishRules({ action: 'publish' })
  console.log(rules.items.length)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

create

create creates a workflow with its stages, the content types it applies to, and its admin users. Its parameters follow:

NameTypeDescription
data (required){ workflow: WorkflowData }

Request body, with the workflow under the workflow key.

Default: Not applicable
data.workflow.name (required)string

Name of the workflow.

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

Content type UIDs, or $all for every content type.

Default: Not applicable
data.workflow.workflow_stages (required)WorkflowStage[]

Stages that entries move through, at least two.

Default: Not applicable
data.workflow.workflow_stages[].name (required)string

Name of the stage.

Default: Not applicable
data.workflow.workflow_stages[].colorstring

Hex color of the stage, for example #2196f3.

Default: API default
data.workflow.workflow_stages[].SYS_ACLSystemACL

Roles and users who can work on entries at this stage.

Default: API default
data.workflow.workflow_stages[].next_available_stagesstring[]

Stages an entry can move to next, or $all.

Default: API default
data.workflow.workflow_stages[].entry_lock (required)string

Who can edit an entry at this stage, for example $none.

Default: Not applicable
data.workflow.workflow_stages[].allStages (required)boolean

Allows a move to every stage.

Default: Not applicable
data.workflow.workflow_stages[].allUsers (required)boolean

Allows every user to change the stage.

Default: Not applicable
data.workflow.workflow_stages[].specificStages (required)boolean

Limits moves to next_available_stages.

Default: Not applicable
data.workflow.workflow_stages[].specificUsers (required)boolean

Limits stage changes to the users in SYS_ACL.

Default: Not applicable
data.workflow.enabled (required)boolean

Turns the workflow on when true.

Default: Not applicable
data.workflow.admin_usersobject

Users and roles who administer the workflow.

Default: API default
data.workflow.branchesstring[]

Branch UIDs that the workflow applies to.

Default: API default
paramobject

Query parameters, sent as given.

Default: undefined (sends no extra query parameters)

Returns: Promise<Workflow>. The new workflow.

Validation

  • There is no client-side validation. create sends data as given and does not check its keys.
  • create exists only on stack.workflow(). On stack.workflow('<WORKFLOW_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.
  • The API rejects a workflow without a name, with fewer than two stages, or with no content type.
  • The API also rejects a content type that another workflow already covers, because each content type belongs to one workflow at most.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends POST /v3/workflows with data as the JSON body and param as query parameters, as Create a workflow describes.
  • The SDK does not wrap data. Put the workflow under the workflow key yourself.
  • Resolves to a Workflow object that the SDK builds from the workflow key of the response, with fetch, update, delete, enable and disable.

Example

Basic usage: create a two-stage review workflow

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

const stage = (name, color) => ({
  name,
  color,
  SYS_ACL: { roles: { uids: [] }, users: { uids: ['$all'] }, others: {} },
  next_available_stages: ['$all'],
  entry_lock: '$none',
  allStages: true,
  allUsers: true,
  specificStages: false,
  specificUsers: false
})

const data = {
  workflow: {
    name: 'docs-test-review',
    content_types: ['<CONTENT_TYPE_UID>'],
    workflow_stages: [stage('Review', '#2196f3'), stage('Complete', '#74ba76')],
    enabled: true
  }
}

try {
  const workflow = await stack.workflow().create(data)
  console.log(workflow.uid, workflow.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 workflow for two branches with admin users

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

const legalStage = {
  name: 'Legal review',
  color: '#ff9800',
  SYS_ACL: { roles: { uids: ['<ROLE_UID>'] }, users: { uids: [] }, others: {} },
  next_available_stages: ['$all'],
  entry_lock: '$none',
  allStages: true,
  allUsers: false,
  specificStages: false,
  specificUsers: true
}
const approvedStage = {
  name: 'Approved',
  color: '#74ba76',
  SYS_ACL: { roles: { uids: [] }, users: { uids: ['$all'] }, others: {} },
  next_available_stages: ['$all'],
  entry_lock: '$none',
  allStages: true,
  allUsers: true,
  specificStages: false,
  specificUsers: false
}

const data = {
  workflow: {
    name: 'docs-test-legal-review',
    content_types: ['<CONTENT_TYPE_UID>'],
    workflow_stages: [legalStage, approvedStage],
    enabled: true,
    admin_users: { users: ['<USER_UID>'] },
    branches: ['main', '<BRANCH>']
  }
}

try {
  // The second argument holds query parameters. The API lists none for this request.
  const workflow = await stack.workflow().create(data, {})
  console.log(workflow.uid, workflow.branches)
} catch (error) {
  console.error(error.errorMessage)
}

delete

delete deletes the workflow whose UID you passed to stack.workflow('<WORKFLOW_UID>'). The following table lists its parameters.

NameTypeDescription
paramobject

Query parameters, sent as given.

Default: {}

Returns: Promise<Response>. The API response with a notice.

Warning Deleting a workflow removes it and its stages from the stack permanently. You cannot undo this. To stop a workflow and keep its setup, use the disable method instead.

Validation

  • There is no client-side validation.
  • delete exists only on stack.workflow('<WORKFLOW_UID>') and on the Workflow objects that requests return. On stack.workflow() 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/workflows/{workflow_uid} with every key of param as a query parameter, as Delete workflow describes. The API reference lists no query parameters for this request.
  • Resolves to the response body as a plain object, with the API message in notice.

Example

Basic usage: delete a workflow

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const response = await stack.workflow('<WORKFLOW_UID>').delete()
  console.log(response.notice)
} 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

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  // delete sends every key of the object as a query parameter. The API lists none for this request.
  const response = await stack.workflow('<WORKFLOW_UID>').delete({})
  console.log(response.notice)
} catch (error) {
  console.error(error.errorMessage)
}

disable

disable turns off the workflow whose UID you passed to stack.workflow('<WORKFLOW_UID>').

This method takes no parameters.

Returns: Promise<Response>. The API response with a notice.

Validation

  • There is no client-side validation.
  • disable exists only on stack.workflow('<WORKFLOW_UID>') and on the Workflow objects that requests return. On stack.workflow() 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/workflows/{workflow_uid}/disable with no query parameters, as Disable workflow describes. The request uses GET, not PUT.
  • Resolves to the response body as a plain object, not to a Workflow object. Call fetch to read the workflow with its new enabled value.
  • Call enable to turn it back on.

Example

Basic usage: disable a workflow

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const response = await stack.workflow('<WORKFLOW_UID>').disable()
  console.log(response.notice)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

enable

enable turns on the workflow whose UID you passed to stack.workflow('<WORKFLOW_UID>').

This method takes no parameters.

Returns: Promise<Response>. The API response with a notice.

Validation

  • There is no client-side validation.
  • enable exists only on stack.workflow('<WORKFLOW_UID>') and on the Workflow objects that requests return. On stack.workflow() 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/workflows/{workflow_uid}/enable with no query parameters, as Enable workflow describes. The request uses GET, not PUT.
  • Resolves to the response body as a plain object, not to a Workflow object. Call fetch to read the workflow with its new enabled value.
  • Call disable to turn it off again.

Example

Basic usage: enable a workflow

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const response = await stack.workflow('<WORKFLOW_UID>').enable()
  console.log(response.notice)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

fetch

fetch retrieves the workflow whose UID you passed to stack.workflow('<WORKFLOW_UID>'), with its stages and settings. The following table lists its parameters.

NameTypeDescription
paramobject

Query parameters, sent as given.

Default: {}

Returns: Promise<Workflow>. The requested workflow.

Validation

  • There is no client-side validation.
  • fetch exists only on stack.workflow('<WORKFLOW_UID>'). On stack.workflow() 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/workflows/{workflow_uid} with every key of param as a query parameter, as Get a single workflow describes. The API reference lists no query parameters for this request.
  • Resolves to a new Workflow object that the SDK builds from the workflow key of the response, with fetch, update, delete, enable and disable.

Example

Basic usage: read a workflow and its stages

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const workflow = await stack.workflow('<WORKFLOW_UID>').fetch()
  console.log(workflow.name, workflow.enabled, workflow.workflow_stages.map((stage) => stage.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: pass query parameters

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  // fetch sends every key of the object as a query parameter. The API lists none for this request.
  const workflow = await stack.workflow('<WORKFLOW_UID>').fetch({})
  console.log(workflow.name)
} catch (error) {
  console.error(error.errorMessage)
}

fetchAll

fetchAll lists the workflows of the stack. The following table lists its parameters.

NameTypeDescription
paramobject

Query parameters for the list request.

Default: {}
param.limitnumber

Maximum number of workflows to return.

Default: API default
param.skipnumber

Number of workflows to skip.

Default: API default
param.include_countboolean

Adds the total workflow count to the response.

Default: API default

Returns: Promise<ContentstackCollection>. The workflows of the stack.

Validation

  • There is no client-side validation.
  • fetchAll exists only on stack.workflow(). On stack.workflow('<WORKFLOW_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/workflows with every key of param as a query parameter, as Get all workflows describes.
  • Resolves to a collection whose items are Workflow objects, each with fetch, update, delete, enable and disable. With include_count: true, the collection also has count.
  • The client does not page through results. Use limit and skip to read more pages.

Example

Basic usage: list the workflows of a stack

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const workflows = await stack.workflow().fetchAll()
  for (const workflow of workflows.items) {
    console.log(workflow.uid, workflow.name, workflow.enabled)
  }
} 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: read the first 10 workflows, with the total count

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const workflows = await stack.workflow().fetchAll({ limit: 10, skip: 0, include_count: true })
  console.log(workflows.count, workflows.items.length)
} catch (error) {
  console.error(error.errorMessage)
}

getPublishRules

getPublishRules retrieves the publish rules that apply to the content type you passed to stack.workflow().contentType('<CONTENT_TYPE_UID>').

NameTypeDescription
params (required)object

Query parameters that select the rules.

Default: Not applicable
params.action (required)string

publish or unpublish.

Default: Not applicable
params.localestring

Locale code that the rule applies to.

Default: API default
params.environmentstring

UID of the environment that the rule applies to.

Default: API default

Returns: Promise<ContentstackCollection>. The publish rules that apply to the content type.

Validation

  • There is no client-side validation. getPublishRules does not check that params holds action.
  • getPublishRules exists only on the object that stack.workflow().contentType('<CONTENT_TYPE_UID>') returns.
  • 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.
  • The API reference marks action as required, so the API can reject a request without it.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends GET /v3/workflows/content_type/{content_type_uid} with every key of params as a query parameter, as Get publish rules by content types describes.
  • Resolves to a collection whose items are publish rule objects, each with fetch, update and delete, from the PublishRules class.

Example

Basic usage: list the publish rules for publishing a content type

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const rules = await stack.workflow().contentType('<CONTENT_TYPE_UID>').getPublishRules({ action: 'publish' })
  for (const rule of rules.items) {
    console.log(rule.uid, rule.environment, rule.locales)
  }
} 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: list the unpublish rules for one locale and environment

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const rules = await stack.workflow().contentType('<CONTENT_TYPE_UID>').getPublishRules({
    action: 'unpublish',
    locale: '<LOCALE>',
    environment: '<ENVIRONMENT>'
  })
  console.log(rules.items.map((rule) => rule.uid))
} catch (error) {
  console.error(error.errorMessage)
}

publishRule

publishRule returns a publish rule object, for all publish rules of the stack or for one rule.

NameTypeDescription
ruleUidstring

UID of one publish rule.

Default: null (returns the collection form)

Returns: PublishRules. A new publish rule object.

Validation

  • There is no client-side validation.
  • publishRule exists only on stack.workflow(). On stack.workflow('<WORKFLOW_UID>') it is undefined, and calling it throws TypeError.
  • An empty string counts as no UID, so publishRule('') returns the collection form.
  • 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

  • publishRule sends no request.
  • Without a UID, the PublishRules object has create and fetchAll.
  • With a UID, the object has fetch, update and delete.
  • The new object starts with the current headers of this workflow object.

Example

Basic usage: list the publish rules, then read one

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const rules = await stack.workflow().publishRule().fetchAll()
  console.log(rules.items.length)

  const rule = await stack.workflow().publishRule('<PUBLISH_RULE_UID>').fetch()
  console.log(rule.uid, rule.actions)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

removeHeader

removeHeader removes one header from the requests that this workflow object sends.

NameTypeDescription
key (required)string

Name of the header to remove.

Default: Not applicable

Returns: Workflow. The same workflow object, for chaining.

Validation

  • There is no client-side validation. A null or undefined key, or a key that the object does not hold, leaves the headers unchanged, and removeHeader returns the same object.
  • An invalid value surfaces as a rejected promise from the request method you call next.

Behavior

  • Client-side only. removeHeader sends no request.
  • The first header change on this object copies the headers that it inherited. The change then applies to this object only, not to the stack or to other objects that the same stack creates.
  • Every request method of this object sends its headers.
  • Objects that this workflow object creates afterwards start with its headers. These include the publish rule object from publishRule and the object from contentType.
  • removeHeader can remove a header that the object inherited from the stack, such as branch. The stack and its other objects keep that header.
  • Do not remove api_key. Without it, the API cannot tell which stack the request is for.

Example

Basic usage: drop a header that you added earlier

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

const target = stack.workflow('<WORKFLOW_UID>')
  .addHeaderDict({ 'x-request-id': 'docs-123', 'x-trace-id': 'trace-456' })
  .removeHeader('x-trace-id')
console.log('x-trace-id' in target.stackHeaders) // false

update

update saves the changes that you made to the properties of this workflow object, such as its name, stages or content types.

NameTypeDescription
paramobject

Query parameters, sent as given.

Default: {}

Returns: Promise<Workflow>. The updated workflow.

Validation

  • There is no client-side validation.
  • update exists only on stack.workflow('<WORKFLOW_UID>') and on the Workflow objects that requests return. On stack.workflow() 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/workflows/{workflow_uid} with every key of param as a query parameter, as Add or update workflow details describes.
  • The body is { workflow: { ... } }, built from the properties of this object. The SDK leaves out uid, created_at, created_by, updated_at, updated_by, deleted_at, org_uid, api_key and its own internal properties.
  • Call fetch first and change the result. An object from stack.workflow('<WORKFLOW_UID>') holds no workflow details, so update on it sends an empty workflow.
  • To add a stage, append it to workflow_stages and call update.
  • Resolves to a new Workflow object that the SDK builds from the workflow key of the response.

Example

Basic usage: rename a workflow

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const workflow = await stack.workflow('<WORKFLOW_UID>').fetch()
  workflow.name = 'docs-test-editorial-review'
  const updated = await workflow.update()
  console.log(updated.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: add a stage and pass query parameters

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const workflow = await stack.workflow('<WORKFLOW_UID>').fetch()
  workflow.workflow_stages.push({
    name: 'SEO check',
    color: '#9c27b0',
    SYS_ACL: { roles: { uids: [] }, users: { uids: ['$all'] }, others: {} },
    next_available_stages: ['$all'],
    entry_lock: '$none',
    allStages: true,
    allUsers: true,
    specificStages: false,
    specificUsers: false
  })
  // update sends every key of the object as a query parameter. The API lists none for this request.
  const updated = await workflow.update({})
  console.log(updated.workflow_stages.length)
} catch (error) {
  console.error(error.errorMessage)
}