---
title: Update/Create Record
slug: updatecreate-record
docTags: 
createdAt: 2025-08-11T11:13:48.000Z
---

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

1. **Search Phase:** The action searches for an existing record where the `keyFieldKey` field matches the `keyFieldValue`.
2. **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.
3. **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

1. 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

1. Click **Select key field** to open the application form.
2. Select **one field** to use as the unique identifier.
3. This field will be used to search for existing records.

::Image[]{src="https://app.archbee.com/api/optimize/511c8QBH-VHiwWnyzIwUb/5lswxusm87nsVi6cF4reb_upsert-map-fields.png" size="80" width="1068" height="742" darkWidth="1068" darkHeight="742" position="center" alt="Select Key Field" showCaption="false"}

### Step 3: Configure Key Field Value

1. 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)

1. Add fields to the **Patch Values** section.
2. Map values to each field:
   - Click the **+** icon next to each field
   - Select a playbook property, enter a static value, or write an expression
3. **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)

1. Add array/multiselect fields to the **Append Values** section.
2. Map values to append:
   - Click the **+** icon next to each field
   - Select a playbook property, enter a static value, or write an expression
3. **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)

1. Add array/multiselect fields to the **Remove Values** section.
2. Map values to remove:
   - Click the **+** icon next to each field
   - Select a playbook property, enter a static value, or write an expression
3. **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:

1. Expand the **Restrictions** section.
2. Add **Users**: Enter user IDs or usernames (can be static or from expressions).
3. 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.

::Image[]{src="https://app.archbee.com/api/optimize/511c8QBH-VHiwWnyzIwUb/PF8RC3R7i6ZWomUSgC1v4_crud-update-record.png" size="80" width="975" height="730" darkWidth="975" darkHeight="730" position="center" alt="Update/Create Record Configuration" showCaption="false"}

## 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

::Image[]{src="https://app.archbee.com/api/optimize/511c8QBH-VHiwWnyzIwUb/PF8RC3R7i6ZWomUSgC1v4_crud-update-record.png" size="80" width="975" height="730" darkWidth="975" darkHeight="730" position="center" showCaption="false"}

## Use Cases

### Example 1: Upsert Record by Email Address

**Scenario:** Create or update a user record based on email address.

**Configuration:**

1. Select the application (e.g., "User Management").
2. Select **Key Field**: `email-address`
3. Set **Key Field Value**: `$inputs.userEmail` (or from upstream action)
4. Configure **Patch Values**:
   - `first-name`: `$inputs.firstName`
   - `last-name`: `$inputs.lastName`
   - `status`: `"Active"`
5. 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:**

1. Select the application.
2. Select **Key Field**: `case-id`
3. Set **Key Field Value**: `$actions.createCase.result['tracking-id']`
4. 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:**

1. Select the application.
2. Select **Key Field**: `record-id`
3. Set **Key Field Value**: `$inputs.recordId`
4. 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:**

1. Select the application.
2. Select **Key Field**: `incident-id`
3. Set **Key Field Value**: `$event.data.incidentId`
4. Configure **Patch Values**:
   - `status`: `"Resolved"`
   - `priority`: `"Low"`
5. Configure **Append Values**:
   - `notes`: `[$event.data.resolutionNote]` (adds note without removing existing notes)
6. 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:**

1. Select the application.
2. Select **Key Field**: `confidential-id`
3. Set **Key Field Value**: `$inputs.confidentialId`
4. Configure **Patch Values** as needed.
5. 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.