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. 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 customizing data tasks with LCA, see topic Customize data tasks with LCAs

You can trigger LCAs against an external service, such as an AWS Lambda function, a Google Cloud function, an Azure function, or a dedicated LCA HTTP endpoint. You configure which hooks trigger which actions on the following object types:

• Entity types - most profile (entity) LCA hooks are configured here.
• Relationship types - the same hook names apply as for entities, except that the validate hook applies when Reltio processes relations (links between entities).
• Change-request types - only the afterDCRSave hook applies to Data Change Requests (DCRs). Other hooks are not used for DCR objects in the same way.

These arguments apply to Java-based LCA implementations. If you are implementing an LCA in a non-Java runtime, such as Python or Node.js, you are responsible for parsing the request and formatting the response yourself. For more information, see Non-Java LCAs in Cloud Functions.

Configuration Patterns

You can configure hook actions in two ways.

Simple configuration - applies the same actions every time a hook fires. Hooks are keys, and values are ordered lists of actions to run in sequence. The following example shows hook actions in an entity type configuration:.

{
  "beforeSave": ["MyBeforeSaveAction", "Lambda/BinaryJSON/MyLambda"],
  "afterMerge": ["NotifyDownstreamAfterMerge"]
}

Conditional configuration - runs actions only when a filter condition evaluates to true Each item contains an actions list and a filter condition that must evaluate to true for the actions to run. The following example runs an action only when the request originates from the Reltio Console:

{
  "beforeSave": [
    {
      "actions": ["UiOnlyEnrichment"],
      "filter": "equals(clientType, 'Reltio UI')"
    }
  ]
}

LCA Payload Models

Reltio sends different payload shapes to your LCA endpoint depending on the hook and operation type.

• Full business object payload - used for most save, update, cleanse, merge, and validate-style hooks. Your service receives the full business object, including attributes, crosswalks, and other metadata. Where supported, your service can return a modified object that the platform uses for subsequent processing or persistence.
• Identifier- and context-only payload - used frequently for matching hooks and potential match events. Typical payload contents include entity URIs, candidate match URIs, pairwise match URIs, tenant and type information, and an access token for downstream Reltio API calls. Your service can call Reltio APIs using the provided token if you need to load full records.

When LCAs Run

An LCA executes only when both of the following are true:

1. The hook has at least one action configured for the relevant entity type, relationship type, or DCR type (for afterDCRSave).
2. The API request does not explicitly disable LCA execution, where that option exists.

Life Cycle Action Hooks

Entity-specific Hooks

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

1. The POST/entities API endpoint receives a list of entities to override. The entities are passed to the rawDataBeforeCleanse hook. Typical use cases include fixing data formats and encodings, rejecting clearly invalid payloads, and pre-enriching attributes that the cleanse step will depend on.
2. The Reltio API cleanses all the entities and then the second hook, rawDataAfterCleanse, is triggered. Typical use cases include validating cleanse results and mapping cleanse output to internal or downstream conventions.
3. 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
   Typical use cases include providing custom survivorship hints, performing pre-merge enrichment, and flagging or vetoing conflicting data conditions.
4. After the override, the afterOverrideBeforeCleanse hook is triggered. Typical use cases include validating the combined contributor view before cleanse and preparing attributes for post-override cleansing.
5. Immediately before the beforeSave hook, the beforeGeneration hook is triggered. Typical use cases include adding or modifying crosswalks before auto-generation runs.
6. Reltio performs attribute auto-generation (for example, sequence or ID generation on autoGenerated attributes), and the afterGeneration hook is triggered. Typical use cases include inspecting or adjusting auto-generated values.
7. After the auto-generation, the beforeSave hook is triggered. Typical use cases include data validation and business-rule enforcement, attribute and crosswalk enrichment, and invoking external masters or reference systems.
8. 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. Typical use cases include publishing events, invoking webhooks, and updating downstream MDM, CRM, or analytics systems.

All Object Hooks

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

Changing Object

Perform the following steps to change an object:

1. 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. Typical use cases include deriving or auto-populating attributes and enforcing business rules before the change is applied.
2. After the object is modified, the afterUpdateBeforeCleanse hook is triggered. Typical use cases include adjusting values that should feed into cleanse and validating the merged view of the update before cleansing.
3. The modified object is cleansed. Immediately before the beforeSave hook, the beforeGeneration hook is triggered, Reltio performs attribute auto-generation, and the afterGeneration hook is triggered. The beforeSave hook is then triggered.
4. The Reltio API saves the object into Cassandra and runs the afterSave hook.

Deleting Object

