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.
Statuses
A new Change Set is "Uncommitted", and only an Uncommitted set can be committed. From there:
| Status | How it is reached | Can 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.
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
Get Change Set by ID
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
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
Rejecting a set marks it "Cancelled" and deletes its preview Tilesets. A committed set cannot be rejected.
Reject Change Set
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
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.
Below is the data each concept reads when the set is committed.
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
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
Create or update several items
Delete item
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.