Configuring a potential overlay workflow

Last updated: May 06, 2025

Configure IBM Match 360 to recognize and quarantine any potential overlay issues in your master data to prevent potentially breaking data changes before they impact your entities.

A potential overlay issue occurs when a record update results in changes that appear to alter the identity of the record, such as a substantially different name, date of birth, or identification number. This type of change can potentially indicate that the record was erroneously overwritten with data from another record, and could improperly alter entity information.

When a record gets updated, the potential overlay workflow compares the updated demographic data with its current value. If key data elements such as name, phone number, gender, or personal identification numbers are very different, the workflow flags that record as having a potential overlay.

When configuring your workflow, you can define the relevant key data elements and the degree of change that result in a potential overlay issue. When a record update occurs that goes beyond the allowed change level, IBM Match 360 locks the record to prevent it from being updated further and creates a potential overlay task.

When a record is locked, there are several restrictions that remain in place until the potential overlay task is completed:

The record cannot be deleted.
Relationships involving the record cannot be created, deleted, or edited.
The record cannot be unlinked from an entity or moved to another entity.
Entities containing a locked record cannot be joined to other entities.
The record cannot be updated by using the IBM Match 360 workspace interface.
Any updates to the record coming from source systems will be acknowledged, but not applied. Instead, these updates will be queued and must be reviewed as part of the remediation task.

From the task inbox, a data steward can remediate each potential overlay issue by reviewing the incoming record updates. During remediation, data stewards must either apply or discard each update that occurred during the locked period, including the initial change that triggered the workflow. By completing the task, the data steward can unlock the record. For more information about working with potential overlay tasks, see Remediating potential overlay issues.

Configuring the workflow

If the potential overlay workflow wasn't configured during initial setup of your IBM Match 360 service instance, you can set one up.

Enable and set up the workflow from the instance settings.
Define a potential overlay workflow type by using the IBM Match 360 API.

Enabling and setting up the workflow

Required permissions: To configure master data workflows, you must be a member of the DataEngineer user group for the IBM Match 360 service.

To enable and set up a new potential overlay workflow:

From the Master data navigation menu, click Instance settings .
Under Workflow configuration, you can see any workflows associated with this service instance.
- Click the linked workflow type name (Potential overlay) to see details of the workflow template, along with any configuration instances of this workflow type.
- Click the linked workflow configuration name to see details of your specific workflow configuration. As part of the potential overlay workflow configuration, you can:
  - Activate or deactivate this workflow.
  - Define what users or groups get assigned potential overlay tasks.
  - Define what users or groups are notified about potential overlay tasks.
  - Rename the workflow configuration for this instance.
Configure a new potential overlay type by using the API. For more information, see Defining a new potential overlay workflow type.

Defining a new potential overlay workflow type

Before your IBM Match 360 service can start recognizing potential overlay issues, you must set the conditions that trigger the workflow by defining a new potential overlay workflow type.

To configure a new potential overlay workflow type by using the API, use the PUT workflows_configuration command from the model microservice API:

PUT /mdm/v1/workflows_configuration/potential_overlay

In the payload of this API, you must define the following:

What record types are applicable for the potential overlay workflow
What data sources to consider
What attributes to consider
What conditions qualify a given change to be considered a potential overlay

Here is a sample payload:

{
  "description": "Potential overlays (person records)",
  "applicable_data_types": {
    "record_types": ["person"]
  },
  "auto_create_tasks": true,
  "max_tasks": {
    "default": 300
  },
  "trigger_operator": {
    "record_types": {
      "person": {
        "excluded_sources": [],
        "included_sources": [],
        "entity_types": {
          "person_entity": {
            "triggers": {
              "default": [
                {
                  "label": "Name and DOB",
                  "recipe": {
                    "pername_compare": 2,
                    "date_compare": 2
                  }
                },
                {
                  "label": "Identifier",
                  "recipe": {
                    "identifiers_compare": 1
                  }
                }
              ],
              "source_based": {
                "sourceA": [
                  {
                    "label": "Name and Gender",
                    "recipe": {
                      "pername_compare": 2,
                      "gender_compare": 1
                    }
                  }
                ]
              }
            }
          }
        }
      }
    }
  }
}

For more information about using the API, see the IBM Match 360 API reference documentation.

Learn more

Parent topic: Configuring master data workflows for IBM Match 360

Was the topic helpful?

0/1000