New Error Handling in the Open-Xchange Connector for UCS

The latest version of the Open-Xchange Connector for UCS changes the way synchronization errors are handled—a feature many of our customers have been waiting for.

Since this is a fundamental change, the new error handling is optional at first. You can turn it on in the app settings. Still, a few of the improvements are already active for everyone.

The Open-Xchange Connector (or OX Connector for short) provisions the information managed in Univention Nubus—such as users, their email addresses, group memberships, and permissions—to the Open-Xchange (OX) groupware. This ensures that as soon as an account is created in Nubus, users can immediately start working with OX, and any changes to their permissions are applied promptly in OX.

The OX Connector works on an event-based model. In other words, it receives individual changes as “events” from a queue and processes them one by one into OX. Occasionally, errors can occur during this process—for example, due to misconfigurations or inconsistent data. Up to now, the connector has handled such cases by pausing briefly and then retrying the failed change. Once the issue was fixed, the remaining events in the queue were processed.

The downside of this approach: when an error is difficult to resolve, events pile up in the queue. In environments with a high volume of changes—such as during migrations—a single problematic account could cause delays for many others.

With the new, currently optional error handling, the connector continues to process subsequent changes even if one of them fails. This way, a single issue no longer creates a bottleneck for updates to many accounts.

• The scope of information synchronized between UCS and OX does not change. The attributes in UDM also remain unchanged.
• For Kubernetes deployments, there are no adjustments for now: the OX Connector for Kubernetes will still stop at each error.

Even without enabling the new error handling, the current version introduces fundamental changes:

• Replacement of JSON files: The previously used JSON files are now written directly into a local SQLite database before being processed. JSON files can therefore no longer be used for debugging.
• New command-line tool: With univention-ox-connector-task-management, the current processing status and the “to-be-synchronized” changes can be viewed and managed. This tool replaces the previous use of JSON files.
• Resynchronization of objects: Objects can now be resynchronized using the new tool. The earlier Bash snippet from the documentation is no longer required.
• Status of the last synchronization: The database stores the state of the last successful synchronization, which can also be queried via the command-line tool.

When the new error handling is enabled, the connector’s behavior in case of errors changes significantly:

• Stop on critical errors: The connector now only stops for errors that are likely to trigger a large number of subsequent errors. Currently, this includes cases where the OX APIs are unavailable or when creating a new context in OX fails. In such cases, the connector automatically retries synchronization so that it resumes on its own once the API is available again.
• “Morgue” storage for individual errors: All other errors are stored in a separate database table (“morgue”), along with an error message or traceback. The connector then immediately continues processing the next change.
• No automatic retry: Entries in the “morgue” are not retried automatically. However, they are removed as soon as the same object is modified again in UDM and successfully synchronized with OX.
• Manual control available: With univention-ox-connector-task-management, “morgue” entries can be viewed, deleted, or released for reprocessing.

The new features are not activated automatically for now. Univention is actively supporting existing customers during the transition — if you are interested in using them, we recommend contacting our Support or Professional Services team. Alternatively, you can find more details about the changes in the documentation. With a future release, the new error handling will become the default behavior.