Bulk update of attributes

Learn how to update the attributes for multiple entities in bulk.

This API initiates a bulk update task using which you can update attributes in bulk. The task divides the multiple updates into batches of 50 or fewer entities in the background.

Request

POST {TenantURL}/entities/_update

Table 1. Parameters
Parameter		Required	Details
Headers	`Authorization`	Yes	Information about authentication access token in format "Bearer `<accessToken>`" (see details in Authentication API).
Body		Yes	The entities' list can be specified by using either a filter with an optional `excludeList` of entities, or, just a list of entities. Example 1 shows a filter and `excludeList` and Example 2 shows just a list of entities. Example 1: `"objects": { "filter": "equals(attributes.Address.City, 'Las Vegas') and equals(type, 'configuration/entityTypes/HCP') ", "excludeList": ["entities/AAA", "entities/BBB"] }` Example 2: `"objects": { "list": ["entities/AAA", "entities/BBB"] }` Action contains an array of actions that will be applied to the selected entities. Each action contains one of the following operation fields: `AddAttribute` `UpdateAttribute` `DeleteAttribute` `RepointReferencedEntity` `operationParameters`
Query	`options`	No	This is a comma-separated list of different options. Available options: `sendHidden` - disabled by default, entity's JSON will contain hidden attributes if this option is enabled. `searchByOv` - disabled by default, to search by all attributes with ov only. `ovOnly` - return only attribute values that have ov=true flag. `nonOvOnly` - return only attribute values that have ov=false flag. If we have nested or reference attribute value which has ov=true, but at the same time it has sub-attributes with ov=false then these subattributes will not appear in the response.
Query	`activeness`	No	The possible values of this parameter are as follows: `active`: This is the default value. This option allows you to search amongst the active entities. `all`: This option allows you to search amongst all the entities (active or expired). `not_active`: This option allows you to search amongst the expired entities.

The AddAttribute operation adds a new attribute value to an entity. For every source type listed in the sourceTypes field, this value is a part of all winner crosswalks if the entity has crosswalks from the winner entity during a merge operation. All loser crosswalks are ignored. On the other hand, the value is a part of all loser crosswalks when the merged entity only has crosswalks from a loser entity. However, if there are no crosswalks for a listed source type, then a new crosswalk is created.

The UpdateAttribute operation updates the existing attribute values. This value is updated if all source types that it’s a part of are listed in the sourceTypes field. The attribute value’s Uniform Resource Identifier (URI) is also preserved. But a new value with its URI is added only if the value is a part of one or more crosswalks whose source types aren’t listed in the sourceTypes field, and is a part of all the crosswalks that are listed in the sourceTypes field. The URI of the earlier value is retained and is a part of all crosswalks that aren’t listed in the sourceTypes field. However, if the existing attribute value isn’t a part of one or more source types in the sourceTypes field, then the updated value is considered to be a part of an existing crosswalk or a new crosswalk (if there are no existing crosswalks) of these source types.

The DeleteAttribute operation affects all attribute values that pass the values in the valueFilter field and has corresponding attributeURI values. This operation deletes all values with crosswalk source types listed in the sourceTypes field, and ignores values that contain other crosswalks.

The RepointReferencedEntity operation changes the referenced entity for a reference attribute. For example, if you want to change the address reference for an entity.

The operationParameters operations can have any of the following fields:

sourceTypes (optional) - list of source types
attributeURI - target attribute type URI. Sub-attributes inside the reference attribute must be specified as entity attribute, rather than relation attribute (for example, configuration/entityTypes/HCP/attributes/Address/attributes/AddressRank)
addNestedAttribute - if true, it enables the user to add a parent to a nested attribute in a bulk update operation.

valueFilter (optional) - attribute value filter. Applied to attribute values and it’s possible to use the attribute value itself, nested attribute values, or, parent attribute value in the expression.
- equals(value, 'Jakson')
- equals(attributes.nestedAttribute, 'Jakson')
- equals(parent.attributes.siblingAttribute, 'Jakson')
- equals(referenced_entity_id, 'Location.1')- you can filter referenced attributes by the referenced entity.
attributeValue - new attribute value. Text value for simple attributes or JSON structure for a nested attribute. When adding a new reference attribute, the user can either specify a new referenced entity or an existing referenced entity URI in the objectURI field inside the refEntity node.
pin (optional) - specifies whether attribute value must be pinned
ignore (optional) - specifies whether attribute value must be ignored.
referencedEntity (optional) - specifies new end entity when re-pointing reference attribute. This can contain either a new entity or just a URI field to reference an existing entity.

