Hub Entity Versioning

The versioning feature allows developers to create multiple versions of any Item-backed entity that can have resources. See here for supported item types. Versions are stored as item resources.

There are two ways of interacting with the versioning API.

1. Longer term, the preferred approach is the IHubItemEntity<Entity> instance methods.
2. In the near term (Q1-2 2023), developers can use the importable functions with IModels.

---

IHubItemEntity Instance Methods

Any IHubItemEntity that implements IWithVersioningBehavior will have versioning. As of 02/2023 only HubSite implements IWithVersioningBehavior.

Searching for versions of an entity

The searchVersions method can be used to get all the versions of an entity. It returns an array of IVersionMetadata.

Getting and working with a particular version of an entity

The getVersion method can be used to get a particular version of an entity. It takes a version id and returns an IVersion.

Creating a new version of an entity

The createVersion method can be used to create a new version of an entity based on the current state of the entity. It takes an optional ICreateVersionOptions and returns an IVersion.

Updating a version of an entity

The updateVersion method can be used to update a version of an entity based on the current state of the entity. It takes an IVersion and returns an IVersion.

Updating the metadata of an entity version

The updateVersionMetadata method can be used to update the metadata (primarily name and description) of an entity version. It takes an IVersionMetadata and returns an IVersionMetadata.

Deleting a version of an entity

The deleteVersion method can be used to delete a version of an entity. It takes a version id.

---

Functional / IModel Approach

Searching for versions of an entity

The searchVersions function can be used to get all the versions of an entity. It takes an item id and an IHubUserRequestOptions and returns an array of IVersionMetadata.

Getting and working with a particular version of an entity

The getVersion function can be used to get a particular version of an entity. It takes an item id, a version id, and an IHubUserRequestOptions and returns an IVersion.

Once you have an entity and a version, you can apply the version to the entity using the applyVersion function. It takes an IModel, an IVersion, and an optional includeList and returns an IModel with the versioned data applied.

Creating a new version of an entity

The createVersion function can be used to create a new version of an entity based on the current state of the entity. It takes an IModel, an IHubUserRequestOptions, and an optional ICreateVersionOptions and returns an IVersion.

Updating a version of an entity

The updateVersion function can be used to update a version of an entity based on the current state of the entity. It takes an IModel, an IVersion, and an IHubUserRequestOptions and returns an IVersion.

Updating the metadata of an entity version

The updateVersionMetadata function can be used to update the metadata (primarily name and description) of an entity version. It takes an item id, an IVersionMetadata, and an IHubUserRequestOptions and returns an IVersionMetadata.

Deleting a version of an entity

The deleteVersion function can be used to delete a version of an entity. It takes an item id, a version id, and an IHubUserRequestOptions.