ACTION_ID: salesforce_upsert_record
NAME: Salesforce: Upsert Record
CATEGORY: sheets
CREDITS: 0

Upsert a record in Salesforce.

================================================================================
PREREQUISITE — USER ACTION REQUIRED
================================================================================

This action only works if the user has connected their Salesforce org
in Floqer. The connection cannot be made via the API or by an AI agent.

The user must do this themselves before this action will run:
  1. Sign in to Floqer at https://app.floqer.com
  2. Open the Connections page from the sidebar
  3. Click Salesforce and complete the OAuth flow

If the user has not connected Salesforce, this action will fail with a
connection / authentication error. Before configuring or running this
action, confirm with the user that the Salesforce connection exists.

INDEX:
  1. Inputs
  2. Outputs
  3. How to configure
  4. Key notes
  5. Where it fits in a workflow
  6. When to use
  7. When not to use

================================================================================
1. INPUTS
================================================================================

salesforce_object (dropdown, required)
  SalesForce Object. Choose the SalesForce Object.

salesforce_external_id_field (externalIdDropdown, required)
  SalesForce External Id Field. Choose the SalesForce External ID
  field for the Upsert Operation.

add_fields_and_their_values (jsonArray, required)
  Add Fields and their Values. Select Fields from the object and add
  Values (useful if your ORG has DuplicateRecord rules).

force_update_on_collision (radio, optional)
  Force update on collision. Force update the record if found
  duplicate.

ignore_empty_values (radio, optional)
  Ignore empty values. Default ON. If ON, empty Floqer fields won't
  replace existing values in Salesforce. If OFF, they will overwrite.

run_salesforce_assignment_rules (radio, optional)
  Run Salesforce assignment rules. Default ON.

================================================================================
2. OUTPUTS
================================================================================

record_id (string) — Record ID. Record ID of the record being
updated.
operation_type (string) — Operation Type. What type of operation was
performed (Insert or Update).
account_url (url) — Account URL. Salesforce Account URL. Placeholder:
  "https://test.my.salesforce.com".

================================================================================
3. HOW TO CONFIGURE
================================================================================

Resolve the dynamic field values via Get Action Field Options
before configuring:

  POST /api/v1/workflows/{workflow_id}/sheets/{sheet_id}/actions/{action_instance_id}/options/salesforce_object
       (body: {})
       → returns the list of objects on your Salesforce org.

  POST .../options/salesforce_external_id_field
       (body: { "context": { "salesforce_object": "Account" } })
       → external-ID-flagged fields on the chosen object.

  POST .../options/add_fields_and_their_values
       (body: { "context": { "salesforce_object": "Account" } })
       → all fields on the chosen object (use to pick column names).

Configure Action body:

{
  "inputs": {
    "salesforce_object": "Account",
    "salesforce_external_id_field": "Domain__c",
    "add_fields_and_their_values": [
      { "name": "Name",    "value": "{{input.company_name}}" },
      { "name": "Website", "value": "{{input.domain}}" }
    ],
    "force_update_on_collision": false,
    "ignore_empty_values": true,
    "run_salesforce_assignment_rules": true
  }
}

Field-by-field:
  - salesforce_object              Object name returned by the
                                   `salesforce_object` options call
                                   (e.g. "Account", "Contact", "Lead").
  - salesforce_external_id_field   External-ID field on the object
                                   (must be flagged as External ID
                                   in Salesforce). Used as the upsert
                                   match key.
  - add_fields_and_their_values    `[{name, value}]` — `name` is the
                                   field's API name (use the
                                   `add_fields_and_their_values` options
                                   call to list valid values); `value`
                                   accepts `{{ref}}` tokens or literals.
                                   Reference-translation runs per item.
  - force_update_on_collision      `true` → update existing record on
                                   match; `false` → skip on duplicate.
  - ignore_empty_values            Default `true`. When `true`, empty
                                   Floqer fields don't overwrite
                                   existing Salesforce values.
  - run_salesforce_assignment_rules Default `true`. Set `false` to skip
                                   Lead/Account/Case assignment rules
                                   on this write.

================================================================================
4. KEY NOTES
================================================================================

- The Salesforce connection must live on the API key's user
  account. If the connection lives under a different team member,
  Get Action Field Options returns a 424 — provision the API key
  from the user who owns the connection.
- The external ID field must be flagged "External ID" in Salesforce
  itself — only those fields appear in
  `options/salesforce_external_id_field`.
- Token refresh is automatic on auth errors; transient
  `INVALID_SESSION_ID` retries once before surfacing as a 502.
- `add_fields_and_their_values` is round-trip lossless: the
  `[{name, value}]` shape you pass is what comes back via Get
  Action.

================================================================================
5. WHERE IT FITS IN A WORKFLOW
================================================================================

Pattern: external system feeds {{external_id}} -> enrichment ->
salesforce_upsert_record (single-step idempotent sync).

================================================================================
6. WHEN TO USE
================================================================================

Use salesforce_upsert_record for idempotent sync from an external
system.

================================================================================
7. WHEN NOT TO USE
================================================================================

No external ID field configured
  -> salesforce_lookup_record + workflow_if_else +
     salesforce_create_record / salesforce_update_record
     (https://floqer.com/docs/action-detail/<action_id>.txt)

Need to always create
  -> salesforce_create_record
     (https://floqer.com/docs/action-detail/salesforce_create_record.txt)

================================================================================

This file is maintained manually. Last updated: 2026-04-28.
Full interactive reference: https://floqer.com/docs/reference
Action catalog: https://floqer.com/docs/action-catalog.txt