Observability

The Campaign client implements an observer mechanism that you can use to hook into what's hapenning internally.

An Observer is an object which has one or several callback methods which will be called at certain particular points in the SDK

SOAP calls

It is possible to observe the SOAP calls that are performed by the SDK. The following callbacks are called whenever a SOAP call is made. They can observe the SOAP calls but are not supposed to modify any of the parameters

onSOAPCall (soapCall, safeCallData)
onSOAPCallSuccess (soapCall, safeCallResponse) {}
onSOAPCallFailure (soapCall, exception) {}

The soapCall parameter is the SOAP call which is being observed. In the onSOAPCall callback, the SOAP call has not been executed yet.

The safeCallData and safeCallResponse represent the text XML of the SOAP request and response, but in which all session and security tokens have been replaced with "***" string. Hence the name "safe". You should use those parameters for any logging purpose to avoid leaking credentials.

The soapCall parameter is a SoapMethodCall object which describes the SOAP call. It has the following public attributes.

urn is the SOAP URN which corresponds to the Campaign schema id. For instance "xtk:session"
methodName is the name of the method to call. For instance "Logon"
internal is true or false, depending if the SOAP call is an internal SOAP call performed by the framework itself, or if it's a SOAP call issued by a SDK user
request is a literal corresponding to the HTTP request. It's compatible with the transport protocol. It may be undefined if the SOAP call has need been completely built
response is a string containing the XML result of the SOAP call if the call was successful. It may be undefined if the call was not executed yet or if the call failed

HTTP calls

For HTTP calls (such as JSP, JSSP...). Note that despite SOAP calls are also HTTP calls, the following callbacks will not be called for SOAP calls. These callbacks are not supposed to modify any of the parameters

onHTTPCall (request, safeCallData)
onHTTPCallSuccess (request, safeCallResponse) {}
onHTTPCallFailure (request, exception) {}

The request parameter is the HTTP request (as defined in the transport protocol above)

Logging all SOAP calls

SOAP calls can be logged by setting the traceAPICalls attribute on the client at any time. For security reasons, the security and session tokens values will be replaced by "***" to avoid leaking them

client.traceAPICalls(true);

This is an example of the logs

SOAP//request xtk:session#GetOption <SOAP-ENV:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns="http://xml.apache.org/xml-soap">
<SOAP-ENV:Header>
<Cookie>__sessiontoken=***</Cookie>
<X-Security-Token>***</X-Security-Token>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<m:GetOption xmlns:m="urn:xtk:session" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<sessiontoken xsi:type="xsd:string">***</sessiontoken>
<name xsi:type="xsd:string">XtkDatabaseId</name>
</m:GetOption>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

SOAP//response xtk:session#GetOption <?xml version='1.0'?>
<SOAP-ENV:Envelope xmlns:xsd='http://www.w3.org/2001/XMLSchema'
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
xmlns:ns='urn:xtk:session'
xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'>
<SOAP-ENV:Body>
<GetOptionResponse xmlns='urn:xtk:session' SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'>
<pstrValue xsi:type='xsd:string'>uFE80000000000000F1FA913DD7CC7C4804BA419F</pstrValue>
<pbtType xsi:type='xsd:byte'>6</pbtType>
</GetOptionResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Observability events

In version 1.1.7, the observer interface is extended to listen for internal events of the SDK. The event function of the observer, if it exist will be call for each SDK event with 2 parameters: the event itself, and for some events, a parent event. For instance a SOAP response event will have the SOAP request for a parent event.

client.registerObserver({
    event: (event, parentEvent) => { ... },
});

The following events are available

Event name	Comment / Description
SDK//logon	A client logs on
SDK//logoff	A client logs off
CACHE//stats	Regularly sends stats about internal caches
SOAP//request	The SDK executes a SOAP request
SOAP//response	The SDK processes the successful response of a SOAP request
SOAP//failure	A SOAP request failed
HTTP//request	The SDK executes an HTTP request
HTTP//response	The SDK processes the successful response of an HTTP request
HTTP//failure	An HTTP request failed
CACHE_REFRESHER//start	A cache auto-refresher starts
CACHE_REFRESHER//stop	A cache auto-refresher stops
CACHE_REFRESHER//tick	A cache auto-refresh occurs
CACHE_REFRESHER//loggedOff	The cache auto-refresh was triggered whereas the client was logged of
CACHE_REFRESHER//error	The cache auto-refresh failed. Auto-refresh will continue.
CACHE_REFRESHER//abort	The cache auto-refresh failed because the server does not support it. Auto-refresh will stop.
CACHE_REFRESHER//response	The server responded to an auto-refresh request

Method interception

In version 1.1.17 of the SDK, it's possible to use the observer mechanism to intercept SOAP calls, modify parameters before the call is made, or modify the response before it's returned to the caller.

Some SOAP calls are not intercepted: internal SOAP calls performed by the SDK itself (for instance to get schemas) are not intercepted. Logon and Logoff methods are not intercepted either.

The beforeSoapCall and afterSoapCall methods can be used. They will be passed the following parameters