Guide on v9.3.1 Upgrade with a Customized Angular Web Portal (4384066)

The fork of the GitHub repository is the single source of truth for customizations — not the database, not the deployed environment. Customizations are never “merged in the environment”. They are merged in Git, rebuilt into fresh bundles, and the bundles are uploaded whole. If the owned fork is healthy, it can always recover the portal, on any version, in a repeatable way.

The public repository is here. One Identity maintains a branch per product version (v92, v93, …). tHE customizations live as a branch (or commits) on top of the matching version branch in the respective fork. Upgrading the portal = moving your customization commits from the old version branch to the new one, fixing what breaks, rebuilding, uploading.

Bookmarks:

Exactly what to do, in order:

Assumptions: you have an existing fork with the v9.2 customizations, Git, and Node.js LTS (Node 20.x works for both v9.2 and v9.3). Nothing else is required.

Phase A — Before the upgrade window
1.    Inventory what have been deployed. List every file your team ever uploaded via Software Loader (query QBMFileRevision and filter for Software Loader-originated rows via the XOrigin flag). Confirm each one maps back to source in the respective fork. Anything that cannot be rebuild from source is a problem to solve now, not on upgrade day.
2.    Get the fork tidy. The customizations should be a clean set of commits on top of the upstream v92 branch. If changes were ever made ad hoc, commit them properly now.
3.    Fetch the new upstream branch:

git remote add upstream https://github.com/OneIdentity/IdentityManager.Imx.git
git fetch upstream v93

4.    Read the two documents. Open UPGRADE.md (the procedure) and skim changesFrom9.2.1To9.3.0.md for every module that is customized (search the file for the module name, e.g. “qbm”, “att”, “rmb”). Make a list of every deleted or changed class your code imports — that list is the work plan.
5.    Rebase the customization branch onto v93 (this is the method UPGRADE.md recommends; merge or cherry-pick are acceptable alternatives):

git checkout <customisation-branch>
git rebase upstream/v93

6.    Resolve the conflicts. Use the changes file as the dictionary: when something imported no longer exists, the file tells what replaced it (e.g. old grid/menu components → the new DataView family). Match the style of the surrounding upstream code.
7.    Run the Angular Update Guide. Go to angular.dev/update-guide, select 14.0 → 18.0, and work through the generated checklist against the rebased tree. Do not skip this — this is where most of the silent breakage hides.
8.    Install and build:

cd imxweb
npm install        # answer 'y' when prompted to use local imx-modules packages
ng build qer-app-portal      # repeat per app/plugin you customized

Optionally, on v9.3 the entire workspace can be built in correct dependency order with a single command: npx nx run-many --target=build --all. The existing ng build pipeline also still works — pick one, don't mix mid-flight.
9.    Test in a sandbox against a 9.3 environment until every customized flow works. The build being green is not the finish line — click through each customization. Do not enter the PROD upgrade window without pre-tested bundles sitting ready in the test instance.

Phase B — During the upgrade window
1.    The SaaS team runs the upgrade. No actions required at the moment except be available.
2.    Know what the users see. From the moment the upgrade's software upload completes until the bundles are re-uploaded, the portal is live but vanilla. Agree in advance whether that gap is acceptable in-hours or whether the re-upload happens inside the same maintenance window.

Phase C — Immediately after
1.    Upload your pre-tested bundles via Software Loader — the exact same upload procedure used on v9.2.
2.    Smoke test every customized flow in the upgraded environment: home page cards/shortcuts, forms UX, info/alert messages, identity/collaborator forms, mandatory/read-only field behavior, bulk enrollment, logo/branding.
3.    Verify plugin loading. If a customized plugin (e.g. att) is consumed by more than one app (portal and password portal), confirm both apps pick up the customized build — check each app's imx-plugin-config.json in the v9.3 source rather than assuming the v9.2 behavior carried over.

Phase D — Going forward (make this routine, not heroics)
1.    Watch the releases page (GitHub → Watch → Custom → Releases) so CU updates on the v93 branch do not become a surprise. Sync, rebuild, and re-upload on a regular cadence.
2.    Budget for the next one now. The move to 10.0 LTS repeats this exact cycle (rebase → update guide → rebuild → upload). It is a recurring cost of owning a customized portal, not a one-off.
3.    Make future customizations cheaper to carry. Where possible, put new work in separately-named libraries/components rather than editing vanilla files in place — additions rebase almost for free; in-place edits are what generate conflicts every release.

The five rules.

1.    The upgrade will wipe the portal customizations. This is expected behavior, not a failure. 
2.    The Git fork is the only thing that saves here. Merging happens in Git, never in the environment.
3.    Do the work before the window. Rebase onto v93, fix, build, and test in a sandbox first. Upgrade day should be: wait, upload, smoke test.
4.    The three documents are UPGRADE.md, the 9.2.1→9.3.0 changes file, and the Angular 14→18 Update Guide. Direct links are in Part 3. Everything we hit is answered in one of them.
5.    Vendor support covers the vanilla product. Portal issues in customized areas will need reproducing on vanilla first. These customizations remain the responsibility of the owning party for this release and all future releases.