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 orbat
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 theSyncOperation
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 bymax_operation_attempts
. -
retry_operation_unlimited
– Retry the operation an unlimited number of times until a success, abort, orretried_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()
, anddebugWarning()
. These methods are described in the Server SDK API Javadocs. Logging related to an individualSyncOperation
should be done with theSyncOperation#logInfo
andSyncOperation#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.