> 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/connectors-and-managed-systems.md). # Connectors and managed systems How a connector package, a connector definition and a managed system relate — the queue naming, the dynamic-field mechanism, and how to tell a runtime fault from a configuration fault. ## What this is, and when you need it Three separate things carry similar names, and almost every "the connector is broken" ticket is really about which one: | Thing | What it is | Where it lives | | ------------------------ | ---------------------------------------------------------------------- | ------------------------------------------------------ | | **Connector package** | A deployed process that talks to the target and consumes an AMQP queue | Outside OpenIAM — its own container or Windows service | | **Connector definition** | A `PROVISION_CONNECTOR` row naming that queue and a metadata type | OpenIAM database, edited at `/webconsole/connector` | | **Managed system** | A `MANAGED_SYS` row: one endpoint, one credential, one target instance | OpenIAM database, edited at `/webconsole/mngsystem` | One package serves many managed systems. One definition is referenced by many managed systems. Deleting a managed system does not touch the package; restarting the package affects every managed system that references its definition. Ownership boundary: the **Connector Configuration Guide** owns installing, registering and upgrading the package, the target-side permissions it needs, and the meaning of each connector-specific value. This guide owns selecting the definition, filling the managed system, and proving the result. A field appearing in Webconsole does not make its meaning generic. ## At a glance The one change made on this page is editing or registering a connector definition; most readers only read the model and go on to [Configure a managed system](/administration-guide/lifecycle/configure-managed-system.md). | | | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **You will end up with** | One saved `PROVISION_CONNECTOR` row — and therefore a changed queue or field set on every managed system that references it — audited `SAVE_CONNECTOR` | | **Where** | **Provisioning → Connectors**, `/webconsole/connectorlist`; `/webconsole/connector?id=` edits one | | **You need first** | The exact queue name the deployed package consumes, character for character; agreement from whoever runs it; and the **Provisioning Connectors** menu resource (`PROVCONNECT_MENU_ITEM`, under **Provisioning**) with its **Create New Connector** child (`PROV_CONNECTOR_NEW`) | | **Takes** | 10–20 minutes, plus one heartbeat sweep (shipped 60 s) before a renamed queue is re-bound | | **Reversible** | Partly — name, queue and urgent-queue values come back by re-saving the previous values; a metadata-type change does not, because values written under the old template stay in their columns while the form stops showing them | ## Before you begin * The queue name the deployed package actually consumes, character for character. OpenIAM does not discover it. * The list of managed systems already referencing the definition, if you are editing rather than creating one: `SELECT MANAGED_SYS_ID, NAME FROM MANAGED_SYS WHERE CONNECTOR_ID = ''`. * Agreement from whoever runs the connector package, because a queue rename has to happen on both sides. ## Edit or register a connector definition {% stepper %} {% step %} ### Open the definition `/webconsole/connectorlist` lists them; `/webconsole/connector?id=` edits one. If the connector you need is not in the list, create it here — a managed system cannot reference a definition that does not exist, and substituting a similar connector is not a workaround, because the metadata type drives the whole field set. Test on a definition no managed system references yet. {% endstep %} {% step %} ### Set the four fields {% hint style="warning" %} One definition is shared by many managed systems, and there is no per-managed-system override of a definition: changing its queue or its metadata type changes all of them at once. {% endhint %} The form has four fields only: | Field | Column | Notes | | -------------------------------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | Name | `NAME` | Shown in the managed-system Connector dropdown and the dashboard's Connector column | | Metadata type | `METADATA_TYPE_ID` | Selects which `MANAGED_SYSTEM_TEMPLATE` page template applies, and therefore which dynamic fields appear | | Connector queue | `CONNECTOR_QUEUE` | The base name; `_Request`/`_Response` are appended | | Enable urgent queue / Urgent connector queue | `IS_URGENT_CONNECTOR_QUEUE_ENABLED`, `URGENT_CONNECTOR_QUEUE` | Second queue for password and login operations | {% hint style="danger" %} Changing `METADATA_TYPE_ID` on a definition that managed systems already reference changes which dynamic fields their forms show. Values already stored in `MANAGED_SYS` columns are not deleted, but they stop being editable and stop being visible — so a base DN can keep going on the wire while nobody can see it. Create a new definition instead. {% endhint %} {% endstep %} {% step %} ### Save, then confirm on a managed system Saving audits `SAVE_CONNECTOR`; deleting audits `DELETE_CONNECTOR`. Both retentions ship `-1` — see [Audit actions and retention](/administration-guide/reference/audit-actions-and-retention.md). Open a managed system that references the definition and confirm the connector-specific fields you expect are present before you rely on it. {% endstep %} {% endstepper %} ## Verification * **Definition.** `SELECT CONNECTOR_ID, NAME, METADATA_TYPE_ID, CONNECTOR_QUEUE, IS_URGENT_CONNECTOR_QUEUE_ENABLED FROM PROVISION_CONNECTOR` — confirm the queue matches what the deployed package is configured to consume, character for character. * **Binding.** A `_Request` queue with a non-zero consumer count on the broker — [Diagnose by layer](/administration-guide/lifecycle/verify-connection.md#diagnose-by-layer). * **Heartbeat.** A `connectorreply` document for the managed system with `operation = "TESTCONNECTION"` and `status = "Ok"`. The dashboard at `/webconsole/mngsystemlist` renders exactly this. * **Template.** Open `/webconsole/mngsystem?id=` and confirm the connector-specific fields you expect are present. ## When it goes wrong ### Telling a runtime problem from a configuration problem The two failure classes look identical in the Webconsole and have nothing in common. Split them with one question: **is there a `connectorreply` document at all?** | Observation | Class | Why | | ------------------------------------------------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Connector Status column shows *no connector active* | **Runtime** | There is no `connectorreply` document with `operation = TESTCONNECTION` for this managed system. The heartbeat was broadcast and nothing answered. | | A `SERVICE_DOWN` document exists in `connectorreply` | **Runtime** | OpenIAM writes one precisely when neither a `TESTCONNECTION` reply nor an earlier `SERVICE_DOWN` document exists — that is, when the connector has answered nothing at all. | | Heartbeat reply present with `status = "Error"` and a `lastError` | **Configuration** — endpoint, credential or permission | The connector process is alive and consuming its queue; it tried and failed. Read `lastError`. | | Heartbeat reply `status = "Ok"`, but a provisioning operation fails | **Configuration** — mapping, scope or target permission | The credential authenticates. What failed is this operation. Read the operation's own `connectorreply` doc. | | Requests accumulate in `_Request` with no consumer | **Runtime** | Nothing is bound to the queue, or the connector process is dead. The broker's management UI shows the queue's consumer count as `0`. | The ordering matters: fixing a base DN cannot help a process that is not running, and restarting a connector cannot fix a wrong credential. The full layer-by-layer table, including the failures a green heartbeat hides, is in [Verify connectivity to the target](/administration-guide/lifecycle/verify-connection.md#diagnose-by-layer). ### Symptom, cause, fix | Symptom | Cause | Fix | | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Connector absent from the managed-system dropdown | No `PROVISION_CONNECTOR` row, or the dropdown's search found nothing matching what you typed | Register the definition. Do not substitute a similar connector — its metadata type drives the field set. | | Expected connector-specific fields missing from the form | `METADATA_TYPE_ID` has no `MANAGED_SYSTEM_TEMPLATE` page template, or `UI_FIELD_TEMPLATE_XREF` has no row for that field | Repair the page template. Do not enter the value into an unrelated field. | | **Create Default Policies** button absent | `MANAGED_SYS.CONNECTOR_ID` empty, the system is manual, or the connector has no `MNG_SYS_POLICY` rows | Assign the connector; build the template at `/webconsole/policyMapTemplate?id=`. | | Template edited, existing managed systems unchanged | The copy is taken once at create-defaults time | Edit each system's map, or clone. | | Two managed systems both stop working after one connector restart | They share a `PROVISION_CONNECTOR` row, therefore a queue and a runtime | Inventory sharing before any operational change: `SELECT MANAGED_SYS_ID, NAME FROM MANAGED_SYS WHERE CONNECTOR_ID = ''`. | | Queue missing after a restart ordering problem | The IDM bound queues at startup before the connector existed | Wait one `org.openiam.idm.connector.health.check.sweeptime` interval (60 s); the sweeper re-binds. | | Adding a second directory connector created duplicate people | The configuration did not match, and **Detect orphans** was off, so every unmatched record was created. Shipped `AZURE_USER_SYNC` ships `IS_ORPHAN_DETECTION = 'N'` | Set `MATCH_FIELD_NAME` to a key that exists in both sources — `MANAGED_SYS_PRINCIPAL` against the other directory's managed system, or an immutable workforce key — and decide **Detect orphans** deliberately. | | Password operations lag behind bulk provisioning | Everything shares one request queue | Set `URGENT_CONNECTOR_QUEUE` and `IS_URGENT_CONNECTOR_QUEUE_ENABLED = 'Y'`, and configure the package to consume it. | Three failures that look like a mapping fault and are not — an Active Directory referral, a Salesforce `redirect_uri_mismatch`, and the two Azure Graph packages — are in [Shipped connectors](/administration-guide/reference/shipped-connectors.md#symptoms-that-point-at-the-wrong-connector-not-the-wrong-mapping). Adding a second connector over a population you already synchronize is a synchronization problem, not a connector one: the correlation is two fields on the synchronization configuration, and no shipped script does it for you. See [How a synchronization matches and processes a record](/administration-guide/lifecycle/synchronize-and-import-data/synchronization-matching-and-processing.md) and [Import from two authoritative sources without overwriting](/administration-guide/lifecycle/synchronize-and-import-data/import-from-two-authoritative-sources.md). ## Rollback Restore the recorded previous `NAME`, `CONNECTOR_QUEUE` and urgent-queue values and save again; the definition is configuration and the save is reversible. A **metadata type** change is not reversible in the sense that matters: values written under the old template stay in their columns while the form no longer shows them, so restoring the old type is the only way to see them again, and creating a fresh definition is the safer path in the first place. A queue rename must be reverted on the connector package as well, or the requests go to a queue nothing consumes. Deleting is audited `DELETE_CONNECTOR` and is not a rollback: inventory the managed systems referencing the definition first, with the query above, and give each of them a connector before the definition goes. ## How the pieces fit None of this is needed to select a connector. Read it when a queue is missing, a field you expect is absent, or you are deciding where a house-standard policy map should live. ### Queues, exchanges and vhosts `PROVISION_CONNECTOR.CONNECTOR_QUEUE` holds a base name. OpenIAM derives everything else from it: | Derived name | Purpose | | ------------------------------------------ | --------------------------------------- | | `_Request` | Requests OpenIAM sends to the connector | | `_Response` | Replies the connector sends back | | `broadcast._Request.test` | Routing key for the fan-out heartbeat | All three live on vhost **`openiam_connector`**. Ordinary requests use the exchange `CONNECTOR_EXCHANGE`; the heartbeat uses the fan-out `CONNECTOR_BROADCAST_EXCHANGE`. Each queue is bound with its routing key equal to its own name, so the names above are exactly what you will see in the broker's management UI — that is where to confirm a queue exists, since the Webconsole never shows it. Two facts that matter operationally: * **Binding is re-attempted on every heartbeat sweep**, for each active managed system's connector, so a start-up ordering problem heals itself. If a queue is still absent after two sweeps the cause is the connector, not the ordering. * **Two definitions can share a queue.** Nothing enforces uniqueness of `CONNECTOR_QUEUE`. The shipped PowerShell family deliberately uses distinct suffixes (`RemoteConnector_2` … `RemoteConnector_6`) for exactly this reason. `PROVISION_CONNECTOR` also carries an optional second queue, `URGENT_CONNECTOR_QUEUE`, enabled by `IS_URGENT_CONNECTOR_QUEUE_ENABLED`. It exists so that set-password, reset-password and login operations do not queue behind a bulk provisioning backlog. It is bound the same way, and the heartbeat sweeper binds it too. ### Connector definitions supply dynamic fields This is the mechanism that makes the managed-system form change shape when you pick a connector. It is four tables deep, and knowing the chain is what lets you diagnose "the field I expect is not there". {% code overflow="wrap" %} ``` PROVISION_CONNECTOR.METADATA_TYPE_ID │ ▼ METADATA_ELEMENT_PAGE_TEMPLATE (TEMPLATE_TYPE_ID = 'MANAGED_SYSTEM_TEMPLATE', │ METADATA_TYPE_ID = the connector's type) ├── UI_FIELD_TEMPLATE_XREF → which built-in MANAGED_SYS columns appear, and whether they are required └── PAGE_TEMPLATE_XREF → extra METADATA_ELEMENTs, which become MANAGED_SYS_ATTRIBUTE rows ``` {% endcode %} **Built-in fields** are selected by `UI_FIELD_TEMPLATE_XREF` rows whose `UI_FIELD_ID` is one of 24 fixed names; a `UI_FIELD_ID` outside that list renders nothing at all, silently. The 24 names and the `MANAGED_SYS` column each one writes to are in [Managed system fields](/administration-guide/reference/managed-system-fields.md#connector-specific-dynamic-fields). The label you see is `UI_FIELD_TEMPLATE_XREF`'s localized `LANGUAGE_MAPPING` text, not the `UI_FIELD_ID` — which is why the same underlying column is called "Connection String" for JDBC and something else elsewhere. `UI_FIELD_TEMPLATE_XREF.IS_REQUIRED` drives the form's own validation — an empty required field is flagged in place rather than reported in a message — and `IS_EDITABLE = 'N'` renders the field read-only. **Extra fields** are `METADATA_ELEMENT` rows joined by `PAGE_TEMPLATE_XREF`. On save, each one becomes a `MANAGED_SYS_ATTRIBUTE` row whose `NAME` is the element's `ATTRIBUTE_NAME`, `VALUE1` the entered value and `METADATA_ID` the element. If the element's `TYPE_ID` is `PASSWORD`, `VALUE1` is stored encrypted and reads back as a mask. **None of this is saved at all when the managed system is manual** — the fields accept input, the save succeeds, and no rows are written. {% hint style="info" %} **A dynamic field is only ever as good as the connector reading it.** OpenIAM does not validate any of these against the target — it copies them onto the wire, and what the connector does with them is the connector's contract. See [Managed system fields](/administration-guide/reference/managed-system-fields.md#what-actually-reaches-the-connector) for the exact wire names, and capture one operation in simulation if you need to prove a value left OpenIAM. {% endhint %} ### The connector policy-map template `MNG_SYS_POLICY.CONNECTOR_ID` lets a policy map hang off a **connector definition** instead of a managed system. Those are templates. * Edit them at `/webconsole/policyMapTemplate?id=`, using the same editor as a real map (`/webconsole/policyMapEdit?connectorId=&type=USER_OBJECT`). * On a managed system with no maps of its own, **Create Default Policies** appears when `MANAGED_SYS.CONNECTOR_ID` is set *and* the connector has at least one policy map. * Pressing the button copies every map on the connector definition, and every `ATTRIBUTE_MAP` row in it, as **new rows** on this managed system — editing the copy afterwards does not touch the template, and editing the template does not touch systems already copied from it. * A **manual** system never gets default policies, and neither does a system with no connector selected. The button is simply absent; there is no message explaining why. The copy is taken **once**. Editing a connector template afterwards changes nothing on managed systems already created from it. If you maintain a house standard for, say, LDAP attribute mapping, the template is the right place to keep it — but rolling a change out to existing systems is a per-system edit, or a **Clone Managed System** with **Clone Policy Map** ticked onto a fresh system. Details in [Build a policy map](/administration-guide/lifecycle/policy-map.md#create-the-map-or-copy-the-connectors). ### Connector families that ship Thirty-four connector definitions ship, each naming the `CONNECTOR_QUEUE` its package must consume. The list, the shipped Workday queue name that no package consumes, and the per-family script directories are in [Shipped connectors](/administration-guide/reference/shipped-connectors.md). ## Related * [Configure a managed system](/administration-guide/lifecycle/configure-managed-system.md) — the task most readers came here on the way to. * [Shipped connectors](/administration-guide/reference/shipped-connectors.md) — the definitions, their queues, and the per-connector traps. * [Managed system fields and the connector request](/administration-guide/reference/managed-system-fields.md) — the 24 dynamic fields and what reaches the connector. * [Verify connectivity to the target](/administration-guide/lifecycle/verify-connection.md) — what a green status does and does not prove. * [Build a policy map](/administration-guide/lifecycle/policy-map.md) — the template mechanism from the policy-map side. * [Import from two authoritative sources without overwriting](/administration-guide/lifecycle/synchronize-and-import-data/import-from-two-authoritative-sources.md) — a second connector over a population you already synchronize. * [Choose an onboarding pattern](/administration-guide/lifecycle/onboarding-patterns.md) — whether you need any of this. *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/connectors-and-managed-systems.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.