Open in Claude Open in ChatGPT

Changeset

An Object

Table of Contents

Cloud CMS automatically creates and maintains the state of the individual changesets that compose your branches as you work with content. A changeset is like a transparency for a visual projector. When you write content into a branch (via a create, update or delete), the content is written onto a changeset (or transparency). That way, the things you worked on before are never affected. The new updates are just overlaid on top.

In this sense, a branch can be thought of as a stack of changesets. There is a root changeset (where the branch starts) and a tip changeset (where the branch ends). Everything in-between constitutes the changeset history of the branch.

This portion of the API therefore is largely for advanced users. The Cloud CMS API lets you dig in and poke around at the changeset history of branches to do things like discover what changes were introduced on which changeset in the branch.

You probably don't need to do this unless you're building some really cool authoring or curation tools. Cloud CMS provides applications out-of-the-box that hopefully let you do most of the heavy lifting from an authoring viewpoint. So most of these APIs are cool but probably not very commonly used.

Changeset IDs

Most of the _doc identifiers for objects inside of Cloud CMS are GUIDs (globally unique IDs). Changesets are a bit different. Changeset IDs are stored in the _doc field but they have a special structure which looks like this:

{revision}:{guid}

As you write nodes into your branch, new changesets are layered into the branch. One at a time. Each new changeset has an incremented revision and a brand new GUID. Thus, the revision number always goes up one integer at a time. The changeset ID ends up looking something like this: 452:4b5b685c980c10f98beb

Transactions

Changesets play an important role in transaction handling for writes onto branches. When a transaction begins, a new changeset is created. All of the writes (creates, updates and deletes) which occur as part of the transaction are committed to the database and flagged with the changeset. Only once all the writes have succeeded is the changeset flipped to an 'active' state.

If a transaction fails, the changeset is not flipped to an 'active' state. Instead, the transaction rolls back and the database state is cleaned up.

Only one changeset in a branch can be written to at a time. Thus, if a transaction is started and another thread running in your application attempts to write to the branch, it will be blocked and forced to wait until the first thread completes.

Note

Drop in one of our language drivers to accelerate your development.
Here are links to some of our popular Cookbooks to help you get started!

Parent

This Changeset is contained within a Repository.

Properties

The following properties are available:

Property Type Default Read-Only Description
_doc string No The primary ID
_system object No Metadata maintained by the system

Methods

The following methods are available:

Export Changeset

Starts an export job for this resource
POST /repositories/{repositoryId}/changesets/{changesetId}/export

Parameters

Name Required Type Description
repositoryId true string The ID of the repository
changesetId true string The ID of the changeset
groupId false string The Group ID to be assigned to the exported archive
artifactId false string The Artifact ID to be assigned to the exported archive
versionId false string The Version ID to be assigned to the exported archive
vaultId false string The ID of the vault where the exported archive should be saved
schedule false string Whether to run the job immediately or in the background (either 'synchronous' or 'asynchronous')

Response

{
  "type": "object",
  "description": "Export Configuration",
  "properties": {
    "startDate": {
      "type": "object",
      "description": "Only include objects whose modification date is after this time (epoch millis). This is used for partial or rolling exports."
    },
    "endDate": {
      "type": "object",
      "description": "Only include objects whose modification date is before this time (epoch millis). This is used for partial or rolling exports."
    },
    "startChangeset": {
      "type": "string",
      "description": "Only include data that is relevant to changesets at or beyond the specified changeset."
    },
    "endChangeset": {
      "type": "string",
      "description": "Only include data that is relevant to changesets at or before the specified changeset."
    },
    "includeACLs": {
      "type": "boolean",
      "default": true,
      "description": "Whether to include ACLs during export."
    },
    "includeTeams": {
      "type": "boolean",
      "default": true,
      "description": "Whether to include Teams during export."
    },
    "includeActivities": {
      "type": "boolean",
      "default": true,
      "description": "Whether to include Activities during export."
    },
    "includeBinaries": {
      "type": "boolean",
      "default": true,
      "description": "Whether to include Binaries for data stores during export."
    },
    "includeAttachments": {
      "type": "boolean",
      "default": true,
      "description": "Whether to include Attachments for Attachables during export."
    },
    "artifactDependencies": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "artifactIncludes": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "forceIncludes": {
      "type": "boolean"
    }
  }
}

Forks Changesets

GET /repositories/{repositoryId}/changesets/forks

Parameters

Name Required Type Description
repositoryId true string The ID of the repository

Heads Changesets

GET /repositories/{repositoryId}/changesets/heads

Parameters

Name Required Type Description
repositoryId true string The ID of the repository

Import Changeset

Starts an import job for this resource
POST /repositories/{repositoryId}/changesets/{changesetId}/import

Parameters

