Version Management Service

Introduction to Version Management

The goal of the VersionManagementService is to fully leverage versioning capabilities.
It allows users to manage and control different versions of their geospatial data, ensuring data integrity and synchronization across the geodatabase. This feature is particularly useful in collaborative environments where multiple users need to work on the same dataset without conflicts. It provides tools for creating, editing, and reconciling versions, as well as undoing and redoing edits, reconciling conflicts, and applying changes to the default version. The Version Management Component offers another way to handle versioning using a UI.

Listing Available Versions

Listing versions is important in order to know the available versions in a version management service. These versions can then be used to perform edits or reconcile/post. The getVersionInfos is used to list versions. The method expects ownerFilter and includeHidden parameters. This method is querying a version based on owner name, and if the query is blank all versions will be returned. The following demonstrates a code example on how to list versions using getVersionInfos.

1
2
3
4
5
// Will get versions owned by publisher1.
const versionInfos = await versionManagementService.getVersionInfos({
  ownerFilter: "publisher1",
  includeHidden: true
});

To get all available versions simply call the getVersionInfos method without passing parameters. The following demonstrates a code example on how to get information on a version using getVersionInfos.

1
const versions = await versionManagementService.getVersionInfos(); // Will list all available versions in service.

Calling getVersionInfos will only return basic information on each version. In order to get extended information about a version, such as current server locks or conflicts then the getVersionInfosExtended method should be used. The following demonstrates a code example on how to get information on a version using getVersionInfosExtended.

1
2
3
4
5
versionIdentifier = {
  guid: "{422D1B63-D795-4478-A4B1-AD6109377075}",
  name: "versionOwner.versionName"
}
const versionInfoExtended = await versionManagementService.getVersionInfoExtended(versionIdentifier);

These methods return versionInfoExtended and a versionInfo object. The versionInfos object contains basic information about a version and the versionInfoExtended contains more detailed information about a version. Finding the default version information is simple, using the defaultVersionIdentifier property on the VersionManagementService class will return that information. The following demonstrates a code example on how to get the defaultVersionIdentifier.

1
const defaultVersionIdentifier = versionManagementService.defaultVersionIdentifier;

Changing Versions on a UtilityNetwork or FeatureLayer

The changeVersion method is used to change a layer or network's version or moment. This method changes versions from a named version to a named version, or from the default version to a moment and vice versa. If a version has a read or write lock, then the user is unable to change versions. The purpose of changing a version is to view/edit a specific version. Change Version iterates through the layer array, changing each layer that references the fromVersion to reference the toVersion​. If the web map contains utility networks, these are also changed appropriately. The method also takes a fromVersion and toVersion parameters to indicate the intended version to change and the intended target. This is to avoid inadvertently changing a version unless the user explicitly describes it. These parameters accept either a Date or a VersionIdentifier. A Date in this instance would refer to a HistoricMoment. Groups of layers point to different versions or groups of layers pointing to default but at different HistoricMoments is by design. HistoricMoments are only for the default version. If the target version has a local lock then the user must clear the lock by calling stopEditing then stopReading. This must be done before switching versions when a lock is present on a version. The getLockType method can be used to confirm if a version has a local read/edit lock.

The following code example demonstrates how to change the version of two FeatureLayers.

1
2
3
4
5
6
7
8
const layer0 = new FeatureLayer({url: `https://sampleserver6.arcgisonline.com/arcgis/rest/services/Wildfire/FeatureServer/0`});
const layer1 = new FeatureLayer({url: `https://sampleserver6.arcgisonline.com/arcgis/rest/services/Wildfire/FeatureServer/1`});
const layers = [layer0, layer1];
await  versionManagementService.changeVersion(
    layers, // a webmap can also be passed here or a UtilityNetwork
    { name: layer0.gdbVersion, guid: "{BD3F4817-9A00-41AC-B0CC-58F78DBAE0A1}"}, // pass current layer gdbVersion and current guid of version
    { name: version.name, guid: version.guid } // pass an incoming version name and incomming version guid.
);

Creating and Deleting Versions

The createVersion method is used to create a named version off of the DEFAULT version. The method expects a versionName, description, and access. The access can be either private, protected, hidden, or public. The purpose of creating a version is to provide editors their own unique, isolated view to work with the same data at the same time. The following is a code example on how to create a new version using this method.

1
2
3
4
5
await versionManagementService.createVersion({
  versionName: "versionOwner.versionName",
  description: "my New Version",
  access: "public"
});

The deleteVersion method is used to delete a named version. The purpose of deleting a version is to remove a version that is no longer needed or being used. Deleting unnecessary versions helps to clean up and organize the data, making it more efficient and easier to manage. This is typically done after a user has finished editing and has posted their changes to the default version. Deleting an unused version helps to keep the system organized. It also ensures that only the relevant and up-to-date versions are retained. Deleting a version is a common practice in managing version control and maintaining a clean and efficient workflow. The method expects a versionIdentifier, which is an object that contains a version name and guid. The following demonstrates a code example on how to delete an existing version.

