salesforce-api

SalesForce client for Nodejs

This node module provides a set of methods to interact against SalesForce's services. The module was created as part of KidoZen project, as a connector for its Enterprise API feature.

Installation

Use npm to install the module:

> npm install salesforce-api

API

Due to the asynchrounous nature of Nodejs, this module uses callbacks in requests. All callbacks have 2 arguments: err and data.

function callback (err, data) {
    // err contains an Error class instance, if any
    // data contains the resulting data
} 

Authentication

UserName and Password login

The module exports a Class and its constructor requires a configuration object with following properties

• username: Required string. End-user’s username.
• password: Required string. End-user’s password.

var SalesForce = require("salesforce-api");
var salesforce = new SalesForce();
salesforce.authenticate({
        username: "[e-mail]",
        password: "secret"
    }, ...

Username and Password Login (OAuth2 Resource Owner Password Credential)

When OAuth2 client information is given to ctor. authenticate(username, password) uses OAuth2 Resource Owner Password Credential flow to login to Salesforce.

• username: Required string. End-user’s username.
• password: Required string. End-user’s password.
• oauth2: Required. OAuth2 information

var SalesForce = require("salesforce-api");
var salesforce = new SalesForce();
salesforce.authenticate({
        username: "[e-mail]",
        password: "secret",
        oauth2 : {
            clientId : '...',
            clientSecret : '...',
            redirectUri : 'https://login.salesforce.com/services/oauth2/token'
        }
    }, ...

Access Token

After the authenticate API call, you can get Salesforce access token and its instance URL. Next time you can use them to establish connection.

var OAUTH2SessionInfo = {
      	instanceUrl : '<your Salesforce server URL (e.g. https://na1.salesforce.com) is here>',
      	accessToken : '<your Salesforce session ID is here>'
   		// you can find this values in the result of authenticate method
    };

var query = {
    credentials : OAUTH2SessionInfo,
    SOSQL: "SELECT Id from Account"
};

api.Query(query, function(err, result) {
    ...
    ...
    ...

Methods

All public methods has the same signature, their have two arguments: options and callback.

• options must be an object instance containig all parameters for the method.
• callback must be a function.

Describe(options, callback)

This method should be used to retrieve metadata for an object.

Parameters:

• options: A required object instance:
  • objectClass: Optional string.
• callback: A required function for callback.

salesforce.Describe({ objectClass:"Account" }, function(err, result) {
    if (err) return console.error (err);
    console.log (result);
});

DescribeGlobal(options, callback)

This method returns all SObject information registered in Salesforce

Parameters:

• callback: A required function for callback.

salesforce.DescribeGlobal(function(err, result) {
    if (err) return console.error (err);
    console.log (result);
});

SOSQL Query(options, callback)

Use this method to execute a SOQL query that returns all the results in a single response, or if needed, returns part of the results and an identifier used to retrieve the remaining results.

Parameters:

• options: A required object instance:
  • SOSQL: Required string.
• callback: A required function for callback.

salesforce.Query({ SOSQL: "SELECT Id, Name, BillingCity FROM Account" }, function(err, result) {
    if (err) return console.error (err);
    console.log (result);
});

Json Query(options, callback)

Use this method to execute a SOQL query that returns all the results in a single response, or if needed, returns part of the results and an identifier used to retrieve the remaining results.

Parameters:

• options: A required object instance:
  • Entity: Required string.
  • Conditions: Required string.
  • Fields: Required string.
  • Options: Required string.
• callback: A required function for callback.

var query = {
                Entity: "Account",
                Conditions : { 
                    Name : { $like : 'G%' }
                },
                Fields : {
                    Id: 1,
                    Name: 1,
                    CreatedDate: 1 
                },
                Options : { 
                    Limit : 5,
                    Skip: 10
                }
            };
salesforce.Query(query, function(err, result) {
    if (err) return console.error (err);
    console.log (result);
});

Create(options, callback)

This method allows you to create a new record. You have to supply the required field values of the resource.

Parameters:

• options: A required object instance:
  • Entity: Required string.
  • Details: Required object instance
• callback: A required function for callback.

The following example creates a new Account record:

var newAccount = { Name: "Foo account" };
salesforce.Create({ Entity: "Account",  Details: newAccount }, function(err, result) {
    if (err) return console.error (err);
    console.log (result);
});

Update(options, callback)

Use this method to update records. Provide the updated record information at the data property.

Parameters:

• options: A required object instance:
  • Entity: Required string.
  • Details: Required object. Updated record. It must have the id property with the object id to update
• callback: A required function for callback.

In the following example, the Billing City within an Account is update.

var options = {
    Entity: "Account",
    Details : 
        {
            id: "CD656092",
            BillingCity: "San Francisco" 
        }
    }
};

salesforce.Update(options, function(err, result) {
    if (err) return console.error (err);
    console.log (result);
});

Upsert(options, callback)

Will upsert a record or records given in first argument. External ID field name must be specified in second argument.

Parameters:

• options: A required object instance:
  • Entity: Required string.
  • Details: Required object. Updated record. It must have the ExtId__c property with the object id to update
  • ExternalIdName the field id name
• callback: A required function for callback.

var options = {
    Entity: "UpsertTable__c",
    Details : 
        {
            Name : 'Record #1',
  			ExtId__c : 'ID-0000001'
  		},
    ExternalIdName : 'ExtId__c'
    }
};

salesforce.Upsert(options, function(err, result) {
    if (err) return console.error (err);
    console.log (result);
});

Delete(options, callback)

Use this method to delete an existing record.

Parameters:

• options: A required object instance:
  • Entity: Required string.
  • Details: Required, string or array of strings with the ids to delete
• callback: A required function for callback.

In the following example removes the record the ID 1234 from Account

var options = {
    Entity: "Account",
    Details: "1234"
};

salesforce.Delete(options, function(err, result) {
    if (err) return console.error (err);
    console.log (result);
});

or

var options = {
    Entity: "Account",
    Details: ["1234","012"]
};

salesforce.Delete(options, function(err, result) {
    if (err) return console.error (err);
    console.log (result);
});