> 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/reference/synchronization-configuration-fields.md). # Synchronization configuration fields Every field on the synchronization form with the column behind it, the five source types, and the batch and threading defaults. ## What this is, and when you need it The form at `/webconsole/synchronization` writes one `SYNCH_CONFIG` row. This page is the field-by-field reference for that form: what each control sets, what it ships as, and which fields a given source type makes mandatory. The procedure that fills it in is [Set up a synchronization](/administration-guide/lifecycle/synchronize-and-import-data.md). ## Every field on the synchronization form Field by field, with the column and what it actually does: | Field | Column | Notes | | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Name** | `NAME` (60, `NOT NULL`) | Also becomes the batch task name `Synchronization=` and the report filename prefix. | | **Synchronize Object** | `PROCESS_RULE` (80) | One of `USER`, `ROLE`, `ORG`, `GROUP`, `RESOURCE`, `MANAGED_SYSTEM`, `LOG`. Required. It decides which processor handles the run, and therefore what the match field means. `POLICY` is handled internally but the form cannot select it. | | **Records per Batch** | `RECORD_COUNT_IN_BATCH` | **Ships `1000`.** Must be greater than zero — a zero or negative value is rejected with `RECORDS_NUMBER_MUST_BE_GREATER_ZERO`. This is the records-per-part figure, that is, per RabbitMQ message. | | **Managed System** | `MANAGED_SYS_ID` (32) | For CSV, RDBMS and LOG sources this is `0` (OpenIAM itself) in every shipped example. For `CONNECTOR_ASYNC` it is the managed system to read through. | | **Active** | `ACTIVE` | An inactive config throws `SYNC_CONFIG_INACTIVE` on start, with the audit failure reason *"Synchronization config is in 'INACTIVE' status. Stopping."* | | **Detect orphans** | `IS_ORPHAN_DETECTION` | See [Orphan detection changes what a run does](/administration-guide/lifecycle/synchronize-and-import-data/synchronization-matching-and-processing.md#orphan-detection-changes-what-a-run-does). | | **Provision to target systems?** | `IS_PROVISION` | The label spells out the consequence of leaving it off: *"(If unchecked, ensure identities are created in the transformation script)."* | | **Synchronization Source** | `SYNCH_SRC` | One of the five values in the table below. | | **CSV File Name / Splitter** | `CSV_SYNC_ID`, `SPLITTER` (a single `Character`) | CSV only. Uploading the file from the configuration screen audits `SYNCHRONIZATION_CSV_FILE_ATTACHED`. | | **Custom Adapter Script** | `CUSTOM_ADAPTER_SCRIPT_ID` | `CUSTOM` source only. | | **Host Name / JDBC Driver / Connection Url / Source login ID / Source password** | `SRC_HOST`, `DRIVER`, `CONNECTION_URL` (500), `SRC_LOGIN_ID`, `SRC_PASSWORD` | `RDBMS` only. The password is obfuscated in audit output — you will not see it in an audit record — and stored encrypted when `IS_PASSWORD_ENCRYPTED` is `Y`, which is the default. | | **SQL Query / Directory Filter** | `QUERY` (4000) | One field, two meanings: a SQL statement for `RDBMS`, a directory filter or connector command for `CONNECTOR_ASYNC`. | | **Sync Type** | `SYNCH_TYPE` (20) | **`FULL`** (labelled "Complete") or **`INCREMENTAL`**. Those are the stored values. | | **Last Update Field** | `QUERY_TIME_FIELD` (50) | Required when Sync Type is `INCREMENTAL`; the form enforces it client-side. | | **Sync Frequency** | `CRON_EXPRESSION` (100) or `RUN_ON` | The form offers *Cron Job* or *Execute once on date*, and they are mutually exclusive — `updateBatchTask` sets one and nulls the other. | | **OpenIAM field name** | `MATCH_FIELD_NAME` (40) | One of `USERID`, `MANAGED_SYS_PRINCIPAL`, `PRINCIPAL`, `EMAIL`, `EMPLOYEE_ID`, `ATTRIBUTE`, `NAME`. Required. Stored as plain text and resolved at run time, so a value outside that set is accepted on save and never resolves — see [The valid match field values](/administration-guide/lifecycle/synchronize-and-import-data/synchronization-matching-and-processing.md#the-valid-match-field-values). | | **OpenIAM Custom Attribute Name** | `CUSTOM_MATCH_ATTR` (40) | Required, and only shown, when **OpenIAM field name** is `ATTRIBUTE`. | | **Source Attribute Name** | `MATCH_SRC_FIELD_NAME` (40) | The source column or attribute holding the match value. Required. | | **Custom rule for matching** | `CUSTOM_MATCH_SCRIPT_ID` (**10 chars**) | Replaces the built-in match rule. The column is only `VARCHAR(10)` — long script IDs will not fit. | | **Source attribute names** | `ATTR_NAMES_LOOKUP_SCRIPT_ID` (120) | An attribute-names lookup script, returning a `String[]` from `getAttributes()`. Required for `CONNECTOR_ASYNC`: it is the list of attributes the connector is asked to return, and an attribute absent from it is absent from `columnMap` in your transformation. | | **Preprocessor Script / Postprocessor Script** | `PREPROCESSOR_SCRIPT_ID`, `POSTPROCESSOR_SCRIPT_ID` (100) | Run once around the whole run, not per record. | | **Validation Rule** | `VALIDATION_SCRIPT_ID` (80) | A validation script. Required. | | **Transformation Rule** | `TRANSFORMATION_SCRIPT_ID` (80) | A transformation script. Required. | | — | `TRANSFORMATION_IMPL` (32) | Holds either `POLICY` or `TRANSFORMATION`, but see the callout. | | — | `SEARCH_SCOPE` | Directory search scope for a connector source, defaulting to a subtree search. | | — | `BASE_DN` (**50 chars**) | Directory base for a connector source. Short column — a deep DN will not fit. | | — | `LAST_EXEC_TIME`, `LAST_REC_PROCESSED` (32) | Set by the run. `LAST_REC_PROCESSED` is the incremental marker, stored as the target's generalized time. | {% hint style="warning" %} **The Transformation Implementation choice does not exist in practice.** Every save forces `TRANSFORMATION_IMPL` to `TRANSFORMATION`, whatever it held before and before validation runs — so the declarative `POLICY` path is unreachable from the Webconsole and every synchronization is script-driven. Plan on writing a transformation script. It would not build in any case: a `POLICY` transformation implementation is refused with `OPERATION_NOT_SUPPORTED`. The check is on the screen: set it, save, reopen the config, and it reads `TRANSFORMATION` again. {% endhint %} ## Source types `SYNCH_SRC` holds one of five values. With the label each one carries on the form: | Value | Label | Reads | Required extra fields | | ----------------- | --------------------------- | --------------------------------------- | ------------------------------------------------------------------------------ | | `CSV` | CSV file | An uploaded file | `CSV_SYNC_ID`, `SPLITTER` | | `RDBMS` | RDBMS | `QUERY` over JDBC | `DRIVER`, `CONNECTION_URL`, `SRC_LOGIN_ID`, `SRC_PASSWORD` | | `CONNECTOR_ASYNC` | Connector — Single-Threaded | A managed system, through its connector | `MANAGED_SYS_ID`, `ATTR_NAMES_LOOKUP_SCRIPT_ID`, usually `QUERY` and `BASE_DN` | | `CUSTOM` | Custom Adapter | Whatever your adapter does | `CUSTOM_ADAPTER_SCRIPT_ID` | | `LOG` | LOG file | OpenIAM audit events | Thread count from `synchronization.log.adapter.thread.number`, default `1` | `CONNECTOR_ASYNC` replaced the earlier `CONNECTOR` value in 4.2.2.0, and that release converted every existing row. On a current build no shipped config reads `CONNECTOR`; if you find one that does, it was created by hand or restored from a pre-4.2.2.0 export, and it will not resolve a source adapter. ## Batch, threading and throttling | Property or column | Default | What it sizes | | ----------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SYNCH_CONFIG.RECORD_COUNT_IN_BATCH` | `1000` | Records per part, that is, per RabbitMQ message. This is both the unit of parallelism and the unit of failure. | | `org.openiam.rabbitmq.sync.thread.concurrent.consumers` | `2` | Consumers per node on the synchronization thread queue | | `org.openiam.rabbitmq.sync.thread.concurrent.consumers_max` | `2` | Its maximum | | `org.openiam.rabbitmq.sync.thread.prefetch.count` | `1` | Prefetch on the same queue | | `org.openiam.rabbitmq.provision.queue.bulk.max` | `5` | Consumers on the **bulk provisioning** queue. The file's own comment: *"Special case for provision bulk queue, because it's may overload whole system. This must be used by sync and in any groovy which call provisioning, otherwise it may make down system."* | | `org.openiam.rabbitmq.provision.queue.bulk.concur` | `4` | Its concurrency | | `org.openiam.rabbitmq.provision.queue.bulk.prefetch` | `1` | Its prefetch | | `org.openiam.rabbitmq.workflow.initiate.max` | `5` | Consumers on the workflow-initiate queue. The comment: *"Initiate workflow is heavy operation. We could go out of database connection pool size."* This is the ceiling on `INITIATE_*_WORKFLOW` throughput. | | `synchronization.log.adapter.thread.number` | `1` | Threads for a `LOG` source | Two runtime counters, both held in the shared cache rather than the database, and both worth knowing when a run appears stuck: * **`RUNNING_SYNC`** is a counter per config ID. A start is refused while it is positive, with `SYNC_CONFIG_ALREADY_RUNNING` and the audit failure reason *"Previous synchronization run is not finished yet"*. It goes up when a run starts and down when it finishes, so a run that dies hard leaves it positive and the config unable to start. You do not read the number itself from a screen; what you see instead is the banner `Synchronization is in progress.` above the configuration's form whenever the counter is positive, with a **Reset** button beside it that clears the counter. Clearing it while work is genuinely in flight allows overlapping runs, so confirm the synchronization queues are empty first — the banner says so too. * **`org.openiam.redis.provisioning.counter.name`** names the counter holding the in-progress provisioning count. It is decremented for every synchronization-originated provisioning request as that request finishes, logging `Decremented value of in progress syncs: ` at info — which is the line to watch when a run looks finished but provisioning is still draining. Start low. Raise `RECORD_COUNT_IN_BATCH` only after you have measured a run; large batches improve throughput until a per-record script or a target call becomes the bottleneck, at which point a part can exceed the message-processing limit and fail as a block of a thousand records. ## Related * [Set up a synchronization](/administration-guide/lifecycle/synchronize-and-import-data.md) — the procedure that fills this form in. * [How a synchronization matches and processes a record](/administration-guide/lifecycle/synchronize-and-import-data/synchronization-matching-and-processing.md) — what the match fields and the orphan flag do at run time. * [Schedule an incremental synchronization](/administration-guide/lifecycle/synchronize-and-import-data/incremental-synchronization.md) — **Sync Type**, **Last Update Field** and **Sync Frequency** in use. * [System properties](/administration-guide/reference/system-properties.md) — the `org.openiam.rabbitmq.*` values in the throttling table. *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/reference/synchronization-configuration-fields.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.