Examples

Add an attribute

Request

POST {{api_uri}}/{{tenant}}/entities/_update
{
    "objects": {
        "list": [
            "entities/1uZzblK"
        ]
    },
    "actions": [
        {
            "operationParameters": {
                "sourceTypes": [
                    "HMS"
                ],
                "attributeURI": "configuration/entityTypes/HCP/attributes/MiddleName",
                "attributeValue": "MiddleName002"
            },
            "operation": "AddAttribute"
        }
    ]
}

Response

GET {{api_uri}}/{{tenant}}/entities/{{id}}
{
    "uri": "entities/1vERAkZ",
    "type": "configuration/entityTypes/HCP",
    "createdBy": "tselezneva",
    "createdTime": 1628484749041,
    "updatedBy": "tselezneva",
    "updatedTime": 1628484971718,
    "attributes": {
        "FirstName": [
            {
                "type": "configuration/entityTypes/HCP/attributes/FirstName",
                "ov": true,
                "value": "Simon",
                "uri": "entities/1vERAkZ/attributes/FirstName/BDVEKGsZ"
            }
        ],
        "LastName": [
            {
                "type": "configuration/entityTypes/HCP/attributes/LastName",
                "ov": true,
                "value": "Mitchell",
                "uri": "entities/1vERAkZ/attributes/LastName/BDVEKL8p"
            }
        ],
        "NestedTest": [
            {
                "label": "Added Nested",
                "value": {
                    "TextField": [
                        {
                            "type": "configuration/entityTypes/HCP/attributes/NestedTest/attributes/TextField",
                            "ov": true,
                            "value": "Added Nested",
                            "uri": "entities/1vERAkZ/attributes/NestedTest/8c7CAJDA/TextField/8c7CANTQ"
                        }
                    ],
                    "Int": [
                        {
                            "type": "configuration/entityTypes/HCP/attributes/NestedTest/attributes/Int",
                            "ov": true,
                            "value": "1111",
                            "uri": "entities/1vERAkZ/attributes/NestedTest/8c7CAJDA/Int/8c7CARjg"
                        }
                    ]
                },
                "ov": true,
                "uri": "entities/1vERAkZ/attributes/NestedTest/8c7CAJDA"
            }
        ]
    },
    "isFavorite": false,
    "crosswalks": [
        {
            "uri": "entities/1vERAkZ/crosswalks/8c7CAAge",
            "type": "configuration/sources/HMS",
            "value": "1vERAkZ",
            "reltioLoadDate": "2021-08-09T04:56:11.718Z",
            "createDate": "2021-08-09T04:56:11.718Z",
            "updateDate": "2021-08-09T04:56:11.718Z",
            "attributes": [
                "entities/1vERAkZ/attributes/NestedTest/8c7CAJDA/Int/8c7CARjg",
                "entities/1vERAkZ/attributes/NestedTest/8c7CAJDA/TextField/8c7CANTQ",
                "entities/1vERAkZ/attributes/NestedTest/8c7CAJDA"
            ],
            "singleAttributeUpdateDates": {
                "entities/1vERAkZ/attributes/NestedTest/8c7CAJDA/Int/8c7CARjg": "2021-08-09T04:56:11.718Z",
                "entities/1vERAkZ/attributes/NestedTest/8c7CAJDA/TextField/8c7CANTQ": "2021-08-09T04:56:11.718Z",
                "entities/1vERAkZ/attributes/NestedTest/8c7CAJDA": "2021-08-09T04:56:11.718Z"
            }
        },
        {
            "uri": "entities/1vERAkZ/crosswalks/8c7CAEwu",
            "type": "configuration/sources/FB",
            "value": "1vERAkZ",
            "reltioLoadDate": "2021-08-09T04:56:11.718Z",
            "createDate": "2021-08-09T04:56:11.718Z",
            "updateDate": "2021-08-09T04:56:11.718Z",
            "attributes": [
                "entities/1vERAkZ/attributes/NestedTest/8c7CAJDA/Int/8c7CARjg",
                "entities/1vERAkZ/attributes/NestedTest/8c7CAJDA/TextField/8c7CANTQ",
                "entities/1vERAkZ/attributes/NestedTest/8c7CAJDA"
            ],
            "singleAttributeUpdateDates": {
                "entities/1vERAkZ/attributes/NestedTest/8c7CAJDA/Int/8c7CARjg": "2021-08-09T04:56:11.718Z",
                "entities/1vERAkZ/attributes/NestedTest/8c7CAJDA/TextField/8c7CANTQ": "2021-08-09T04:56:11.718Z",
                "entities/1vERAkZ/attributes/NestedTest/8c7CAJDA": "2021-08-09T04:56:11.718Z"
            }
        },
        {
            "uri": "entities/1vERAkZ/crosswalks/BDVEKPP5",
            "type": "configuration/sources/Reltio",
            "value": "1vERAkZ",
            "reltioLoadDate": "2021-08-09T04:52:29.041Z",
            "createDate": "2021-08-09T04:52:29.041Z",
            "updateDate": "2021-08-09T04:52:29.041Z",
            "attributes": [
                "entities/1vERAkZ/attributes/FirstName/BDVEKGsZ",
                "entities/1vERAkZ/attributes/LastName/BDVEKL8p"
            ],
            "singleAttributeUpdateDates": {}
        }
    ],
    "analyticsAttributes": {},
    "label": "Simon Mitchell,",
    "secondaryLabel": ""
}

