When you update simple data types, such as numbers, strings, booleans, etc., Unit21 simply overwrites the old data.
With complex data types, such as arrays (e.g. location_data
and tags
) and the custom_data
object, you have granular control of the updates, allowing you to:
- Join old items with new items
- Replace old items with new items
- Remove items from the array
For these operations, many endpoints receive a top-level options
object. Within this object, there are fields that let you configure exactly how array data is merged.
curl -X POST \
https://<API_ENDPOINT>/v1/alerts/list \
-H 'Content-Type: application/json' \
-H 'u21-key: <YOUR_API_KEY>' \
-d '{
"options": {
"include_associations": false,
"include_actions": false,
"include_checklist": false
}
}'
For almost all complex data models, you can configure merges with the field options.list_merge_strategy
. The only exception is the custom_data
object. For custom_data
, use the field options.merge_custom_data
.
Arrays merged using options.list_merge_strategy
options.list_merge_strategy
If you are merging this field, | Then configure your merge: |
---|---|
tags (across all objects)parents (in general_data for entities)document_data location_data digital_data communication data (emails & phone arrays) |
In the options object, use the field list_merge_strategy . This field has three different parameters that define how operation merges the data. |
custom_data |
In the options object, use the field merge_custom_data . |
For items you cannot modify or delete, please send a request directly to the Unit21 team.
List Merge Strategy
The list_merge_strategy
configuration in the options
object provides three different methods to merge list values in an object update. By default, the union
strategy is applied.
list_merge_strategy | Description |
---|---|
union | (Default) Performs a set-union on the old and new lists, adding values that did not previously exist in the object. If the original list is ["abc", "def"] , and the upsert/update request specifies ["def", "ghi"] , then the resulting list is ["abc", "def", "ghi"] . |
replace | Replaces the entire old list with the newly provided list. If original list is ["abc", "def"] , and the upsert/update request specifies ["def", "ghi"] , then the resulting list is ["def", "ghi"] . If you provide an empty list, the API deletes all previous list values from the object. |
difference | Performs a set-difference by subtracting values provided in the new list from the old list. If original list is ["abc", "def"] , and the request specifies ["def", "ghi"] , then the resulting list is ["abc"] . The API ignores values provided in the new list that did not exist in the old list. |
One list merge strategy per API request.
All lists in an update or upsert API request (single or bulk) will be merged according to the specified
list_merge_strategy
. It is not possible to have different lists be merged with different strategies in one API request.
Custom Data Merge Strategy
The default behavior for updating the custom_data
field of an object is to perform a full object overwrite. This is equivalent to setting merge_custom_data
in the options
section as false
.
- When the
merge_custom_data
field is set totrue
, a deep recursive merge strategy is used to updatecustom_data
. - Any conflicting keys take on the newly provided value. This will apply a recursive merge to both objects and lists within
custom_data
. - List member index positions are used as their keys i.e. merging
["a", "b", "c", "d"]
with["e", "f"]
results in["e", "f", "c", "d"]
.