Named Versions

Every ChangeSet pushed to iModelHub creates a new Version of iModel. To distinguish a specific ChangeSet in iModel's timeline, that represents an important milestone or significant event for that iModel, its Version can be given a unique human-readable name, creating a Named Version. It will allow Version to be easier to recognize and access. Named Versions can be queried separately from ChangeSets and they get Thumbnails rendered.

Creating Named Versions

Named Version can be created by calling VersionHandler.create. To create a Named Version a ChangeSet id has to be specified. You can get ChangeSet ids by querying ChangeSets through ChangeSetHandler.get.

To create a Named Version from a ChangeSet query:

  // Query all ChangeSets
  const changeSets: ChangeSet[] = await imodelHubClient.changeSets.get(authorizedRequestContext, imodelId);
  // Select one of the resulting ChangeSets
  const changeSetId: string = changeSets[0].id!;
  // Create a Named Version for that ChangeSet
  const createdVersion: Version = await imodelHubClient.versions.create(authorizedRequestContext, imodelId, changeSetId, "Version name", "Version description");

Querying Named Versions

After creating Named Version, its possible to query them by calling VersionHandler.get. Results of this query can be modified by using VersionQuery. Named Versions by default are ordered from the newest ChangeSet to the oldest.

  // Query all Named Versions
  const allVersions: Version[] = await imodelHubClient.versions.get(authorizedRequestContext, imodelId);
  // Query a single Named Version by its name
  const queryByName: VersionQuery = new VersionQuery().byName("Version name");
  const versionByName: Version[] = await imodelHubClient.versions.get(authorizedRequestContext, imodelId, queryByName);

Downloading Thumbnails

Once a Named Version is created, iModelHub generates its Thumbnail in the background. To get this Thumbnail, a Version query can be specified with VersionQuery.selectThumbnailId or all Thumbnails can be queried through ThumbnailHandler.get.

Thumbnail might not be immediately available after creating a Named Version, as generating it could take some time. If Thumbnail is not returned after creating Named Version, you can try querying it again later.

  // Query Named Version with its Thumbnail Id
  const thumbnailIdQuery: VersionQuery = new VersionQuery().byName("Version name").selectThumbnailId("Small");
  const versionWithThumbnailId: Version[] = await imodelHubClient.versions.get(authorizedRequestContext, imodelId, thumbnailIdQuery);
  // Download the Thumbnail
  const thumbnail: SmallThumbnail = new SmallThumbnail();
  thumbnail.id = versionWithThumbnailId[0].smallThumbnailId!;
  const thumbnailContents: string = await imodelHubClient.thumbnails.download(authorizedRequestContext, imodelId, thumbnail);

Last Updated: 13 June, 2024