Update an attribute

Request

POST {{api_uri}}/{{tenant}}/entities/_update
{
    "objects": {
        "list": [
            "entities/0AR19KV"
        ]
    },
    "actions": [
        {
            "operationParameters": {
                "attributeURI": "configuration/entityTypes/HCP/attributes/FirstName",
                "valueFilter": "equals(value, 'Saimon')",
                "attributeValue":  "Gregory"
            },
            "operation": "UpdateAttribute"
        }
    ]
}

Response

GET {{api_uri}}/{{tenant}}/entities/{{id}}
{
    "uri": "entities/0AR19KV",
    "type": "configuration/entityTypes/HCP",
    "createdBy": "tselezneva",
    "createdTime": 1628497257398,
    "updatedBy": "tselezneva",
    "updatedTime": 1628497365747,
    "attributes": {
        "FirstName": [
            {
                "type": "configuration/entityTypes/HCP/attributes/FirstName",
                "ov": true,
                "value": "Gregory",
                "uri": "entities/0AR19KV/attributes/FirstName/ykeRkah"
            },
            {
                "type": "configuration/entityTypes/HCP/attributes/FirstName",
                "ov": true,
                "value": "Simon",
                "uri": "entities/0AR19KV/attributes/FirstName/ykeRgKR"
            }
        ],
        "LastName": [
            {
                "type": "configuration/entityTypes/HCP/attributes/LastName",
                "ov": true,
                "value": "Mitchell",
                "uri": "entities/0AR19KV/attributes/LastName/ykeRoqx"
            }
        ]
    },
    "isFavorite": false,
    "crosswalks": [
        {
            "uri": "entities/0AR19KV/crosswalks/ykeRt7D",
            "type": "configuration/sources/Reltio",
            "value": "0AR19KV",
            "reltioLoadDate": "2021-08-09T08:20:57.398Z",
            "createDate": "2021-08-09T08:20:57.398Z",
            "updateDate": "2021-08-09T08:20:57.398Z",
            "attributes": [
                "entities/0AR19KV/attributes/FirstName/ykeRgKR",
                "entities/0AR19KV/attributes/LastName/ykeRoqx",
                "entities/0AR19KV/attributes/FirstName/ykeRkah"
            ],
            "singleAttributeUpdateDates": {}
        }
    ],
    "analyticsAttributes": {},
    "label": "Gregory Mitchell,",
    "secondaryLabel": ""
}

Delete an attribute

Request

