Cumulative Entity Update

You can make multiple changes to an entity's attribute at the same time using a cumulative update request.

The following request allows you to do a cumulative entity update:

Request

POST {TenantURL}/{objectURI}/_update

Table 1. Parameters
Parameter		Required	Details
Headers	`Authorization`	Yes	Information about the authentication access token must be in the following format "Bearer `<accessToken>`". For more information, see Authentication API.
Query	`changeRequestId`	No	If this parameter is present, all changes will be added to the DCR with a given ID instead of updating the entity.
	`alwaysCreateDCR`	No	If `true`, create a DCR without updating an entity. Example: POST {{api_uri}}/{{tenant}}/entities/{{entity_id}}/_update?alwaysCreateDCR=true [ { "type": "UPDATE_ATTRIBUTE", "uri": "entities/{{entityID}}/attributes/FirstName/{{FirstNameID}}", "newValue": { "value": "Updated" }, "crosswalk": { "type": "configuration/sources/Reltio", "value": "{{entityID}}", "sourceTable": "testTable" } }, { "type": "DELETE_ATTRIBUTE", "uri": "entities/{{entityID}}/attributes/LastName/{{LastNameID}}", "crosswalk": { "type": "configuration/sources/Reltio", "value": "{{entityID}}", "sourceTable": "testTable" } }, { "type": "IGNORE_ATTRIBUTE", "uri": "entities/{{entityID}}/attributes/MiddleName/{{MiddleNameID}}", "newValue": { "value": true } }, { "type": "INSERT_ATTRIBUTE", "uri": "entities/{{entityID}}/attributes/Int", "newValue": [ { "value": "55" } ] } ]
	`overwriteDefaultCrosswalkValue`	No	If set to `false`, the process of normalization of Reltio crosswalk is skipped. Default is `true`.
	`returnUriOnly`	No	When set to `true`, the response includes only the URIs of the processed entities or relations, instead of the full object payloads. Use this option to reduce response size and improve performance in high-volume or bulk operations.
Body	Request definition	Yes	Array of JSON objects, where each object represents changing of an attribute, tags, or roles. Each object must have a `type` property, which is the type of change.

The following types of changes can be done for an entity:

INSERT_ATTRIBUTE
UPDATE_ATTRIBUTE
DELETE_ATTRIBUTE
PIN_ATTRIBUTE
IGNORE_ATTRIBUTE
UPDATE_TAGS
UPDATE_ROLES
UPDATE_START_DATE
UPDATE_END_DATE

All changes, except DELETE_ATTRIBUTE, must have a newValue property, which is the new value of attributes, tags, or roles.

INSERT_ATTRIBUTE, UPDATE_ATTRIBUTE, DELETE_ATTRIBUTE, PIN_ATTRIBUTE, IGNORE_ATTRIBUTE changes must have the uri property,which is the URI of the attribute.

INSERT_ATTRIBUTE, UPDATE_ATTRIBUTE, and DELETE_ATTRIBUTE changes must have the crosswalk property, which is the crosswalk for which this attribute should be updated.

Request Examples

Example 1:

[
    {
        "type": "INSERT_ATTRIBUTE",
        "uri": "entities/000005KL/attributes/FirstName",
        "newValue": [
            {
                "value": "John"
            },
            {
                "value": "Jonny"
            }
        ],
        "crosswalk": {
            "type": "configuration/sources/HMS",
            "value": "test1",
            "sourceTable": "testTable"
        }
    },
    {
        "type": "INSERT_ATTRIBUTE",
        "uri": "entities/000005KL/attributes/Identifiers",
        "newValue": [
            {
                "value": {
                    "Type": [
                        {
                            "value": "Test"
                        }
                    ],
                    "ID": [
                        {
                            "value": "1111"
                        }
                    ]
                }
            }
        ],
        "crosswalk": {
            "type": "configuration/sources/Reltio",
            "value": "000005KL",
            "sourceTable": "testTable"
        }
    },
    {
        "type": "UPDATE_ATTRIBUTE",
        "uri": "entities/000005KL/attributes/LastName/ohg4GDs3",
        "newValue": {
            "value": "Smith"
        },
        "crosswalk": {
            "type": "configuration/sources/HMS",
            "value": "test1",
            "sourceTable": "testTable"
        }
    },
    {
        "type": "DELETE_ATTRIBUTE",
        "uri": "entities/000005KL/attributes/MiddleName/Jk07LJ3d",
        "crosswalk": {
            "type": "configuration/sources/HMS",
            "value": "test1",
            "sourceTable": "testTable"
        }
    },
    {
        "type": "PIN_ATTRIBUTE",
        "uri": "entities/000005KL/attributes/ProductMetrics/IL98KH3f",
        "newValue": {
            "value": "true"
        }
    },
    {
        "type": "IGNORE_ATTRIBUTE",
        "uri": "entities/000005KL/attributes/ProductMetrics/IL98KH3f/Name/ohgGk4wd",
        "newValue": {
            "value": "false"
        }
    },
    {
        "type": "UPDATE_TAGS",
        "newValue": [
            "tag1",
            "tag2"
        ]
    },
    {
        "type": "UPDATE_ROLES",
        "newValue": []
    },
    {
        "type": "UPDATE_START_DATE",
        "newValue": "1455702524000"
    },
    {
        "type": "UPDATE_END_DATE",
        "newValue": "1455702524000"
    }
]

Example 2:

 [
    {
        "type": "INSERT_ATTRIBUTE",
        "uri": "entities/000005KL/attributes/Address",
        "newValue": [
            {
                "value": {
                    "AddressRank": [
                        {
                            "value": "1"
                        }
                    ],
                    "AddressLine1": [
                        {
                            "value": "Address1"
                        }
                    ]
                },
                "refEntity": {
                    "crosswalks": [
                        {
                            "type": "configuration/sources/Veeva",
                            "value": "763127815f9f6ec9e2b9a399db8d18c7",
                            "sourceTable": "testTable"
                        }
                    ]
                },
                "refRelation": {
                    "crosswalks": [
                        {
                            "type": "configuration/sources/Veeva",
                            "value": "r1",
                            "sourceTable": "testTable"
                        }
                    ],
                    "startRefPinned": false,
                    "endRefPinned": false,
                    "startRefIgnored": false,
                    "endRefIgnored": false
                }
            }
        ],
        "crosswalk": {
            "type": "configuration/sources/Reltio",
            "value": "000005KL",
            "sourceTable": "testTable"
        }
    },
    {
        "type": "UPDATE_ATTRIBUTE",
        "uri": "entities/000005KL/attributes/Address/IL98KH3f/AddressRank/ohgGk4wd",
        "newValue": {
            "value": "7"
        },
        "crosswalk": {
            "type": "configuration/sources/Reltio",
            "value": "00000Hg3",
            "sourceTable": "testTable"
        }
    }
]

Response

Changed entity or data change request (if changeRequestId is defined or if you don't have access to update the object, but you do have permission to initiate a data change request).

Note: If the cumulative update request contains a crosswalk of an existing entity that does not belong to the entity being updated, such a request is rejected, and the following error message is returned: "Cumulative update request should not contain crosswalk of already existing entity".

Note: If the cumulative update request contains a new crosswalk, the initial contributor of the entity is selected as the contributor for the new crosswalk. If the initial contributor is not found, all existing contributors are sorted, and the first one is selected.

Unify and manage your data

Cumulative Entity Update

Footer