node-salesforce -- Salesforce API Connection Library for Node.js Applications
Abstract
Node-salesforce, which is designed to be a wrapper of Salesforce REST API in Node.js, enables Salesforce application development in event-driven style. It capsulates the access to REST API end point in asynchronous JavaScript function call. You can use both OAuth2 access token and SOAP login sessionId for API authentication.
Install
npm install node-salesforce
or
git clone git://github.com/stomita/node-salesforce.git cd node-salesforce npm link
Establish Connection
Using Session ID
var sf = ;var conn = serverUrl : '<your Salesforce server URL (e.g. https://na1.salesforce.com) is here>' sessionId : '<your Salesforce session ID is here>';
Using OAuth2 Access Token
var sf = ;var conn = instanceUrl : '<your Salesforce server URL (e.g. https://na1.salesforce.com) is here>' accessToken : '<your Salesforrce OAuth2 access token is here>';
Using OAuth2 Access Token with Refresh Token (automatically refresh access token when expired)
var sf = ;var conn = oauth2 : clientId : '<your Salesforce OAuth2 client ID is here>' clientSecret : '<your Salesforce OAuth2 client secret is here>' redirectUri : '<your Salesforce OAuth2 redirect URI is here>' instanceUrl : '<your Salesforce server URL (e.g. https://na1.salesforce.com) is here>' accessToken : '<your Salesforrce OAuth2 access token is here>' refreshToken : '<your Salesforce OAuth2 refresh token is here>';conn;
Username and Password Login (SOAP API)
var sf = ;var conn = // you can change loginUrl to connect to sandbox or prerelease env. // loginUrl : 'https://test.salesforce.com';conn;
Username and Password Login (OAuth2 Resource Owner Password Credential)
var sf = ;var conn = oauth2 : // you can change loginUrl to connect to sandbox or prerelease env. // loginUrl : 'https://test.salesforce.com', clientId : '<your Salesforce OAuth2 client ID is here>' clientSecret : '<your Salesforce OAuth2 client secret is here>' redirectUri : '<callback URI is here>' ;conn;
Logout (Only for SOAP API session)
var sf = ;var conn = sessionId : '<session id to logout>' serverUrl : '<your Salesforce Server url to logout is here>';conn;
OAuth2 Web Server Flow
Authorization Request
Following example is using express.js framework
var sf = ; // OAuth2 client information can be shared with multiple connections.var oauth2 = // you can change loginUrl to connect to sandbox or prerelease env. // loginUrl : 'https://test.salesforce.com', clientId : '<your Salesforce OAuth2 client ID is here>' clientSecret : '<your Salesforce OAuth2 client secret is here>' redirectUri : '<callback URI is here>'; // get authz url and redirect to it.app;
Access Token Request
// pass received authz code and get access tokenapp;
Query Records
Using SOQL
Event-Driven Style
var records = ;conn ;
Callback Style
var records = ;conn;
Using JSON-style Query object and method chaining (like MongoDB)
// following query is equivalent to this SOQL// "SELECT Id, Name, CreatedDate FROM Contact// WHERE LastName LIKE 'A%' AND CreatedDate >= YESTERDAY AND Account.Name = 'Sony, Inc.'// ORDER BY CreatedDate DESC, Name ASC// LIMIT 5 OFFSET 10"conn ;
CRUD Operation
Retrieve
conn; // Multiple records retrieval consumes one API request per record.// Be careful for the API quota.conn;
Create
conn;// Multiple records creation consumes one API request per record.// Be careful for the API quota.conn;
Update
conn; // Multiple records modification consumes one API request per record.// Be careful for the API quota.conn;
Delete
conn; // Multiple records deletion consumes one API request per record.// Be careful for the API quota.conn;
Upsert
conn;// Multiple records modification consumes one API request per record.// Be careful for the API quota.conn;
Describe
SObject
conn;
Global Object
conn;
Streaming
/** Before the subscription, you should insert appropriate PushTopic record (in this example, "InvoiceStatementUpdates") as written in Streaming API guide. */conn;
Bulk Operation
Loading records
// Records to insert in bulk.var accounts = Name : 'Account #1' ... Name : 'Account #2' ... Name : 'Account #3' ... ...; // Create bulkload job and add batch to execute loading,var job = connbulk;var batch = job;batch;batch; // and check the status later.var job = connbulk;var batch = job;batch; // start pollingbatch; // or use Bulk#load() method in one call to upload records and fetch results. connbulk; // same as following callsconn; // conn;
Loading CSV file
// CSV file to uploadvar csvFileIn = ; // Create bulkload job and add batch to execute loading,var job = connbulk;var batch = job;batch; // connect any readable stream via pipe methodcsvFileIn; // or use Bulk#load() method in one call to upload file and fetch results. connbulk;
Record Stream Pipeline
Record stream is a stream system which regards records in its stream, similar to Node.js's standard readable/writable streams.
Query object returned by Connection#query() / SObject#find() method is considered as InputRecordStream which emits event "record" when received record from server.
Batch object returned by Job#createBatch() / Bulk#load() / SObject#bulkload() method is considered as OutputRecordStream and have send() and end() method to accept incoming record.
You can use InputRecordStream#pipe(outputRecordStream) to pipe record stream.
RecordStream can be converted to usual Node.js's stream object by calling RecordStream#stream() method. By default (and only currently) records are serizalized to CSV string.
Piping Query Record Stream
// DELETE FROM Account WHERE CreatedDate < LAST_YEARvar Account = conn;Account ; // UPDATE Opportunity SET Name = Accout.Name + ' - ' + Name WHERE Account.Id = :accIdvar Opportunity = conn;Opportunity ; // Export all account records to CSV filevar csvFileOut = ;conn // Convert to Node.js's usual readable stream. ;
Record Stream Filters
// Map record and pass to downstreamconn ; // Filter only matching record to pass downstreamvar emails = {};conn ;
Data Migration using Bulkload Batch Record Stream
// Connection for org which migrating data fromvar conn1 = // ...; // Connection for org which migrating data tovar conn2 = // ...; var query = conn1;var job = conn2bulk;var batch = job;query;batch
Change History
v0.5.1 (Jan 11, 2013):
- Move Query#stream() method to RecordStream#stream() to support stream serialization even in filtered stream.
v0.5.0 (Jan 11, 2013):
-
Support Bulk API for insert/update/upsert/delete/hardDelete operation (except for 'query').
-
Refine Query#pipe to pipe to other output record stream (like bulk upload batch).
-
Add Query#stream() method to convert record stream to general node.js readable stream (generates CSV data).
v0.4.0 (Nov 05, 2012):
-
Support JSON-style query object to query records other than SOQL, inspired by MongoDB query interface.
-
Change default API version to 26.0 (Winter '13).
-
Return logged-in user info in the callback response of Connection#login() and Connection#authorize().
-
Add Connection#logout() method to terminate session explicitly (Note: only useful for SOAP API login session).
v0.3.4 (Oct 19, 2012):
-
Fix issue to refresh access token multiple time in concurrent requests.
-
Change to use "Bearer", not "OAuth" in HTTP Authorization header to attach access token.
-
Separate oauth2 configuration into different hash object in connection constructor option (old style is still supported for backward compatiblity).
v0.3.2 (Oct 18, 2012):
- Fix error handling in access token refresh flow.
v0.3.1 (Jun 26, 2012):
- Add support of Node.js 0.8.x.
v0.3.0 (May 10, 2012):
- Support Salesforce Streaming API.