LCA Framework

The Life Cycle Action (LCA) framework allows you to execute custom tasks on different events in an object's life cycle.

This framework enables you to build and deploy custom logic for creating, updating, deleting, and performing other operations (such as controlling passed data or the prevention of operations). You can apply custom LCA logic to entities and relationships in the Reltio platform.

LCA Service Architecture

The Life Cycle Actions, or LCA, is a standalone service. You can implement the LCA service by creating an LCA Handler and deploying it to AWS.

Note: In LCA, garbage collection works in the same way as in a regular Java application. You do not need to clear the local variable in the block of methods used in the code. Also, you do not need to use the System.gc() method for garbage collection explicitly. For more details, refer to the Oracle documentation.

LCA Service Flow

The following steps explain the LCA service flow:

Before invoking an LCA, the LCA service API serializes an object into JSON and passes it to the LCA service.
As a result, the LCA handler returns the modified entity serialized into JSON. The handler will output special results for the following cases:
- When an object should not be modified
- When the whole operation should be canceled
The LCA service API applies the modified JSON to the object by substituting the object with the result from LCA.
LCAs can be injected before operation (synchronous operation) or after operation (asynchronous operation). If a synchronous operation does not respond within a specified time, the LCA service API cancels the operation, returns and logs a corresponding error message.

Predefined Actions

LCA service provides predefined actions that can be used without registering. This is done using a request on a shared Reltio tenant.

Life Cycle Action Data Access Interface

Depending on the hook type action, a handler gets one of the following objects as input:

ILifeCycleObjectData - contains information about a single object
ILifeCycleMergeData - contains information about a merge winner object and a list of loser objects (as URIs)
ILifeCycleObjectsPairData - contains information about a pair of objects
ILifeCyclePotentialMatchesData - contains a list of potentially matching objects (as URIs)

Interface Diagram

The following diagrams displays the Life Cycle Actions data access interface methods and relationships.

IReltio API Interface

The IReltioAPI interface is used by the action implementation to send requests to the Reltio API. This interface does not require you to specify the full URL (Specify the URI relative to the API URI) of the request or the tenant name. The request is then sent to the Reltio API and the tenant that invoked the Life Cycle Action.

This interface has the following methods:

String get (String URI, Map<String, String> headers)
String post (String URI, String body, Map<String, String> headers)
String put (String URI, String body, Map<String, String> headers)
String delete (String URI, Map<String, String> headers)
String get (String URI, boolean isUriEncoded, Map<String, String> headers)
String delete (String URI, boolean isUriEncoded, Map<String, String> headers)

Note: The body and the return value are strings representing a JSON.

The IReltioAPI interface provides the following methods to log data:

void logError(String message)
void logWarning(String message)
void logInfo(String message)

ILifeCycleAction Interface

Lifecycle Executor

The test framework contains the LifecycleExecutor class that lets you execute Life Cycle Action handlers. It provides the following methods:

String executeAction(ILifeCycleAction handler, LifeCycleHook hook, and string input)
String executeAction(ILifeCycleAction handler, LifeCycleHook hook, IReltioAPI reltioAPI, and string input)

The executeActions method considers the following points:

The instance of a Life Cycle Actions handler under test
The hook that should be executed
The instance of IReltioAPI (optional, could be used when it is necessary to test communication with the API) and
A string with the input JSON

This method returns a Life Cycle Action output JSON string.

IReltioAPI

An instance of IReltioAPI should be passed to the executeAction method when communication with the API is being tested. You can either pass your own mock implementation or use a real implementation that communicates with the API. In the latter case you can pass an instance of the ReltioAPI class using the constructor, ReltioAPI (String environment, String tenant, String token).

Note: The constructor takes the environment URL, tenant ID, and access token as input.

Obtaining JSON Input

The input JSON string used to test a Life Cycle Actions handler can be composed manually.

LCA JSON Input Template

{
  "object": {
    "type": "{{typeURI}}",
    "attributes": {
      "{{Attribute_Values}}"
    },
    "crosswalks": [
      {
        "type": "{{crosswalkURI}}",
        "value": "{{crosswalkValue}}"
      }
    ]
  },
  "tenant": "{{tenantId}}",
  "environment": "http://360.reltio.com/reltio/",
  "token": "{{accessToken}}"
}

LCA JSON Input Sample

{
  "object": {
    "type": "configuration/entityTypes/HCP",
    "attributes": {
      "FirstName": [
        {
          "value": "beforeSave"
        }
      ],
      "LastName": [
        {
          "value": "MultiNestedModifyObjectIntoLCA"
        }
      ]
    },
    "crosswalks": [
      {
        "type": "configuration/sources/HMS",
        "value": "HMS0001"
      }
    ]
  },
  "tenant": "zcdDsdg355Xggf",
  "environment": "http://360.reltio.com/reltio/",
  "token": "xxxx0f4a-xxxx-xxx-xxx-704642bxxxx"
}

Checking JSON Output

Reltio recommends the following two approaches to check the output JSON.

Comparing JSON Strings
The first approach is to use a library to compare two JSON strings by ignoring the representation details. JSONassert is one such library and you can add it to a Maven-based project by adding the following dependency:
```
 <dependency>
                    <groupId>org.skyscreamer</groupId>
                    <artifactId>jsonassert</artifactId>
                    <scope>test</scope>
                    </dependency>
```
Once added, you can compare your JSON strings as follows:
```
JSONAssert.assertEquals(expectedJSONString, actualJSON, strictMode);
```
Checking Particular Fields
Another approach is to use JSON library to parse output JSON string into a map or some JSON representing the object and then check only necessary fields in that object.

Field Example

This is an example of a test for Life Cycle Handler action that appends the string (Appended) to the value of the FirstName attribute.

LifecycleExecutor executor = new LifecycleExecutor();
ILifeCycleAction handler = new FirstNameAppendAction();
String actual = executor.executeAction(handler, LifeCycleHook.beforeSave, "{\"object\": {\"URI\":\"entities/HCP.1\", \"attributes\":{\"FirstName\":[{\"value\":\"John\"}]}}}");
String expected = "{\"object\": {\"URI\":\"entities/HCP.1\", \"attributes\":{\"FirstName\":[{\"value\":\"JohnAppended\"}]}, \"roles\":[], \"tags\":[], \"crosswalks\":[], \"categories\":[]}, \"successful\": true}";
JSONAssert.assertEquals(expected, actual, true);

GCP Support for LCA

For GCP tenants, Cloud Function Support equivalent to Lambda is not available. Therefore, LCA is implemented and deployed into the LCA Service from S3 (S3 JAR based LCA).

How does it work?

The following steps describe the implementation:

Build the JAR file without any dependencies.
Send the JAR file to Reltio for review and deployment. A Reltio engineer will then review and deploy the JAR to S3 and share the S3 path.
Register the JAR file into the LCA Framework using a unique name.
The LCA Service automatically downloads the JAR file(s) and loads the same into the memory for further execution. The S3 bucket only serves as a placeholder to keep the JAR file(s). The JAR file(s) are loaded into the LCA Service and executed.

Accelerate the Value of Data