Workspaces and Settings

Two recurring run-time needs in non-trivial iTwin.js applications are configuration (which tools are available, what units to use, which data sources are active) and resources (binary assets like fonts, textures, and templates). iTwin.js provides two complementary systems to address these needs:

• Settings — a priority-ordered stack of key-value configuration pairs. Configuration flows from cloud-hosted settings containers into the active Settings runtime, where values can be read by name.
• Workspace resources — versioned binary assets stored in WorkspaceDb containers. Settings tell the application which WorkspaceDbs to load; the application then retrieves resources from them.

These two systems are deliberately separate. If everything were stored in workspace containers, there would be no way to know which container to open first. Settings containers solve this bootstrapping problem — they are loaded first and tell the application which workspace containers to open.

At runtime, settings and resources are accessed through one of three workspace scopes:

All three scopes use the same Settings priority stack — iTwin-level and iModel-level settings both override application defaults. getITwinWorkspace is independent from IModelDb.workspace — its settings are only available to an iModel if explicitly referenced (see Referencing iTwin settings from an iModel). getITwinWorkspace is also discovery-only: the first default iTwin settings container is created on first write via IModelHost.saveSettingDictionary, not on read. See Choosing the right workspace for guidance on when to use each scope.

Scope and priority

Settings from multiple sources are merged using a priority stack. A higher-priority dictionary overrides a lower-priority one for any given setting name.

In practice:

• Organization-wide defaults are stored in a settings container and loaded at SettingsPriority.iTwin (400).
• iModel-specific overrides are loaded at SettingsPriority.iModel (600) — iModel wins over iTwin.
• Application defaults are loaded at SettingsPriority.application (200) — overrideable by any cloud-backed settings.

The full priority stack also includes a separate SettingsPriority.organization (300) level — see Settings priorities for the complete list.

Recommended reading order

Prefer hands-on learning? Start with the tutorial — it introduces each concept as the code demands it, then come back here for reference.

1. This overview — understand the two systems and three workspace scopes.
2. Settings — how to define settings schemas, load dictionaries, read values, and create/manage settings containers in the cloud.
3. Workspace resources — how to create, version, and access binary resources stored in WorkspaceDb containers.
4. Tutorial: Configuring an iTwin Application — a hands-on walkthrough that builds a complete application configuration end-to-end.