salesforce@7.2.0

bulk(sObjectName, operation, records, [options])

bulkQuery(query, [options])

create(sObjectName, records)

describe(sObjectName)

destroy(sObjectName, ids, [options])

insert(sObjectName, records)

query(query, [options])

retrieve(sObjectName, id)

update(sObjectName, records)

upsert(sObjectName, externalId, records)

This adaptor exports the following namespaced functions:

bulk2.destroy(sObject, records, [options])

bulk2.insert(sObject, records, [options])

bulk2.query(query, options)

bulk2.update(sObject, records, [options])

bulk2.upsert(sObject, externalIdFieldName, records, [options])

http.get(path, [options])

http.post(path, body, [options])

http.request(path, [options])

util.toUTF8(input)

This adaptor exports the following from common:

alterState()

arrayToString()

as()

chunk()

combine()

dataPath()

dataValue()

dateFns

each()

field()

fields()

fn()

fnIf()

group()

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);

---

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);

---

query

query(query, [options]) ⇒ Operation

Executes an SOQL (Salesforce Object Query Language) query to retrieve records from Salesforce. 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	Default	Description
query	string		A SOQL query string. Must be less than 4000 characters in WHERE clause
[options]	object		Query options
[options.limit]	number	10000	Maximum number of records to fetch. If limit: Infinity is passed, all records will be fetched.

This operation writes the following keys to state:

State Key	Description
data	Array of result objects
references	History of all previous states
response	An object of result metadata. { done, totalSize, nextRecordsUrl?: string } where nextRecordsUrl is only present when done is false

Example: Run a query and download all matching records

query('SELECT Id FROM Patient__c', { limit: Infinity });

Example: Run a query and limit records

query('SELECT Id From Account Limit 10');

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}'`);

---

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"
  }
});

---

bulk2

These functions belong to the bulk2 namespace.

bulk2.destroy

destroy(sObject, records, [options]) ⇒ Operation

Bulk deletes records using Salesforce Bulk API 2.0

Param	Type	Description
sObject	string	The Salesforce object type
records	Array	Array of records to delete
[options]	Bulk2LoadOptions	Bulk delete options

This operation writes the following keys to state:

State Key	Description
data	The processed records or results from the bulk insert operation
data.successfulResults	Array of successful results
data.failedResults	Array of failed results
data.unprocessedRecords	Array of unprocessed records
references	Array of previous state data objects used in the job

Example: Delete records

bulk2.destroy("Account", [
  "0010500000fxbcuAAA",
  "0010500000fxbcvAAA",
]);

Example: Delete records with custom options

bulk2.destroy(
  "Account",
  [
    "0010500000fxbcuAAA",
    "0010500000fxbcvAAA",
  ],
  {
    pollInterval: 1000,
    pollTimeout: 3000,
  }
);

---

bulk2.insert

insert(sObject, records, [options]) ⇒ Operation

Bulk inserts records using Salesforce Bulk API 2.0

Param	Type	Description
sObject	string	The Salesforce object type
records	Array	Array of records to insert
[options]	Bulk2LoadOptions	Bulk insert options

This operation writes the following keys to state:

State Key	Description
data	The processed records or results from the bulk insert operation
data.successfulResults	Array of successful results
data.failedResults	Array of failed results
data.unprocessedRecords	Array of unprocessed records
references	Array of previous state data objects used in the job

Example: Insert multiple records

bulk2.insert('Account', [{ Name: 'Coco' }, { Name: 'Melon' }]);

Example: Insert with custom options

bulk2.insert('Account', [{ Name: 'Coco' }, { Name: 'Melon' }], {
  pollInterval: 1000,
  pollTimeout: 3000,
});

---

bulk2.query

query(query, options) ⇒ Operation

Executes a bulk query using Salesforce Bulk API 2.0

Param	Type	Description
query	string	SOQL query string to execute
options	QueryOptions	Query options

This operation writes the following keys to state:

State Key	Description
data	The processed records or query results from the Bulk API operation
references	Array of previous state data objects used in the job

Example: Query records

bulk2.query('SELECT Id, Name FROM Account');

Example: Query with scanAll enabled

bulk2.query('SELECT Id, Name FROM Account', { scanAll: true });

Example: Query with custom options

bulk2.query(
  'SELECT Id, Name FROM Account',
  {
    scanAll: true,
    pollInterval: 1000,
    pollTimeout: 3000,
  }
);

---

bulk2.update

update(sObject, records, [options]) ⇒ Operation

Bulk updates records using Salesforce Bulk API 2.0

Param	Type	Description
sObject	string	The Salesforce object type
records	Array	Array of records to update
[options]	Bulk2LoadOptions	Bulk update options

This operation writes the following keys to state:

State Key	Description
data	The processed records or results from the bulk insert operation
data.successfulResults	Array of successful results
data.failedResults	Array of failed results
data.unprocessedRecords	Array of unprocessed records
references	Array of previous state data objects used in the job

Example: Update records

bulk2.update("Account", [
  { Id: "0010500000fxbcuAAA", Name: "Updated Account #1" },
  { Id: "0010500000fxbcvAAA", Name: "Updated Account #2" },
]);

Example: Update records with custom options

bulk2.update(
  "Account",
  [
    { Id: "0010500000fxbcuAAA", Name: "Updated Account #1" },
    { Id: "0010500000fxbcvAAA", Name: "Updated Account #2" },
  ],
  {
    pollInterval: 1000,
    pollTimeout: 3000,
  }
);

---

bulk2.upsert

upsert(sObject, externalIdFieldName, records, [options]) ⇒ Operation

Bulk upserts records using Salesforce Bulk API 2.0

Param	Type	Description
sObject	string	The Salesforce object type
externalIdFieldName	string	External ID field name for upsert matching
records	Array	Array of records to upsert
[options]	Bulk2LoadOptions	Bulk upsert options

This operation writes the following keys to state:

State Key	Description
data	The processed records or results from the bulk insert operation
data.successfulResults	Array of successful results
data.failedResults	Array of failed results
data.unprocessedRecords	Array of unprocessed records
references	Array of previous state data objects used in the job

Example: Upsert records

bulk2.upsert("UpsertTable__c", "ExtId__c", [
  { Name: "Record #1", ExtId__c : 'ID-0000001' },
  { Name: "Record #2", ExtId__c : 'ID-0000002' },
]);

Example: Upsert records with custom options

bulk2.upsert(
  "UpsertTable__c",
  "ExtId__c",
  [
    { Name: "Record #1", ExtId__c : 'ID-0000001' },
    { Name: "Record #2", ExtId__c : 'ID-0000002' },
  ],
  {
    pollInterval: 1000,
    pollTimeout: 3000,
  }
);

---

http

These functions belong to the http namespace.

http.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

http.get('/actions/custom/flow/POC_OpenFN_Test_Flow');

Example: Make a GET request to a custom Salesforce flow with query parameters

http.get('/actions/custom/flow/POC_OpenFN_Test_Flow', { query: { Status: 'Active' } });

Example: Make a GET request then map the response

http.get("/jobs/query/v1/jobs/001XXXXXXXXXXXXXXX/results").then((state) => {
  state.mapping = state.data.map((d) => ({ name: d.name, id: d.extId }));
  return state;
});

---

http.post

post(path, body, [options]) ⇒ Operation

Send a POST request to salesforce server configured in state.configuration.

Param	Type	Description
path	string	The Salesforce API endpoint.
body	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: POST request to Salesforce

http.post("/jobs/query", {
  operation: "query",
  query: "SELECT Id, Name FROM Account LIMIT 1000",
});

---

http.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

http.request("/actions/custom/flow/POC_OpenFN_Test_Flow", {
  method: "POST",
  body: { inputs: [{}] },
});

---

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

Bulk2LoadOptions

Bulk insert options

Properties

Name	Type	Default	Description
[pollInterval]	number	1000	Polling interval in milliseconds. Default: 1000 (1 second)
[pollTimeout]	number	30000	Polling timeout in milliseconds. Default: 30000 (30 seconds)

---

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.
body	object		Object request body.

---

QueryOptions

Options for configuring Salesforce Bulk API 2.0 queries

Properties

Name	Type	Default	Description
[scanAll]	boolean	false	Whether to scan through all records including deleted and archived ones
[pollInterval]	number	1000	Polling interval in milliseconds. Default: 1000 (1 second)
[pollTimeout]	number	30000	Polling timeout in milliseconds. Default: 30000 (30 seconds)

---

SalesforceResultState

State object

Properties

Name	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

---

SimpleRequestOptions

Properties

Name	Type	Description
headers	object	Object of request headers.
query	object	Object of request query.

---