Salesforce Reports and Dashboards REST API Developer Guide

153 Pages·2016·1.62 MB·English

Salesforce Reports and
Dashboards REST API
Developer Guide
Version 45.0, Spring ’19
@salesforcedocs
Last updated: March 11, 2019
© Copyright 2000–2019 salesforce.com, inc. All rights reserved. Salesforce is a registered trademark of salesforce.com, inc.,
as are other names and marks. Other marks appearing herein may be trademarks of their respective owners.
CONTENTS
Chapter 1: Salesforce Reports and Dashboards REST API . . . . . . . . . . . . . . . . . . . . . . . 1
Requirements and Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Chapter 2: Examples: Reports REST API Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Create a New Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Run Reports Synchronously or Asynchronously . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Get Report Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Get a List of Report Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Download Formatted Excel Reports Using the Reports REST API. . . . . . . . . . . . . . . . . . . . . . 52
List Asynchronous Runs of a Report. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Filter Reports on Demand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
List Recently Viewed Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Decode the Fact Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Get Report Data without Saving Changes to or Creating a Report. . . . . . . . . . . . . . . . . . . . . 61
Save Changes to Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Clone Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Delete Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Chapter 3: Examples: Dashboards REST API Resources . . . . . . . . . . . . . . . . . . . . . . . 76
Get List of Recently Used Dashboards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Get Dashboard Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Filter Dashboard Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Get Dashboard Status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Refresh a Dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Save a Dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Set a Sticky Dashboard Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Return Details About Dashboard Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Get Dashboard Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Clone a Dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Delete a Dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Chapter 4: Examples: Analytics Notifications REST API. . . . . . . . . . . . . . . . . . . . . . . . 113
Get Analytics Notifications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Create an Analytics Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Save Changes to an Analytics Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Delete an Analytics Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Check Limits for Analytics Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Chapter 5: Reports API Resource Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Report. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Contents
Describe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Execute Sync . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Execute Async . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Instances List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Instance Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Report List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Report Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Report Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Chapter 6: Report Types API Resource Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Report Type List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Report Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Chapter 7: Filter Operators API Resource Reference . . . . . . . . . . . . . . . . . . . . . . . . . 212
Filter Operator List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Chapter 8: Dashboards API Resource Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Dashboard List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Dashboard Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Dashboard Describe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Dashboard Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Dashboard Filter Options Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Dashboard and Component Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Chapter 9: Analytics Notifications API Resource Reference. . . . . . . . . . . . . . . . . . . . 248
Analytics Notification List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Analytics Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Analytics Notification Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
Chapter 10: Analytics Folders API Resource Reference . . . . . . . . . . . . . . . . . . . . . . . 262
Folder Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
Folder Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
Folder Shares . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
Folder Share by ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Folder Share Recipients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Folder Child Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
CHAPTER 1 Salesforce Reports and Dashboards REST API
In this chapter ... The Reports and Dashboards REST API gives you programmatic access to your report and dashboard
data as defined in the report builder and dashboard builder. The API lets you integrate the data into any
• Requirements and web or mobile application, inside or outside the Salesforce platform. For example, you might use the
Limitations
API to trigger a Chatter post with a snapshot of top-performing reps each quarter.
The Reports and Dashboards REST API will revolutionize the way you access and visualize your data. You
can:
• Integrate report data into custom objects.
• Define rich visualizations on top of the API to animate the data.
• Build custom dashboards.
• Automate reporting tasks.
At a high level, the API resources let you query and filter report data. You can:
• Run tabular, summary, or matrix reports synchronously or asynchronously.
• Filter for specific data on the fly.
• Query report metadata.
You can also work with dashboard resources to:
• Get a list of recently used dashboards.
• Get dashboard metadata and data.
• Query dashboard status.
• Refresh dashboards.
1
Salesforce Reports and Dashboards REST API Requirements and Limitations
Requirements and Limitations
The Reports and Dashboards REST API is available for any organization that has API enabled. You must establish an authenticated session
using OAuth in order to access the Reports and Dashboards REST API. When working with this API, consider these restrictions in addition
to general API limits.
As of API version 43.0, if your org turns on the Lightning Experience joined report beta, then you can use the Reports REST API to work
with joined reports. For more information about the Lightning Experience joined report beta, including how to opt in, see Enable
Lightning Joined Reports (Beta) in Salesforce help.
A report is a joined report when reportFormat is MULTI_BLOCK.
As you get ready to work with joined reports in the REST API, take note of these beta limitations and known issues.
• If you make a POST or PATCH request on a joined report to edit the report, only some properties can be edited:
– hasDetailRows
– hasRecordCount
– showSubtotals
– showGrandTotal
• If you make a POST or PATCH request on a joined report and try to change reportFormat then you get a success code but
reportFormat isn’t updated.
• You can’t change reportFormat to MULTI_BLOCK.
Note: As a beta feature, Lightning Experience joined reports is a preview and isn’t part of the “Services” under your master
subscription agreement with Salesforce. Use this feature at your sole discretion, and make your purchase decisions only on the
basis of generally available products and features. Salesforce doesn’t guarantee general availability of this feature within any
particular time frame or at all, and we can discontinue it at any time. This feature is for evaluation purposes only, not for production
use. It’s offered as is and isn’t supported, and Salesforce has no liability for any harm or damage arising out of or in connection
with it. All restrictions, Salesforce reservation of rights, obligations concerning the Services, and terms for related Non-Salesforce
Applications and Content apply equally to your use of this feature.
Note: Responses and requests are in JSON. While using the Reports and Dashboards REST API with a POST request body, you
must use content-type: application/json. You might get unexpected results if you don’t use this content type.
Reports Limits
• Cross filters, standard report filters, and filtering by row limit are unavailable when filtering data.
• Historical tracking reports are only supported for matrix reports.
• Subscriptions aren't supported for historical tracking reports.
• The API can process only reports that contain up to 100 fields selected as columns.
• A list of up to 200 recently viewed reports can be returned.
• Your org can request up to 500 synchronous report runs per hour.
• The API supports up to 20 synchronous report run requests at a time.
• A list of up to 2,000 instances of a report that was run asynchronously can be returned.
• The API supports up to 200 requests at a time to get results of asynchronous report runs.
• Your organization can request up to 1,200 asynchronous requests per hour.
• Asynchronous report run results are available within a 24-hour rolling period.
• The API returns up to the first 2,000 report rows. You can narrow results using filters.
• You can add up to 20 custom field filters when you run a report.
2
Salesforce Reports and Dashboards REST API Requirements and Limitations
Dashboards Limits
• Your org can request up to 200 dashboard refreshes per hour.
• Your org can request results for up to 5,000 dashboards per hour.
Analytics Notification Limits
• Each user can subscribe to up to 5 reports.
• Each user can create up to 5 Wave notifications.
Note: All limits that apply to reports created in the report builder also apply to the API, as do limits for dashboards created in the
dashboard builder. For more information, see “Salesforce Reports and Dashboards Limits” in the Salesforce online help.
3
CHAPTER 2 Examples: Reports REST API Resources
In this chapter ... The Reports and Dashboards REST API is designed to let you query report data easily.
As of API version 43.0, if your org turns on the Lightning Experience joined report beta, then you can use
• Create a New Report
the Reports REST API to work with joined reports. For more information about the Lightning Experience
• Run Reports
joined report beta, including how to opt in, see Enable Lightning Joined Reports (Beta) in Salesforce
Synchronously or
help.
Asynchronously
A report is a joined report when reportFormat is MULTI_BLOCK.
• Get Report Metadata
• Get a List of Report As you get ready to work with joined reports in the REST API, take note of these beta limitations and
Types known issues.
• Download Formatted • If you make a POST or PATCH request on a joined report to edit the report, only some properties
Excel Reports Using can be edited:
the Reports REST API
– hasDetailRows
• List Asynchronous
– hasRecordCount
Runs of a Report
– showSubtotals
• Filter Reports on
Demand – showGrandTotal
• List Recently Viewed
• If you make a POST or PATCH request on a joined report and try to change reportFormat
Reports
then you get a success code but reportFormat isn’t updated.
• Decode the Fact Map
• You can’t change reportFormat to MULTI_BLOCK.
• Get Report Data
without Saving Note: As a beta feature, Lightning Experience joined reports is a preview and isn’t part of the
Changes to or “Services” under your master subscription agreement with Salesforce. Use this feature at your sole
Creating a Report discretion, and make your purchase decisions only on the basis of generally available products
• Save Changes to and features. Salesforce doesn’t guarantee general availability of this feature within any particular
Reports time frame or at all, and we can discontinue it at any time. This feature is for evaluation purposes
only, not for production use. It’s offered as is and isn’t supported, and Salesforce has no liability for
• Clone Reports
any harm or damage arising out of or in connection with it. All restrictions, Salesforce reservation
• Delete Reports
of rights, obligations concerning the Services, and terms for related Non-Salesforce Applications
and Content apply equally to your use of this feature.
• Run Reports Synchronously or Asynchronously.
Run a report immediately or asynchronously to get summary data with or without details. We
recommend that you run reports asynchronously to avoid report timeouts and other API limits.
• Get Report Metadata.
Get information about fields in the report and report type. This includes information about fields
used for report groupings, summaries, detailed data, and filters.
• List Asynchronous Runs of a Report.
Get a list of all instances of a report run asynchronously.
4
Examples: Reports REST API Resources
• Filter Reports on Demand.
Get specific data back by running a report with filter changes in the metadata.
• List Recently Viewed Reports
Get most recently viewed reports that you have permission to access.
• Decode the Fact Map.
Get a visualized view of your report data.
• Save Changes to Reports
Save changes to reports.
• Clone Reports
Make copies of existing reports.
• Delete Reports
Clean up unused and obsolete reports.
5
Examples: Reports REST API Resources Create a New Report
Create a New Report
Create a new report using a POST request.
Example Usage
/services/data/v39.0/analytics/reports
Example Request Body
To create a report, you only have to specify reportMetadata with a name and a reportType to create a new report. Other
properties are optional.
{
"reportMetadata": {
"name":"NewReport",
"reportType": {
"type" : "Opportunity"
}
}
}
Example Response Body
The response includes the new report’s reportExtendedMetadata, reportMetadata, and reportTypeMetadata.
{
"reportExtendedMetadata" : {
"aggregateColumnInfo" : {
"RowCount" : {
"dataType" : "int",
"label" : "Record Count"
}
},
"detailColumnInfo" : {
"ROLLUP_DESCRIPTION" : {
"dataType" : "string",
"label" : "Owner Role"
},
"FULL_NAME" : {
"dataType" : "string",
"label" : "Opportunity Owner"
},
"ACCOUNT_NAME" : {
"dataType" : "string",
"label" : "Account Name"
},
"OPPORTUNITY_NAME" : {
"dataType" : "string",
"label" : "Opportunity Name"
},
"STAGE_NAME" : {
"dataType" : "picklist",
"label" : "Stage"
},
"FISCAL_QUARTER" : {
"dataType" : "string",
"label" : "Fiscal Period"
6