The Dashboard Health Check with Analytics API

August 14, 2014 Appirio

Contributed by : Asset Library Team

Salesforce Dashboards can now be queried using Analytics API. Querying dashboards with the API can be very useful for administrators to find unused and invalid dashboards. We will use a Visualforce page to demonstrate the query and determine the health of a Salesforce dashboard.


A dashboard may become invalid due to several reasons. When this happens, usually the end user will notify an administrator and the administrator can fix it. It’s tedious work for the administrator to go through individual dashboards to see if they have become invalid. Fortunately, Analytics API can be used to run through all dashboards in the organization periodically and determine if all dashboards are running well.

An administrator can also determine when the dashboard was last viewed and was last refreshed. This information can be valuable to see which dashboards are gaining adoption by users.

A few of the reasons that can render a dashboard invalid include:

1. The running user for the dashboard loses the permission to run reports.

2. The running user for the dashboard becomes inactive.

3. The filter on dashboard becomes invalid.

Similarly, individual components on the dashboard can become invalid. Some reasons for this happening includes:

1. The source report isn’t available.

2. The source report is based on a report type that is inaccessible to the dashboard’s running user.

3. A row-limited tabular report cannot be used as the source for a component.


To retrieve the dashboard’s current status, we need to query Analytics API. The API accepts a dashboard ID, and returns a JSON response containing overall dashboard health and status of individual components, that comprises the dashboard.

Here is a code sample that is invoking the API in Apex:

[snippet caption=”Apex code to invoke Analytics API dashboard”]

public HttpResponse getDashboardStatus(String dashboardID){

String salesforceInstance = Url.getSalesforceBaseUrl().toExternalForm();

String baseURL = salesforceInstance +

+ ‘/services/data/v31.0/analytics/dashboards/’ + dashboardID + ”;

HttpRequest request = new HttpRequest();



request.setHeader(‘Authorization’,’Bearer ‘ + UserInfo.getSessionID());


Http http = new Http();

HttpResponse response = http.send(request);

return response;



[snippet caption=”Sample JSON Responses”]

Dashboard is invalid

[ {

“errorCode” : “BAD_REQUEST”,

“message” : “The running user for this dashboard is inactive. Your system administrator should select an active user for this dashboard.”


Dashboard is valid, and t individual components status

“componentData” : [ {


“status” : {

“dataStatus” : “DATA”,

“errorCode” : null,

“errorMessage” : null,

“errorSeverity” : null,

“refreshDate” : “2014-08-02T11:33:23.000+0000”,

“refreshStatus” : “IDLE”




The visualforce page invokes the api passing in the dashboard ID and parses the JSON responses and displays it on the page.



Analytics API is a great addition in the Salesforce Tools arsenal. Querying report and dashboard metadata directly enables administrators to proactively support production system.

Previous Article
Integration Friday Episode 1: Boomi and WSDL
Integration Friday Episode 1: Boomi and WSDL

By Matt Ainsworth and Anna Knyazyan Integration is the key to success for many cloud implementations. Getti...

Next Article
Activity Contact Lookup Override
Activity Contact Lookup Override

By Bryan Leboff I recently asked a good friend of mine what was his number one issue with Salesforce and wi...