Change Sets


A Change Set is a bundle of proposed changes to Entities, their relationships, representations and Assemblies, held back until someone reviews and commits it. Nothing in a Change Set touches your data until it is committed.

Change Sets are most often created by an import run in staged mode, so a large update can be checked in Operator or Navigator before it lands. You can also build one yourself by adding change items to it.

This article will cover how to manage Change Sets and their items, and how to commit, reject and export them.

Data model

Below is the core data model for a Change Set. The changes themselves are separate item records, covered in the Change Sets: Items section below.

interface IChangeSet {
    // Unique ID for the Change Set.
    // Exclude this value for new records.
    ID?: number;
    // Description of the change. Imports fill this with the import and file name.
    Description: string;
    // See the statuses section below. "Error" is reserved and not set by the API.
    // Default is "Uncommitted".
    Status?: "Uncommitted" | "Committed" | "Cancelled" | "Error";
    // ID of the user who created the record, set by the API.
    "Created.ByUser.ID"?: string;
    // ISO 8601 date time strings, set by the API.
    Created?: string;
    Updated?: string;
    // What the requesting user can do with Change Sets.
    // A combination of "C" (create), "R" (read), "U" (update) and "D" (delete). Eg: "RU".
    Permission?: string;

    // Only returned when "Count" is expanded.
    // Item counts by action, across Entity, relationship and representation changes.
    Count?: IChangeCount;
    // Only returned when "CountByConcept" is expanded on a single record.
    // The same counts for each concept the set has items of, keyed by concept code.
    CountByConcept?: { [concept: string]: IChangeCount };

    // Only returned on a single record.
    // IDs that help show the set in a scene, including the preview Tilesets made for it.
    Context?: {
        "EntityType.ID"?: string[];
        "RootEntity.ID"?: string[];
        "Tileset.ID"?: string[];
    };
    // Only returned on a single record.
    // The latest pending action run against the set, such as its import or commit.
    "PendingAction.ID"?: number;
    PendingAction?: any;
}

interface IChangeCount {
    Create: number;
    Update: number;
    Delete: number;
}

Statuses

A new Change Set is "Uncommitted", and only an Uncommitted set can be committed. From there:

StatusHow it is reachedCan change to
"Uncommitted"A new set, or reopening a Cancelled set."Cancelled" by rejecting it, or "Committed" by committing it.
"Committed"The commit request finishing.Nothing. A committed set is final.
"Cancelled"The reject request, or saving the status directly."Uncommitted", to reopen it.

Moving a set out of "Uncommitted" deletes the preview Tilesets made for it.

Staging an import

Assembly, CSV, GeoJSON, JSON and XLSX imports can stage their changes instead of applying them. Add "ChangeSet": true to the import settings. The import creates a new Change Set, and its pending action result includes the set's ID.

// Added to the import settings.
{
    "ChangeSet": true
}

// Part of the import's pending action result.
{
    "ChangeSet.ID": 42
}

You can read about each import in Import Assemblies, Import CSV, Import GeoJSON and Import JSON, and about pending actions in Pending Actions.

Requesting records

The list is paged, newest first. The first page includes the total count. Set both "PageSize" and "PageIndex" to -1 to get only the count.

Get a list of Change Sets

Response
interface IResponse {
    Items: IChangeSet[];
    // Only included on the first page.
    TotalCount?: number;
}
Javascript example

Get Change Set by ID

Response
// The response is the Change Set record directly, including "Context" and the latest pending action.
Javascript example

Create and update records

You can create a Change Set by setting the ID as '0', or update one by its ID. Changing "Status" follows the rules in the statuses section above. A set cannot be saved as "Committed", use the commit request instead.

Create or update Change Set

Request body
// Body should be the Change Set JSON as specified at the top of the article.
Response
// The response is the Change Set record directly.
Javascript example

Committing and rejecting

Committing applies every item in the set, as a background job. Entity Type changes are applied first, then Entities, relationships, representations and Assemblies. Once done, the set is marked "Committed", Tilesets showing the changed Entities are regenerated, and the preview Tilesets are deleted.

The response gives the job's pending action ID, which you can follow until it finishes. Only one commit of a set can run at a time.

Commit Change Set

Response
interface IResponse {
    PendingActionID: number;
}

Rejecting a set marks it "Cancelled" and deletes its preview Tilesets. A committed set cannot be rejected.

Reject Change Set

Response
// The response is the Change Set record directly.

Delete a record

