> 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/connector-configuration/rexx.md).

# Rexx connector

This page describes how to use OpenIAM Rexx Connector

The Rexx connector integrates OpenIAM with the **Rexx HR** system. It synchronizes users **from** Rexx to OpenIAM, and exports user data **to** Rexx as a CSV file delivered on a schedule.

| Operation                            | Supported                                                                 |
| ------------------------------------ | ------------------------------------------------------------------------- |
| Import / synchronize users from Rexx | ✅                                                                         |
| Export users to Rexx (batched CSV)   | ✅                                                                         |
| Test connection                      | ✅                                                                         |
| Delete propagation to Rexx           | Configurable — off by default (`org.openiam.connector.rexx.delete=false`) |

## Use cases

* Using **Rexx HR as an authoritative source** — importing employees into OpenIAM.
* **Exporting identity data back to Rexx** in its expected CSV format, on an hourly batch schedule.

## Versions and compatibility

The end application is **Rexx HR**. The connector does not call a record-at-a-time API: it writes the users it is given to a CSV file and POSTs that file to Rexx's interface on a timer, so there is no API version to match — what matters is the interface IDs Rexx issues you.

<table><thead><tr><th width="160">Property</th><th>Value</th></tr></thead><tbody><tr><td><strong>Platform</strong></td><td>Rexx HR</td></tr><tr><td><strong>Interface</strong></td><td>HTTPS, with the export delivered as a <code>text/csv</code> upload</td></tr><tr><td><strong>Host</strong></td><td>The managed system's URL</td></tr><tr><td><strong>Authentication</strong></td><td>A Rexx API token</td></tr><tr><td><strong>Addressing</strong></td><td>Numeric interface IDs for the import, export and test APIs, set on the managed system</td></tr></tbody></table>

{% hint style="danger" %}
**Provisioning to Rexx is not immediate, and nothing in OpenIAM shows that it is pending.** A save appends a row to the export file; a scheduled job sends the file separately, every hour as shipped. The operation is reported successful as soon as the row is written, so a user can exist in OpenIAM, show as provisioned, and not be in Rexx for up to an hour. Allow for that when planning a go-live or testing a policy map, and see `org.openiam.rexx.send.rate` below if the interval needs to change.
{% endhint %}

## Prerequisites

* A Rexx **API authentication token**.
* The numeric **interface IDs** for the test, export, and import APIs (from your Rexx configuration).
* Network access from the connector host to the Rexx API host (HTTPS).

## Installing the connector

### Kubernetes

Enable the connector in your deployment configuration; no separate installation is required.

### RPM

Use the connector service unit (`openiam-connector@rexx-connector-rabbitmq`) or run the connector JAR — see [Connectors via RPM](/installation/rpm/rpm-single-node/add-a-connector.md).

## Starting, stopping, and restarting

<table><thead><tr><th width="172">Deployment</th><th>Commands</th></tr></thead><tbody><tr><td>RPM (systemd)</td><td><code>systemctl start|stop|restart openiam-connector@rexx-connector-rabbitmq</code></td></tr><tr><td>Kubernetes</td><td><code>kubectl rollout restart</code> the connector deployment.</td></tr></tbody></table>

## Command-line parameters and properties

The connector is a Spring Boot application. Its defaults ship inside the jar, and you override them in either of two places:

* **An external property file**, read at `${confpath}/conf/properties/rexx-connector-rabbitmq.properties`. The file is optional, and `confpath` is itself a system property, set with `-Dconfpath=/data/openiam/`.
* **Directly on the command line**, as `-D` arguments, which win over the file.

{% code overflow="wrap" %}

```bash
java -Dconfpath=/data/openiam/ -Dlogging.level.root=INFO -Dorg.openiam.connector.queue=REXX_Connector_1_Request -jar rexx-connector-rabbitmq.jar
```

{% endcode %}

| Property                            | Default                    | Purpose                                                                                                                     |
| ----------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `org.openiam.connector.queue`       | `REXX_Connector_1_Request` | Must match the connector record in OpenIAM.                                                                                 |
| `org.openiam.rexx.send.rate`        | `3600000`                  | Interval (ms) of the scheduled batch send to Rexx — saved changes are queued and pushed on this schedule (default: hourly). |
| `org.openiam.connector.rexx.delete` | `false`                    | When `false`, delete operations are suppressed during save processing; set `true` to allow deletions to propagate to Rexx.  |

