Reports and Dashboards REST API

Reports and Dashboards REST API enhancements include new resources for describing and testing dashboard filters and report fields, new methods for setting dashboard filter values and describing a single analytics notification, and new properties describing analytics notification recipients and running users.

New Resources: Filter Operators, Filter Options Analysis, Report Fields

The Reports and Dashboards REST API includes new resources that describe and test dashboard filters and report fields.
Resource URI Supported HTTP Methods Description
/services/data/v40.0/analytics/reports/<report id>/fields POST If the request body is empty, the response returns a list of all possible report fields.

If the request body includes the new intersectWith property, which is an array of report ids, then the response returns only report fields specified reports share.

Use the fields resource to determine the best fields for use in dashboard filters.

Here’s an example request body:

{
   "intersectWith": ["<report id 1>", "<report id 2>"]
}
/services/data/v40.0/analytics/filteroperators

and

/services/data/v40.0/analytics/filteroperators?forDashboards=true

GET If forDashboards isn’t specified or forDashboards=false, the response returns all report filter operators.

If forDashboards=true, the response returns all dashboard filter operators.

/services/data/v40.0/analytics/dashboards/filteroptionsanalysis POST Verifies that dashboard filter options are compatible with report fields. Specify the reportId of a dashboard’s components’ source report.

Here’s an example request body:

{
   "filterColumns" : [{
      "reportId": "00OR0000000PIGYMA4",
      "name": "ACCOUNT_TYPE"
   }],
   "options": [{
      "alias": "New",
      "operation": "contains",
      "value": "New",
      "startValue": null,
      "endValue": null
   }]
}

For more information, see the Reports and Dashboards REST API Developer Guide.

New Methods

The Reports and Dashboards REST API has new methods for getting info about a single analytic notification and setting values for dashboard filters.
Resource Supported HTTP Method Description
/services/data/v40.0/analytics/notifications/<notification id> GET Return details about an analytic notification.
/servies/data/v40.0/analytics/dashboards/<dashboard id>?isStickyFilterSave=true PATCH Set a default filter value to apply to a dashboard when you open it. The default filter value you specify applies only to you (other people won’t see it when they open the dashboard). If you change the filter value while viewing the dashboard, then the filter value you set in the user interface overwrites the value you set in the API.

In the request body, set the new "selectedOption" property to the index of the filter option you’d like to apply.

Here’s an example request body:

{
  "filters" : [ {
    "errorMessage" : null,
    "id" : "0IBR00000004D4iOAE",
    "name" : "Billing City",
    "options" : [ {
      "alias" : "New York City",
      "endValue" : null,
      "id" : "0ICR00000004FtQOAU",
      "operation" : "equals",
      "startValue" : null,
      "value" : "New York City"
      }, {
      "alias" : "Chicago",
      "endValue" : null,
      "id" : "0ICR00000004FtROAU",
      "operation" : "equals",
      "startValue" : null,
      "value" : "Chicago"
      }, {
      "alias" : "Los Angeles",
      "endValue" : null,
      "id" : "0ICR00000004FtSOAU",
      "operation" : "equals",
      "startValue" : null,
      "value" : "Los Angeles"
      }
    ],
    "selectedOption" : 1
    }
  ]
}

For more information about these methods, see the Reports and Dashboards REST API Developer Guide.

Changed Resources: Analytics Notifications and Dashboard Describe

The Reports and Dashboards REST API includes new properties that describe analytic notification recipients and running users.
Notifications
The Notifications Results resource contains both new and changed properties.
Table 1. New Properties
Property Type Description
recipients recipients[] An array of people who receive the analytic notification. Each object in the array has these properties:
  • displayName — The person’s first and last name.
  • id — The person’s Salesforce user ID.

Requires the “Subscribe to Reports: Add Recipients” user perm.

runAs runAs The person who runs the report in a report subscription. Report recipients see data in the emailed report that this person has access to in Salesforce. Has these properties:
  • id — The person’s Salesforce user ID.
  • name — The person’s first and last name.

Requires the “Subscribe to Reports: Set Running User” user perm.

Table 2. Changed Properties
Property Type Description
configuration configuration[] Previously, configuration returned null and was reserved for future use. Now, configuration returns a recipients object when an analytic notification has multiple recipients. If the subscription is only sent to the person who sets it up, then configuration still returns null.
Dashboard Describe
The Dashboard Describe resource contains new properties.
Table 3. New Properties
Property Type Description
reportFormat String The format of a dashboard’s source report.
maxFilterOptions Integer The maximum number of values allowed in a dashboard filter.

For more information, see the Reports and Dashboards REST API Developer Guide.