LCA Hooks

A hook determines when an object receives an event action during the life cycle (for example: before saving).

Life Cycle Hooks

Life Cycle Actions (LCA) hooks in Reltio allow you to define custom logic to be executed at specific points during the life cycle of an object, such as before saving or after deletion. These hooks provide a flexible framework for implementing custom tasks and enhancing data management processes. By configuring hooks, you can ensure specific actions are taken automatically based on events, improving the automation and consistency of your data workflows. For more details on LCA, see topic Customize data tasks with LCAs

Every hook method receives the following two arguments:

An instance of the iReltioAPI (for sending REST requests to the API)
One of the implementations of ILifeCycleData (for processing passed data)

Life Cycle Action Hooks

Reltio supports the following LCA hooks:

rawDataBeforeCleanse
rawDataAfterCleanse
beforeOverride
afterOverrideBeforeCleanse
beforeSave
afterSave
beforeUpdate
afterUpdateBeforeCleanse
beforeDelete
afterDelete
beforeMerge
afterMerge
beforeUnmerge
afterUnmerge
potentialMatchesFound
beforeNotAMatchSet
afterNotAMatchSet
beforeNotAMatchReset
beforeMarkAsMatch
afterNotAMatchReset
afterMarkAsMatch
beforeReferenceAttributeAdded
afterReferenceAttributeAdded
beforeReferenceAttributeChanged
afterReferenceAttributeChanged
beforeReferenceAttributeRemoved
afterReferenceAttributeRemoved

Note: During validation, the beforeSave hook is called with one of the following ActionType as the parameter.

CREATE
UPDATE
MERGE
SPLIT
VALIDATE
RECLEANSE
CREATE

Warning:

The beforeSave hook can run during validation or preview flows (for example, ActionType=VALIDATE). In these cases, LCAs execute before validation completes. If an LCA performs write operations, such as _update, /ignore, or delete, those writes are committed independently. These writes are not rolled back if a Data Validation Function (DVF) fails or the user clicks Cancel. As a result, changes can persist even when the save operation does not complete.

For example, during UI validation, when beforeSave(ActionType=VALIDATE) runs, if an LCA invokes _update or /ignore, the change may still persist even when DVF fails and the user cancels the operation.

To avoid this issue, do not perform write operations in beforeSave during validation or preview; run them only during the actual save operation.

Entity-specific Hooks

These hooks are only applicable to entities and their functionality is explained in the following steps:

The POST/entities API endpoint receives a list of entities to override. The entities are passed to the rawDataBeforeCleanse hook.
The Reltio API cleanses all the entities and then the second hook, rawDataAfterCleanse, is triggered.
The Reltio API searches for matches (by auto rules or by crosswalks). If any matches are found, the beforeOverride hook, is triggered. The Action Handler receives the following objects:
- Raw data that came from the client
- Content of the object to be overridden
After the override, the afterOverrideBeforeCleanse hook is triggered.
The results are cleansed and then the beforeSave hook is triggered.
Reltio API saves the modified (or created, if there were no matches to override) object. After the object is saved into Cassandra, the afterSave hook is triggered. This hook cannot make any changes to the object and also cannot cancel the operation.

All Object Hooks

These hooks are applicable for entities, graphs, interactions, and groups.

Changing Object

Perform the following steps to change an object:

After any change is made to the content of an object (such as attribute, role, tag, crosswalk added/modified/removed, and so on), the Reltio API loads the object. Before the object is modified, the beforeUpdate hook is triggered.
After the object is modified, the afterUpdateBeforeCleanse hook is triggered.
The modified object is cleansed and the beforeSave hook is triggered.
The Reltio API saves the object into Cassandra and runs the afterSave hook.

Deleting Object

When an object is deleted, the beforeDelete and afterDelete hooks are triggered.

Note: These hooks are not triggered when the Reltio API deletes the loser object during a merge operation.

Merging Objects

When several objects are merged, the beforeMerge and afterMerge hooks are triggered. The Reltio API cleanses the results of the merge and then saves the result to Cassandra. Appropriate hooks (afterUpdateBeforeCleanse, beforeSave, and afterSave) are triggered.

Unmerging Object

If an object is unmerged, the beforeUnmerge hook is triggered, followed by the beforeNotAMatchSet and afterNotAMatchSet hooks. The beforeSave and afterSave hooks are executed for both the unmerged objects, followed by the afterUnmerge hook. The afterUnmerge hook receives both the objects as a result of the unmerge operation.

Potential Matches Found

If potential matches are found for an object, the potentialMatchesFound hook is triggered.

Mark as Match, Mark as Not a Match

If a client is asked to set Not a Match, remove Not a Match, or set Mark as Match, the following hooks can be triggered:

beforeNotAMatchSet
afterNotAMatchSet
beforeNotAMatchReset
afterNotAMatchReset
beforeMarkAsMatch
afterMarkAsMatch
beforeUnmarkAsMatch
afterUnmarkAsMatch

Warning: All of these hooks can cancel the operation but cannot make any changes to the content of the objects.

Reference Attributes Changes

If reference attributes are changed, the following hooks are triggered:

beforeReferenceAttributeAdded
afterReferenceAttributeAdded
beforeReferenceAttributeChanged
afterReferenceAttributeChanged
beforeReferenceAttributeRemoved
afterReferenceAttributeRemoved

These hooks are triggered only for Relationship reference attributes, not for referenced entity reference attributes.

Important: Reference attribute hooks execute in relationship scope. Parent entity attributes are not available in reference-hook filters or hook code.

Use the following based on the type of validation required:

If you need entity-level context, enforce the rule in an entity hook such as beforeSave or validate.
If the rule is relation-centric, store the required fields on the relation and validate them using a relation hook or a data validation framework (DVF).

Note: When a filter references a field outside the relation scope, the system does not return an error. The condition is ignored, and the hook does not run.

Unify and manage your data