> 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/administration-guide/lifecycle/decommission-a-managed-system.md).

# Decommission a managed system

Retire a managed system in the order the product enforces — three blocking dependencies, two silent unlinks, and the references nothing cleans up for you.

## What this is, and when you need it

Deleting the `MANAGED_SYS` row does not retire the application and does not delete a single target account. OpenIAM blocks the delete for three dependencies, silently unlinks two more, and leaves the rest to you. The order matters, because the step that cannot be redone — deprovisioning or migrating the accounts — has to happen while the connector still works.

## At a glance

|                          |                                                                                                                                                     |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **You will end up with** | The managed system deleted, every target account in the state you chose, nothing scheduled against it, and `DELETE_MANAGED_SYSTEM` in the audit log |
| **Where**                | **Provisioning → Managed System**, plus **Administration → Batch Tasks**                                                                            |
| **You need first**       | The target-account decision written down, and a break-glass administrator who does not sign in through this system                                  |
| **Takes**                | Days to weeks — the observation period is the long part, not the clicks                                                                             |
| **Reversible**           | Only during the deactivated observation period. After the delete, restoration is a database restore                                                 |

## Before you begin: decide the target-account outcome

Before anything else, pick one per population and write it down:

| Outcome                | What it means                                      | Must happen **while the managed system is still active**                                            |
| ---------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| **Deprovision**        | Accounts removed or disabled through the connector | Yes — after deletion or deactivation OpenIAM cannot reach the target through this integration again |
| **Migrate**            | Ownership moves to another integration             | Yes, and the new integration must correlate the accounts before you retire this one                 |
| **Retain unmanaged**   | Accounts stay, orphaned from OpenIAM               | No, but assign an owner and a new inventory or "retained" becomes "unmanaged"                       |
| **Retain for records** | Disabled, data preserved under retention policy    | Yes — the disable has to be issued while the connector still works                                  |

## Decommission in dependency-safe order

{% stepper %}
{% step %}

### Freeze new access

Remove the `CATEGORY_TYPE_ID` so it leaves the request catalog. Untick `ASSIGN_TO_ALL`. Set every business rule that grants it to `INACTIVE` — not deleted, so the audit trail survives. Do **not** deactivate the managed system yet.
{% endstep %}

{% step %}

### Resolve in-flight work

Complete or cancel open requests, approvals and manual tasks. Apply or discard every row in `SIMULATION_PROV_REQUEST` for this managed system — discarding is the safe default and `DELETE_SIMULATION_REQ` preserves the attribute set in the audit record.
{% endstep %}

{% step %}

### Apply the target-account decision, while the connector still works

Deprovision, disable or migrate. Confirm the outcome **in the target**, not in the OpenIAM audit log. This is the step that cannot be redone later.

Set `ON_DELETE` to the value your decision needs before you start: absent or blank means `DELETE`.
{% endstep %}

{% step %}

### Stop the schedules

Delete or disable the `Synchronization=<name>` and `Reconcile=<managed system name>` batch tasks. Confirm no run is in flight: open each synchronization configuration on **Provisioning → Synchronization** and look above the form. While the `RUNNING_SYNC` counter for that configuration is positive the screen shows `Synchronization is in progress.` with a **Reset** button; a clean configuration shows neither. Reconciliation refuses to start while its `RUNNING_RECON` entry is positive.

Unticking Active on a reconciliation config, or clearing its Frequency, deletes its batch task automatically. The same is true for a synchronization config.
{% endstep %}

{% step %}

### Remove governed relationships

Remove or migrate entitlements, then the policy maps, then the role/group/resource links, then certification scope. The policy maps are cascade-deleted with the system, so removing them first is optional — but doing it deliberately means the final delete has nothing left to surprise you with.
{% endstep %}

{% step %}

### Clear the three blocking dependencies

In this order, because each is cheaper than the next:

1. **Access rights** — remove the links. `LINKED_TO_ACCESS_RIGHTS` names the first one it finds.
2. **Authentication providers** — repoint or retire each one, and test sign-in through it afterwards. Do this from a separate browser session with a working break-glass administrator.
3. **User logins** — remove every `LOGIN` row for the system. This is the long one, and it is why step 3 has to come first: removing an identity for an account you have not deprovisioned strands the account.
   {% endstep %}

{% step %}

### Deactivate and observe

Untick **Active** and save. The heartbeat sweeper stops broadcasting and deletes the system's `TESTCONNECTION` documents on its next pass; the down-check sweeper stops considering it. Watch for attempted traffic for an agreed period — a request arriving now tells you a grant path you did not find.
{% endstep %}

{% step %}

### Delete

Open the system on **Provisioning → Managed System** and use **Delete**, then confirm with **Yes, delete this Managed System**. The removal is audited `DELETE_MANAGED_SYSTEM`. Afterwards, verify that the groups and roles that were bound to it still exist and are now unlinked, rather than assuming.
{% endstep %}

{% step %}

### Retire the connector and the credential

Stop or remove the connector package **only** if no other managed system references its definition: `SELECT MANAGED_SYS_ID, NAME FROM MANAGED_SYS WHERE CONNECTOR_ID = '<connectorId>'`. Then revoke the target credential and **prove it fails**. A revocation you did not test is not a revocation.
{% endstep %}
{% endstepper %}

## What the product enforces, and what it silently unlinks

OpenIAM makes these checks, in this order. The first three refuse the delete outright:

| Check                                                     | Refused with                        | Message payload               |
| --------------------------------------------------------- | ----------------------------------- | ----------------------------- |
| Any authentication provider points at this managed system | `LINKED_TO_AUTHENTICATION_PROVIDER` | The first provider's name     |
| Any `LOGIN` row exists for this managed system            | `LINKED_TO_USERS`                   | The **count** of logins       |
| Any access right references this managed system           | `LINKED_TO_ACCESS_RIGHTS`           | The first access right's name |