POST {{api_uri}}/{{tenant}}/entities/_update
{
    "objects": {
        "list": [
            "entities/0AR2nch"
        ]
    },
    "actions": [
        {
            "operationParameters": {
                "attributeURI": "configuration/entityTypes/HCP/attributes/FirstName",
                "valueFilter": "equals(value, 'Saimon')"
            },
            "operation": "DeleteAttribute"
        }
    ]
}

Response

GET {{api_uri}}/{{tenant}}/entities/{{id}}
{
    "uri": "entities/0AR2nch",
    "type": "configuration/entityTypes/HCP",
    "createdBy": "tselezneva",
    "createdTime": 1628508396543,
    "updatedBy": "tselezneva",
    "updatedTime": 1628508489430,
    "attributes": {
        "FirstName": [
            {
                "type": "configuration/entityTypes/HCP/attributes/FirstName",
                "ov": true,
                "value": "Simon",
                "uri": "entities/0AR2nch/attributes/FirstName/ykepKXD"
            }
        ],
        "LastName": [
            {
                "type": "configuration/entityTypes/HCP/attributes/LastName",
                "ov": true,
                "value": "Mitchell",
                "uri": "entities/0AR2nch/attributes/LastName/ykepT3j"
            }
        ]
    },
    "isFavorite": false,
    "crosswalks": [
        {
            "uri": "entities/0AR2nch/crosswalks/ykepXJz",
            "type": "configuration/sources/Reltio",
            "value": "0AR2nch",
            "reltioLoadDate": "2021-08-09T11:26:36.543Z",
            "createDate": "2021-08-09T11:26:36.543Z",
            "updateDate": "2021-08-09T11:26:36.543Z",
            "attributes": [
                "entities/0AR2nch/attributes/FirstName/ykepKXD",
                "entities/0AR2nch/attributes/LastName/ykepT3j"
            ],
            "singleAttributeUpdateDates": {}
        }
    ],
    "analyticsAttributes": {},
    "label": "Simon Mitchell,",
    "secondaryLabel": ""
}

Repoint a reference entity for an attribute

Request

POST {{api_uri}}/{{tenant}}/entities/_update
{
    "objects": {
        "list": [
            "entities/1Xd78XT"
        ]
    },
    "actions": [
        {
            "operationParameters": {
                "attributeURI": "configuration/entityTypes/HCP/attributes/Address",
                "valueFilter": "equals(referenced_entity_id,'1Xd7H3z')",
                "referencedEntity": {
                    "uri": "entities/0yxtctf"
                }
            },
            "operation": "RepointReferencedEntity"
        }
    ]
}

Response