Typical use cases for beforeDelete include compliance checks (for example, legal hold), blocking deletes that violate policy or dependents, and pre-delete approval workflows. Typical use cases for afterDelete include emitting tombstone or deletion events, cleaning up references in external systems, and archiving or logging delete metadata.

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.

Typical use cases for beforeMerge include setting or correcting winner attributes, logging merge intent and rationale, and integrating with an external merge-approval or governance process. Typical use cases for afterMerge include notifying downstream MDM, CRM, or analytics systems that two identities have been merged, and updating master records or operational data stores.

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.

Typical use cases for beforeUnmerge include capturing audit snapshots and validating eligibility for split according to business rules. Typical use cases for afterUnmerge include updating external registries or downstream systems and emitting split-completed or unmerge events.

Potential Matches Found

If potential matches are found for an object, the potentialMatchesFound hook is triggered. Typical use cases include routing candidate pairs to a data steward queue or workflow, and scoring or filtering candidates in an external decisioning system.

Potential Matches Removed

If potential matches are removed for an object, for example due to profile changes or match graph evolution, the potentialMatchesRemoved hook is triggered. Typical use cases include closing tasks in external workflow systems and cleaning up downstream potential-match queues.

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

Typical use cases for the beforeNotAMatchSet and beforeMarkAsMatch hooks include enforcing policy or approval checks before the decision is recorded. Typical use cases for the corresponding after* hooks include notifications, audit logging, syncing decisions to external match registries, and updating golden records or downstream master systems. The beforeNotAMatchReset, afterNotAMatchReset, beforeUnmarkAsMatch, and afterUnmarkAsMatch hooks are typically used to align match overrides with external registries and to track or report overrides that may re-open candidates.

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.

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

Data Change Request Hook

The afterDCRSave hook runs after a Data Change Request (DCR) is saved, whether created or updated in storage. This is distinct from the standard entity afterSave hook. You configure this hook on the change-request type, not on a standard entity type.

Typical use cases include kicking off approval or review workflows and synchronizing DCR metadata with ticketing or case-management systems.

Validation Hook

The validate hook provides a dedicated hook for validation-only LCAs that return structured validation errors. It is typically used when your integration pattern is built explicitly around a validation contract.

This hook runs only when something in your environment explicitly invokes LCAs under the validate hook name, for example custom tools or APIs you enable. It is not invoked automatically on every standard create, update, or delete operation.

Standalone LCA Execution (What-If Scenarios)

Some APIs allow you to execute a configured LCA action against a supplied payload for a chosen hook, commonly beforeSave, without persisting data.

Typical uses include what-if validation from integration layers or the UI, testing rule behavior before committing changes, and external systems performing pre-checks using Reltio rules.

Design Guidelines for Customer Implementations

1. Keep LCAs fast. LCAs frequently run synchronously on the request's critical path. Long-running actions increase API latency and raise the risk of timeouts and partial failures.
2. Prefer idempotent after* logic. Retries can cause after* hooks to be invoked more than once for the same business event. Design after* actions to tolerate duplicates where possible.
3. Use before* hooks to block bad data. Return structured errors, as defined by your LCA contract, when policy requires stopping an operation. Exact behavior can depend on hook type and Reltio version; refer to your official product documentation for details.
4. Match the hook to your intent. Do not rely on afterSave to fix data that you intended to persist differently. Use beforeSave or earlier hooks, such as rawDataBeforeCleanse or beforeUpdate, when the platform allows mutation of the working object.
5. Test with realistic volumes. Batch APIs can send many objects in a single LCA call. Ensure your service handles batching correctly, observes documented ordering guarantees, and scales for your expected throughput.

Attribute Generation Hooks

The beforeGeneration and afterGeneration hooks bracket the platform's attribute auto-generation step. During this step, Reltio populates values for attributes configured with an autoGenerated generator, such as a sequence or ID generator. Like other hook methods, each receives two arguments, which are an instance of IReltioAPI and an implementation of ILifeCycleObjectData.

For a given save operation, Reltio triggers beforeGeneration, runs the attribute auto-generation, triggers afterGeneration, and then triggers beforeSave.

LifeCycleActionBase provides a default no-op implementation for both hooks. Existing handlers that omit beforeGeneration and afterGeneration keep their current behavior.

Attribute generation runs immediately before beforeSave. A crosswalk that a beforeSave hook action adds to the object misses that generation pass and not receive a generated value. To generate a value for a crosswalk that hook logic adds, add the crosswalk in beforeGeneration instead. For the opt-in generateAttributePerCrosswalk tenant parameter, see Autogenerated IDs for simple and nested attributes.