Name Required Type Description
repositoryId true string The ID of the repository
changesetId true string The ID of the changeset
groupId false string The Group ID to be assigned to the exported archive
artifactId false string The Artifact ID to be assigned to the exported archive
versionId false string The Version ID to be assigned to the exported archive
vaultId false string The ID of the vault where the exported archive should be saved
schedule false string Whether to run the job immediately or in the background (either 'synchronous' or 'asynchronous')

Response

{
  "type": "object",
  "description": "Import Configuration",
  "properties": {
    "includeACLs": {
      "type": "boolean",
      "default": true,
      "description": "Whether to include ACLs during import."
    },
    "includeTeams": {
      "type": "boolean",
      "default": true,
      "description": "Whether to include Teams during import."
    },
    "includeActivities": {
      "type": "boolean",
      "default": true,
      "description": "Whether to include Activities during import."
    },
    "includeBinaries": {
      "type": "boolean",
      "default": true,
      "description": "Whether to include Binaries for data stores during import."
    },
    "includeAttachments": {
      "type": "boolean",
      "default": true,
      "description": "Whether to include Attachments for Attachables during import."
    },
    "strategy": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "default": "CLONE",
      "description": "Either CLONE or COPY_EVERYTHING. Use CLONE to keep the same IDs on import. Use COPY_EVERYTHING to generate all new IDs for all entries on every import."
    },
    "substitutions": {
      "type": "string"
    }
  }
}

Joins Changesets

GET /repositories/{repositoryId}/changesets/joins

Parameters

Name Required Type Description
repositoryId true string The ID of the repository

List Nodes

GET /repositories/{repositoryId}/changesets/{changesetId}/nodes

Parameters

Name Required Type Description
repositoryId true string The ID of the repository
changesetId true string The ID of the changeset

List Parents

GET /repositories/{repositoryId}/changesets/{changesetId}/parents

Parameters

Name Required Type Description
repositoryId true string The ID of the repository
changesetId true string The ID of the changeset

Lists Changeset

Retrieves a list of Changeset instances
GET /repositories/{repositoryId}/changesets

Parameters

Name Required Type Description
repositoryId true string The ID of the repository
sort false object Defines how to sort fields in the result set
skip false number Skips the result set cursor ahead the specified number of records
limit false number Specifies the number of records to be handed back in the result set
This method supports pagination.

Response

{
  "type": "object",
  "description": "Result Map",
  "properties": {
    "total_rows": {
      "type": "number"
    },
    "offset": {
      "type": "number"
    },
    "size": {
      "type": "number"
    },
    "rows": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/resultmap_changeset"
      }
    }
  }
}

Queries for Changeset

Queries for instances of type Changeset
POST /repositories/{repositoryId}/changesets/query

Parameters

Name Required Type Description
repositoryId true string The ID of the repository
sort false object Defines how to sort fields in the result set
skip false number Skips the result set cursor ahead the specified number of records
limit false number Specifies the number of records to be handed back in the result set
This method supports pagination.

Response

{
  "type": "object",
  "description": "Result Map",
  "properties": {
    "total_rows": {
      "type": "number"
    },
    "offset": {
      "type": "number"
    },
    "size": {
      "type": "number"
    },
    "rows": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/resultmap_changeset"
      }
    }
  }
}

Read Changeset

Reads an instance of a Changeset
GET /repositories/{repositoryId}/changesets/{changesetId}

Parameters

Name Required Type Description
repositoryId true string The ID of the repository
changesetId true string The ID of the changeset

Response

{
  "type": "object",
  "extends": "document",
  "description": "Changeset",
  "container": "repository",
  "properties": {
    "_doc": null,
    "_system": null
  }
}

Read Children Changeset

GET /repositories/{repositoryId}/changesets/{changesetId}/children

Parameters

Name Required Type Description
repositoryId true string The ID of the repository
changesetId true string The ID of the changeset

Read Node

GET /repositories/{repositoryId}/changesets/{changesetId}/nodes/{nodeId}

Parameters

Name Required Type Description
repositoryId true string The ID of the repository
changesetId true string The ID of the changeset
nodeId true string The ID of the node

Root Changesets

GET /repositories/{repositoryId}/changesets/root

Parameters

Name Required Type Description
repositoryId true string The ID of the repository

Update Changeset

PUT /repositories/{repositoryId}/changesets/{changesetId}

Parameters

Name Required Type Description
repositoryId true string The ID of the repository
changesetId true string The ID of the changeset

Update Changeset

Updates an existing Changeset
POST /repositories/{repositoryId}/changesets/{changesetId}/update

Parameters

Name Required Type Description
repositoryId true string The ID of the repository
changesetId true string The ID of the changeset

Response

{
  "type": "object",
  "description": "Status of Operation",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Indicates whether the operation succeeded or not"
    }
  }
}

Schema


{
  "type": "object",
  "extends": "document",
  "description": "Changeset",
  "container": "repository",
  "properties": {
    "_doc": null,
    "_system": null
  },
  "id": "changeset"
}