Deleting a Change Set also deletes all its items and its preview Tilesets. Changes already committed are not undone.

Delete Change Set

Javascript example

Change Sets: Items

Each item is one proposed change. Its concept says what kind of record it changes, its action says whether it creates, updates or deletes it, and its data holds the details.

interface IChangeItem {
    // Unique ID for the item.
    // Exclude this value for new records.
    ID?: number;
    // ID of the Change Set the item belongs to.
    "Change.ID": number;
    // C = create, U = update, D = delete.
    Action: "C" | "U" | "D";
    /**
     * What kind of record the item changes.
     *
     * E = Entity.
     * ER = Entity relationship.
     * EL = Entity representation (LOD).
     * A = Assembly. Only create is supported.
     * ET = Entity Type. These are staged by imports and listed alongside, but cannot be written here.
     */
    Concept: "E" | "ER" | "EL" | "A" | "ET";
    // The details, based on the concept. See below.
    Data: any;
    // ISO 8601 date time strings, set by the API.
    Created?: string;
    Updated?: string;
}

Below is the data each concept reads when the set is committed.

// E: Entity.
interface IEntityChangeData {
    "Entity.ID": string;
    // Required when creating.
    "EntityType.ID"?: string;
    // The Entity's new attributes and Bruce values, such as name, location and transform.
    // You can read about the Entity structure in Entities.
    Entity?: any;
    // Layer IDs to set on the Entity.
    "Layer.ID"?: number[];
    // For updates. Attribute paths to remove from the Entity.
    "Entity.RemovedAttributes"?: string[];
}

// ER: Entity relationship.
interface IRelationChangeData {
    "Principal.Entity.ID": string;
    "Relation.Type.ID": string;
    "Other.Entity.ID": string;
    "Dimension.ID"?: number;
    "DisplayOrder"?: number;
    // Entity holding extra data about the relationship.
    "Data.Entity.ID"?: string;
    Collapsed?: boolean;
}

// EL: Entity representation (LOD).
// A delete removes every representation of the Entity.
interface ILodChangeData {
    "Entity.ID": string;
    "LODCategory.Key"?: string;
    Level?: number;
    Group?: string;
    ScaleToMeter?: number;
    "ClientFile.ID"?: string;
    "Geometry.ID"?: number;
}

// A: Assembly. Skipped when the root Entity already has an Assembly.
interface IAssemblyChangeData {
    "RootEntity.ID": string;
    // Default is "Unnamed Assembly".
    Name?: string;
    "RelationType.ID"?: string;
    "FileImport.ID"?: number;
    "ParentAssembly.ID"?: number;
}

You can read about the records these change in Entities, Relationships, Entity LODs and Import Assemblies.

Requesting items

Items are paged and can be filtered by concept and action. Prefix a filter with "!" to exclude it instead, such as "!D" for everything but deletes.

"IndexOf" finds where an Entity's first item sits in the list, so a paged review can turn to the page holding it.

Get Change Set items

Response
interface IResponse {
    // The Change Set the items belong to.
    Change: IChangeSet;
    Items: IChangeItem[];
    // Only included on the first page.
    TotalCount?: number;
}

// The response when "IndexOf" is used.
interface IIndexOfResponse {
    Change: IChangeSet;
    // Position of the Entity's first item, starting from 0, or -1 when no item names it.
    Index: number;
    // The concept the position is counted within. Absent when Index is -1.
    Concept?: string;
}
Javascript example

Writing items

You can create an item by setting the ID as '0', or update one by its ID. To write many at once, use the batch request, where items with an ID are updated and items without one are created.

Create or update item

Request body
// Body should be the item JSON as specified above.
Response
// The response is the item record directly.
Javascript example

Create or update several items

Request body
interface IBody {
    Items: IChangeItem[];
}
Response
interface IResponse {
    // Number of new items created.
    Created: number;
    // Number of existing items updated.
    Updated: number;
}

Delete item

Javascript example

Change Sets: Export

You can export a Change Set as a spreadsheet, for example to share it for sign-off. The export runs as a background job, and its pending action result holds a temp file ID and a download URL once it finishes. You can read about temp files in Client and temp files.

Export Change Set

Request body
interface IBody {
    // The file format. Only "XLSX" is supported.
    Type: "XLSX";
}
Response
interface IResponse {
    "PendingAction.ID": number;
    // Request URL for the pending action, returning its result as JSON.
    "PendingAction.URL": string;
}
Javascript example