Skip to main content

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:

util.toUTF8(input)

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.

ParamTypeDescription
sObjectNamestringAPI name of the sObject.
operationstringThe bulk operation to be performed.Eg insert, update or upsert
recordsarrayan array of records, or a function which returns an array.
[options]BulkOptionsOptions 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 KeyDescription
dataSummary of the response from Salesforce
data.successtrue if Salesforce reports no errors from the operation
data.completedArray of ids for every successful completion
data.errorsArray of errors reported by Salesforce
referencesHistory 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.

ParamTypeDescription
querystringA query string.
[options]BulkQueryOptionsOptions passed to the bulk api.

This operation writes the following keys to state:

State KeyDescription
dataAPI response data. Can be either an object or array of objects
referencesHistory 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

ParamTypeDescription
sObjectNamestringAPI name of the sObject.
recordsObject | Array.<Object>Field attributes for the new record, or an array of field attributes.

This operation writes the following keys to state:

State KeyDescription
dataSummary of the response from Salesforce
data.successtrue if Salesforce reports no errors from the operation
data.completedArray of ids for every successful completion
data.errorsArray of errors reported by Salesforce
referencesHistory 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.

ParamTypeDescription
sObjectNamestringThe API name of the sObject. If omitted, fetches metadata for all sObjects.

This operation writes the following keys to state:

State KeyDescription
dataAPI response data. Can be either an object or array of objects
referencesHistory 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.

ParamTypeDefaultDescription
sObjectNamestringAPI name of the sObject.
idsstring | Array.<string>ID or array of IDs of records to delete
[options]objectOptions for the destroy delete operation.
[options.failOnError]booleanfalseIf true, the operation will fail if any record fails to delete.

This operation writes the following keys to state:

State KeyDescription
dataSummary of the response from Salesforce
data.successtrue if Salesforce reports no errors from the operation
data.completedArray of ids for every successful completion
data.errorsArray of errors reported by Salesforce
referencesHistory 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.

ParamTypeDescription
pathstringThe Salesforce API endpoint.
[options]SimpleRequestOptionsConfigure headers and query parameters for the request.

This operation writes the following keys to state:

State KeyDescription
dataAPI response data. Can be either an object or array of objects
referencesHistory 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)".

ParamTypeDescription
sObjectNamestringAPI name of the sObject.
recordsObject | Array.<Object>Field attributes for the new record, or an array of field attributes.

This operation writes the following keys to state:

State KeyDescription
dataAPI response data. Can be either an object or array of objects
referencesHistory 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.

ParamTypeDescription
pathstringThe Salesforce API endpoint.
dataobjectA JSON Object request body.
[options]SimpleRequestOptionsConfigure headers and query parameters for the request.

This operation writes the following keys to state:

State KeyDescription
dataAPI response data. Can be either an object or array of objects
referencesHistory 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.

ParamTypeDescription
querystring | functionA SOQL query string or a function that returns a query string. Must be less than 4000 characters in WHERE clause
[options]QueryOptionsOptional configuration for the query operation

This operation writes the following keys to state:

State KeyDescription
dataAPI response data. Can be either an object or array of objects
referencesHistory of all previous states

Properties

NameDescription
dataArray 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.

ParamTypeDescription
pathstringThe Salesforce API endpoint.
[options]FullRequestOptionsConfigure headers, query and body parameters for the request.

This operation writes the following keys to state:

State KeyDescription
dataAPI response data. Can be either an object or array of objects
referencesHistory 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).

ParamTypeDescription
sObjectNamestringThe sObject to retrieve
idstringThe id of the record

This operation writes the following keys to state:

State KeyDescription
dataAPI response data. Can be either an object or array of objects
referencesHistory 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

ParamTypeDescription
sObjectNamestringAPI name of the sObject.
recordsobject | Array.<object>Field attributes for the new object.

This operation writes the following keys to state:

State KeyDescription
dataSummary of the response from Salesforce
data.successtrue if Salesforce reports no errors from the operation
data.completedArray of ids for every successful completion
data.errorsArray of errors reported by Salesforce
referencesHistory 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

ParamTypeDescription
sObjectNamestringAPI name of the sObject.
externalIdstringThe external ID of the sObject.
recordsObject | Array.<Object>Field attributes for the records to upsert, or an array of field attributes.

This operation writes the following keys to state:

State KeyDescription
dataAPI response data. Can be either an object or array of objects
referencesHistory 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

ParamTypeDescription
inputstringA 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

NameTypeDefaultDescription
extIdFieldstringExternal id field. Required for upsert.
[allowNoOp]booleanfalseSkipping bulk operation if no records.
[failOnError]booleanfalseFail the operation on error.
[pollTimeout]integer240000Polling timeout in milliseconds.
[pollInterval]integer6000Polling interval in milliseconds.

BulkQueryOptions

Options provided to the Salesforce bulk query API request

Properties

NameTypeDefaultDescription
[pollTimeout]integer90000Polling timeout in milliseconds.
[pollInterval]integer3000Polling interval in milliseconds.

FullRequestOptions

Options provided to the Salesforce HTTP request

Properties

NameTypeDefaultDescription
[method]string"GET"HTTP method to use.
headersobjectObject of request headers.
queryobjectObject request query.
jsonobjectObject request body.
bodystringA string request body.

QueryOptions

Properties

NameTypeDefaultDescription
[autoFetch]booleanfalseWhen true, automatically fetches next batch of records if available.

SimpleRequestOptions

Properties

NameTypeDescription
headersobjectObject of request headers.
queryobjectObject of request query.