Opening an iModel via the IModelDb class

Opening a local briefcase of an iModel managed by iModelHub

The BriefcaseManager class provides a method to download a briefcase (i.e. a local copy of an iModel.). Once downloaded, the BriefcaseDb class provides methods for opening, closing, and accessing the briefcase. An instance of BriefcaseDb in memory holds a briefcase file open.

Use BriefcaseManager.downloadBriefcase to download a briefcase, and BriefcaseDb.open to open the downloaded briefcase.

Use BriefcaseDb.close to close the local briefcase.

Note that an AccessToken is an argument to BriefcaseDb.open.

Opening a snapshot iModel

The SnapshotDb class also provides methods for opening, closing, and accessing a snapshot iModel. A snapshot iModel is a file that is disconnected from iModelHub and therefore does not have a change timeline. Once created, a snapshot iModel is read-only and cannot be changed. This makes snapshot iModels ideal for archival or data transfer purposes.

Use SnapshotDb.openFile to open an existing snapshot iModel.

Use SnapshotDb.close to close the snapshot iModel.

Upgrading schemas in an iModel

Every now and then the schemas in the iModel may become incompatible with newer versions of the software. In these cases it may be recommended, and sometimes even mandatory to upgrade the schemas in the iModel before it can be opened. Note that whether an upgrade is mandatory may depend on if the model is to be opened ReadOnly or ReadWrite - the requirements for the latter are more stringent.

There are two kinds of schemas that typically get upgraded:

• Domain schemas - the ECSchema-s that define the information for specific Domains
• Profile schemas - the Schemas of database tables that are either not mapped to domain schemas, or are otherwise used to store meta-data about the mapping of database tables to domain schemas.

The iTwin.js API provides for a way to validate (check compatibility) and upgrade all the schemas in the iModel. To upgrade -

• Download a local copy of the iModel as a briefcase with BriefcaseManager.downloadBriefcase
• Call BriefcaseDb.validateSchemas to validate the schemas in the iModel.
• Call BriefcaseDb.upgradeSchemas to upgrade schemas - the upgrade process involves the following steps:
  • Open the local briefcase.
  • Check if the profile/domain schema upgrade changes require a data transform.
  • If a data transform is required, acquire a schema lock to avoid concurrent schema changes by different users.
  • Make the necessary schema changes for a profile upgrade to the briefcase.
  • Capture profile upgrade schema changes (if any) as a Changeset and push it to iModel Hub.
  • Then, make the necessary schema changes for a domain schema upgrade to the briefcase.
  • Capture domain schema upgrade changes (if any) as a Changeset and push it to iModel Hub.
  • If schema lock was acquired earlier due to a data transform, release the schema lock.
  • Close the briefcase.

Working with newer schemas having an unsupported ECXml version

With the general evolution of schemas, there may come a time when a schema has been released with a newer ECXml version than the one supported by the ECDb runtime being used. A write-incompatable schema can be loaded, but it can be neither imported into an iModel, nor can it be serialized to a file or string.

Such a schema is likely to contain elements that are unknown to the current ECDb runtime being used. To know more about how these unknown elements are handled, refer to Handling Unknown Schema Elements

To be able to perform read and write operations on a schema with a newer ECXml version, it us recommended to upgrade the ECDb runtime to a version that supports the ECXml version.