Salesforce composite upsert Sink
Provided by: "Apache Software Foundation"
Support Level for this Kamelet is: "Stable"
Creates or updates many Salesforce records of one kind in a single call, matching each record to an existing one by an external ID field.
Use it to copy a batch of customers, products or orders from another system into Salesforce without creating duplicates: a record whose external ID is already in Salesforce is updated, the others are created. To create or change one record at a time, use salesforce-create-sink or salesforce-update-sink.
Input: the body is JSON text with a records list. Each record gives its kind in attributes, such as {"attributes": {"type": "Contact"}, "External_Id__c": "C-1", "LastName": "Lovelace"}, and holds the external ID field named by sObjectIdName with its value, and the fields to set. Salesforce accepts up to 200 records in one call.
Output: when it is used inside a route, the body afterwards is a List with one result per record, in the same order, each with id, success, created (true for a new record) and errors.
Good to know: a record that Salesforce refuses does not fail the message, and the other records are still saved: check success in the results. Headers that start with CamelSalesforce are removed from the message first, so they cannot change what the Kamelet does.
Configuration Options
The following table summarizes the configuration options available for the salesforce-composite-upsert-sink Kamelet:
| Property | Name | Description | Type | Default | Example |
|---|---|---|---|---|---|
Consumer Key | Required The consumer key of the connected app that the Kamelet logs in through. In Salesforce Setup, open App Manager, choose View on the app, then Manage Consumer Details. | string | |||
Consumer Secret | Required The consumer secret of the same connected app, shown next to the consumer key under Manage Consumer Details. | string | |||
External ID Field | Required The API name of the field that matches each record to an existing one, such as | string | External_Id__c | ||
Object Name | Required The API name of the kind of the records, such as | string | Contact | ||
Authentication Type | How the Kamelet logs in. Enum values: * USERNAME_PASSWORD * CLIENT_CREDENTIALS * REFRESH_TOKEN * JWT | string | USERNAME_PASSWORD | ||
Instance URL | The address of your org, such as | string | https://myinstance.my.salesforce.com | ||
JWT Audience | The audience of the JWT that the Kamelet signs to log in: | string | https://login.salesforce.com | ||
Keystore | A reference to a bean of type | string | #bean:myKeystore | ||
Login URL | The address the Kamelet logs in to. Keep the default for a production org, use | string | https://test.salesforce.com | ||
Password | The password of | string | |||
Refresh Token | A refresh token of the connected app for the user to act as, obtained once through an OAuth login in a browser with the | string | |||
Username | The user name of the Salesforce user to log in as, which looks like an email address. Used by the | string |
Dependencies
At runtime, the salesforce-composite-upsert-sink Kamelet relies upon the presence of the following dependencies:
-
camel:jsonpath
-
camel:jackson3
-
camel:salesforce
-
camel:kamelet
Camel JBang usage
Prerequisites
-
You’ve installed JBang.
-
You have executed the following command:
jbang app install camel@apache/camel Supposing you have a file named route.yaml with this content:
- route:
from:
uri: "kamelet:timer-source"
parameters:
period: 10000
message: 'test'
steps:
- to:
uri: "kamelet:salesforce-composite-upsert-sink" You can now run it directly through the following command
camel run route.yaml Salesforce Composite Upsert Sink Kamelet Description
Salesforce CRM Integration
This Kamelet integrates with Salesforce CRM using the composite upsert operation of the sObject Collections API. Several records are processed in a single API call, which reduces API usage.
Upsert Operations
Performs upsert (insert or update) operations: a record whose external ID is already in Salesforce is updated, and the others are created. This avoids duplicate records when the same data is sent again.
Input Format
The body is JSON text with a records list. All the records are of the kind named by sObjectName, and each one holds the external ID field named by sObjectIdName:
{
"records": [
{ "attributes": { "type": "Contact" }, "External_Id__c": "C-1", "LastName": "Lovelace" },
{ "attributes": { "type": "Contact" }, "External_Id__c": "C-2", "LastName": "Hopper" }
]
} Salesforce accepts up to 200 records in one call.
External ID Matching
Uses an external ID field for record matching, so that records keep the IDs of the system they come from. The field must be marked as External ID in Salesforce.
Error Handling
The Kamelet does not use all-or-none: a record that Salesforce refuses does not fail the message, and the other records are still saved. The result is a list with one entry per record, in the same order, each with id, success, created (true for a new record) and errors.
API Authentication
The Kamelet logs in through a connected app of your org. Create one in Salesforce Setup, under App Manager, with OAuth enabled, and copy its consumer key and secret into clientId and clientSecret. authenticationType chooses how the Kamelet logs in, and which other options it needs.