salesforce@5.0.4
- bulk(sObjectName, operation, records, [options])
- bulkQuery(query, [options])
- create(sObjectName, records)
- describe(sObjectName)
- destroy(sObjectName, ids, [options])
- get(path, [options])
- insert(sObjectName, records)
- post(path, data, [options])
- query(query, [options])
- request(path, [options])
- retrieve(sObjectName, id)
- update(sObjectName, records)
- upsert(sObjectName, externalId, records)
This adaptor exports the following namespaced functions:
This adaptor exports the following from common:
- alterState()
- arrayToString()
- chunk()
- combine()
- dataPath()
- dataValue()
- dateFns
- each()
- expandReferences()
- field()
- fields()
- fn()
- fnIf()
- group()
- http
- humanProper()
- index()
- join()
- jsonValue()
- lastReferenceValue()
- map()
- merge()
- referencePath()
- scrubEmojis()
- source()
- sourceValue()
- toArray()
Functions
bulk
bulk(sObjectName, operation, records, [options]) ⇒ Operation
Create and execute a bulk job. Nested relationships will be flattened to dot notation automatically. This function uses Bulk API, which is subject to rate limits.
Param | Type | Description |
---|---|---|
sObjectName | string | API name of the sObject. |
operation | string | The bulk operation to be performed.Eg insert , update or upsert |
records | array | an array of records, or a function which returns an array. |
[options] | BulkOptions | Options to configure the request. In addition to these, you can pass any of the options supported by the jsforce API. |
This operation writes the following keys to state:
State Key | Description |
---|---|
data | Summary of the response from Salesforce |
data.success | true if Salesforce reports no errors from the operation |
data.completed | Array of ids for every successful completion |
data.errors | Array of errors reported by Salesforce |
references | History of all previous states |
Example: Bulk insert
bulk(
"Patient__c",
"insert",
(state) => state.patients.map((x) => ({ Age__c: x.age, Name: x.name })),
{ failOnError: true }
);
Example: Bulk upsert
bulk(
"vera__Beneficiary__c",
"upsert",
[
{
vera__Reporting_Period__c: 2023,
vera__Geographic_Area__c: "Uganda",
"vera__Indicator__r.vera__ExtId__c": 1001,
vera__Result_UID__c: "1001_2023_Uganda",
},
],
{ extIdField: "vera__Result_UID__c" }
);
Example: Bulk upsert with a nested relationship
bulk(
"vera__Beneficiary__c",
"upsert",
[
{
vera__Reporting_Period__c: 2023,
"vera_Project": {
"Metrics_ID__c": "jfh5LAnxu1i4na"
}
},
],
{ extIdField: "vera__Result_UID__c" }
);
Example: Bulk update Account records using a lazy state reference
fn((state) => {
state.accounts = state.data.map((a) => ({ Id: a.id, Name: a.name }));
return state;
});
bulk("Account", "update", $.accounts, { failOnError: true });
bulkQuery
bulkQuery(query, [options]) ⇒ Operation
Execute an SOQL Bulk Query.
This function query large data sets and reduce the number of API requests.
bulkQuery()
uses Bulk API v2.0 Query which is available in API version 47.0 and later.
This API is subject to rate limits.
Param | Type | Description |
---|---|---|
query | string | A query string. |
[options] | BulkQueryOptions | Options passed to the bulk api. |
This operation writes the following keys to state:
State Key | Description |
---|---|
data | API response data. Can be either an object or array of objects |
references | History of all previous states |
Example: Bulk query patient records where "Health_ID__c" is equal to the value in "state.data.healthId"
bulkQuery(`SELECT Id FROM Patient__c WHERE Health_ID__c = '${$.data.healthId}'`);
Example: Bulk query with custom polling options
bulkQuery(
(state) =>
`SELECT Id FROM Patient__c WHERE Health_ID__c = '${state.data.field1}'`,
{ pollTimeout: 10000, pollInterval: 6000 }
);
create
create(sObjectName, records) ⇒ Operation
Create one or more new sObject records. Relationships in the record should be nested and not use dot-notation syntax
Param | Type | Description |
---|---|---|
sObjectName | string | API name of the sObject. |
records | Object | Array.<Object> | Field attributes for the new record, or an array of field attributes. |
This operation writes the following keys to state:
State Key | Description |
---|---|
data | Summary of the response from Salesforce |
data.success | true if Salesforce reports no errors from the operation |
data.completed | Array of ids for every successful completion |
data.errors | Array of errors reported by Salesforce |
references | History of all previous states |
Example: Single record creation
create("Account", { Name: "My Account #1" });
Example: Multiple records creation
create("Account",[{ Name: "My Account #1" }, { Name: "My Account #2" }]);
Example: Create records from data on state
create("Account",
$.data.map((account) => ({
Name: account.label
})
));
Example: Update a record with a relationship
create("Account", {
Name: "My Account #1" ,
"Project__r": {
"Metrics_ID__c": "jfh5LAnxu1i4na"
}
});
describe
describe(sObjectName) ⇒ Operation
Fetches and logs metadata for an sObject and pushes the result to state.data
.
If sObjectName
is not specified, it will print the total number of all available sObjects and push the result to state.data
.
Param | Type | Description |
---|---|---|
sObjectName | string | The API name of the sObject. If omitted, fetches metadata for all sObjects. |
This operation writes the following keys to state:
State Key | Description |
---|---|
data | API response data. Can be either an object or array of objects |
references | History of all previous states |
Example: Fetch metadata for all available sObjects
describe()
Example: Fetch metadata for Account sObject
describe('Account')
destroy
destroy(sObjectName, ids, [options]) ⇒ Operation
Delete records of an sObject.
Param | Type | Default | Description |
---|---|---|---|
sObjectName | string | API name of the sObject. | |
ids | string | Array.<string> | ID or array of IDs of records to delete | |
[options] | object | Options for the destroy delete operation. | |
[options.failOnError] | boolean | false | If true, the operation will fail if any record fails to delete. |
This operation writes the following keys to state:
State Key | Description |
---|---|
data | Summary of the response from Salesforce |
data.success | true if Salesforce reports no errors from the operation |
data.completed | Array of ids for every successful completion |
data.errors | Array of errors reported by Salesforce |
references | History of all previous states |
Example: Delete a single record
destroy("Account", "001XXXXXXXXXXXXXXX");
Example: Allow operation to fail if any record fails to delete
destroy("Account", ["001XXXXXXXXXXXXXXX", "001YYYYYYYYYYYYYYY"], {
failOnError: true,
});
Example: Using a state variable
fn((state) => {
state.data = ["001XXXXXXXXXXXXXXX", "001YYYYYYYYYYYYYYY"];
return state;
});
destroy("Account", $.data);
get
get(path, [options]) ⇒ Operation
Send a GET request on salesforce server configured in state.configuration
.
Param | Type | Description |
---|---|---|
path | string | The Salesforce API endpoint. |
[options] | SimpleRequestOptions | Configure headers and query parameters for the request. |
This operation writes the following keys to state:
State Key | Description |
---|---|
data | API response data. Can be either an object or array of objects |
references | History of all previous states |
Example: Make a GET request to a custom Salesforce flow
get('/actions/custom/flow/POC_OpenFN_Test_Flow');
Example: Make a GET request to a custom Salesforce flow with query parameters
get('/actions/custom/flow/POC_OpenFN_Test_Flow', { query: { Status: 'Active' } });
Example: Make a GET request then map the response
get('/jobs/query/v1/jobs/001XXXXXXXXXXXXXXX/results', (state) => {
// Mapping the response
state.mapping = state.data.map(d => ({ name: d.name, id: d.extId }));
return state;
});
insert
insert(sObjectName, records) ⇒ Operation
Alias for "create(sObjectName, records)".
Param | Type | Description |
---|---|---|
sObjectName | string | API name of the sObject. |
records | Object | Array.<Object> | Field attributes for the new record, or an array of field attributes. |
This operation writes the following keys to state:
State Key | Description |
---|---|
data | API response data. Can be either an object or array of objects |
references | History of all previous states |
Example: Single record creation
insert("Account", { Name: "My Account #1" });
Example: Multiple records creation
insert("Account",[{ Name: "My Account #1" }, { Name: "My Account #2" }]);
Example: Using a state variable
fn((state) => {
state.data = [{ Name: "My Account #1" }, { Name: "My Account #2" }];
return state;
});
insert("Account", $.data);
post
post(path, data, [options]) ⇒ Operation
Send a POST request to salesforce server configured in state.configuration
.
Param | Type | Description |
---|---|---|
path | string | The Salesforce API endpoint. |
data | object | A JSON Object request body. |
[options] | SimpleRequestOptions | Configure headers and query parameters for the request. |
This operation writes the following keys to state:
State Key | Description |
---|---|
data | API response data. Can be either an object or array of objects |
references | History of all previous states |
Example: Make a POST request to a custom Salesforce flow
post("/actions/custom/flow/POC_OpenFN_Test_Flow", {
body: {
inputs: [
{
CommentCount: 6,
FeedItemId: "0D5D0000000cfMY",
},
],
},
});
query
query(query, [options]) ⇒ Operation
Executes an SOQL (Salesforce Object Query Language) query to retrieve records from Salesforce. This operation uses for querying salesforce records using SOQL query and handles pagination. Note that in an event of a query error, error logs will be printed but the operation will not throw the error.
The Salesforce query API is subject to rate limits, learn more here.
Param | Type | Description |
---|---|---|
query | string | function | A SOQL query string or a function that returns a query string. Must be less than 4000 characters in WHERE clause |
[options] | QueryOptions | Optional configuration for the query operation |
This operation writes the following keys to state:
State Key | Description |
---|---|
data | API response data. Can be either an object or array of objects |
references | History of all previous states |
Properties
Name | Description |
---|---|
data | Array of result objects of the form { done, totalSize, records } |
Example: Run a query and download all matching records
query('SELECT Id FROM Patient__c', { autoFetch: true });
Example: Query patients by Health ID
query(state => `SELECT Id FROM Patient__c WHERE Health_ID__c = '${state.data.healthId}'`);
Example: Query patients by Health ID using a lazy state reference
query(`SELECT Id FROM Patient__c WHERE Health_ID__c = '${$.data.healthId}'`);
request
request(path, [options]) ⇒ Operation
Send a request to salesforce server configured in state.configuration
.
Param | Type | Description |
---|---|---|
path | string | The Salesforce API endpoint. |
[options] | FullRequestOptions | Configure headers, query and body parameters for the request. |
This operation writes the following keys to state:
State Key | Description |
---|---|
data | API response data. Can be either an object or array of objects |
references | History of all previous states |
Example: Make a POST request to a custom Salesforce flow
request("/actions/custom/flow/POC_OpenFN_Test_Flow", {
method: "POST",
json: { inputs: [{}] },
});
retrieve
retrieve(sObjectName, id) ⇒ Operation
Retrieves a Salesforce sObject(s).
Param | Type | Description |
---|---|---|
sObjectName | string | The sObject to retrieve |
id | string | The id of the record |
This operation writes the following keys to state:
State Key | Description |
---|---|
data | API response data. Can be either an object or array of objects |
references | History of all previous states |
Example: Retrieve a specific ContentVersion record
retrieve('ContentVersion', '0684K0000020Au7QAE/VersionData');
update
update(sObjectName, records) ⇒ Operation
Update an sObject record or records. Relationships in the record should be nested and not use dot-notation syntax
Param | Type | Description |
---|---|---|
sObjectName | string | API name of the sObject. |
records | object | Array.<object> | Field attributes for the new object. |
This operation writes the following keys to state:
State Key | Description |
---|---|
data | Summary of the response from Salesforce |
data.success | true if Salesforce reports no errors from the operation |
data.completed | Array of ids for every successful completion |
data.errors | Array of errors reported by Salesforce |
references | History of all previous states |
Example: Single record update
update("Account", {
Id: "0010500000fxbcuAAA",
Name: "Updated Account #1",
});
Example: Multiple records update
update("Account", [
{ Id: "0010500000fxbcuAAA", Name: "Updated Account #1" },
{ Id: "0010500000fxbcvAAA", Name: "Updated Account #2" },
]);
Example: Update a record with a relationship
update("Account", {
Id: "0010500000fxbcuAAA",
"Project__r": {
"Metrics_ID__c": "jfh5LAnxu1i4na"
}
});
upsert
upsert(sObjectName, externalId, records) ⇒ Operation
Create a new sObject record, or updates it if it already exists. Relationships in the record should be nested and not use dot-notation syntax
Param | Type | Description |
---|---|---|
sObjectName | string | API name of the sObject. |
externalId | string | The external ID of the sObject. |
records | Object | Array.<Object> | Field attributes for the records to upsert, or an array of field attributes. |
This operation writes the following keys to state:
State Key | Description |
---|---|
data | API response data. Can be either an object or array of objects |
references | History of all previous states |
Example: Single record upsert
upsert("UpsertTable__c", "ExtId__c", { Name: "Record #1", ExtId__c : 'ID-0000001' });
Example: Multiple record upsert
upsert("UpsertTable__c", "ExtId__c", [
{ Name: "Record #1", ExtId__c : 'ID-0000001' },
{ Name: "Record #2", ExtId__c : 'ID-0000002' },
]);
Example: Update a record with a relationship
upsert("UpsertTable__c", {
Name: "Record #1",
"Project__r": {
"Metrics_ID__c": "jfh5LAnxu1i4na"
}
});
util
These functions belong to the util namespace.
util.toUTF8
toUTF8(input) ⇒ string
Transliterates unicode characters to their best ASCII representation
Returns: string
- - ASCII representation of input string
Param | Type | Description |
---|---|---|
input | string | A string with unicode characters |
Example: Transliterate άνθρωποι
to anthropoi
fn((state) => {
const s = util.toUTF8("άνθρωποι");
console.log(s); // anthropoi
return state;
});
Interfaces
BulkOptions
Options provided to the Salesforce bulk API request
Properties
Name | Type | Default | Description |
---|---|---|---|
extIdField | string | External id field. Required for upsert. | |
[allowNoOp] | boolean | false | Skipping bulk operation if no records. |
[failOnError] | boolean | false | Fail the operation on error. |
[pollTimeout] | integer | 240000 | Polling timeout in milliseconds. |
[pollInterval] | integer | 6000 | Polling interval in milliseconds. |
BulkQueryOptions
Options provided to the Salesforce bulk query API request
Properties
Name | Type | Default | Description |
---|---|---|---|
[pollTimeout] | integer | 90000 | Polling timeout in milliseconds. |
[pollInterval] | integer | 3000 | Polling interval in milliseconds. |
FullRequestOptions
Options provided to the Salesforce HTTP request
Properties
Name | Type | Default | Description |
---|---|---|---|
[method] | string | "GET" | HTTP method to use. |
headers | object | Object of request headers. | |
query | object | Object request query. | |
json | object | Object request body. | |
body | string | A string request body. |
QueryOptions
Properties
Name | Type | Default | Description |
---|---|---|---|
[autoFetch] | boolean | false | When true, automatically fetches next batch of records if available. |
SimpleRequestOptions
Properties
Name | Type | Description |
---|---|---|
headers | object | Object of request headers. |
query | object | Object of request query. |