> 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/integration/connector-strategy.md). # Connector strategy: how each system is reached How each system in the estate integrates — what to inventory before choosing anything, when a shipped connector, a scripted connector, a custom source adapter or a human task is the right answer, and ## What this is, and when you need it Every entitlement in the design has to be delivered by something. This page decides what that something is, system by system: a shipped connector, a generic scripted one, a custom inbound adapter, a connector you build, a human task, or nothing at all. It determines whether the role model, the certification programme and the leaver process are executable or merely drawn. Make it early, and make it as an inventory rather than as a series of escalations. The architect needs it before the wave plan, and the programme before anyone claims a date. ## Take the inventory first [Phasing a rollout](/solution-architecture/programme/phasing-a-rollout.md) sets a phase-one gate — *a shipped connector, proved against a non-production instance* — which cannot be applied until somebody has written down, per system, what is available. Six things, none of them inferable from the application's name. | What you need to know per system | Why it decides something | | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Does a shipped connector runtime exist?** Not a catalogue definition — a process that starts | The difference between an integration and a development task, and so between phase one and a later wave | | **Read, write, or both?** | A read-only integration fulfils nothing; a write-only one cannot be reconciled, and so cannot be evidenced | | **Is there a programmable interface at all?** REST, SOAP, a database, LDAP, a shell, a file drop, or nothing | Decides whether the scripted path is available. A system with no interface is a manual or out-of-scope candidate, and budget does not change that | | **Who owns it, and will they engage?** | Under manual fulfilment the owner *is* the fulfilment mechanism, and an unengaged owner fails at the first request and again at the first campaign | | **Is a non-production instance available?** | Without one, the first exercise of the integration is in production | | **What identifies a person there?** | Accounts that cannot be correlated produce orphans, not governance. See [Identity correlation: choosing a matching key](/solution-architecture/identity/correlation-key.md) | The first row carries a distinction that catches designs regularly. **A seeded managed-system definition is not a shipped connector runtime.** The catalogue holds connector records — some with complete policy-map templates — whose executable is not in the shipped set: Microsoft Graph, SuccessFactors and a WSDL-based hardware security module are all present as metadata, and one further entry is vestigial. *Shipped connectors* in the Administration Guide carries the current list of runtimes, and it is what the inventory's first column should be checked against. ## The decision | Option | What it buys | What it costs | | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | **A shipped connector** — directories, databases, cloud applications, HR systems, generic protocols | Full lifecycle out of the box, and reconciliation against the target. The only option that satisfies the phase-one gate | Configuration and proving | | **The generic scripted connector** — the Groovy Script Connector, one class per operation | Reaches anything addressable over REST, SOAP, JDBC or a shell, without a new binary | You own the script and its tests. No pooling, and a script change needs a process restart | | **A custom source adapter** — Groovy replacing a synchronization's entire inbound read | Ingests from a source with no connector at all: an internal API, an unusual export, a query-only system | Inbound only. It brings data in; it fulfils nothing | | **Build a connector** — a standalone process against the platform's connector contract | A first-class integration with pooling and no scripting limits | A development project with a release train and an upgrade obligation | | **Manual fulfilment** — the system is flagged manual, and an approved request becomes a human task | Governs a system OpenIAM cannot touch: catalogue entry, approval, audit trail and revocation are all real | Nothing reads the target, and a pending entitlement is excluded from certification | | **Out of scope** — not represented in OpenIAM | Honest, and cheap | Every access decision stays where it is today, and the leaver process has a hole nobody tracks | The rows are in order of preference, and that ordering is the recommendation. Read the diagram as the sequence a single system passes through. ```mermaid flowchart TD A[System in the inventory] --> B{Shipped connector runtime?} B -->|Yes| C[Configure and prove it] B -->|No| D{Inbound ingestion only?} D -->|Yes| E[Custom source adapter] D -->|No| F{Reachable over REST, SOAP, JDBC or shell?} F -->|Yes| G[Groovy Script Connector] F -->|No| H{Human fulfilment acceptable?} H -->|Yes| I[Manual managed system] H -->|No| J[Build a connector, or leave out of scope] ``` ## Three runtimes, and why the difference matters Connectors are not one thing operationally, and a design that treats the runtimes as interchangeable gets the operating model wrong. **Java connectors** are the main family. Twenty-five are in the container distribution, each packaged and deployed as its own unit. On a packaged Linux installation the picture differs in a way worth planning for: **the installer bootstraps exactly one connector — the LDAP connector.** Every other one is a separate download and copy onto the host, then a service instance per connector. Same connectors, different packaging — but it is a real planning surprise that lands in the middle of an install day. **The .NET and PowerShell family** runs on Windows as a Windows Service, installed and versioned separately, because some Microsoft operations have no clean equivalent over another protocol. [Connector placement](/solution-architecture/integration/connector-placement.md) covers what needs it and what it needs. **Source adapters** are the inbound half and are not connectors at all: they run as their own processes and feed a synchronization rather than fulfilling requests. A design that says "we will integrate the HR system" should say which it means, because the two fail in different ways. ## The generic paths, and their real limits **The Groovy Script Connector is the answer for "no dedicated connector".** It is a shipped connector like any other: one Groovy class per operation, taking its connection details from the managed system's own metadata and named attributes, free to reach REST, SOAP, JDBC or a shell. Most estates that integrate something unusual do it here rather than by building anything. Two limits belong in the design rather than in an incident. **It holds no persistent connection and no pool.** Each operation stands up what it needs and tears it down. Against a target that is slow to authenticate that is a throughput ceiling — and the connector is already the terminal bottleneck for bulk provisioning and reconciliation. **Scripts are cached when the connector process starts.** Editing a script does not change the running behaviour; the process has to be restarted. Every script change in production is therefore a service restart, and the design should say who may perform one and in what window. **The custom source adapter is the most under-used option in the product.** Where a synchronization has no connector to read from, a Groovy class can replace the entire inbound read — the adapter itself, not a transformation hung off one. It is the right answer for an internal system that has an API and no connector, and it is missed because it looks like a scripting feature rather than an integration option. **CSV is inbound only.** A synchronization can read a file; **there is no write-to-file provisioning path.** No connector serialises an account change to a drop directory for another system to collect. That surprises people, because file interfaces are common in these estates and the inbound direction works so cleanly. An outbound file interface is a scripted connector you write. ## Manual fulfilment, and its ceiling Manual fulfilment is a first-class design choice. A managed system can be flagged manual, which changes what it is: it becomes a manual managed system and no longer provisions. The mechanism matters, because the governance consequences follow from it. An approved request against a manual managed system raises a task in the workflow engine assigned to **the owners of the target resource**, and tags the requested roles or groups as pending manual assignment. When a human marks the task complete, the tag is removed and the requester is notified. The same path runs for revocation, for termination, and for a revoke decision taken in a certification campaign. **Nothing reads the target.** The tag clears because a person clicked Complete, not because the account was found. Manual fulfilment is human attestation, not verification, and the design should say so in those words to whoever relies on it. Two consequences follow. **A pending manual entitlement is excluded from certification** — not presented to a reviewer, and not counted as a grant origin when access risk is calculated — so an entitlement left pending because an owner has not worked the task is invisible to the programme meant to review it. That is a coverage gap [Designing a certification programme](/solution-architecture/governance/certification-programme.md) has to carry. And **a manual managed system cannot be reconciled at all**, which closes off the pattern most architects reach for next. ### The semi-manual gap Where fulfilment is manual but assurance is required, the pattern usually reached for is a semi-manual one: raise a human task to make the change, then reconcile the target afterwards to confirm the change landed. **In this release that pattern is assembled rather than configured**, because the same managed system cannot be both the manual fulfilment target and the reconciled target — a manual managed system is not reconciled. The pieces exist separately — a reconciliation can be made purely observational by setting every situation's response to do nothing — but nothing ties a reconciliation result back to an open manual task. An architect who needs the assurance would model the target twice — one manual managed system for fulfilment, one read-capable managed system that only observes — and compare the two out of band. That is a build rather than a configuration, and it should be costed as one. ## What happens when there is no connector **You cannot create a non-manual managed system without a connector.** The save is rejected: a managed system either has a connector or is flagged manual, and there is no third state. **A request whose connector is missing, inactive or has no queue fails.** It does not fall back to a human task and it does not queue for later. Manual fulfilment is a configuration chosen in advance, never a safety net that catches a broken integration. ## ITSM is a notification channel, not a fulfilment channel This is proposed in nearly every enterprise design, and it does not do what it is assumed to do. OpenIAM can call a Groovy script attached to a target resource at four points: when an access request is created, when access is revoked, when a new user is created, and when a group is saved. The shipped example raises a ServiceNow incident and writes the incident number back onto the user. The hook is real, it is useful for notification, and it produces its own audit event. It is not fulfilment, for three reasons. The **entitlement is already saved before the hook runs.** The grant exists whether or not a ticket is ever created. **The call cannot fail visibly.** The hook returns nothing, the caller does not inspect a result, and the shipped ServiceNow script catches its own exceptions and returns null. **A service-desk outage therefore produces a successful audit event and no ticket** — no retry, no alert, nothing in the request record to show anything went wrong. **The loop does not close.** There is no callback, no polling, and no OpenIAM state tied to the ticket. Nothing marks access delivered when the ticket is resolved, and nothing reopens the request when it is rejected. Where the intent is "a human does the work in the service desk and OpenIAM knows when it is done", the mechanism is manual fulfilment, with the ticket hook alongside it for visibility. ## Build versus adapt Before costing a connector, establish that a connector is what is missing. Much of what looks like connector work is configuration, or a small script at a defined attachment point. **What can be adapted without writing anything new:** the policy map that decides which identity attributes become which target attributes, copyable from a template and extendable with per-attribute transformation scripts; the managed system's additional attributes, for connection parameters the standard fields do not carry; and Groovy attachment points across the whole integration surface, from synchronization processing, validation and custom matching through reconciliation matching and situation handling to the custom source adapter and the post-approval hook above. *Groovy script reference* in the Administration Guide enumerates them. **Building a connector is a development project against the platform's connector contract.** The platform side of that contract is well defined: the operations a connector must implement for users and for groups are a fixed set, each with its own request and response type, and a connector that implements them is a first-class integration with pooling and no scripting limits. The connector-side framework is distributed by OpenIAM rather than bundled with the deployment tooling, so **agree the scope, the tooling and the support model with OpenIAM as part of the design**, in the same conversation as the licence and the roadmap. Cost the result as a build with a release train and an upgrade obligation behind it, not as a configuration task. ## Sequencing the integration work Connector maturity should order the waves, not application importance. Systems with a shipped, proved connector and an engaged owner go first, because they exercise the identity model without simultaneously exercising a development project; scripted connectors follow in a second wave, with the script treated as a deliverable that has tests; systems needing a built connector go into a backlog, not into a phase. Manual-fulfilment systems can go anywhere, but each adds a certification gap the governance plan carries. [Phasing a rollout](/solution-architecture/programme/phasing-a-rollout.md) applies this ordering to a first phase. ## What we recommend **Run the inventory before the wave plan, and publish it with the gaps visible.** The rows with empty cells are the risk register. **Use a shipped connector wherever one exists, and prove it against a non-production instance before it enters a phase.** It is the only row in the decision table with no residual engineering risk. **Reach for the Groovy Script Connector before reaching for a build,** and design around its two limits from the start. Both are manageable when planned and disruptive when discovered. **Choose manual fulfilment deliberately, and record its ceiling beside the choice.** It is right for systems that genuinely have no interface, and poor for one somebody else is already provisioning automatically — see the fulfilment row of the ownership table in [Coexisting with an incumbent IGA](/solution-architecture/coexistence/coexisting-with-an-incumbent-iga.md). **Never present an ITSM hook as fulfilment in a design document.** The circumstance that changes all of this is an estate of modern SaaS applications with clean APIs and a shipped connector each. There the inventory takes a morning, every row says "shipped connector", and this page reduces to its first table. ## What OpenIAM does not do here * **There is no write-to-file provisioning path.** Files are an inbound source only. * **Manual fulfilment verifies nothing.** No product function reads the target; the pending tag clears when a human clicks Complete. * **A manual managed system cannot be reconciled**, so "raise a task, then confirm by reconciliation" is not available. * **A pending manual entitlement is excluded from certification** and is not counted as a grant origin for risk. * **A failed or missing connector does not fall back to a human task.** The request fails — and you cannot create a non-manual managed system without a connector in the first place. * **The ITSM hook cannot report failure.** It returns nothing, the caller does not inspect it, and the shipped script swallows its own errors, so an outage looks like a success in the audit trail. * **A seeded connector definition is not a runtime.** A record in the managed-system catalogue, even one with a complete policy-map template, does not mean a connector process ships with the release. Check the shipped set before a design depends on one. ## Related * [Connector placement](/solution-architecture/integration/connector-placement.md) — where the processes chosen here physically run, and what each host must reach. * [Phasing a rollout](/solution-architecture/programme/phasing-a-rollout.md) — how connector maturity orders the waves. * *Connectors and managed systems* and *Manual fulfilment* in the Administration Guide — the model behind this decision, and how the human path is configured. * *Shipped connectors* in the Administration Guide — the catalogue the inventory's first column is checked against. *Applies to OpenIAM 2026.8.1. Last reviewed 13 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/integration/connector-strategy.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.