1
2
3
4
await versionManagementService.deleteVersion({
  name: "versionOwner.versionName",
  guid: "{BD3F4817-9A00-41AC-B0CC-58F78DBAE0A1}"
});

Altering a Version

The alterVersion method allows users to change a version's name, description, and access permissions. This method can be used to pass ownership of a version to another user. By changing the owner, in essence the ownership of a version is being transferred. Changing access permissions can be used to make a version private or protected thus, restricting access. It can also be used to make a version public, thereby granting access to other users. The following demonstrates a code example on altering a version.

1
2
3
4
5
6
7
8
9
10
await versionManagementService.alterVersion({
  name: "versionOwner.versionName", // current version name
  guid: "{49C6AC87-CDA8-46D4-A79B-449105981209}"}, // versionIdentifier
  {
    versionName: "newVersionName", // parameter to alter version name
    ownerName: "newOwner",
    description: "newDescription",
    access: "public"
  }
);

Editing Versions

Editing Versions Without an Edit Session

Users are able to edit a version without an edit session but doing so has implications. Edits are immediately committed to the database, missing the ability to revert changes, lacking read consistency, but behaving like a traditional website. Once an edit is performed without an edit session it cannot be reverted. The only way to revert the edit, is to perform a new edit that undoes the initial edit. This type of edit is done by calling applyEdits without calling start editing first.

Editing Versions with Save and Revert

Editing while in session makes use of shared and exclusive locks. These locks are acquired via making the REST calls startReading and startEditing respectively. The locks are released via the REST calls stopReading and stopEditing respectively. These routine and others, including applyEdits take a session ID parameter which would need to be generated client side and be used while the locks are held. While a shared lock is held no other user can acquire an exclusive lock, and in reverse an exclusive lock will block a shared lock. Simply put readers block writers and writers block readers. During an editing session the user is able to save edits after calling stopEditing or the user has the option to not save edits. This feature is important because it allows users to easily discard their edits if they change their mind and decide not to keep the changes. By calling the stopEditing method with the option of not saving edits, users can conveniently revert back to the original version without permanently altering the content. The methods to begin sessions and end sessions require a versionIdentifier parameter to specify the version on which the edit session will be initiated or ended.

1
2
3
4
5
await versionManagementService.startReading(version);
await versionManagementService.startEditing(version);
featureService.applyEdits(...); // now perform an applyEdits call
await versionManagementService.stopEditing(version, true); // if false edits will be discarded
await versionManagementService.stopReading(version); // all locks will be cleared

Editing Versions with Undo and Redo

The undo and redo functionality allows users to easily revert or redo changes made. This feature is particularly useful when working on complex projects where mistakes can happen or when experimenting with different configurations. With the undo option, users can step back through their editing history and revert changes to a previous state, effectively undoing any modifications made. Conversely, the redo option allows users to reapply changes that were previously undone. This functionality provides flexibility and confidence to users, ensuring that they can easily correct errors or explore different design options without the fear of losing progress. An edit operation stack holds the edit moments for each operation​. Undo moves backward through the stack​. Redo moves forward through the stack

1
2
3
4
5
await versionManagementService.startReading(version);
await versionManagementService.startEditing(version);
featureService.applyEdits(...); // now perform an applyEdits call
await versionManagementService.undo(version); // undos edits
await versionManagementService.redo(version); // redos edits

Reconcile and Post

The reconcile method compares the edit version (E.g. the named version) and the target version (default version) to find conflicts between the two. The reconcile method requires that you are the only user currently editing the version and remain so throughout the reconcile process until you save or post your edits. You must have full permissions to all the feature classes that have been modified in the version being edited. This method detects differences between the named version and the default version and flags these differences as conflicts. This updates the version with edits that have been made to default since the last reconcile (or version creation). Reconciling helps to detect conflicts that may arise when multiple users edit the same features or attributes. It ensures data integrity and consistency by applying changes in a controlled and systematic manner. The following demonstrates a code example on how to perform a reconcile on a version.

1
2
3
4
5
6
7
8
const reconcileResult = await versionManagementService.reconcile(
  versionIdentifier,
  {
    abortIfConflicts: true,
    conflictDetection: "by-object",
    withPost: false
  }
);

The post method is used to apply edits made on a named version to the default version. It is used after reconciling and resolving conflicts. A reconcile operation must be performed prior to post. By posting edits, the changes made in the version are permanently applied to the default version, ensuring data consistency and synchronization across the geodatabase. The following demonstrates a code example on how to perform a post operation on a version.

1
const postResult = await versionManagementService.post(versionIdentifier);

Conclusion

The VersionManagementService class is a powerful tool for managing feature services that work with named versioned datasets. It provides a range of functionality to create, delete, alter, and change versions, as well as start/stop reading and editing, reconciling, posting, and getting version information. The VersionManagementService provides a comprehensive set of methods to manage versions and streamline versioning workflows.