Update/Create Record

the update/create record (also called upsert record ) native action updates an existing record or creates a new record based on a unique identifier field the action searches for a record using a key field and value; if found, it updates the record; if not found, it creates a new one key benefits native action integrated directly into the playbook builder for streamlined workflow creation upsert functionality automatically creates or updates records based on a unique identifier flexible field operations supports patching (overwrite), appending (add to arrays), and removing (remove from arrays) values single action eliminates the need for separate create and update actions with conditional logic at most once execution ensures the record is created or updated exactly once, even if the playbook is retried how update/create record works search phase the action searches for an existing record where the keyfieldkey field matches the keyfieldvalue update path (record found) applies patchvalues to overwrite existing field values applies appendvalues to add items to array/multiselect fields applies removevalues to remove items from array/multiselect fields updates restrictions if provided create path (record not found) creates a new record combines patchvalues and appendvalues for initial field values sets restrictions if provided inputs the update/create record action requires the following inputs required inputs application select an application by either application id the unique identifier of the application application name the name of the application note you must provide either applicationid or applicationname , but not necessarily both key field key the field key to use as a unique identifier for finding or creating records this must be a single field (not multiple fields) note only one field can be selected as the key field key field value the value of the key field to search for this can be a static value (string or number) a reference to a playbook property from upstream actions a reference to playbook inputs an expression that evaluates to a string or number optional inputs patch values fields to update/overwrite on the record these values replace existing field values works for all field types except comments (comments only work with append) if updating an array field with patch, it replaces the entire array append values array/multiselect fields to append items to these values are added to existing arrays without removing existing items only works for array/multiselect field types if you pass an empty array or null value, nothing changes comments fields only work with append, not patch remove values array/multiselect fields to remove items from these values are removed from existing arrays if they match only works for array/multiselect field types only removes values that match existing array items if you pass items that don't match, nothing changes if you remove all items, the field is removed from the record (no empty array/null) restrictions users and/or groups to restrict the record to users array of user ids or usernames groups array of group ids or group names configuring the update/create record action step 1 select application from the inputs tab, select an application choose from the dropdown list of available applications, or use an expression to reference an application id or name dynamically step 2 select key field click select key field to open the application form select one field to use as the unique identifier this field will be used to search for existing records step 3 configure key field value set the key field value enter a static value (string or number), or click the + icon to select a playbook property from upstream actions or playbook inputs, or write an expression to calculate the value dynamically example to use a value from an upstream http request action click the + icon next to key field value select playbook property navigate to $actions httprequestname result body id step 4 configure field values configure how fields should be updated or created patch values (update/overwrite) add fields to the patch values section map values to each field click the + icon next to each field select a playbook property, enter a static value, or write an expression behavior these values overwrite existing field values important notes array fields if you patch an array field, it replaces the entire array for example, if an array has \[a, b, c] and you patch with \[d] , the result is \[d] (not \[a, b, c, d] ) comments comments fields cannot be patched; use append instead null values you can clear fields by sending null for string, numeric, and list types append values (add to arrays) add array/multiselect fields to the append values section map values to append click the + icon next to each field select a playbook property, enter a static value, or write an expression behavior these values are added to existing arrays without removing existing items important notes only array/multiselect fields append only works for array/multiselect field types empty arrays/null if you pass an empty array or null value, nothing changes comments comments fields work with append operations preserves existing data existing array items are preserved; new items are added remove values (remove from arrays) add array/multiselect fields to the remove values section map values to remove click the + icon next to each field select a playbook property, enter a static value, or write an expression behavior these values are removed from existing arrays if they match important notes only array/multiselect fields remove only works for array/multiselect field types matching required only removes values that match existing array items exactly no match if you pass items that don't match existing items, nothing changes remove all if you remove all items from an array, the field is removed from the record (no empty array/null is stored) step 5 configure restrictions (optional) if you need to restrict record access expand the restrictions section add users enter user ids or usernames (can be static or from expressions) add groups enter group ids or group names (can be static or from expressions) note restrictions determine who can view and access the record if not specified, the record follows the application's default access rules step 6 apply changes click apply to save your configuration understanding field operations patch (update/overwrite) use case replace existing field values with new values behavior string/number fields replaces the existing value with the new value array fields replaces the entire array with the new array comments fields cannot be patched; use append instead example existing array \["item1", "item2", "item3"] patch with \["item4"] result \["item4"] (original items are lost) append (add to arrays) use case add items to existing arrays without removing existing items behavior array/multiselect fields adds new items to the existing array comments fields works with append operations empty/null values if you pass an empty array or null, nothing changes example existing array \["item1", "item2"] append with \["item3"] result \["item1", "item2", "item3"] (original items are preserved) remove (remove from arrays) use case remove specific items from existing arrays behavior array/multiselect fields removes matching items from the existing array exact match required only removes items that exactly match existing array items no match if items don't match, nothing changes remove all if all items are removed, the field is removed from the record example existing array \["item1", "item2", "item3"] remove \["item2"] result \["item1", "item3"] (only matching item is removed) outputs the update/create record action provides the following outputs success output when the record is created or updated successfully, the action returns result tracking id the tracking id (trackingfull) of the created or updated record this can be used in downstream actions to reference the record example access the tracking id in downstream actions error output if the record creation or update fails, the action returns error error information containing details about why the operation failed common error scenarios application not found key field not found in application invalid key field value type invalid field values permission errors validation errors use cases example 1 upsert record by email address scenario create or update a user record based on email address configuration select the application (e g , "user management") select key field email address set key field value $inputs useremail (or from upstream action) configure patch values first name $inputs firstname last name $inputs lastname status "active" configure append values (if updating) roles \["user", "viewer"] (adds roles without removing existing ones) result if a record with the email exists, it updates the name and status, and adds roles if no record exists, it creates a new record with the provided values example 2 update array field with append scenario add log entries to a record without overwriting existing logs configuration select the application select key field case id set key field value $actions createcase result\['tracking id'] configure append values log entries \[$inputs newlogentry] (adds to existing log entries) result new log entries are added to the existing array without removing previous entries note if you used patch instead of append, it would replace all existing log entries with only the new entry example 3 remove items from array field scenario remove specific tags from a record configuration select the application select key field record id set key field value $inputs recordid configure remove values tags \["deprecated", "old"] (removes these tags if they exist) result only matching tags are removed from the array non matching tags remain unchanged example 4 combined patch, append, and remove scenario update a record with multiple field operations configuration select the application select key field incident id set key field value $event data incidentid configure patch values status "resolved" priority "low" configure append values notes \[$event data resolutionnote] (adds note without removing existing notes) configure remove values assigned teams \["team a"] (removes team a if present) result the action updates status and priority, adds a resolution note, and removes team a from assigned teams example 5 create record with restrictions scenario create or update a sensitive record restricted to specific users configuration select the application select key field confidential id set key field value $inputs confidentialid configure patch values as needed configure restrictions users \["admin\@example com", "manager\@example com"] groups \["security team"] result the record is created or updated with restrictions, making it accessible only to the specified users and groups best practices choose appropriate key field select a field that uniquely identifies records (e g , email, id, tracking number) avoid fields with duplicate values use append for arrays when working with array/multiselect fields, use append to preserve existing data rather than patch, which replaces the entire array use patch for single values use patch for string, number, and single select fields where you want to replace the existing value handle comments correctly comments fields only work with append operations, not patch use append to add comments validate key field value ensure the key field value is correctly formatted and matches the field type (string or number) test both paths test scenarios where records exist (update) and where they don't exist (create) to ensure both paths work correctly use restrictions wisely apply restrictions when creating sensitive records that should only be accessible to specific users or groups clear fields with null use patch with null values to clear string, numeric, and list fields troubleshooting record not found (expected create) verify the key field key is correct ensure the key field value matches the expected format check that the application contains the key field record found (expected create) the action updates existing records if a match is found if you want to always create new records, use the create record action instead array field not updating verify you're using append for array fields, not patch (unless you want to replace the entire array) check that the field type is array/multiselect ensure values are in array format \["value1", "value2"] append not working verify the field is an array/multiselect type check that you're not passing empty arrays or null values (these don't change anything) ensure values are properly formatted as arrays remove not working verify the field is an array/multiselect type check that the values you're removing exactly match existing array items ensure values are properly formatted as arrays patch overwriting arrays remember that patch replaces entire arrays use append to add items without removing existing ones if you need to both add and remove items, use append and remove together comments not updating comments fields only work with append operations, not patch use append to add comments to existing comment arrays key field value type error ensure the key field value matches the field type (string or number) verify the value is not null or undefined application not found verify the application id or name is correct ensure the application exists and is accessible check that application references are properly formatted