Salesforce Extension

The Salesforce extension enables reading from and writing to Salesforce in Grainite applications.

Setup

In order to be able to use the Salesforce extension, first include it as a dependency in your application's pom.xml file.

...
<dependency>
  <groupId>ext.grainite</groupId>
  <artifactId>grainite-sfdc</artifactId>
  <version>{GRAINITE-VERSION}</version>
</dependency>
...

Replace {GRAINITE-VERSION} with the version of Grainite you are also using for libgrainite (the Grainite Client library for Java).

Contents

The SFDC Extension includes:

• SFDCReaderTask: Task that fetches changes from Salesforce - either using the CDC mechanism or by directly issuing SOQL queries for each object.

• SFDCWriterHandler: Handler that can emit a record into the target Salesforce record using the REST API

SFDCReaderTask

Note on Parallelism

The SFDCReaderTask creates one task instance per task entry specified in the app.yaml. The single task instance is responsible for polling Salesforce and getting changes across all Salesforce objects provided via the objects property.

If useCDC is true, the task uses the Salesforce CDC pubsub endpoint to fetch changes. If useCDC is false, the task uses SOQL APIs to fetch changes for the specified objects. A scheduler within the task decides which objects to look for changes on, and when the next query should be scheduled. This is based on a prioritization considering various factors, including, if the last poll returned any changes, the time since the last poll, and other factors.

Each SOQL query will poll changes for 5 objects in one request - where the objects are picked using the priority specified above.

The output of the task is directed to Grains or Topic Keys that are keyed by the object type. So the consumption is parallel by object e.g. if Lead and Account objects are being polled, and both generate 5 change records each, they will be consumed with a parallelism of 2 (one for Lead, and the other for Account), and the 5 records will be consumed sequentially on each Grain or Topic subscription.

Usage

To include this task in your application, you must specify the taskClass ext.grainite.tasks.sfdcreader.SFDCReaderTask and taskInstanceClass ext.grainite.tasks.sfdcreader.SFDCReaderInstance in your application's configuration YAML file.

app.yaml

...
tasks:
  - task_name: my_sfdcreader_task
    taskClass: ext.grainite.tasks.sfdcreader.SFDCReaderTask
    taskInstanceClass: ext.grainite.tasks.sfdcreader.SFDCReaderInstance
    config:
...

Below are the configuration options that can be passed in under config:

Property	Required?	Value	Description
loginUrl	REQUIRED	If using a sandbox organization, use https://test.salesforce.com Otherwise, the value should be https://login.salesforce.com	Login URL for the target Salesforce organization.
serverUrl	REQUIRED	Example: https://mysandbox.develop.my.salesforce.com/	URL for the target Salesforce organization.
clientID	REQUIRED	Example: xxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxx	Client ID obtained by adding an app to the SFDC App Manager
clientSecret	REQUIRED	xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx	Client Secret obtained by adding an app to the SFDC App Manager
privateKey	REQUIRED	Example: $secret:my_secret	Private key that will be used to encrypt the JWT token for auth. In the example shown, my_secret is the name of a Grainite secret stored for this app. Alternatively, this value can be a path to a file containing only the privateKey although this is not recommended unless testing with a non-sensitive use case.
useCdc	Optional	true or false Default: false	When true, the task polls the Salesforce CDC pubsub API for changes. When false, the task polls each of the objects specified in parallel by directly issuing SOQL queries
pubsubHost	Required if useCdc is set to true	Example: api.pubsub.salesforce.com	When using CDC, Salesforce pubsub hostname. Usually api.pubsub.salesforce.com
pubsubPort	Required if useCdc is set to true	Example: 7443	When using Salesforce CDC, port of the pubsub API service, usually 7443
objects	Required if useCdc is set to false	Example: Lead;Account;Contact	List of objects to be polled, separated by semicolons. Valid only when useCdc is false. A parallel reader is started for each object.
maxDelayTime	Optional	Example: 30 Default: 60	Maximum duration between polls. The task backs off (up to this limit) when no data is found on successive polls, and resets the backoff when any data is found.
output.topic	Optional	Example: my_events	Grainite topic to emit output of this task to
output.table	Optional	Example: my_table	Grainite table to emit output of this task to via Grain message (output.table_action must also be provided)
output.table_action	Optional	Example: my_table_action	Given action to invoke via Grain Message to the table specified in output.table

SFDCWriterHandler

Expects these fields in the incoming record: entityName to represent the target SF Object, recordId to reflect the ID of the record, and a changeType (UPDATE/DELETE/CREATE)

Usage

To include this handler in your application, you must specify the class_name ext.grainite.handlers.sfdcwriter.SFDCWriterHandler in your application's configuration YAML file.

app.yaml

...
tables:
  - table_name: my_sfdc_writer
    key_type: string
    action_handlers:
      - name: my_sfdc_writer
        type: java
        class_name: ext.grainite.handlers.sfdcwriter.SFDCWriterHandler
        config:
...

Below are the configuration options that can be passed in under config:

Property	Required?	Value	Description
loginUrl	REQUIRED	If using a sandbox organization, use https://test.salesforce.com Otherwise, the value should be https://login.salesforce.com	Login URL for the target Salesforce organization.
serverUrl	REQUIRED	Example: https://mysandbox.develop.my.salesforce.com/	URL for the target Salesforce organization.
clientID	REQUIRED	Example: xxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxx	Client ID obtained by adding an app to the SFDC App Manager
clientSecret	REQUIRED	xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx	Client Secret obtained by adding an app to the SFDC App Manager
privateKey	REQUIRED	Example: $secret:my_secret	Private key that will be used to encrypt the JWT token for auth. In the example shown, my_secret is the name of a Grainite secret stored for this app. Alternatively, this value can be a path to a file containing only the privateKey although this is not recommended unless testing with a non-sensitive use case.

Salesforce and SFDC are trademarks of Salesforce.com, inc.