GET {{api_uri}}/{{tenant}}/entities/{{id}}
{
    "uri": "entities/1Xd78XT",
    "type": "configuration/entityTypes/HCP",
    "createdBy": "tselezneva",
    "createdTime": 1628531133613,
    "updatedBy": "tselezneva",
    "updatedTime": 1628531552500,
    "attributes": {
        "FirstName": [
            {
                "type": "configuration/entityTypes/HCP/attributes/FirstName",
                "ov": true,
                "value": "Simon",
                "uri": "entities/1Xd78XT/attributes/FirstName/A3HMJYdn"
            }
        ],
        "LastName": [
            {
                "type": "configuration/entityTypes/HCP/attributes/LastName",
                "ov": true,
                "value": "Mitchell",
                "uri": "entities/1Xd78XT/attributes/LastName/A3HMJcu3"
            }
        ],
        "Address": [
            {
                "label": "Address_1",
                "relationshipLabel": "Home",
                "value": {
                    "AddressType": [
                        {
                            "type": "configuration/relationTypes/HasAddress/attributes/AddressType",
                            "ov": true,
                            "value": "Home",
                            "lookupError": "Lookup isn't found",
                            "uri": "entities/1Xd78XT/attributes/Address/1IyYX5f/AddressType/A3HMJyDL"
                        }
                    ],
                    "AddressLine1": [
                        {
                            "type": "configuration/entityTypes/Location/attributes/AddressLine1",
                            "ov": true,
                            "value": "Address_1",
                            "uri": "entities/1Xd78XT/attributes/Address/1IyYX5f/AddressLine1/5yeo16WR"
                        }
                    ]
                },
                "ov": true,
                "uri": "entities/1Xd78XT/attributes/Address/1IyYX5f",
                "refEntity": {
                    "type": "configuration/entityTypes/Location",
                    "crosswalks": [
                        {
                            "uri": "entities/1Xd78XT/crosswalks/0yxtctf.5yeo1Amh",
                            "type": "configuration/sources/FB",
                            "value": "loc_1",
                            "createDate": "2021-08-09T17:44:04.476Z",
                            "updateDate": "2021-08-09T17:44:04.476Z",
                            "attributeURIs": [
                                "entities/1Xd78XT/attributes/Address/1IyYX5f/AddressLine1/5yeo16WR",
                                "entities/1Xd78XT/attributes/Address/1IyYX5f"
                            ]
                        },
                        {
                            "uri": "entities/1Xd78XT/crosswalks/0yxtctf.5yeqVRDn",
                            "type": "configuration/sources/Reltio",
                            "value": "0yxtctf",
                            "createDate": "2021-08-09T17:52:32.500Z",
                            "updateDate": "2021-08-09T17:52:32.500Z"
                        }
                    ],
                    "objectURI": "entities/0yxtctf"
                },
                "refRelation": {
                    "type": "configuration/relationTypes/HasAddress",
                    "crosswalks": [
                        {
                            "uri": "entities/1Xd78XT/crosswalks/1IyYX5f.A3HMKepv",
                            "type": "configuration/sources/Reltio",
                            "value": "1IyYX5f",
                            "createDate": "2021-08-09T17:45:33.613Z",
                            "updateDate": "2021-08-09T17:45:33.613Z",
                            "attributeURIs": [
                                "entities/1Xd78XT/attributes/Address/1IyYX5f",
                                "entities/1Xd78XT/attributes/Address/1IyYX5f/AddressType/A3HMJyDL"
                            ]
                        }
                    ],
                    "startRefPinned": false,
                    "endRefPinned": false,
                    "startRefIgnored": false,
                    "endRefIgnored": false,
                    "objectURI": "relations/1IyYX5f"
                },
                "startObjectCrosswalks": [
                    {
                        "type": "configuration/sources/Reltio",
                        "value": "1Xd78XT"
                    }
                ],
                "endObjectCrosswalks": [
                    {
                        "type": "configuration/sources/Reltio",
                        "value": "0yxtctf"
                    }
                ]
            },
            {
                "label": "350 Hawthorne Ave",
                "relationshipLabel": "ShipTo",
                "value": {
                    "AddressType": [
                        {
                            "type": "configuration/relationTypes/HasAddress/attributes/AddressType",
                            "ov": true,
                            "value": "ShipTo",
                            "lookupError": "Lookup isn't found",
                            "uri": "entities/1Xd78XT/attributes/Address/1IyYSpP/AddressType/A3HMJlQZ"
                        }
                    ],
                    "AddressLine1": [
                        {
                            "type": "configuration/entityTypes/Location/attributes/AddressLine1",
                            "ov": true,
                            "value": "350 Hawthorne Ave",
                            "uri": "entities/1Xd78XT/attributes/Address/1IyYSpP/AddressLine1/A3HMJpgp"
                        }
                    ]
                },
                "ov": true,
                "uri": "entities/1Xd78XT/attributes/Address/1IyYSpP",
                "refEntity": {
                    "type": "configuration/entityTypes/Location",
                    "crosswalks": [
                        {
                            "uri": "entities/1Xd78XT/crosswalks/1Xd7Cnj.A3HMKS39",
                            "type": "configuration/sources/Reltio",
                            "value": "1Xd7Cnj",
                            "createDate": "2021-08-09T17:45:33.613Z",
                            "updateDate": "2021-08-09T17:45:33.613Z",
                            "attributeURIs": [
                                "entities/1Xd78XT/attributes/Address/1IyYSpP/AddressLine1/A3HMJpgp",
                                "entities/1Xd78XT/attributes/Address/1IyYSpP"
                            ]
                        }
                    ],
                    "objectURI": "entities/1Xd7Cnj"
                },
                "refRelation": {
                    "type": "configuration/relationTypes/HasAddress",
                    "crosswalks": [
                        {
                            "uri": "entities/1Xd78XT/crosswalks/1IyYSpP.A3HMKWJP",
                            "type": "configuration/sources/Reltio",
                            "value": "1IyYSpP",
                            "createDate": "2021-08-09T17:45:33.613Z",
                            "updateDate": "2021-08-09T17:45:33.613Z",
                            "attributeURIs": [
                                "entities/1Xd78XT/attributes/Address/1IyYSpP/AddressType/A3HMJlQZ",
                                "entities/1Xd78XT/attributes/Address/1IyYSpP"
                            ]
                        }
                    ],
                    "startRefPinned": false,
                    "endRefPinned": false,
                    "startRefIgnored": false,
                    "endRefIgnored": false,
                    "objectURI": "relations/1IyYSpP"
                },
                "startObjectCrosswalks": [
                    {
                        "type": "configuration/sources/Reltio",
                        "value": "1Xd78XT"
                    }
                ]
            }
        ]
    },
    "isFavorite": false,
    "crosswalks": [
        {
            "uri": "entities/1Xd78XT/crosswalks/A3HMKj6B",
            "type": "configuration/sources/Reltio",
            "value": "1Xd78XT",
            "reltioLoadDate": "2021-08-09T17:45:33.613Z",
            "createDate": "2021-08-09T17:45:33.613Z",
            "updateDate": "2021-08-09T17:45:33.613Z",
            "attributes": [
                "entities/1Xd78XT/attributes/FirstName/A3HMJYdn",
                "entities/1Xd78XT/attributes/LastName/A3HMJcu3"
            ],
            "singleAttributeUpdateDates": {}
        }
    ],
    "analyticsAttributes": {},
    "label": "Simon Mitchell,",
    "secondaryLabel": "Address_1"
}