| Property                            | Default   | Purpose                                                                              |
| ----------------------------------- | --------- | ------------------------------------------------------------------------------------ |
| `org.openiam.rexx.send.rate`        | `3600000` | How often, in milliseconds, the accumulated CSV is sent to Rexx. One hour as shipped |
| `org.openiam.connector.rexx.delete` | `false`   | Whether the CSV file is deleted after it has been sent                               |

{% hint style="warning" %}
**The export file holds user data and is not deleted by default.** Each export is written to `/tmp/Users_Export<managedSystemId>.csv` on the connector host, and `org.openiam.connector.rexx.delete` is `false` as shipped — so the file stays there after it has been sent, and the next export appends to it. On a host where `/tmp` is not cleared between reboots this accumulates indefinitely. Set the property to `true`, or make sure the directory is covered by whatever handles personal data on that host.
{% endhint %}

The connection details themselves are **not** set here — they are managed system parameters, covered under [Configuring the managed system](#configuring-the-managed-system).

## Verifying the connector is running

{% stepper %}
{% step %}
In the Webconsole, open the managed system — the **Running connector status** indicator must be green.
{% endstep %}

{% step %}
Click **Test Connection** — it must return success (uses the **Test API Id** interface).
{% endstep %}

{% step %}
In the RabbitMQ management console, confirm the `REXX_Connector_1_Request` queue exists and has a consumer.
{% endstep %}

{% step %}
After provisioning changes, check `/tmp/Users_Export.csv` on the connector host and confirm the batch is delivered on the next send cycle.
{% endstep %}
{% endstepper %}

## Troubleshooting

| Symptom                                                                       | Likely cause                      | Resolution                                                                                                                             |
| ----------------------------------------------------------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Changes don't appear in Rexx immediately                                      | Batched delivery                  | Expected — exports are sent hourly (or when the CSV header changes). Adjust `org.openiam.rexx.send.rate` if needed.                    |
| Deletions never reach Rexx                                                    | Delete propagation off by default | Set `org.openiam.connector.rexx.delete=true` and restart the connector.                                                                |
| Duplicate or stale rows in the export                                         | Unique Attribute misconfigured    | The **Unique Attribute** must identify each user uniquely — rows are replaced by matching it.                                          |
| Test connection fails                                                         | Wrong token or Test API Id        | Verify the Password (token) and the numeric interface IDs.                                                                             |
| Delete, suspend, resume or password reset reports success but nothing changes | Those operations are stubs        | Delete, suspend, resume, password reset and group create/delete each return `SUCCESS` without calling rexx. Create and update do work. |

See also: [general connector troubleshooting](/connector-configuration/4-troubleshootingconnector.md) and the [connector error-code reference](/connector-configuration/4-troubleshootingconnector.md#connector-error-codes).

## Registering the connector in OpenIAM

Register the connector under **Provisioning → Connectors** and attach it to the managed system — see [Registering the connector](/administration-guide/lifecycle/connectors-and-managed-systems.md).

## Configuring the managed system

Go to Webconsole → **Provisioning → Managed System → Rexx Managed system** and configure the fields for your environment:

<table><thead><tr><th width="169">Field</th><th>Value</th></tr></thead><tbody><tr><td>Host</td><td>The Rexx API host.</td></tr><tr><td>Password</td><td>The authentication token you have for the Rexx API.</td></tr><tr><td>Test API Id</td><td>The numeric interface ID used for test calls.</td></tr><tr><td>Export API Id</td><td>The numeric interface ID used for exporting users to Rexx.</td></tr><tr><td>Import API Id</td><td>The numeric interface ID used for importing users from Rexx.</td></tr><tr><td>Unique Attribute</td><td>The name of the Rexx attribute that must be unique for every user.</td></tr></tbody></table>

## Attribute mapping and policy map

Provisioning to Rexx is performed according to the Rexx system requirement: OpenIAM sends user data to Rexx in a **CSV file** whose header consists of the attribute names in the **policy map** for the Rexx managed system. Adjust the policy map to control which attributes are exported.

## Reconciliation and synchronization

The import API supplies Rexx users as source records — configure a sync against the managed system as described in [Configuring synchronization](/administration-guide/lifecycle/synchronize-and-import-data.md).

### How the CSV export works

During provisioning, every user creates a new row in the file `/tmp/Users_Export.csv`. If information is written for a user who already has an entry in the file (recognized by the **Unique Attribute**), the old row is deleted and a new one is added.

The file is sent to the Rexx HR system in two cases:

* **Every hour** (the `org.openiam.rexx.send.rate` schedule), or
* When the **header of the CSV file changes** — i.e., the policy map was changed or the order of attributes changed.


---

# 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/connector-configuration/rexx.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.