Ctrlk
YouTube ChannelBook A Demo🪄 Build with AIJoin The Community
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Upsert Record

The Upsert Record interaction creates a new Salesforce record or updates an existing one using the values in a record variable.

Overview

The Upsert Record interaction is a smart "Create or Update" action. It automatically determines whether to create a new record or update an existing one based on the presence of a Record ID in the variable.

  • If the Record ID exists: The system performs an Update.

  • If the Record ID is missing (null): The system performs a Create.

This interaction is perfect for reusable forms (e.g., a "Contact Details" modal) that serve dual purposes: adding new records and editing existing ones.

Configuration

Because Upsert handles both creation and updates, the configuration relies heavily on how you supply the record. You can bind a Record Variable, or choose "Enter Records Data Manually" to provide a Record Id, Object API Name, and field mappings directly (see Method 3).

Method 1: Upserting via Target Page Context

Use this method if you are building a component that might be placed on a record page (to edit) or might be initialized without a record context (though this is less common for Upsert than Method 2).

1. Define the Context

  • Open your Dynamic Component's Settings (gear icon ⚙️).

  • Set the Target Page Object (e.g., Account).

2. Configure the Interaction

  • Add an Avonni Button component (e.g., "Save").

  • Add an On Click interaction.

  • Action Type: Select Upsert Record.

  • Record Variable: Select Target Page Record.

    • Behavior: If the component is on a Record Page, it updates that record. If the component is somehow loaded without an ID (e.g., in a preview or specific app context where ID is null), it attempts to create.

Method 2: Upserting a Custom Record Variable (Most Common)

This is the standard use case for custom forms. You use a single variable that starts empty (for new records) or gets populated with data (for existing records).

1. Define the Variable Create a Record Variable (e.g., contactData) for the object you are working with.

2. Populate the Variable (The "Smart" Part)

  • Scenario A (New Record): If the user is adding a new item, ensure the variable is empty or initialized without an ID.

  • Scenario B (Edit Record): If the user is editing an item, use On Load > Get Records (or a Set Variable action) to load the existing data—specifically the Record ID—into the contactData variable.

3. Configure the Interaction

  • Add an Avonni Button component.

  • Add an On Click interaction.

  • Action Type: Select Upsert Record.

  • Record Variable: Select your variable (e.g., {!contactData}).

Method 3: Upserting a Record by ID Manually

You can also upsert without binding to a Record Variable by providing the record details directly:

  • Record Variable: Select the manual option.

  • Record ID: The Salesforce record ID to upsert (leave empty to create a new record).

  • Object API Name: The object of the record you are upserting (e.g., Account, Case, or a custom object).

Field Mappings

You can supply field/value mappings that are applied to the record. When a Record Variable is selected, these mappings are merged into its values (overriding matching fields); in manual mode, they are how you provide the record's field values. Each mapping is a Field (a valid field API name on the object) and a Value (a literal, or a {{Record.FieldName}} reference when the interaction is triggered by a record-related item).

Follow-up Interactions

  • On Success: The interactions to execute when the record is upserted successfully.

  • On Error: The interactions to execute when the upsert fails.

Accepted follow-up interactions for both outcomes are: Show Toast, Refresh All Queries, Refresh Query, Get Record, and Assignment.

Example

Imagine a "Manage Address" form.

  1. User clicks "Add New Address":

    • You clear the addressData variable.

    • User fills the form.

    • User clicks Save (Upsert).

    • Result: System sees no ID. -> Creates a new record.

  2. User clicks "Edit" on an existing Address:

    • You fetch that address record into the addressData variable (including its ID).

    • User modifies the Street field.

    • User clicks Save (Upsert).

    • Result: System sees an ID. -> Updates that specific record.

Important Considerations

The Importance of the ID Field The logic is strictly binary:

  • ID present? -> Update.

  • No ID? -> Create.

  • Warning: If you fetch a record but forget to query the Id field, the system will not see an ID and will attempt to create a duplicate record instead of updating the existing one.

External ID Support Currently, the Avonni Upsert interaction primarily supports standard Salesforce Record IDs (Id field) for determining the operation. It does not support upserting based on custom External ID fields in the same way Data Loader does.

Last updated

Was this helpful?