Patch Object

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

1. Provide an optional Name for the node.

   • By default a Patch Object node will be shown with a label of "Patch Object", but the value you provide in the Name field will replace it in the Flow Editor UI making your flow easier to read and understand.

2. Select a Config for the node.

   • This tells the node how to access your Object Types. The default value should suffice.

3. Select a Type Id for the node, a value specified using one of several options.

   • 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 in a string for the Object Type ID that you want to search, using type is recommended instead of string

   • msg. - choose this option to specify a path in the msg. object that contains the Object Type ID value that you want to perform the search against, e.g. msg.payload.thePropertyWithTheObjectTypeId, msg.event.thePropertyWithTheObjectTypeId, or msg.customObject.thePropertyWithTheObjectTypeId- the msg. object and its content are available to nodes within any flow in the same Flow Editor window (i.e., across multiple tabs in the Node-RED Flow Editor interface).

   • flow. - values in the flow. scope can be set and retrieved by nodes that exist within the same tab of your flow in the Contextual Flow Editor.

   • global. - values in the .global scope are shared, and can be set and retrieved, by nodes across any tab of your flow in the Contextual Flow Editor.

   • env variable - Environmental Variables are a feature of Agents in Contextual. Any Environmental Variables that you define as Label/Value pairs for an Agent that is sending events to a Flow, will be available to the Flow, simply type the Label of the Evironmental Variable from which you want to use the value.

4. Specify the Input path to an array of patch operations.

   • Use msg., flow., global., or env variable paths, similar to above.

   • Each member of the array should be an object with the properties:

     • op – the operation, one of "set", "add", "remove", or "increment".

     • path – the JSON path of the field to update, e.g. "/foo/bar".

     • value – the value to set, if applicable.

   • See below for a description of these operations.

5. Specify the Output msg. object path for the details of the record that was just patched, to be returned to, e.g. msg.myPatchedRecordDetails.

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.

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.