IModelsClientManagement.md

@itwin/imodels-client-management

Key types

• IModelsClient
• IModelsClientOptions

Parameter and response types

• AuthorizationParam
• EntityListIterator<TEntity>

Entities

• MinimalIModel, IModel
• MinimalBriefcase, Briefcase
• MinimalChangeset, Changeset
• MinimalNamedVersion, NamedVersion
• Checkpoint
• Thumbnail
• MinimalUser, User
• UserPermissions

Key methods

• IModelsClient.iModels
  • getMinimalList(params: GetIModelListParams): EntityListIterator<MinimalIModel> (sample)
  • getRepresentationList(params: GetIModelListParams): EntityListIterator<IModel>
  • getSingle(params: GetSingleIModelParams): Promise<IModel>
  • createEmpty(params: CreateEmptyIModelParams): Promise<IModel>
  • delete(params: DeleteIModelParams): Promise<void>
• IModelsClient.briefcases
  • getMinimalList(params: GetBriefcaseListParams): EntityListIterator<MinimalBriefcase>
  • getRepresentationList(params: GetBriefcaseListParams): EntityListIterator<Briefcase>
  • getSingle(params: GetSingleBriefcaseParams): Promise<Briefcase>
• IModelsClient.changesets
  • getMinimalList(params: GetChangesetListParams): EntityListIterator<MinimalChangeset> (sample)
  • getRepresentationList(params: GetChangesetListParams): EntityListIterator<Changeset>
  • getSingle(params: GetSingleChangesetParams): Promise<Changeset>
• IModelsClient.namedVersions
  • getMinimalList(params: GetNamedVersionListParams): EntityListIterator<MinimalNamedVersion>
  • getRepresentationList(params: GetNamedVersionListParams): EntityListIterator<NamedVersion>
  • getSingle(params: GetSingleNamedVersionParams): Promise<NamedVersion>
  • create(params: CreateNamedVersionParams): Promise<NamedVersion> (sample)
  • update(params: UpdateNamedVersionParams): Promise<NamedVersion>
• IModelsClient.checkpoints
  • getSingle(params: GetSingleCheckpointParams): Promise<Checkpoint>
• IModelsClient.thumbnails
  • download(params: DownloadThumbnailParams): Promise<Thumbnail>
  • upload(params: UploadThumbnailParams): Promise<void>
• IModelsClient.users
  • getMinimalList(params: GetUserListParams): EntityListIterator<MinimalUser>
  • getRepresentationList(params: GetUserListParams): EntityListIterator<User>
  • getSingle(params: GetSingleUserParams): Promise<User>
• IModelsClient.userPermissions
  • get(params: GetUserPermissionsParams): Promise<UserPermissions>

Usage examples

Authorization

IModelsClient expects the authorization info to be passed in a form of an asynchronous callback that returns authorization info. It is a common use case to consume IModelsClient in iTwin.js platform based applications which use IModelApp.getAccessToken or IModelHost.getAccessToken to get the authorization header value returned as a string. The authorization header value specifies the schema and access token e.g. Bearer ey.... To convert this value into the format that IModelsClients expect users can use AccessTokenAdapter class which is exported by both @itwin/imodels-access-frontend and @itwin/imodels-access-backend packages.

const iModelIterator: EntityListIterator<MinimalIModel> = iModelsClient.iModels.getMinimalList({
  authorization: AccessTokenAdapter.toAuthorizationCallback(IModelApp.getAccessToken),
  urlParams: {
    iTwinId: "8a1fcd73-8c23-460d-a392-8b4afc00affc"
  }
});

Get all iTwin iModels

import { Authorization, EntityListIterator, IModelsClient, MinimalIModel } from "@itwin/imodels-client-management";

/** Function that queries all iModels for a particular iTwinId and prints their ids to the console. */
async function printiModelIds(): Promise<void> {
  const iModelsClient: IModelsClient = new IModelsClient();
  const iModelIterator: EntityListIterator<MinimalIModel> = iModelsClient.iModels.getMinimalList({
    authorization: () => getAuthorization(),
    urlParams: {
      iTwinId: "8a1fcd73-8c23-460d-a392-8b4afc00affc"
    }
  });

  for await (const iModel of iModelIterator)
    console.log(iModel.id);
}

/** Function that returns valid authorization information. */
async function getAuthorization(): Promise<Authorization> {
  return { scheme: "Bearer", token: "ey..." };
}

Get an iModel with a specific name

import { EntityListIterator, IModel, IModelsClient, toArray } from "@itwin/imodels-client-management";

/** Function that queries an iModel with a specific name. Function returns `undefined` if such iModel does not exist. */
async function getiModel(): Promise<IModel | undefined> {
  const iModelsClient: IModelsClient = new IModelsClient();
  const iModelIterator: EntityListIterator<IModel> = iModelsClient.iModels.getRepresentationList({
    authorization: () => getAuthorization(),
    urlParams: {
      iTwinId: "8a1fcd73-8c23-460d-a392-8b4afc00affc",
      name: "Sun City Renewable-energy Plant",
    }
  });

  const iModelArray = await toArray(iModelIterator);
  if (iModelArray.length === 0)
    return undefined;

  const iModel = iModelArray[0];
  return iModel;
}

Get all iModel Changesets

import { Authorization, EntityListIterator, IModelsClient, MinimalChangeset } from "@itwin/imodels-client-management";

/** Function that queries all Changesets for a particular iModel and prints their ids to the console. */
async function printChangesetIds(): Promise<void> {
  const iModelsClient: IModelsClient = new IModelsClient();
  const changesetIterator: EntityListIterator<MinimalChangeset> = iModelsClient.changesets.getMinimalList({
    authorization: () => getAuthorization(),
    iModelId: "30c8505e-fa7a-4b53-a13f-e6a193da8ffc"
  });

  for await (const changeset of changesetIterator)
    console.log(changeset.id);
}

Create a Named Version on a Changeset

import { Authorization, IModelsClient, NamedVersion } from "@itwin/imodels-client-management";

/** Function that creates a Named Version on a particular changeset and prints its id to the console. */
async function createNamedVersion(): Promise<void> {
  const iModelsClient: IModelsClient = new IModelsClient();
  const namedVersion: NamedVersion = await iModelsClient.namedVersions.create({
    authorization: () => getAuthorization(),
    iModelId: "30c8505e-fa7a-4b53-a13f-e6a193da8ffc",
    namedVersionProperties: {
      name: "Milestone",
      changesetId: "bd51c08eb44f40d49fee9a0c7d6fc018c3b5ba3f"
    }
  });

  console.log(namedVersion.id);
}