Patch Object

Patches a record of a given type by applying only the requested field changes.

Use a Patch Object node in your Flow to apply a partial update to a record of the specified Object Type. The Patch Object node only modifies the specified fields, leaving the rest of the record unchanged.

Example of settings for a Create Object node

Config tab

• Name - optional display name for the node in the editor

• Config - the native-object config used to access your Object Types

• Type Id - the Object Type to update, specified using one of several value types:

  • type - choose this option for a dropdown that includes the Display Names of the Object Types you have created in your Contextual tenant. If the dropdown appears empty for you, be sure that your Flow has been initialized with a Config, after which the dropdown will be kept in sync with your tenant.

  • string - choose the string option and type the Object Type ID directly. Using type is recommended when possible.

  • msg. - choose this option to read the Object Type ID from the current message, for example msg.payload.typeId or msg.event.typeId.

  • env variable - choose this option to read the Object Type ID from an agent environment variable.

• Object Id - the record identifier to patch

• Input - the typed-input path to an array of patch operations. In most flows, this comes from msg or an environment variable.

• Concurrency control - optional optimistic-locking toggle

• Hash - the message path that contains the record hash when concurrency control is enabled

• Output - the message path that receives the updated record

• Response - the message path that receives response metadata

The Input value should point to an array of patch operations. Each member of the array should be an object with these properties:

• op - the operation, one of set, add, remove, or increment

• path - the JSON path of the field to update, for example /foo/bar

• value - the value to set, when applicable

See below for a description of these operations.

When the Patch Object node is included in the path of your flow, it will patch a record and return its updated details, including _metaData, for further use within your flow as desired.

Concurrency control

The optional Concurrency control setting enables optimistic locking by record hash.

When enabled, the node reads a hash value from the configured message path and sends it with the update. If the record has changed since that hash was captured, the patch fails with a 412 Precondition Failed response instead of applying against a newer version of the record.

The hash you pass here typically comes from a previously retrieved record's _metaData.hash.

Source tab

The Source tab controls how the node behaves when it is processing a source stream rather than a single message.

• Parallelism can be set to None, Ordered, or Unordered

• None processes source items sequentially

• Ordered processes source items concurrently up to Max while preserving output order

• Unordered processes source items concurrently up to Max and emits results as they finish

These settings only apply when the node is operating on a source.

Patch operations

Each patch operation makes a change based on its value for op. The below examples show how operations would be applied to a record with this JSON structure:

{
  "name": "Oz",
  "items": ["first", "second"],
  "info": { "valid": true }
}

Set

A set operation (also aliased as replace) will add or change the value at the given path. For example, applied to the record above, this operation:

{
  "op": "set",
  "path": "/name",
  "value": "Yin"
}

will change the value of "name":

{
  "name": "Yin",
  "items": ["first", "second"],
  "info": { "valid": true }
}

Using set with a path that doesn't exist adds it:

{
  "op": "set",
  "path": "/count",
  "value": 4
}

{
  "name": "Oz",
  "items": ["first", "second"],
  "info": { "valid": true },
  "count": 4
}

To set a value in a nested location, use slashes in the path:

[
  {
    "op": "set",
    "path": "/items/0",
    "value": "1st"
  },
  {
    "op": "set",
    "path": "/info/counts/n",
    "value": 2
  }
]

{
  "name": "Oz",
  "items": ["1st", "second"],
  "info": {
    "valid": true,
    "counts": {
      "n": 2
    }
  }
}

Add

An add operation works the same as a set operation with one exception. With add , a value can be appended to an array by adding "/-" to the path to indicate the end position of the array:

{
  "op": "add",
  "path": "/items/-",
  "value": "third"
}

{
  "name": "Oz",
  "items": ["first", "second", "third"],
  "info": { "valid": true }
}

The only way to insert a value elsewhere into an array is to replace the entire array:

{
  "op": "add",
  "path": "/items",
  "value": ["0th", "first", "second"]
}

{
  "name": "Oz",
  "items": ["0th", "first", "second"],
  "info": { "valid": true }
}

Note: it would be more clear to use set or replace for modifying an array like this, but this example demonstrates that add has the same behavior in this situation.

Remove

A remove operation deletes the value at path:

{
  "op": "remove",
  "path": "/info"
}

{
  "name": "Oz",
  "items": ["first", "second"]
}

If used on an array element, it removes that element from the array:

{
  "op": "remove",
  "path": "/items/0"
}

{
  "name": "Oz",
  "items": ["second"],
  "info": { "valid": true }
}

Increment

An increment operation (also aliased as incr ) atomically increases a numeric value by the value amount:

{
  "op": "increment",
  "path": "/count",
  "value": 2
}

{
  "name": "Oz",
  "items": ["first", "second"],
  "info": { "valid": true },
  "count": 6
}

This can be superior to using set to change the value to 6 because if another operation has incremented the value since it was read, it will still be increased by the intended amount.

It cannot be used on values of other types. If there is no value at the path, it acts as a set.