Changeset

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

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");
});

Retrieve Changeset Parents

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 0:root changeset which is the first changeset installed for any new repository. The 0:root changeset does not have a parent.

If a changeset is the changeset that "joins" two or more branches, then it may have multiple changeset parents.

Here is an example that retrieves the parents of a changeset:

// 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());
});

Retrieve Changeset Children

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.

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.

Here is an example that retrieves the children of a changeset:

// 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 Changesets

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.

Here is an example that lists changesets and logs to console:

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

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

Query Changesets

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.

// 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());
});

And here is an example that paginates instead of retrieving everything all at once:

// 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());
});