Log 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, if a service call log is from an Exchange package, we don't know which Exchange package it is from.

Logging convention

In order to address this problem and be able to know which Exchange package a service log record belongs to (with minimum backend and API changes), we can 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()

To support the new logging convention, change it as follows:

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

The Exchange project code should match the project.code defined in 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

All new projects must follow this convention.

For existing projects, follow this convention when upgrading the package.

Usage

When calling third-party services in Groovy service definitions, it is important to record each successful use. Usage statistics are very useful and sometimes required to be tracked for reconciliation and billing purposes. The TxnUpdater class provides a function to record these events as demonstrated below.

The service call should be logged only if:

• A successful response has been received from the service. This can be verified with the HttpResponse.isSuccess convenience function.
• No data errors were reported in the response from the service. Typically, a 400 BAD REQUEST status code is received when there is an issue with the data provided in the request. However, some third-party integration APIs will incorrectly return a 200 status code but still report data errors in the body of the response (for example, 'Invalid SSN'). These need to be identified and the service log skipped in this scenario as data errors do not typically represent a billable event.

For billing purposes, this is important because unsuccessful calls should not be billed. See the following code sample for an example usage scenario.

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
        ...
    }

The inputs to this addServiceCallLog function are:

• svcName: The name of the third-party service. This is not the SOAP Action name but rather a relevant name that clearly identifies the vendor and service being called (for example, '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.