Having passed those, OpenIAM checks the authentication providers a second time from the other side of the relationship and can refuse with `LINKED_TO_AUTHENTICATION_PROVIDER` again.

What it then does *without asking*:

| Object                                                                                               | Action                                                                                |
| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `MNG_SYS_OBJECT_MATCH` rows                                                                          | Deleted                                                                               |
| Groups whose managed system is this one                                                              | **Unlinked** — the managed system is cleared and the group saved. The groups survive. |
| Roles whose managed system is this one                                                               | **Unlinked** the same way                                                             |
| Questionnaires on the managed system's resource                                                      | Deleted by resource ID                                                                |
| The `MANAGED_SYS` row and, by cascade, its resource, policy maps, attributes and simulation requests | Deleted                                                                               |

And what it does **not** clean up, which you must do deliberately or leave dangling:

* `SYNCH_CONFIG` rows with this `MANAGED_SYS_ID`, and their `Synchronization=<name>` batch tasks
* `RECONCILIATION_CONFIG` rows, and their `Reconcile=<managed system name>` batch tasks
* `DOWNSTREAM_SYSTEM_ID` on *other* managed systems pointing at this one
* The `APPLICATION_CATEGORY` association, so obsolete access stops being discoverable
* Reports, certification scope, and any Groovy script that references the ID as a literal
* `connectorreply` and `provisionconnectorrequest` documents in the search indexes

{% hint style="warning" %}
Deletion is blocked by `LINKED_TO_USERS` while **any** `LOGIN` row exists for the system — including inactive ones, and including rows for users who were deprovisioned but whose identity was never removed. That is usually the check that stops a decommission, and the message gives you the count, which is the number to work down.
{% endhint %}

## Verification

* No new request, synchronization, provisioning, reconciliation, simulation or connector message is generated for the system over the observation window.
* Every target account is in the approved retained, disabled, migrated or removed state — verified at the target.
* `SELECT COUNT(*) FROM LOGIN WHERE MANAGED_SYS_ID = '<MANAGED_SYSTEM_ID>'` returns `0`.
* No `SYNCH_CONFIG` or `RECONCILIATION_CONFIG` row references it; no `BATCH_CONFIG` row named for it survives.
* No other managed system's `DOWNSTREAM_SYSTEM_ID` points at it.
* Systems that share the connector still work; this one does not.
* `DELETE_MANAGED_SYSTEM` in the audit log, and the target-account evidence retained under your retention policy.

## When it goes wrong

| Symptom                                                           | Cause                                                                                                                          | Fix                                                                                              |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| Delete refused, `LINKED_TO_AUTHENTICATION_PROVIDER`               | An `AUTH_PROVIDER` row points here                                                                                             | Repoint or retire the provider, then test sign-in through it.                                    |
| Delete refused, `LINKED_TO_USERS`                                 | `LOGIN` rows exist — the message carries the count                                                                             | Deprovision the accounts **first**, then remove the identities.                                  |
| Delete refused, `LINKED_TO_ACCESS_RIGHTS`                         | `ACCESS_RIGHT` rows reference the system                                                                                       | Remove the links.                                                                                |
| Groups or roles vanished from a target after the delete           | They were not deleted — their managed system was cleared, so they now belong to none                                           | Re-point them, or accept them as unmanaged. This is by design and is silent.                     |
| A batch task keeps firing for a deleted system                    | The `Synchronization=` or `Reconcile=` `BATCH_CONFIG` row was never removed                                                    | Delete it. Managed-system deletion does not touch `BATCH_CONFIG`.                                |
| Another system's provisioning breaks after the delete             | Its `DOWNSTREAM_SYSTEM_ID` pointed at the deleted one                                                                          | Clear the reference on the surviving system.                                                     |
| Accounts left in the target with nobody accountable               | "Retain unmanaged" chosen without transferring ownership                                                                       | Establish a new authoritative inventory and an owner, or the accounts are simply ungoverned.     |
| Deactivated the system, then found accounts still needed removing | Deactivation stops OpenIAM using the integration                                                                               | Reactivate temporarily, deprovision, then deactivate again. Reactivating restarts the heartbeat. |
| Cannot recreate the integration with the same relationships       | Configuration IDs and historical relationships are not recoverable after deletion; a same-named managed system is a new object | Restore from backup, or rebuild and re-correlate.                                                |

## Roll it back

Rollback is safe during the **deactivated observation period** and not afterwards. Keep every configuration in disabled form until acceptance rather than deleting it.

If you must restore during that window: restore dependencies in forward order (identities, then access rights, then providers), issue **new** credentials where secrets were revoked — a revoked secret is rolled forward, never restored — validate the connector against one disposable object, and only then resume schedules and catalog visibility.

After deletion, restoration is a database restore. Recreating a managed system with the same name does not restore its policy maps, its identities, its reconciliation history or the references other objects held to its ID.

## Related

* [Grant birthright access](/administration-guide/lifecycle/birthright-access.md) — `ASSIGN_TO_ALL` and the rules that keep granting access here
* [Configure a managed system](/administration-guide/lifecycle/configure-managed-system.md) — `ASSIGN_TO_ALL`, `ON_DELETE` and the downstream reference
* [Managed system fields and the connector request](/administration-guide/reference/managed-system-fields.md) — every field on the object you are deleting
* [Resolve orphan accounts](/administration-guide/identities/resolve-orphan-accounts.md) — what "retain unmanaged" leaves behind
* [Change configuration safely](/administration-guide/start/change-safely.md) — the observation period and the rollback standard

*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/administration-guide/lifecycle/decommission-a-managed-system.md?ask=<question>&goal=<user_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.