> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/solution-architecture/coexistence/planning-a-wave-migration.md). # Planning a wave migration Choosing the order applications migrate in, what a wave contains, how to validate one, how write ownership actually moves for a single application, and how the incumbent is retired. ## What this is, and when you need it A wave is **a set of applications whose write ownership transfers together, on a date, with a validation step**. It is the unit in which a coexistence architecture is dismantled, and the wave plan is the only document that says when the arrangement ends. The decisions here are the order, the size, the acceptance criteria and the end date. They are programme decisions rather than configuration ones, but they are constrained by the product in specific ways — what can be proved before a cutover, what evidence a transfer leaves, and what cannot be rehearsed — and that is what this page is about. ## The decision The first choice is what determines the order. It is usually made implicitly, which is how programmes end up having migrated everything except the applications the auditor asks about. | Sequencing strategy | What it buys | What it costs | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **By risk and dependency** (recommended) | The applications whose entitlements feed other decisions move first, so everything downstream inherits correct data. The highest-risk application moves early enough to matter and late enough that the process has been proved | Requires knowing the dependency graph, which most estates have not written down. Producing it is real work and it is work you need anyway | | **By organizational unit** | Clean communications; one business area is either migrated or not; a single sponsor per wave | Cuts across applications rather than along them, so a shared application ends up half-migrated — which the single-writer rule forbids. Workable only where applications are genuinely unit-specific | | **By connector readiness** | Nothing slips; every wave is achievable on its date | Optimises for the schedule rather than the estate. You migrate what is easy and arrive at the last wave holding everything that was hard, with no contingency left | | **By certification calendar** | No campaign ever straddles a change of write owner | A strong constraint, but not a plan on its own — it says when applications must *not* move, not which should move first | | **Big bang** | Coexistence never has to be operated | Only viable where the incumbent's coverage is thin or the estate small. If it is, take it: coexistence is a cost you accept to avoid a larger one, and where the larger one is absent you should not accept it | **Sequence by risk and dependency, constrained by the certification calendar and gated by connector readiness.** In that order. The other three are inputs to the plan, not the plan. ## Choosing the order Four rules do most of the work. **Entitlement suppliers go early.** An application whose roles or groups feed other applications' access decisions should move before its consumers, because everything downstream inherits its correctness. If it moves last, every consumer is validated twice. **Nothing moves during its own certification cycle.** A campaign that straddles a change of write owner is very hard to explain and, if a revoke decision lands in the interval, may not be executable by either platform. Applications in scope for the next campaign move before it opens or after it closes. **No wave depends on an integration that does not exist yet.** An application whose connector still has to be written does not go into a dated wave; it goes into a backlog with the connector work, and joins a wave once the connector has been proved against a non-production instance of the target. A wave that depends on development is a wave that slips, and it slips late. **The highest-risk application is not first and not last.** Not first, because the process has not been proved. Not last, because by then there is no contingency and the programme is under pressure to declare victory. Second or third wave, deliberately. A fifth consideration is worth naming even though it is not about applications: **wave size should shrink before it grows.** The first wave should be small enough that a failure is a bad week rather than a bad quarter, and small enough that the whole team can attend the cutover. ## What a wave contains For each application in the wave, the same four things move together — the catalogue entry, the approval policy, the provisioning path and the certification. A wave is complete when, for every application in it, the incumbent holds none of the four and OpenIAM holds all four. Anything less is a partial transfer, and [Coexisting with an incumbent IGA](/solution-architecture/coexistence/coexisting-with-an-incumbent-iga.md) explains why there is no such thing. Alongside the applications, a wave carries three things that are easy to forget until they are missing: the **owner** who accepts the approval policy, the **reviewer population** for the first campaign under new ownership, and the **evidence pack** described below. An application with no accepted owner is not ready for a wave regardless of how good its connector is. ## Validating a wave The product supports a genuine dry run for the part that matters most, and does not support one for the rest. Both facts should shape the plan. **Establish the before-state, from the application.** Reconcile the application into OpenIAM read-only and produce the entitlement listing. This is the baseline the after-state is compared against, and it should come from the application itself rather than from the incumbent's belief about the application — they differ more often than anyone expects, and discovering that during a cutover is expensive. **Rehearse the writes without performing them.** With the managed system's simulation list populated, OpenIAM builds each provisioning request exactly as it would for a real send and stores it for review instead of dispatching it, recording it under the `SIMULATE_PROVISIONING` audit action. Reading those requests is the closest thing to a dry run that exists: it shows the actual outbound attribute set, for real people, before the target receives anything. Two cautions. The capture is per managed system and per operation, so an operation you did not list is sent normally; and captured requests contain the full outbound attribute set, including sensitive attributes, so the reviewers need appropriate access. **Transfer, then reconcile again.** The acceptance test for a wave is that the access after the transfer matches the access before it, allowing for changes the business made in between. That is a comparison of two reconciliation results, not an assertion. **Keep the evidence.** For each application: the before-state listing, the simulation review, the date and time ownership moved, the after-state listing, and the first campaign under the new owner. This is the pack that answers "who was accountable for this grant on this date", which is the question the whole coexistence architecture exists to keep answerable. **Know what cannot be rehearsed.** The approval routing, the certification scoping and the request experience are validated in a non-production environment with representative configuration, not in production simulation. Moving that configuration between environments is a first-class task — see *Promote configuration between environments* in the Administration Guide — and it should be in the wave plan rather than assumed. ## Moving write ownership for one application The transfer itself is a short, ordered sequence, and its shape is the reason it needs planning rather than a change ticket. The incumbent stops being the write owner **before** OpenIAM starts. It has to: if both are live for even an hour, both reconciliation loops are running and the application has two owners. The interval between the two is the quiesced state — nobody governs the application, and any access change during it is a manual exception with no approval record. That interval is the risk, and it is managed rather than eliminated. Keep it short. Choose a window outside a certification period, outside month-end, and outside whatever the application's own busy season is. Announce it, so that requests raised during it are queued rather than worked around. And publish the exception path in advance, because there will be one urgent request during the window and the decision about it should not be made under pressure. Two practical points. First, cutting over the connector is not the same as cutting over the catalogue: the catalogue entry, the approval policy and the certification ownership have to move in the same window, or you have created a split. Second, do not remove the incumbent's read access on the same day. Leave it able to see the application for at least one reconciliation cycle, so that a discrepancy can be diagnosed against both records. ## Retiring the incumbent **Plan the retirement as a wave with a date, not as an eventual state.** A coexistence architecture that loses its end date becomes permanent, and a permanent two-platform estate has all of the cost and none of the benefit — two licences, two operating teams, two audit conversations, and a user population that has learned to ask in both places. The final wave is different from the others in three ways. It has no successor, so anything deferred has nowhere left to go; the applications remaining in it are by construction the ones nobody wanted to move; and the incumbent's own historical records become an archiving question rather than a live one. Decide early what happens to the incumbent's approval and certification history — it is the evidence for grants made under its ownership, and it does not come across into OpenIAM. Whether it is retained in place, exported, or archived is a records decision with a retention period attached, and it belongs in the programme plan, not in a decommissioning ticket. Retirement is complete when the incumbent holds none of the four things for any application, its feeds are stopped, its read access is removed, and its records are where the retention policy says they should be. ## Operating under a quality framework In a regulated estate each change of governance owner is a validated change rather than a configured one, and the wave is the natural validation unit: a defined scope, a documented before-state, a rehearsal, a transfer, and an after-state that demonstrates the intended outcome. State the boundary carefully, because it is frequently overstated in both directions. **The technology supports the controls and produces the evidence; the organization validates the configured process under its own quality framework.** OpenIAM gives you the reconciliation results, the simulation records, the audit trail and the certification history that a validation needs as objective evidence. It does not deliver compliance, and no product does — the qualification of the process, the acceptance criteria and the sign-off are the customer's, under its own procedures. Practically, this means the wave plan and the validation plan should be the same document, and the acceptance criteria for a wave should be written before the wave is scheduled rather than after it is executed. ## What we recommend **Sequence by risk and dependency; use the certification calendar as a constraint and connector readiness as a gate.** Do not let ease of migration choose the order. **Make the first wave small and boring.** Its purpose is to prove the process end to end, including the evidence pack, not to demonstrate progress. **Put every candidate managed system into full simulation as soon as it is configured, and read the captured requests as the wave's dry run.** This is the highest-value validation activity available and it costs nothing. **Baseline from the application, not from the incumbent.** The comparison that matters is against the target's own state. **Keep the quiesced interval short, announced, and outside a certification period.** Publish the exception path before you need it. **Do not remove the incumbent's read access on cutover day.** One reconciliation cycle of overlap costs nothing and buys you a diagnosis. **Give the retirement a date and defend it.** The end date is the single most valuable line in the plan, and it is the first one to be quietly dropped. **Decide the fate of the incumbent's historical records early.** They are the evidence for everything granted before the migration and they do not migrate. ## What OpenIAM does not do here * **There is no migration mode and no ownership field.** OpenIAM has no notion of an application being governed elsewhere; the wave plan is the only record of who owns what. * **Nothing transfers configuration from another governance platform.** Catalogue entries, approval policies and certification scopes are built in OpenIAM, not imported from the incumbent. * **Simulation covers the provisioning dispatch, not the whole request.** Approval routing, catalogue behaviour and certification scoping are validated in a non-production environment, not by simulating in production. * **Simulation is per managed system and per operation.** An operation absent from the list is dispatched normally, which makes an incomplete list more dangerous than no list at all. * **There is no before-and-after comparison report.** Comparing two reconciliation results across a cutover is something you assemble from the run outputs; the product does not do it for you. * **The incumbent's approval and certification history does not come across.** OpenIAM has nowhere to put it, and its retention is a records decision outside the product. ## Related * [Coexisting with an incumbent IGA](/solution-architecture/coexistence/coexisting-with-an-incumbent-iga.md) — what a wave moves, and why all four things move together. * [The enterprise view without duplicate governance](/solution-architecture/coexistence/the-enterprise-view.md) — the baseline a wave is validated against. * Part 8, *Operating in a regulated environment* — validation, evidence and the boundary of the product's claim. * *Simulation mode* and *Promote configuration between environments* in the Administration Guide — the dry run, and moving validated configuration between environments. *Applies to OpenIAM 2026.8.1. Last reviewed 7 August 2026.* --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.openiam.com/solution-architecture/coexistence/planning-a-wave-migration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.