ReleaseItem

View as Markdown

ReleaseItem

A release item is one entry or asset in a release, with the action to apply on deploy and the version and locale to use. Use the ReleaseItem class to add items to a release, list them, move them to another release, or remove them.

The item method on stack.release('<RELEASE_UID>') returns a new ReleaseItem for that release and sends no request.

Additional Resource The Release Items requests of the Content Management API (CMA) reference describe each item request and its body.

Instance State

  • stack.release('<RELEASE_UID>').item() returns an object with every method in the Method Index below. Each method acts on the items of that release.
  • item exists only on a release with a UID. On stack.release() it is undefined, and calling it throws TypeError.
  • The objects in the items array of a findAll result are also ReleaseItem objects. Each one holds the item fields, such as uid, version, locale, content_type_uid and action, and has the same methods.

Class-Level Notes

One object per request.

  • A ReleaseItem stores its request path. A call to create or delete with a single item changes that path for every later call on the same object. Each of those two method pages includes a Known issue line.
  • Call release.item() again for each request, so that each call starts from the right path.

Item fields.

  • Each item names its entry or asset with uid, its version, its locale, its content_type_uid and its action (publish or unpublish).
  • For an asset, the API expects content_type_uid: 'built_io_upload'.

Release version header.

  • Every method takes a release_version option and sends it as the release_version header. The API reference requires 2.0 when the latest release feature is on for your organization.

Headers and branches.

  • The object starts with the headers of the release object that created it, such as api_key and branch. addHeader changes only this object.

Rate limiting and retry.

  • This SDK retries 429 automatically, with configurable delay and attempt limits.

Additional Resource The Contentstack class covers the retry options of contentstack.client() and their defaults.

Method Index

Add and list items. The methods in the table below are available on stack.release('<RELEASE_UID>').item().

Method NameReturnsDescription
createThe updated release.Adds one or more items to the release.
findAllThe items of the release.Lists the items of the release.

Move and remove items. The methods in the table below are available on stack.release('<RELEASE_UID>').item().

Method NameReturnsDescription
moveThe API response body.Moves items to another release.
deleteThe API response with a notice.Removes items, or all items, from the release.

Set request headers. The methods in the table below are available on stack.release('<RELEASE_UID>').item().

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

Class-Level Snippet

The snippet below adds an entry and an asset to a release and then lists the items of the release.

import contentstack from '@contentstack/management'

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

try {
  await release.item().create({
    items: [
      { uid: '<ENTRY_UID>', version: 1, locale: '<LOCALE>', content_type_uid: '<CONTENT_TYPE_UID>', action: 'publish' },
      { uid: '<ASSET_UID>', version: 1, locale: '<LOCALE>', content_type_uid: 'built_io_upload', action: 'publish' }
    ]
  })
  const result = await release.item().findAll()
  result.items.forEach((item) => console.log(item.uid, item.action))
} 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 ReleaseItem class has its own section below, with its parameters, validation rules, behavior, and examples.

addHeader

addHeader adds one header to every request that this release item object sends afterwards.

NameTypeDescription
key (required)string

Name of the request header.

Default: Not applicable
value (required)string

Value of the request header.

Default: Not applicable

Returns: ReleaseItem. The same release item object, for chaining.

Validation

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

Behavior

  • Client-side only. addHeader stores the header on this release item object and sends no request.
  • The first header method call on this object copies the headers it received from the stack, so the change applies to this release item object only. The stack and other objects keep their headers.
  • Every later request from this object sends the header. A key that already exists, such as branch, takes the new value.

Example

Basic usage: send this object's requests to another branch

import contentstack from '@contentstack/management'

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

const items = stack.release('<RELEASE_UID>').item().addHeader('branch', '<BRANCH>')
console.log(items.stackHeaders)

addHeaderDict

addHeaderDict adds several headers to every request that this release item object sends afterwards.

NameTypeDescription
headerDict (required)object

Header names and values to add.

Default: Not applicable

Returns: ReleaseItem. The same release item object, for chaining.

Validation

  • There is no client-side validation of the names or the values.
  • A headerDict that is null, undefined or not an object leaves the headers unchanged, and addHeaderDict returns the object without an error.
  • An invalid header surfaces as a rejected promise from the request method you call next.

Behavior

  • Client-side only. addHeaderDict copies each key and value of headerDict into the headers of this release item object and sends no request.
  • The first header method call on this object copies the headers it received from the stack, so the change applies to this release item object only. The stack and other objects keep their headers.
  • A key that already exists, such as branch, takes the new value.

Example

Basic usage: add a branch and a request ID in one call

import contentstack from '@contentstack/management'

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

const items = stack.release('<RELEASE_UID>').item().addHeaderDict({
  branch: '<BRANCH>',
  'x-request-id': 'docs-123'
})
console.log(items.stackHeaders)

