2.17.0 Change Notes

UI Changes

Cube Navigation Aid

The enums HitBoxX, HitBoxY, and HitBoxZ used by the CubeNavigationAid have been renamed to CubeNavigationHitBoxX, CubeNavigationHitBoxY, and CubeNavigationHitBoxZ, respectively. The old enums are deprecated.

TimelineComponent and TimelineComponentDataProvider

The incomplete milestones feature was removed from the TimelineComponent and TimelineComponentDataProvider in preparation to move the APIs to @public.

New IModel events

IModels now emit events when their properties change.

Within IpcApp-based applications, BriefcaseConnections now automatically synchronize their properties in response to such events produced by changes on the backend. For example, if BriefcaseDb.projectExtents is modified, BriefcaseConnection.projectExtents will be updated to match and both the BriefcaseDb and BriefcaseConnection will emit an onProjectExtentsChanged event.

Reality model APIs

Several APIs relating to reality models have been introduced, in some cases replacing previous beta APIs. A reality model can be displayed in a Viewport in one of two ways:

The set of ContextRealityModels attached to a display style can be accessed and modified via DisplayStyleSettings.contextRealityModels.

Spatial classification can be applied to a reality model using ContextRealityModel.classifiers or SpatialModelState.classifiers. The SpatialClassifier APIs replace the previous beta APIs in the SpatialClassificationProps namespace.

Portions of a reality model can be masked by other models using ContextRealityModel.planarClipMaskSettings or, for persistent models, DisplayStyleSettings.planarClipMasks.

The color, transparency, locatability, and "emphasized" state of a reality model can be overridden using ContextRealityModel.appearanceOverrides or, for persistent models, DisplayStyleSettings.modelAppearanceOverrides.

A reality model displaying simple building meshes for locations all over the world obtained from OpenStreetMap Buildings can be enabled via DisplayStyleState.setOSMBuildingDisplay.

Popout Widgets

IModelApps, that use AppUi version "2", can now specify if a Widget can support being "popped-out" to a child popup window. The child window runs in the same javascript context as the parent application window. See Child Window Manager for more details.

External textures

The external textures feature is now enabled by default.

Previously, by default the images for textured materials would be embedded in the tile contents. This increased the size of the tile, consumed bandwidth, and imposed other penalties. The external textures feature, however, requires only the Id of the texture element to be included in the tile; the image can then be requested separately. Texture images are cached, so the image need only be requested once no matter how many tiles reference it.

Additionally, if a dimension of the external texture exceeds the client's maximum supported texture size, the image will be downsampled to adhere to that limit before being transmitted to the client.

To disable external textures, pass a TileAdmin to IModelApp.startup with the feature disabled as follows:

  const tileAdminProps: TileAdmin.Props = { enableExternalTextures: false };
  const tileAdmin = TileAdmin.create(tileAdminProps);
  IModelApp.startup({ tileAdmin });

Disabling this feature is not recommended and will incur a performance penalty. The option to disable the feature will likely be removed in the future.

ECClass Ids in changed events

The events TxnManager.onElementsChanged and TxnManager.onModelsChanged now include the Id of each changed entity's ECClass. The OrderedId64Array properties of TxnChangedEntities are deprecated in favor of the new EntityIdAndClassIdIterable properties.


Associating content items with given input

Sometimes there's a need to associate content items with given input. For example, when requesting child elements' content based on given parent keys, we may want to know which child element content item is related to which given parent key. That information has been made available through Item.inputKeys attribute. Because getting this information may be somewhat expensive and is needed only occasionally, it's only set when content is requested with ContentFlags.IncludeInputKeys flag.

Custom category nesting

A new requiredSchemas attribute was added to Ruleset, Rule and SubCondition definitions. The attribute allows specifying ECSchema requirements for rules and avoid using them when requirements are not met. See the schema requirements page for more details.

Promoted APIs

The following APIs have been promoted to public. Public APIs are guaranteed to remain stable for the duration of the current major version of a package.



  • RenderSchedule for defining scripts to visualize changes in an iModel over time.


@bentley/imodeljs-backend package

In addition, new protected static methods were added:

  • Element [onChildInsert, onChildInserted, onChildUpdate, onChildUpdated, onChildDelete, onChildDeleted, onChildAdd, onChildAdded, onChildDrop, onChildDropped]


Breaking API changes

During the course of routine improvement and stabilization of formerly alpha and beta APIs, some such APIs have changed. No breaking changes have been made to public APIs.


The following APIs have been replaced:



To make it easier to use async APIs while exporting a schema, IModelExportHandler.onExportSchema has been made async and must return a promise. For example, serialization APIs can be async, and previously to have custom async schema serialization, one would have to manually synchronize around their call to IModelExporter.exportSchemas.

IModelTransformer.shouldExportSchema now gets a SchemaKey schema key as argument, instead of a full Schema. If you need to check the full schema, return true in shouldExportSchema and in IModelExportHandler.onExportSchema, you can use the schema object to check and then return early.

Last Updated: 28 June, 2021