Salesforce - Upsert Record

↩ Part of the Salesforce integration.

Description

Creates or updates a record identified by an external id field (PATCH /sobjects/{sobject}/{extField}/{extValue}).

Salesforce decides for you: if a record already carries that external value it is updated, otherwise a new one is created. It is the node to use when you sync from another system — an ERP, a shop, a database — and you hold their key, not the Salesforce id.

Because the same call is safe to repeat, an upsert is also the way to make a flow idempotent: running it twice does not create two records.

Configuration

Field	Type	Required	Description
`credentials_id`	credentials	Yes	Salesforce credential
`sobject`	text	Yes	API name of the object: `Account`, `Contact`, `Lead`…
`external_id_field`	text	Yes	External id field, e.g. `ExternalId__c`
`external_id_value`	text	Yes	Value of the external id to match on
`fields`	json	Yes	Record fields

All the parameters accept dynamic variables; the fields string is resolved as text before being parsed as JSON.

Credentials

This module requires a Salesforce credential:

Field	Description
`login_url`	`https://login.salesforce.com` or `https://test.salesforce.com` for a sandbox
`client_id` / `client_secret`	Consumer Key and Secret of the Connected App
`username`	Salesforce user
`password`	Password plus the security token, concatenated

Output

When Salesforce creates the record it answers 201 with a body, and data looks like this:

{
  "id": "0015g00000AbCdEFGH",
  "success": true,
  "created": true
}

When it updates an existing record it answers 204 with no body, so the node builds the confirmation itself:

{
  "external_id": "ERP-10045",
  "upserted": true,
  "created": false
}

Along with it, _meta:

{ "moduleVersion": "1.0.0", "success": true, "id": "0015g00000AbCdEFGH", "created": true, "totalMs": 410 }

Branch on created to tell an insert from an update. Note that on the update path there is no id in the output — read the record with Get record or a SOQL query if you need it.

Usage Example

Account synced from an ERP

{
  "credentials_id": "salesforce_prod",
  "sobject": "Account",
  "external_id_field": "ERP_Code__c",
  "external_id_value": "{{data.erpCode}}",
  "fields": {
    "Name": "{{data.name}}",
    "Phone": "{{data.phone}}",
    "BillingCity": "{{data.city}}"
  }
}

Contact keyed by email

{
  "credentials_id": "salesforce_prod",
  "sobject": "Contact",
  "external_id_field": "External_Email__c",
  "external_id_value": "{{data.email}}",
  "fields": {
    "FirstName": "{{data.firstName}}",
    "LastName": "{{data.lastName}}",
    "Email": "{{data.email}}"
  }
}

Custom object from a shop

{
  "credentials_id": "salesforce_prod",
  "sobject": "Subscription__c",
  "external_id_field": "Shop_Order_Id__c",
  "external_id_value": "{{data.orderId}}",
  "fields": {
    "Status__c": "Active",
    "Amount__c": "{{data.total}}"
  }
}

Notes

The field named in external_id_field must be marked as External ID in Salesforce (Setup → Object Manager → Fields → External ID). A regular field returns 400 NOT_FOUND or INVALID_FIELD.
Mark the field as Unique too. If several records share the value, Salesforce answers 300 Multiple Choices and the upsert fails.
Do not repeat the external id inside fields; it already travels in the URL.
Standard Email on a Contact is not an external id. To key on an email you need a custom External ID field, as in the second example.
The rest of the rules of an update apply: validation rules fire, read-only fields are rejected, and those 400 errors are not retried.

Salesforce: Create record — when you always want a new record.
Salesforce: Update record — when you already hold the Salesforce id.
Salesforce: SOQL query — recover the id after an update-path upsert.