Updating Tags

The tags associated with multiple entities can be managed as a bulk update. The following operations are available for working with tags:

AddTags - To add one or more new tags
ReplaceTag - To replace an existing tag with another tag
DeleteTags - To delete the existing tags by specifying the tags to be deleted
ClearTags - To clear all the existing tags without specifying the tags in the request

Request Sample for Tags:

{
    "actions": [
        {
            "operation": "AddTags",
            "operationParameters": {
                "tags": [ "a", "b", "c" ]
            }
        },
        {
            "operation": "ReplaceTag",
            "operationParameters": {
                "newValue": "c",
                "oldValue": "d"
            }
        },
        {
            "operation": "DeleteTags",
            "operationParameters": {
                "tags": [ "a", "b" ]
            }
        },
        {
            "operation": "ClearTags"
        }
    ],
    "objects": {
        "list": [ "entities/a", "entities/b" ]
    }
}

Response

JSON object with created Bulk Attribute Update task information.

Request

POST {
	TenantURL
}
/entities/_update
Headers: Authorization: Bearer c3f28fdd-e082-4 f90-8840-9896914e af41 {
	"objects": {
		"filter": "equals(attributes.Address.City, 'Las Vegas') and equals(type, 'configuration/entityTypes/HCP')",
		"excludeList": ["entities/AAA", "entities/BBB"]
	},
	"actions": [{
		"operation": "AddAttribute",
		"operationParameters": {
			"sourceTypes": ["FB", "Reltio"],
			"attributeURI": "configuration/entityTypes/HCP/attributes/FirstName",
			"attributeValue": "John"
		}
	}]
}

Response

{
	"id": "35e465b1-f7c5-462d-a78e-ba9158c0e6c7",
	"createdTime": 1447237852497,
	"createdBy": "username",
	"updatedTime": 1447237852497,
	"updatedBy": "username",
	"type": "com.reltio.businesslogic.tasks.update.UpdateAttributesTask",
	"status": "SCHEDULED",
	"createdOnHost": "tst-01-asdl04",
	"parallelExecution": false,
	"parameters": {
		"tenantId": "tenantName",
		"updateAttributesRequest": "..."
	},
	"currentState": {},
	"duration": "0s"
}

Accelerate the Value of Data

Bulk update of attributes

Footer