Partial Updates for Source Mappings

Learn how to use partial operations to add, modify or remove source mapped values in lookups.

Partial updates in source mappings allow you to modify lookup definitions incrementally using the operation field. The supported operations include:

INSERT – adds new source values.
UPDATE – modifies existing source values.
DELETE – removes source values from an RDM lookup.

You can include multiple operation types in a single request, enabling you to insert, update, and delete source-mapped values in the same payload. This approach enables efficient, targeted updates without replacing the entire lookup.

INSERT - Add a new source value

The following table describes the request body parameters for the INSERT operation, which lets you add a new source-specific value to a lookup.


Parameter	Type	Required	Description	Default values	Accepted values
`operation`	String	Yes	Specifies `INSERT` operation.	None	"INSERT"
`code`	String	Yes	Source value identifier to be added.	None	"US"
`value`	String	Yes	Source value description to be added.	None	"United States"
`enabled`	Boolean	No	Indicates whether the source value is active.	`true`	`true` or `false`
`canonicalValue`	Boolean	No	Marks if the value is canonical.	`false`	`true` or `false`
`downStreamDefaultValue`	Boolean	No	Indicates if the value should be default for downstream processes.	`false`	`true` or `false`
`description`	String	No	Description for source values	None	None

Example request for INSERT operation

{
  "operation": "INSERT",
  "code": "US",
  "value": "United States",
  "enabled": true,
  "canonicalValue": false,
  "downStreamDefaultValue": true
}

This INSERT operation adds a new source value with code "US" and value "United States" to a lookup, marking it active and setting it as the default value used in downstream processes.

UPDATE - Modify attributes of an existing source value

The UPDATE operation modifies an existing source-mapped value. There are two UPDATE modes:

Standard UPDATE without oldValue uses the code and value fields to identify the entry to update.
Targeted UPDATE with oldValue uses the oldValue object to identify one exact existing entry.

Standard UPDATE without oldValue

Use a standard UPDATE to modify an existing source-mapped value by matching both the code and value fields exactly. If multiple entries share the same code and value, all matching entries are replaced with the new values.

The following table describes the request body parameters for a standard UPDATE operation, which identifies entries by matching the code and value fields.


Parameter	Type	Required	Description	Default Value	Accepted values
`operation`	String	Yes	Specifies UPDATE operation.	None	"UPDATE"
`code`	String	Yes	Must match existing code for update.	None	"US"
`value`	String	Yes	Must match existing value for update.	None	"United States"
`enabled`	Boolean	No	Updated enabled status.	`true`	`true` or `false`
`canonicalValue`	Boolean	No	Updated canonical flag.	`false`	`true` or `false`
`downStreamDefaultValue`	Boolean	No	Updated downstream default flag.	`false`	`true` or `false`
`description`	String	No	Description for source values	None	None

Example request for standard UPDATE operation

{
  "operation": "UPDATE",
  "code": "US",
  "value": "United States",
  "enabled": false,
  "canonicalValue": false,
  "downStreamDefaultValue": true
}

This request updates the enabled value to false for the entry matching code US and value United States.

Targeted UPDATE with oldValue

Use a targeted UPDATE when you need to update one specific entry, especially when multiple entries share the same code and value, or when you want to change the code or value fields themselves.

The oldValue object specifies the exact existing entry to replace. All fields in oldValue must match the existing entry exactly, including enabled, canonicalValue, downStreamDefaultValue, and description when present.

The following table describes the request body parameters for a targeted UPDATE operation, which uses oldValue to identify the exact entry to replace.


Parameter	Type	Required	Description	Default Value	Accepted Values
`operation`	String	Yes	Specifies UPDATE operation.	None	`"UPDATE"`
`code`	String	Yes	New code for the entry	None	`"US_NEW"`
`value`	String	Yes	New value for entry	None	"United States of America"
`enabled`	Boolean	No	New enabled status	`true`	`true` or `false`
`canonicalValue`	Boolean	No	New canonical flag	`false`	`true` or `false`
`downStreamDefaultValue`	Boolean	No	New downstream default flag.	`false`	`true` or `false`
`description`	String	No	New description for the entry.	None	Any string
`oldValue`	Object	No	The exact existing source value to replace. See below for fields.	None	See oldValue fields

oldValue fields

The following table describes the fields supported in the oldValue object.


Parameter	Type	Required	Description
`code`	String	Yes	Must match existing code exactly.
`value`	String	Yes	Must match existing value exactly.
`description`	String	No	Must match existing description if present.
`enabled`	Boolean	No	Must match existing enabled flag.
`canonicalValue`	Boolean	No	Must match existing canonical flag.
`downStreamDefaultValue`	Boolean	No	Must match existing downstream default flag.