create

create adds one entry or asset, or a list of them, to a release.

NameTypeDescription
param (required)object

One item, or a list of items.

Default: Not applicable
param.itemReleaseItemData

One item to add. Pass item or items.

Default: undefined
param.item.uid (required)string

UID of the entry or asset.

Default: Not applicable
param.item.version (required)number

Version of the entry or asset.

Default: Not applicable
param.item.locale (required)string

Locale code of the item.

Default: Not applicable
param.item.content_type_uid (required)string

Content type UID, or built_io_upload for an asset.

Default: Not applicable
param.item.action (required)string

publish or unpublish.

Default: Not applicable
param.itemsReleaseItemData[]

Items to add, with the fields of item.

Default: undefined
param.release_versionstring

Release version header, for example 2.0.

Default: undefined (not sent)

Returns: Promise<Release>. The updated release.

Known issue After a call with a single item, this ReleaseItem keeps the /item path, so later findAll, move and delete calls on the same object go to the wrong endpoint and fail. Call release.item() again for each request.

Validation

  • There is no client-side validation. The SDK sends param as you pass it.
  • Calling create() with no argument returns a promise that rejects with TypeError, because create reads properties of param.
  • 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

  • With param.item, one call sends one Add a single item to a Release request (POST /v3/releases/{release_uid}/item).
  • Without param.item, one call sends one Add multiple items to a Release request (POST /v3/releases/{release_uid}/items).
  • The SDK sends the whole param object as the JSON body. A release_version value goes as the release_version header and also stays in the body.
  • create resolves to a new Release that the SDK builds from the release key of the response, with the headers of the stack.

Example

Basic usage: add one entry to a release

import contentstack from '@contentstack/management'

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

try {
  const release = await stack.release('<RELEASE_UID>').item().create({
    item: { uid: '<ENTRY_UID>', version: 1, locale: '<LOCALE>', content_type_uid: '<CONTENT_TYPE_UID>', action: 'publish' }
  })
  console.log(release.uid)
} 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 an entry and an asset with the release version header

import contentstack from '@contentstack/management'

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

try {
  const release = await stack.release('<RELEASE_UID>').item().create({
    items: [
      { uid: '<ENTRY_UID>', version: 1, locale: '<LOCALE>', content_type_uid: '<CONTENT_TYPE_UID>', action: 'publish' },
      { uid: '<ASSET_UID>', version: 1, locale: '<LOCALE>', content_type_uid: 'built_io_upload', action: 'publish' }
    ],
    release_version: '2.0'
  })
  console.log(release.uid)
} catch (error) { console.error(error.errorMessage) }

delete

delete removes the items you list from a release, or every item when you list none.

NameTypeDescription
params (required)object

Items to remove, or {} for every item.

Default: Not applicable
params.itemsReleaseItemData[]

Items to remove.

Default: undefined (removes every item)
params.itemReleaseItemData

One item to remove.

Default: undefined
params.release_versionstring

Release version header, for example 2.0.

Default: undefined (not sent)

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

Warning delete({}) removes every item from the release. The entries and assets stay in the stack, but you need to add them to the release again with the create method.

Known issue delete() with no argument returns a promise that rejects with TypeError instead of removing every item. Pass {} to remove every item.

Known issue After a call with a single item, this ReleaseItem keeps the /item path, so later findAll, move and delete calls on the same object go to the wrong endpoint and fail. Call release.item() again for each request.

Validation

  • There is no client-side validation. The SDK sends the items as you pass them.
  • 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

  • The request depends on which key params holds:
    • With items, one call sends one Delete multiple items from a Release request (DELETE /v3/releases/{release_uid}/items) with the body { "items": [...] }.
    • With neither item nor items, the SDK adds the query parameter all=true and sends { "items": [] }, so the API removes every item.
    • With item, the SDK sends the request to /v3/releases/{release_uid}/item with the body { "item": {...} }.
  • The API reference documents the removal of one item at /items. To remove one item, pass a one-element items array.
  • A release_version value goes as the release_version header and also stays in the body.
  • delete resolves to the response body, which holds notice.

Example

Basic usage: remove one entry from a release

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.release('<RELEASE_UID>').item().delete({
    items: [{ uid: '<ENTRY_UID>', version: 1, locale: '<LOCALE>', content_type_uid: '<CONTENT_TYPE_UID>', action: 'publish' }]
  })
  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: remove every item with the release version header

import contentstack from '@contentstack/management'

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

try {
  // No item or items key, so the SDK removes every item
  const response = await stack.release('<RELEASE_UID>').item().delete({ release_version: '2.0' })
  console.log(response.notice)
} catch (error) { console.error(error.errorMessage) }

