PingDirectory

Implementing the server extension

Notification mode relies heavily on the server extension code to process and transmit the change using the required protocol and data formats needed for the client applications.

Create the extension using the Server SDK, which provides the APIs to develop code for any destination endpoint type. The Server SDK’s documentation (Javadoc and examples) is delivered with the Server SDK built-in zip format. The SDK provides all of the necessary classes to extend the functionality of PingDataSync without code changes to the core product. After the server extension is in place, use other third-party libraries to transform the notification to any desired output format.

Consider the following when implementing the extension:

Use the manage-extension tool

Use the manage-extension tool in the bin directory or bat directory (Windows) to install or update the extension. For more information, see Managing Server SDK extensions..

Review the Server SDK package

Review Server SDK documentation and examples before building and deploying a Java or Groovy extension.

Connection and protocol logic

The Server SDK extension must manage the notification connection and protocol logic to the client applications.

Implementing extensions

Test the create, delete, and modify methods for each entry type. Update the configuration as needed. Finally, package the extensions for deployment. Logging levels can be increased to include more details.

Use the SyncOperation type

The SyncOperation class encapsulates everything to do with a given change. Objects of this type are used in all of the synchronization SDK extensions. See the Server SDK Javadoc for the SyncOperation class for information on the full set of methods.

Use the EndpointException type

The Sync Destination type offers an exception type called EndpointException to extend a standard Java exception and provide custom exceptions. There is also logic to handle Lightweight Directory Access Protocol (LDAP) exceptions, using the LDAP SDK.

About the PostStep result codes

The EndpointException class uses PostStep result codes that are returned in the server extension:

  • retry_operation_limited – Retry a failed attempt up to the limit set by max_operation_attempts.

  • retry_operation_unlimited – Retry the operation an unlimited number of times until a success, abort, or retried_operation_limited. This should only be used when the destination endpoint is unavailable.

  • abort_operation – Abort the current operation without any additional processing.

Use the ServerContext class for logging

The ServerContext class provides several logging methods that can be used to generate log messages and/or alerts from the scripted layer: logMessage(), sendAlert(), debugCaught(), debugError(), debugInfo(), debugThrown(), debugVerbose(), and debugWarning(). These methods are described in the Server SDK API Javadocs. Logging related to an individual SyncOperation should be done with the SyncOperation#logInfo and SyncOperation#logError methods.

Diagnosing script errors

When a Groovy extension does not behave as expected, first look in the error log for stack traces. If classLoader errors are present, the script could be in the wrong location or might not have the correct package. Groovy checks for errors at runtime. Business logic errors must be systematically found by testing each operation. Make sure logger levels are set high enough to debug.