Exchange Framework 1.4.0 upgrade guide

Automated response processing

This release introduces a huge step towards automated response processing. Instead of manually coding the response processor to parse and set individual fields in the Server VO, you can now use the @ResponsePath annotation in your Server VO to define where the data is and the response processor will automatically inject values from the raw response into the Server VO.

For example, say you have the raw response shown below:

{
    "id": "a2970744-a97a-44f3-829c-95a8e6cd76c8",
    "statedIp": "1.1.1.1",
    "details": {
        "ruleResults": {
            "score": 80,
            "rulesMatched": 1
        },
        "machineLearning": {
            "mlValue1": {
            "value": 640
            }
        }
    }
}

You can define @ResponsePath as shown below to let the response processor inject values from the response into its properties.

public class MyServerVO extends TifServerVO {

    @ResponsePath('details.machineLearning.mlValue1.value')
    public String machineLearningValue
    
    @ResponsePath('details.ruleResults.score')
    public String score
  
    public String id
    public String statedIp
    
}

If the property name you defined matches the first level JSON field name in the raw response (such as id and statedIp), you don't even need to define @ResponsePath; the response processor will inject the value automatically by naming convention.

This feature supports both XML and JSON responses. In case of an XML response, you just need to define the correct xpath in @ResponsePath.

Better Server VO and Client VO definition

This release intrduces a much more elegant way to define your Server VO and Client VO. Use the @XPath annotation to simplify the definition of Server VO and Client VO.

Prior to this release, you needed to implement the abstract xpath() method to provide the xpath of your VO as shown below.

class MyServerVO extends TifServerVO {
    static final private String XPATH = 'Provider/Product/Result'

    @Override
    public String xpath() {
        return XPATH
    }
}

Starting from this release, you can simply define your xpath value using @XPath.

@XPath('Provider/Product/Result')
class MyServerVO extends TifServerVO {
}

This works the same way for both Server VO and Client VO definition. We've also used the same pattern for the TifServerVO and TifClientVO base classes to define their root xpath using @RootXPath.

Support for Http Audit

In this release, the framework now supports the Http Audit feature. This gives you the ability to record your entire history of requests and responses as txn httpAudit properties for auditing purpose.

For example:

HttpResponse response = new HttpEvent(txn, "ServiceName", logger).execute(request)

To use this feature in your service, typically you define a service parameter as enableHttpAudit, create a HttpEvent object and inject into your TifService if enableHttpAudit is true, as shown below.

boolean httpAuditFlag = svcDef.paramsMap.get("enableHttpAudit")?.toBoolean()
// Create http audit event
HttpEvent httpEvent = httpAuditFlag ? new HttpEvent(txn, PRODUCT, logger) : null
YourService serviceSession = (YourService) new YourService()
    .httpEvent(httpEvent)

We've also enhanced the standard http and SOAP calls, Utils.callHttpPost() and Utils.callSoapService(), to accept and use the HttpEvent object if available.

Here is an example in your API layer to trigger a Http Post call with Http Audit logged.

HttpResponse response = Utils.callHttpPost(endPoint, requestMessage, contextType, logger, true, username, password, httpEvent)

info

We've included the Http Audit feature in Iovation TAF project 1.1 so you can check out how it works in action.

The entire Http Audit implementation will be included in the TPac archetype (v1.3.0), from service definition, getting service parameter, injecting HttpEvent object into the service, passing it through API layer, and making the Http call using the HttpEvent object. So, when your next new TPac project is generated, it will already have this feature available out of the box (building and running correctly from day one).