Changeset

Type	{{#dataTypeArticle objectTypeId}}{{objectTypeId}}{{/dataTypeArticle}}
Datastore Type	{{#dataTypeArticle datastoreTypeId}}{{datastoreTypeId}}{{/dataTypeArticle}}
Supports	{{#article "security/authorities"}}authorities{{/article}}, {{#article "security/permissions"}}permissions{{/article}}, {{#article "transfer"}}transfer{{/article}}

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.

Configuration

The changeset configuration contains system and custom properties. You can write your own properties onto this configuration document if you wish. However, as noted above, this should be exceedingly rare.

Some system properties are read-only and others are writable. You can adjust the writable properties to modify the behavior and characteristics of the branch.

The following table presents you the system properties.

Branch Properties

Property	Type	Default	Read-Only	Description
revision	number		Read-Only	The revision number. This is the portion of the changeset ID before the ":".
tags	text		Read-Only	An array of text elements that tag the changeset.
active	text		Read-Only	Indicates whether the changeset has been successfully "committed" to the branch. See the section on transations above.
parents	array		Read-Only	In the case of a merge, this is an text array that contains the IDs of any parent changesets which were merged together underneath this changeset.
branch	text		Read-Only	The ID of the branch that this changeset sits within.

Any system properties that are shown to be Read-Only are not modifiable on calls to create() or update(). Anything else is fair game.

Read a Changeset

If you have the ID of a changeset, you can retrieve the individual changeset like this:

```` // assume we have a repository var repository = ...;

// assume we have a branch Id var branchId = "4b5b685c980c10f98beb";

// read the branch repository.readBranch(branchId).then(function() { console.log("Found branch: " + this.getId()); });

// read the master branch repository.readBranch("master").then(function() { console.log("Found master branch"); });

<!-- LIST CHANGESET PARENTS -->

<h2 id="list-parents">Retrieve Changeset Parents</h2>
<p>
    Every changeset has at least one parent changeset.  The parent changeset is the previous changeset in the
    sequence that composes the branch.  The only exception is the <code>0:root</code> changeset which is the first
    changeset installed for any new repository.  The <code>0:root</code> changeset does not have a parent.
    <br/>
    <br/>
    If a changeset is the changeset that "joins" two or more branches, then it may have multiple changeset
    parents.
    <br/>
    <br/>
    Here is an example that retrieves the parents of a changeset:
</p>

// assume we have a repository var repository = ...;

// here is our changeset id var changesetId = "4b5b685c980c10f98beb";

// grab the parents repository.listChangesetChildren(changesetId).each(function() { console.log("The changeset: " + changesetId + " has child: " + this.getId()); });

<!-- LIST CHANGESET PARENTS -->

<h2 id="list-children">Retrieve Changeset Children</h2>
<p>
    Every changeset has at least one child.  The child is the next changeset in the sequence that
    composes the branch.  The only exception is the "tip" changeset of the branch.  The "tip" is the most
    recent changeset applied to the branch.  It does not have children.
    <br/>
    <br/>
    If a new branch has been forked from the current branch, then the changeset sitting at the point of the
    fork may have multiple children.  One child may be the next changeset in the current branch.  And the other
    child may be the first changeset in the new branch.
    <br/>
    <br/>
    Here is an example that retrieves the children of a changeset:
</p>

// assume we have a repository var repository = ...;

// here is our changeset id var changesetId = "4b5b685c980c10f98beb";

// grab the parents repository.listChangesetParents(changesetId).each(function() { console.log("The changeset: " + changesetId + " has parent: " + this.getId()); });

<!-- LIST -->

<h2 id="create">List Changesets</h2>
<p>
    You can retrieve a manual list of all of the changesets in the repository.  This call is potentially very
    expensive.  For performance, it is recommended instead to query with pagination.
    <br/>
    <br/>
    Here is an example that lists changesets and logs to console:
</p>

// assume we have a repository var repository = ...;

repository.listChangesets().each(function() { console.log("Found changeset: " + this.getId()); });

<!-- QUERY -->

<h2 id="query">Query Changesets</h2>
<p>
    You can run custom queries against your changesets to find exactly what you're looking for.
    Here is a query that looks for changesets that sit in a specific branch.
</p>

// assume we have a repository var repository = ...;

// here is our branch id var branchId = "4b5b685c980c10f98beb";

repository.queryChangesets({ "branch": branchId }).each(function() { console.log("Found changeset: " + this.getId()); });

<p>
    And here is an example that paginates instead of retrieving everything all at once:
</p>

// assume we have a repository var repository = ...;

// here is our branch id var branchId = "4b5b685c980c10f98beb";

repository.queryChangesets({ "branch": branchId },{ "limit": 10, "skip": 20, "sort": { "title": -1 } }).each(function() { console.log("Found changeset: " + this.getId()); });