Salesforce provides a ton of different APIs for use, just some of the different APIs are:
- Analytics API
- Apex REST
- Bulk API
- Chatter API
- Metadata API
- REST API (SOQL, SOSL, CRUD, describe, etc.)
- SOAP Api
- Streaming API
- Tooling API
In this blog article, we’ll be focused in on the Analytics API because it’s primarily used for reporting and dashboards. If you are interested in learning about the other APIs, you should check out the blog article Understanding the Different Salesforce APIs.
Connecting to the Salesforce Analytics Api isn’t too complicated if you have already used any of the other Salesforce APIs and if you can use one a library that is built to connect to it. In this blog article, we’ll be using the JSforce library.
The blog article Connecting to the Salesforce APIs through Node.js gives a pretty good overview of the JSforce library.
When should we use the the Analytics API?
It’s very exciting and allows us to do a lot of things without necessarily needing to mess around with writing a lot of different SOQL queries.
The Analytics API is great for building secondary applications whether they be mobile or web based. We can pull data from Salesforce and use it in our application.
You could also use calls to the Analytics API within Salesforce pages to do things like show customer graphs, dashboards, or etc.
Salesforce Analytics API Limits
There are a number of limits that we need to keep in mind as we work with the Analytics API:
- The API returns data for the same number of records that are available when the report is run in the Salesforce user interface
- The most recently viewed reports will only show up to the last 200 reports.
- The RESTful API consumes API calls.
- Synchronous report executions have limits per hour (believe it’s 1k).
- Asynchronous report results are available for 24 hours after execution.
Logging Into the Salesforce Analytics API
There’s a few different ways to log into the analytics api. The most common login method is to use the username (most likely your email address), password, and a secret token that Salesforce will email you when you request a new one.
The JSForce library is very rich and can support all of the ways I know to log into Salesforce (oAuth, tokens, username + password, etc.)
Here’s an example of how we might log in using a username, password, and secret key.
Running Reports
Reports may be run asynchronously or synchronously. If your report takes less than two minutes to run it can be easily executed synchronously.
JSForce hides a lot of the complexity behind calling the reports endpoint by providing a synchronous endpoint which is simply “execute”. The asynchronous variant is “executeAsync”.
If you want to include rows and not just aggregate data, you need to pass in details: true to the execute method. To use the reports we need to instantiate a connection.analytics.report object by passing in a Salesforce Id.
Next we need to call execute or executeAsync off of the report and then use the data. Using the data isn’t too difficult after we understand how the factMap and labelling works.
Understanding the factMap
When you run a report, a “factMap” is created which is a fairly difficult to understand data structure. It’s probably best to read Salesforce’s instruction manual on it.
The factMap has different indexes depending on the type of report that is being used. Check out Understanding the Fact Map from Salesforce Help.
Wrapping it up
With callbacks, here’s a pretty good example of logging in to pulling the recently used reports and then querying one of the reports to build a data structure that could more easily be used in an application
Using Bluebird or util.promisify it’s pretty easy to convert this to using promises instead of callbacks. The blog article Adding Promise Support to a Node.js Library shows a few different ways that this can be done.
Also published on Medium.
