Logging third party service calls

   Exchange Pre-configured Maestro services.  |   Platform Developer |  All versions   This feature is related to v5.1 and higher.

Background

Currently, Journey Manager provides the following API to log third party service calls:

new TxnUpdater(txn).addServiceCallLog(serviceName, moreInfo, serviceEndpoint).update();

The problem with the existing data is that:

• We don't know if a certain service call log is from an Exchange package or not.
• Furthermore, we don't know if a certain service call log is from which Exchange package.

Logging convention

In order to solve this and be able to know which Exchange package a service log record belongs to, with minimum backend and API changes, we use the moreInfo parameter to provide the Exchange package information in the following format:

EXCHANGE|exchange-project-code|moreInfo

For example, the Mitek TIDEN project has the following code to record service log at the moment:

// record service usage
new TxnUpdater(txn).addServiceCallLog('MitekTidenId Prefill',"EvidenceId: $evidenceId", endPoint).update()

It should be changed to the following to support the new convention:

// record service usage
new TxnUpdater(txn).addServiceCallLog('MitekTidenId Prefill',"EXCHANGE|mitek-tiden|EvidenceId: $evidenceId", endPoint).update()

Please note that the Exchange project code should match the "project.code" defined in the build.properties. For example, in the Mitek TIDEN project, build.properties has the following line:

project.code=mitek-tiden

Hence, mitek-tiden should be used as the Exchange project code in the moreInfo string.

Migration Policy

Any new project needs to follows this convention.

For all existing projects, we need to follow this convention whenever we upgrade the package.

 

More on logging third party service calls

Usage

When utilizing third party services in groovy service definitions it is important to record each successful usage. Usage statistics are very useful and sometimes required to be tracked for reconciliation and billing purposes.

The TxnUpdater provides a function to record these events as demonstrated below.

The service call should be logged only if:

1. A successful response has been received from the service - this can be verified with the convenience function isSuccess() on the HttpResponse object.
2. No data errors were reported in the response from the service. Typically a 400 (BAD REQUEST) response is received when there is an issue with the data provided in the request, however some 3rd integration APIs will incorrectly return a 200 response type but still report data errors in the body of the response (e.g. 'Invalid SSN') - these will need identified and the service log skipped in this scenario as data errors do not typically represent a billable event.

Sample code

import com.avoka.tm.svc.TxnUpdater
import com.avoka.tm.http.GetRequest
import com.avoka.tm.http.HttpResponse
...
try {
	response = new GetRequest(serviceEndpoint).execute()
} catch(Exception e){
	// Log and return
	new EventLogger().setTxn(txn).setMessage(e.getMessage()).logError()
	return result.systemError()
}

if (response?.isDataError() || checkBodyError(response)) {
	return result.dataError(getDataErrorMsg(response))
}

if (response?.isSuccess()) {
	// Add the 3rd Party Service Call Log entry
	new TxnUpdater(txn).addServiceCallLog(serviceName, 'More Info (optional)', serviceEndpoint).update()
	
	// Now process the response
	...
}

Inputs

The inputs to this addServiceLog function are:

• svcName - The name of the third party service - this is not the SOAP Action name but rather relevant name that clearly identifies the vendor and service being called (e.g. FIS - QualiFile)
• info - Any additional details you may want to provide to assist in auditing, this may include key attributes included in the call (optional)
• url - Where the third party provides multiple endpoint URLs for different environments it is important to record this URL as calls to the test environment would be excluded from billing transactions. See also Managing multiple service endpoints and credentials for external service calls.