Example: Targeted UPDATE to change identity fields


{
  "operation": "UPDATE",
  "code": "USA",
  "value": "United States of America",
  "enabled": true,
  "canonicalValue": false,
  "downStreamDefaultValue": true,
  "oldValue": {
    "code": "US",
    "value": "United States",
    "enabled": true,
    "canonicalValue": false,
    "downStreamDefaultValue": true
  }
}

This targeted UPDATE looks for an entry that matches all the fields in oldValue: code: "US", value: "United States", enabled: true, canonicalValue: false, and downStreamDefaultValue: true. Once it finds that exact match, it replaces the entry's code and value with "USA" and "United States of America". The other settings, enabled, canonicalValue, and downStreamDefaultValue, stay the same as before.

Example: Targeted UPDATE to modify one duplicate among several


{
  "operation": "UPDATE",
  "code": "USA",
  "value": "United States of America",
  "enabled": true,
  "canonicalValue": false,
  "downStreamDefaultValue": false,
  "description": "updated description",
  "oldValue": {
    "code": "US",
    "value": "United States",
    "enabled": true,
    "canonicalValue": false,
    "downStreamDefaultValue": true,
    "description": "original description"
  }
}

Only the entry matching all fields in oldValue is replaced. Other entries with the same code and value remain unchanged.

Note: The oldValue field is supported only for UPDATE operations. Providing oldValue with INSERT or DELETE returns an error.

DELETE - Remove an existing source value

The DELETE operation removes only the first entry that matches all provided fields exactly. If multiple identical entries exist with the same code, value, description, enabled, canonicalValue, and downStreamDefaultValue, only one is removed per DELETE operation.

The following table describes the request body parameters for the DELETE operation, which removes a source-specific value from the lookup. All fields must match the existing entry exactly.


Parameter	Type	Required	Description	Default Value	Accepted values
`operation`	String	Yes	Specifies DELETE operation.	None	"DELETE"
`code`	String	Yes	Must match existing code exactly for deletion.	None	"US"
`value`	String	Yes	Must match existing value exactly for deletion.	None	"United States"
`enabled`	Boolean	Yes	Must match existing enabled value.	`true`	`true` or `false`
`canonicalValue`	Boolean	Yes	Must match existing canonical flag.	`false`	`true` or `false`
`downStreamDefaultValue`	Boolean	Yes	Must match existing downstream default flag.	`false`	`true` or false
`description`	String	No	Description for source values	None	None

Example request for DELETE operation

{
  "operation": "DELETE",
  "code": "US",
  "value": "United States",
  "enabled": true,
  "canonicalValue": false,
  "downStreamDefaultValue": true
}

This DELETE operation looks for an entry with code: "US", value: "United States", enabled: true, canonicalValue: false, and downStreamDefaultValue: true. When it finds an entry that matches all these fields exactly, The DELETE operationremoves that entry from the lookup.

Example: Deleting one of multiple identical entries

{
  "source": "Reltio",
  "values": [
    { "code": "US", "value": "United States", "enabled": true, "canonicalValue": false, "downStreamDefaultValue": false },
    { "code": "US", "value": "United States", "enabled": true, "canonicalValue": false, "downStreamDefaultValue": false }
  ]
}

This example shows a lookup source named "Reltio" that has two identical entries. Both entries have code: "US", value: "United States", enabled: true, canonicalValue: false, and downStreamDefaultValue: false. Since both entries match on every field, a single DELETE operation can only target one of them at a time.

Example: A single DELETE removes only the first match

{
  "operation": "DELETE",
  "code": "US",
  "value": "United States",
  "enabled": true,
  "canonicalValue": false,
  "downStreamDefaultValue": false
}

This DELETE operation matches both duplicate entries, but removes only one. Two DELETE operations are needed to remove both.

Using multiple operations in a single request

You can combine INSERT, UPDATE, and DELETE operations in the same request body. This allows you to update multiple source-mapped values efficiently without replacing the full lookup.

When combining operations in a single request, the system applies them in the following order regardless of their position in the request:

DELETE
UPDATE
INSERT

Rules for combining operations