Single item form: remove one item with the item key

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.release('<RELEASE_UID>').item().delete({
    item: { uid: '<ENTRY_UID>', version: 1, locale: '<LOCALE>', content_type_uid: '<CONTENT_TYPE_UID>', action: 'publish' }
  })
  console.log(response.notice)
} catch (error) { console.error(error.errorMessage) }

findAll

findAll lists the entries and assets in a release.

NameTypeDescription
paramAnyProperty

Query parameters for the request.

Default: {}
param.include_countboolean

Adds the total number as count.

Default: API default
param.limitnumber

Number of items to return.

Default: API default
param.skipnumber

Number of items to skip.

Default: API default
param.include_branchboolean

Adds the _branch key to the response.

Default: API default
param.release_versionstring

Release version header, for example 2.0.

Default: undefined (not sent)

Returns: Promise<ContentstackCollection>. The items of the release.

Validation

  • There is no client-side validation.
  • 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

  • One call sends one Get all items in a Release request (GET /v3/releases/{release_uid}/items).
  • The SDK sends param.release_version as the release_version header and removes it from the query. Every other key of param goes in the query string.
  • findAll resolves to a ContentstackCollection. Its items are ReleaseItem objects with the item fields, and it holds count when the response has one.
  • The SDK does not page through results. Use limit and skip to read the next page.

Example

Basic usage: list the items of a release

import contentstack from '@contentstack/management'

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

try {
  const result = await stack.release('<RELEASE_UID>').item().findAll()
  result.items.forEach((item) => console.log(item.uid, item.content_type_uid, item.action))
} 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 a page of ten items 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 result = await stack.release('<RELEASE_UID>').item().findAll({
    include_count: true,
    limit: 10,
    skip: 0,
    include_branch: true,
    release_version: '2.0'
  })
  console.log(result.count, result.items.length)
} catch (error) { console.error(error.errorMessage) }

move

move moves items from this release to the release that release_uid names.

NameTypeDescription
options (required)object

Request body and the release version.

Default: Not applicable
options.param (required)MoveReleaseItems

Request body with the target release and items.

Default: Not applicable
options.param.release_uid (required)string

UID of the release to move the items to.

Default: Not applicable
options.param.items (required)ReleaseItemData[]

Items to move.

Default: Not applicable
options.release_versionstring

Release version header, for example 2.0.

Default: '' (not sent)

Returns: Promise<Response>. The API response body.

Validation

  • There is no client-side validation. The SDK sends options.param as you pass it.
  • Calling move() with no argument returns a promise that rejects with TypeError, because move reads its options from one object.
  • move reads the body only from options.param. Under any other key, such as data, the SDK sends the request with no body.
  • 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

  • One call sends one PUT /v3/releases/{release_uid}/items/move request with options.param as the JSON body.
  • A non-empty options.release_version goes as the release_version header.
  • move resolves to the response body. When the response has no body, it resolves to undefined.

Example

Basic usage: move one entry to another release

import contentstack from '@contentstack/management'

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

try {
  const target = await stack.release().create({ release: { name: 'docs-test-summer-campaign' } })
  const response = await stack.release('<RELEASE_UID>').item().move({
    param: {
      release_uid: target.uid,
      items: [{ uid: '<ENTRY_UID>', version: 1, locale: '<LOCALE>', content_type_uid: '<CONTENT_TYPE_UID>', action: 'publish' }]
    }
  })
  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: move an entry with the release version header

import contentstack from '@contentstack/management'

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

try {
  const target = await stack.release().create({ release: { name: 'docs-test-summer-campaign' } })
  const response = await stack.release('<RELEASE_UID>').item().move({
    param: {
      release_uid: target.uid,
      items: [{ uid: '<ENTRY_UID>', version: 1, locale: '<LOCALE>', content_type_uid: '<CONTENT_TYPE_UID>', action: 'publish' }]
    },
    release_version: '2.0'
  })
  console.log(response)
} catch (error) { console.error(error.errorMessage) }

removeHeader

removeHeader removes one header from the requests that this release item object sends afterwards.

NameTypeDescription
key (required)string

Name of the header to remove.

Default: Not applicable

Returns: ReleaseItem. The same release item 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 object without an error.
  • Removing api_key makes the next request fail with an API error, because every stack request needs the API key.

Behavior

  • Client-side only. removeHeader deletes the header from this release item object and sends no request.
  • When the header came from the stack, the SDK first copies the headers, so the stack and other objects keep it.
  • The management token and the authtoken live on the client, not on this object. removeHeader('authorization') does not remove them.

Example

Basic usage: stop sending the branch header from one object

import contentstack from '@contentstack/management'

const client = contentstack.client()
// This stack sends a branch header on every request
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>', branch_uid: '<BRANCH>' })

const items = stack.release('<RELEASE_UID>').item().removeHeader('branch')
console.log(items.stackHeaders)