Salesforce Node Client

Table of Content

• About
• Installation
• Documentation
  • Declaring your application in Salesforce
  • Configuring and instantiating the client
  • Authenticating
  • Interacting with Salesforce data
  • Interacting with Apex REST resources
• Changelog

About

Node.js client library for the Salesforce Platform.

This library provides access to the following Salesforce Platform services:

• Authentication through OAuth 2.0
• Data through Salesforce Platform REST APIs
• Apex REST resources

This client is provided “as is“ without any warranty or support. Salesforce does not officially endorse it.

Credit
The authentication service of this project is largely inspired by cangencer's project.

Sample application
A sample React.js application that integrates with Salesforce using this client can be found in this repository.
Even if you are not familiar with React.js, the Node.js backend code is worth looking at.

Installation

This project can be installed through NPM:

1$ npm install salesforce-node-client --save

Documentation

Declaring your application in Salesforce

Before being able to interact with the Salesforce Platform with your application, you will have to declare it as a connected application:

1. Log in your Salesforce administrator account
2. Access Setup
3. Type 'App' in the quick find box and navigate to Build > Create > Apps
4. Scroll down and click 'New' in the 'Connected Apps' section
5. Fill in the required fields in the 'Basic Information' section
6. Check 'Enable OAuth Settings', this will open some additional settings
7. Provide a callback URL (this is an endpoint belonging to your application that should match auth.callbackUrl specified in the client configuration later)
8. Select your OAuth scope(s) ('api' is a good start)
9. Save your settings

Configuring and instantiating the client

The first thing that you need to do to use this project is to set its configuration and create a client instance.

There are two options to configure the client:

Option 1: instantiating the client with a configuration object

1const SalesforceClient = require('salesforce-node-client');
2
3// Settings for Salesforce connection
4const sfdcConfig = {
5  // OAuth authentication domain
6  // For production or a Developer Edition (DE) use
7  domain: 'https://login.salesforce.com',
8  // For a sandbox use
9  //domain : 'https://test.salesforce.com',
10
11  // URL called by Salesforce after authorization and used to extract an authorization code.
12  // This should point to your app and match the value configured in your App in SFDC setup)
13  callbackUrl: 'http://localhost:3000/auth/callback',
14
15  // Set of secret keys that allow your app to authenticate with Salesforce
16  // These values are retrieved from your App configuration in SFDC setup.
17  // NEVER share them with a client.
18  consumerKey: 'your consumer key',
19  consumerSecret: 'your consumer secret key',
20
21  // Salesforce API version
22  apiVersion: 'v41.0'
23};
24
25// Instantiate Salesforce client with configuration
26const sfdcClient = new SalesforceClient(sfdcConfig);

Option 2: instantiating the client with Node.js environment variables

Ensure that the Node.js environment variables (process.env) contains the same keys/values as the sfdcConfig object in option 1 before calling the client constructor. You can set environment variables in several ways but I recommend storring them in a .env file and loading them with dotenv when the server starts.

1const SalesforceClient = require('salesforce-node-client');
2
3// Instantiate Salesforce client with Node.js environment variables.
4// It's your responsibility to set those ahead of this call or you will get an error.
5const sfdcClient = new SalesforceClient();

Once the client is instantiated with either options, you may access the underlying client services with these properties:

• auth for the authentication service
• data for the data service
• apex for the apex REST service

Authenticating

Prior to performing any operation, you will need to authenticate with Salesforce.

There are two authentication methods available:

• Standard user authentication (requires a browser).
• Password authentication for non-browser operations such as programmatic access.

Standard user authentication mode

The first step in standard user authentication is to generate the authorization URL with your OAuth scope(s) (API only in in this example) and redirect the user to it:

1// Redirect to Salesforce login/authorization page
2var uri = sfdc.auth.getAuthorizationUrl({scope: 'api'});
3return response.redirect(uri);

The user will authorize your application to connect to Salesforce and will be redirected to the auth.callbackUrl URL you specified in the client configuration.
Important: the callback URL you specified in the client configuration MUST match your connected applications settings in Salesforce.

The user will be redirected to that call back URL with an authorization code passed as a query parameter.
The Node client library will use that code (request.query.code in the following example) to authenticate with Salesforce. The, once the authentication is completed:

1. persist the response payload in a server-side session (you will need this for all further operations)
2. redirect the user to your application's home page

1// Authenticate with Salesforce
2sfdc.auth.authenticate({'code': request.query.code}, function(error, payload) {
3	// Store the payload content in a server-side session
4	// Redirect your user to your app's home page
5});

The authenticate response payload is an object with the following format:

Attribute	Description
id	URL that represents logged in user
issued_at	Timestamp of token creation
refresh_token	Long-lived token that may be used to obtain a fresh access token on expiry of the access token
instance_url	URL that identifies the Salesforce instance to which API calls should be sent
access_token	Short-lived access token
signature	Hash used to sign requests sent to Salesforce (the client library will take care of that for you)

Password authentication mode

In order to perform password authentication, use the following:

1// Authenticate with Salesforce
2sfdc.auth.password({
3	'username': 'the user name',
4	'password': 'the user password',
5}, function(error, payload) {
6	// Store the payload content in a server-side session
7	// Do something
8});

Logging out

You may log out a user of your application by revoking his access token accessToken with the following code:

1// Revokes your user's access to Salesforce
2sfdc.auth.revoke({'token': accessToken}, function(error) {
3	// Do something
4});

Important: revoking a user's access token logs the user out of your application but not Salesforce.

Interacting with Salesforce data

Once you have authenticated, you may perform various operations on the Salesforce Platform.

For all operations, you will need the response payload of auth.authenticate or auth.password. We will refer to it as sfdcSession.

Interacting with Salesforce data

Interactions with Salesforce data performed with this client are handled with REST APIs in two steps.

First, prepare the request options and sign it with the client by calling data.createDataRequest. To do so, you will need to provide two paramters:

• sfdcSession the session information
• resourceUrlSuffix a string containing the location of the REST resource you wish to interact with (you may use the REST Explorer from the Workbench to get the right URL).

Finally, send the request with the HTTP verb of your choice and process the response.

1// Prepare Salesforce request options with a SOQL query that lists users
2var query = encodeURI('SELECT Id, Name FROM User LIMIT 10');
3var apiRequestOptions = sfdc.data.createDataRequest(sfdcSession, 'query?q='+ query);
4// Send an HTTP GET request with our options
5httpClient.get(apiRequestOptions, function (error, payload) {
6	// Do something
7});

Retrieving the currently logged user

As a convenience, you can retrieve the currently logged in user with this call:

1// Request logged user info
2sfdc.data.getLoggedUser(sfdcSession, function (error, userData) {
3	// Do something
4});

Interacting with Apex REST resources

Apex REST resources can be called in the following way:

1// Builds a REST query to a custom Apex resource
2var apiRequestOptions = sfdc.apex.createApexRequest(sfdcSession, 'MyCustomApexResource/001B000000RS9WWIA1');
3// Send an HTTP GET request with our options
4httpClient.get(apiRequestOptions, function (error, payload) {
5	// Do something
6});