At skyline.ai, we are managing a heavy duty Salesforce operation. We offer our qualified investors access to a proprietary platform site on mobile and web, where they can manage their investment portfolio with skyline and followup on existing and new investments vetted by our technology.

Since the investor relations team is using Salesforce for managing clients and deals, we need a way of accessing Salesforce’s DB from within our own platform, and vice versa (some actions on the platform may trigger changes on Salesforce).

Here’s simplified view of the investor’s platform site architecture:

When it was time to look at the “Salesforce” part (marked by a red rectangle), we found that we were not very satisfied with the standard Salesforce REST API.

We found a super awesome project called JSforce which allowed us to do pretty much whatever we wanted with Salesforce from Node.js, which was a perfect fit for our need.

But JSforce in itself is a library, and in order to consume it as a microservice, one needs to wrap in up in some manner. In our case most microservices in the platform site communicate over HTTPS using REST APIs built with Swagger for Node.js over express (read more about swagger here and here).

Why not use Salesforce API directly? Well, there are a couple of benefits to wrapping up Salesforce API with Swagger:

Get swagger goodness over the plain old Salesforce REST API — declarative coding, documentation, API playground, etc.

Be able to manipulate Salesforce API results using node (express middlewares and more)

The vanilla Salesforce REST API is designed for client apps, not server integrations (it only offers OAuth authentication). Projects created with node-swagger-salesforce may be easily used for server integrations simply by supplying users credentials (no need to work with the OAuth endpoint).

may be easily used for server integrations simply by supplying users credentials (no need to work with the OAuth endpoint). The result project may be deployed to a PaaS like Heroku with just a few clicks

Auto generating CRUD APIs

node-swagger-salesforce may be used to easily and automatically create a REST API containing CRUD operations covering Salesforce entities. The generator connects to your Salesforce instance (for example, your sandbox environment) using credentials supplied as env vars and proceeds to automatically generate an entire swagger project (controllers, configuration, etc.) over an express.js API server.

You can choose to auto generate controllers for all your Salesforce entities, or you can configure a white or a black list of entities.

Usage

Install swagger for node

$ npm install -g swagger

Get the project and install it’s dependancies



$ cd node-swagger-salesforce && npm install $ git clone https://github.com/skyline-ai/node-swagger-salesforce.git $ cd node-swagger-salesforce && npm install

Build the project (this will run the gulpfile)

$ npm run build

Set required env vars — credentials for Salesforce (mandatory) and login URL (this value is optional, the value https://test.salesforce.com should be used in order to connect to sandbox envs). see configuration section for more available config options



$ export SF_USER=your Salesforce username

$ export SF_PASSWORD=your Salesforce password

# if you don't know what your token is, you can **RESET** it by following this link:

# https://YOUR_SALES_FORCE_DOMAIN/_ui/system/security/ResetApiTokenConfirm?retURL=%2Fui%2Fsetup%2FSetup%3Fsetupid%3DPersonalInfo&setupid=ResetApiToken

$ export SF_TOKEN=your sales force security token

# optional: connect to sandbox env

$ export SF_LOGIN_URL=https://test.salesforce.com # for example: john.doe@example.com$ export SF_USER=your Salesforce username$ export SF_PASSWORD=your Salesforce password# if you don't know what your token is, you can **RESET** it by following this link:$ export SF_TOKEN=your sales force security token# optional: connect to sandbox env$ export SF_LOGIN_URL=https://test.salesforce.com

Finally, generated your swagger project and run it. The project uses ES6 syntax and therefore needs to be transpiled in order for node to run it (at the time of this post the latest dev version of node still doesn’t support things like ES6 import ). By default, the babel configuration will create an output at dist directory. The output is the generator in ES5 code that node can run. This is the actual generator code that you need to run in order to create the final swagger project. By default the dist node app will create your new swagger project at the out directory under dist .

$ cd dist && node app.js

$ cd out && npm install

$ swagger project start

To edit your swagger project:

$ swagger project edit

optional: using white-lists or black-lists

If you want the generator to only create controllers for specific entities, use a white list. Configure the location of the list as the env var SF_WL_PATH :

$ export SF_WL_PATH=../lists/wl.txt

If you want the generator to dismiss specific entities and create controllers for the rest, use a black list. Configure the location of the list as the env var SF_BL_PATH :

$ export SF_BL_PATH=../lists/bl.txt

The list should be a UTF-8 text file where every line contains the name of the entity in lower case. For example, the following list is set to tell the generator to only create a controller for the account entity:

$ cat lists/wl.txt

account

TODO