Overview

Starting with version 2.14.0, User Sync provides a public Java API that allows customers to synchronize single users with configured connectors. This API can be integrated into your own products to enable seamless user data synchronization.

Package

The API is located in the following package:

package de.resolution.usersync.external.api.service;

Interface: ExternalUserSyncService

The ExternalUserSyncService interface defines operations for synchronizing user data with external systems or connectors. It provides a method to update or synchronize a single user's information based on an identifier and a specific connector.

Method: syncSingleUser

Synchronizes a single user's information with an external system identified by the connector UID. This method ensures that the user data is updated or synchronized based on the provided identifier.

ExternalSyncSingleUserResult syncSingleUser(@Nonnull String identifier,
                                            @Nonnull String connectorUID)
    throws ConnectorNotAvailableException, 
           ConnectorFactoryNotAvailableException, 
           ConfigurationFailedException, 
           ConnectorNotFoundException;

Parameters

• identifier (@Nonnull String): The unique identifier of the user to be synchronized. This identifier must be non-null and is typically a username or user ID that is known both to the calling system and the external system.

• connectorUID (@Nonnull String): The unique identifier of the connector to use for synchronization. This UID must correspond to a connector that is configured and available in the system.

Returns

• ExternalSyncSingleUserResult: An object representing the result of the synchronization operation, including success or failure information and any relevant details about the process.

Exceptions

• ConnectorNotAvailableException: Thrown if the specified connector is not available at the time of the request, possibly due to network issues or connector downtime.

• ConnectorFactoryNotAvailableException: Thrown if the system is unable to instantiate the connector due to configuration or operational issues.

• ConfigurationFailedException: Thrown if there is a problem with the configuration that prevents the synchronization from proceeding.

• ConnectorNotFoundException: Thrown if the specified connector UID does not match any known connectors in the system, indicating a possible misconfiguration or typo.

Usage Example

The ExternalUserSyncService can be used in a ScriptRunner script as shown below:

import com.onresolve.scriptrunner.runner.customisers.WithPlugin;
import com.onresolve.scriptrunner.runner.customisers.PluginModule;

@WithPlugin("de.resolution.usersync.jira")
import de.resolution.usersync.external.api.service.ExternalUserSyncService;

@PluginModule
ExternalUserSyncService externalUserSyncService;

externalUserSyncService.syncSingleUser("<userId>", "<connectorId>");

Replace "<userId>" and "<connectorId>" with the actual user ID and connector ID you wish to use for synchronization.

Exception Handling

When calling the syncSingleUser method, ensure you handle the possible exceptions appropriately to maintain robust and error-resistant code. For example:

try {
    ExternalSyncSingleUserResult result = externalUserSyncService.syncSingleUser("<userId>", "<connectorId>");
    // Process the result
} catch (ConnectorNotAvailableException | 
         ConnectorFactoryNotAvailableException | 
         ConfigurationFailedException | 
         ConnectorNotFoundException e) {
    // Handle the exception
}