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
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 objectILifeCycleMergeData
- contains information about a merge winner object and a list of loser objects (as URIs)ILifeCycleObjectsPairData
- contains information about a pair of objectsILifeCyclePotentialMatchesData
- 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)
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)
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
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).
Obtaining JSON Input
The input JSON string used to test a Life Cycle Actions handler can be composed manually.
{
"object": {
"type": "{{typeURI}}",
"attributes": {
"{{Attribute_Values}}"
},
"crosswalks": [
{
"type": "{{crosswalkURI}}",
"value": "{{crosswalkValue}}"
}
]
},
"tenant": "{{tenantId}}",
"environment": "http://360.reltio.com/reltio/",
"token": "{{accessToken}}"
}
{
"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
- 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).
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 theJAR
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 theJAR
file(s). TheJAR
file(s) are loaded into the LCA Service and executed.