Only one value per lookup code can have "canonicalValue": true. If multiple values are marked as canonical, the system returns an error.
Only one value per source can have "downStreamDefaultValue": true. If none is specified, the first enabled value for that source becomes the default.
Only Include the source mappings you want to modify; any sources or source values not included in the request will remain unchanged.
You can combine INSERT and DELETE on the same code and value pair in a single request.
You cannot combine a standard UPDATE without oldValue with INSERT or DELETE on the same code and value pair. The system returns a duplicate error.
Targeted UPDATE operations with oldValue can coexist with any other operation in the same request, because oldValue uniquely identifies the entry.

Example: Existing lookup

[
  {
    "tenantId": "{{rdm_tenant}}",
    "type": "rdm/lookupTypes/Gender",
    "code": "M",
    "enabled": true,
    "sourceMappings": [
      {
        "source": "Reltio",
        "values": [
          {
            "code": "Men",
            "value": "Men",
            "enabled": true,
            "canonicalValue": true,
            "downStreamDefaultValue": false
          },
          {
            "code": "0",
            "value": "0",
            "enabled": true,
            "canonicalValue": false,
            "downStreamDefaultValue": false
          }
        ]
      }
    ]
  }
]

Request body

[
  {
    "tenantId": "{{rdm_tenant}}",
    "type": "rdm/lookupTypes/Gender",
    "code": "M",
    "enabled": true,
    "sourceMappings": [
      {
        "source": "Reltio",
        "values": [
          {
            "operation": "INSERT",
            "code": "Male",
            "value": "Male",
            "enabled": true,
            "canonicalValue": true,
            "downStreamDefaultValue": true
          },
          {
            "operation": "UPDATE",
            "code": "Men",
            "value": "Men",
            "enabled": true,
            "canonicalValue": false,
            "downStreamDefaultValue": false
          },
          {
            "operation": "DELETE",
            "code": "0",
            "value": "0",
            "enabled": true,
            "canonicalValue": false,
            "downStreamDefaultValue": false
          }
        ]
      },
      {
        "source": "Reltio2",
        "values": [
          {
            "operation": "INSERT",
            "code": "Male",
            "value": "Male",
            "enabled": true,
            "canonicalValue": false,
            "downStreamDefaultValue": true
          }
        ]
      }
    ]
  }
]

This request performs multiple operations on the existing lookup. For source "Reltio", it inserts a new source value "Male" and sets its canonicalValue to true, updates the existing value "Men" by changing its canonicalValue to false, and deletes the source value "0". It also inserts a new source value "Male" for source "Reltio2", with canonicalValue set to false and downStreamDefaultValue set to true.

Response body

[
  {
    "uri": "{{rdm_tenant}}/Gender/M",
    "value": {
      "tenantId": "{{rdm_tenant}}",
      "type": "rdm/lookupTypes/Gender",
      "code": "M",
      "enabled": true,
      "sourceMappings": [
        {
          "source": "Reltio",
          "values": [
            {
              "code": "Men",
              "value": "Men",
              "enabled": true,
              "canonicalValue": false,
              "downStreamDefaultValue": false
            },
            {
              "code": "Male",
              "value": "Male",
              "enabled": true,
              "canonicalValue": true,
              "downStreamDefaultValue": true
            }
          ]
        },
        {
          "source": "Reltio2",
          "values": [
            {
              "code": "Male",
              "value": "Male",
              "enabled": true,
              "canonicalValue": false,
              "downStreamDefaultValue": true
            }
          ]
        }
      ],
      "startDate": 0,
      "endDate": 0,
      "updatedBy": "{{user}}",
      "updateDate": "{{update_date}}",
      "version": "{{version}}"
    }
  }
]

Example: Targeted UPDATE to change identity fields

This lookup has a source value with code US and value United States. The following request uses oldValue to match that entry and update its code and value in place.

[
  {
    "tenantId": "{{rdm_tenant}}",
    "type": "rdm/lookupTypes/Country",
    "code": "US",
    "sourceMappings": [
      {
        "source": "Reltio",
        "values": [
          {
            "operation": "UPDATE",
            "code": "USA",
            "value": "United States of America",
            "enabled": true,
            "canonicalValue": false,
            "downStreamDefaultValue": false,
            "oldValue": {
              "code": "US",
              "value": "United States",
              "enabled": true,
              "canonicalValue": false,
              "downStreamDefaultValue": false
            }
          }
        ]
      }
    ]
  }
]

This targeted UPDATE changes the entry's code from "US" to "USA" and its value to "United States of America". The entry is not deleted and re-added, it is updated in place, so it stays in the same position in the source mapping list.

Unify and manage your data

Partial Updates for Source Mappings

INSERT - Add a new source value

UPDATE - Modify attributes of an existing source value

DELETE - Remove an existing source value

Using multiple operations in a single request

Footer