Skip to content

iTwin workspace#9116

Merged
johnnyd710 merged 62 commits into
masterfrom
john/itwin-workspace
Apr 2, 2026
Merged

iTwin workspace#9116
johnnyd710 merged 62 commits into
masterfrom
john/itwin-workspace

Conversation

@johnnyd710

@johnnyd710 johnnyd710 commented Mar 23, 2026

Copy link
Copy Markdown
Contributor

Attempt to address some of the problems from https://github.com/iTwin/itwinjs-backlog/issues/1898 and #7316

This PR adds a high-level API for persisting iTwin-scoped settings dictionaries through IModelHost, and aligns the iTwin workspace model with the existing iModel pattern.

await IModelHost.getITwinWorkspace(iTwinId); // analogous to `IModelDb.workspace`
await IModelHost.saveSettingDictionary(iTwinId, settingName, value); // analogous to `IModelDb.saveSettingDictionary`
await IModelHost.deleteSettingDictionary(iTwinId, settingName); // analogous to `IModelDb.deleteSettingDictionary`

Instead of requiring callers to:

  1. find the iTwin settings container (and what if it doesn't exist)
  2. initialize it
  3. acquire and release write locks
  4. discover or create an editable prerelease SettingsDb
  5. open and close the db
  6. handle abandon/cleanup paths

Why IModelHost?
I don't know if IModelHost is the right place for these APIs, but I ended up choosing it because (1) where else would we put it, there's no ITwin or ITwinDb equivalent to IModelDb? and (2) appWorkspace is already there.
Open to other suggestions

Why

We already have a simple API for the iModel workspace, and two methods to persist settings scoped to an iModel:

iModel.workspace;
iModel.saveSettingDictionary(name, dict);
iModel.deleteSettingDictionary(name, dict);

I'm introducing the "iTwin workspace" and attempting to match the iModel workspace's functionality. There are some key differences between the workspaces:

Workspaces

IModelHost.appWorkspace

  • Application-scoped.
  • The "source-of-truth" is the JSON schema files registered at startup.
  • Holds app/default settings and containers.

IModelDb.workspace

  • iModel-scoped.
  • The "source-of-truth" is the dictionaries explicitly persisted into the iModel itself via saveSettingDictionary(...).
  • The settings themselves stored in the iModels are iModel-scoped, but you can store pointers to iTwin settings, which can be used to snapshot or persist iTwin settings into the iModel when that is desired (i.e., to support ISO 19650 workflows - for example the latest iTwin workspace might be on v2.1.7, but there may be an iModel on the project given to a contractor that you want to stay on v1.1.0, ~v1.9.0, etc.)

IModelHost.getITwinWorkspace(iTwinId) (new)

  • iTwin-scoped.
  • The "source-of-truth" are the dictionaries persisted into the iTwin SettingsDb via saveITwinSettingDictionary(...).
  • Useful for admin tooling and iTwin settings management without requiring an iModel.

@johnnyd710 johnnyd710 changed the title The iTwin workspace iTwin workspace Mar 23, 2026
Comment thread core/backend/src/workspace/SettingsEditor.ts Outdated

This comment was marked as outdated.

Comment thread core/backend/src/workspace/Settings.ts Outdated
Comment thread core/backend/src/IModelHost.ts
Comment thread core/backend/src/IModelHost.ts Outdated
Comment thread core/backend/src/IModelHost.ts Outdated
Comment thread core/backend/src/IModelHost.ts Outdated
@johnnyd710 johnnyd710 marked this pull request as ready for review March 30, 2026 19:51
@mergify

mergify Bot commented Mar 30, 2026

Copy link
Copy Markdown
Contributor

This pull request is now in conflicts. Could you fix it @johnnyd710? 🙏
To fixup this pull request, you can check out it locally. See documentation: https://help.github.com/articles/checking-out-pull-requests-locally/

@hl662 hl662 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review from interactive code walkthrough — 5 suggestions, all non-blocking. Nice simplification overall 👍

Comment thread core/backend/src/IModelHost.ts Outdated
Comment thread core/backend/src/IModelHost.ts Outdated
Comment thread core/backend/src/internal/workspace/WorkspaceImpl.ts Outdated
Comment thread core/backend/src/test/standalone/ITwinWorkspace.test.ts
Comment thread core/backend/src/test/standalone/ITwinWorkspace.test.ts
Comment thread core/backend/src/internal/workspace/WorkspaceImpl.ts
Comment thread core/backend/src/internal/workspace/WorkspaceImpl.ts Outdated
Comment thread core/backend/src/internal/workspace/WorkspaceImpl.ts Outdated
Comment thread core/backend/src/internal/workspace/WorkspaceImpl.ts
@johnnyd710 johnnyd710 merged commit e9274f0 into master Apr 2, 2026
18 checks passed
@johnnyd710 johnnyd710 deleted the john/itwin-workspace branch April 2, 2026 21:28
hl662 added a commit that referenced this pull request Apr 7, 2026
- Settings.md: consolidated all settings content (schemas, dictionaries,
  priorities, iTwin settings, iModel settings, SettingsDb) as single
  source of truth. Added iTwin settings section and expanded iModel
  settings with override/reference/pin subsections.

- Workspace.md: trimmed from 348 to 138 lines. Removed all settings
  content. Added 'Choosing the right workspace' decision guide near top
  with scope table (appWorkspace vs getITwinWorkspace vs IModelDb.workspace).

- WorkspacesAndSettings.md: added three-workspace scope table for the
  app/iTwin/iModel model introduced in PR #9116.

- Fixed cross-references: 5.8.0.md settingsdb link now points to
  Settings.md, NextVersion.md links to both Settings and Workspace docs.

- Verified all 28 code example includes appear exactly once (zero
  duplicates across files).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants