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.

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.

---

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

---

SalesforceState

State object

Properties

Name	Description
data	API response data. Can be either an object or array of objects
references	History of all previous states

---

SimpleRequestOptions

Properties

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

---