How should I upgrade toolkit dependencies across many process apps safely (snapshot strategy, breaking changes, verification)?

Question

We have a shared toolkit used by 30 process apps. Every change to it means upgrading the dependency in each app, retesting and redeploying. What strategy keeps this manageable and what breaks when a toolkit changes?

Answer 1

Toolkit dependencies are pinned per process app snapshot; upgrading is an explicit action (Dependencies > the toolkit > pick a newer snapshot) followed by a new app snapshot. What can break during that upgrade:

• Removed or renamed artifacts (services, business objects, coach views, EPVs) - references become "missing" and the app cannot be snapshotted until fixed.
• Changed business object structure - existing instances hold the old shape in their execution contexts; the new snapshot reads missing fields as undefined; use instance migration and defensive scripts.
• Changed service contracts (new required inputs, changed output types) - runtime mapping errors rather than design-time errors.
• Coach view behaviour - a change in a shared view changes every coach that uses it; that is the point, and the risk.

Strategy that works with dozens of consumers:

1. Semantic snapshot names (1.4.0) with a compatibility promise: patch versions never remove, rename or change contracts; minor versions add; a major version may break and ships with migration notes. Enforce with a changelog and an automated diff of the toolkit's twx between versions (removed / changed artifacts).
2. Layered toolkits: core (data types, utilities - changes rarely), UI (views - changes often), integrations (connectors); apps depend only on the layers they need, so a UI change does not force a re-snapshot of a batch-only app.
3. Upgrade waves: apps upgrade on their own release cadence, not the toolkit's; only security or defect fixes are pushed to all (patch version). Several toolkit snapshots can be installed side by side, so different apps safely run different toolkit versions.
4. Automated verification: after the dependency upgrade, snapshot, run the app's regression suite (question on automated tests) and the validation report. The dependency change itself stays a Process Designer action (the Process Center REST does not change dependencies) - keep that step manual and automate everything around it.
5. Tip vs snapshot: apps in development may depend on the toolkit's tip (auto-updates); never in a snapshot that leaves development.

# which installed app snapshots depend on which toolkit snapshot - classic REST (8.5+)
GET /rest/bpm/wle/v1/processApp/2066.abc?parts=all           -> installedSnapshots[] with their dependencies
# release-independent: export each app's twx and read META-INF/package.xml
unzip -p OrderApp-1.4.0.twx META-INF/package.xml | grep -o '<dependency[^>]*>'
#   <dependency name="Core Toolkit" snapshotId="2064.1234..." snapshotName="1.4.0" .../>

References

• BAW documentation - toolkits and dependency management
• Operations REST API