Reports and Dashboards REST API Cheatsheet
Total Page:16
File Type:pdf, Size:1020Kb
Reports and Dashboards REST API Cheatsheet Overview The Salesforce Reports and Dashboards REST API provides simple and easy-to-use APIs to interact with Salesforce reports and dashboards. Each resource in the REST API is a named URI that's used with an HTTP GET, POST, or PUT method. All resources are accessed using a generic interface over HTTP with a base URI that follows your Force.com URI. The Reports and Dashboards REST API supports JSON. For more detailed information, see the Reports and Dashboards API Developer Guide at https://developer.salesforce.com/docs/atlas.en-us.api_analytics.meta/api_analytics/ Constructing the URL Dashboards Resources All Reports and Dashboards API resources are accessed using: Resource Description Method • A base URI for your company (for example, https://na1. /analytics/dashboards List all recently used dashboards. GET salesforce.com) /analytics/dashboards/ Retrieve metadata, data, and • Version information (for example /services/data/v37.0/analytics) GET • A named resource (for example, /reports or /dashboards) <dashboardId> status for the specified dashboard. /analytics/dashboards/ Put together, an example of the full URL to the resource is: Trigger a dashboard refresh. PUT https://na1.salesforce.com/services/data/v37.0/analytics/reports/ <dashboardId> /analytics/dashboards/ Retrieve status for the GET <dashboardId>/status specified dashboard. Authentication The Reports and Dashboards API uses OAuth 2.0 for authentication. Reports Examples The return from a successful authentication includes an access token, which can be used for subsequent calls to the Reports Run a Report Synchronously and Dashboards API resources. For information on setting up To run a report, use GET with the reportId parameter and your OAuth header. authentication, see “Web Service Authorization with OAuth” at This example runs the report with the ID 00OD0000001ZbP7MAK. https://developer.salesforce.com/page/Getting_Started_with_the_ curl -s -H 'Authorization: Bearer token ...' Force.com_REST_API/ https://na1.salesforce.com/services/data/v37.0/analytics/ reports/00OD0000001ZbP7MAK To include details, not just the aggregated values, append ?includeDetails=true after the report ID. This is equivalent to toggling the Show Details button in the user interface. Reports Resources Run a Report Asynchronously Request Use POST with the reportId parameter and an empty payload to run a report Resource Description Method Body asynchronously. The system returns an instance ID. curl -s -H 'Authorization: Bearer token ...' List all recently used, /analytics/reports GET N/A https://na1.salesforce.com/services/data/v37.0/analytics/ supported reports. reports/00OD0000001ZbP7MAK/instances -X POST -d '' To get the results of your asynchronous run, poll the report run instance with GET. Retrieve report, /analytics/ report type, and curl -s -H 'Authorization: Bearer token ...' reports/<reportId>/ GET N/A related metadata for https://na1.salesforce.com/services/data/v37.0/analytics/ describe reports/00OD0000001ZbP7MAK/instances/instance_id the specified report. Run a Report with Dynamic Filters /analytics/ Run the To apply dynamic filters to your report, send back the report metadata object, GET N/A reports/<reportId> specified report. with edited filters. Here’s some typical metadata that your report run might have returned. Run the specified /analytics/ Report report with POST {"reportMetadata": reports/<reportId> Metadata {"name":"CaseGeoReport","id":"00OV0000000OPPYMA4","developerName": dynamic filters. "CaseGeoReport","reportType": {"type":"CaseList","label":"Cases"},"reportFormat":"MATRIX", /analytics/ Run the "reportBooleanFilter":null,"reportFilters":[{"column": "OPEN", reports/<reportId>/ specified report POST N/A "operator":"equals", "value":"True"}],"detailColumns":["ACCOUNT. NAME","SUBJECT","CREATED_DATE","AGE","OPEN","CLOSED"],"currency": instances asynchronously. null,"aggregates":["RowCount"],"groupingsDown":[{"name":"CONTACT2. COUNTRY_CODE","sortOrder":"Asc","dateGranularity":"None"}],"grouping Run the /analytics/ sAcross":[{"name":"OWNER","sortOrder":"Asc","dateGranularity":"None"}]}} specified report Report reports/<reportId>/ POST Change the filter and run the report. It will look like this. (This example is asynchronously Metadata instances synchronous, but an asynchronous run works the same way.) with filters. curl -s -H 'Authorization: Bearer token ...' https:// List the 200 na1.salesforce.com/services/data/v37.0/analytics/ /analytics/ reports/00OV0000000OPPYMA4 -X POST -d '{"reportMetadata": most recent run {"name":"CaseGeoReport","id":"00OV0000000OPPYMA4","developerName": reports/<reportId>/ GET N/A instances of the "CaseGeoReport","reportType":{"type":"CaseList","label":"Cases"}, instances "reportFormat":"MATRIX","reportBooleanFilter":null,"reportFilters": specified report. [{"column": "OPEN", "operator":"equals", "value":"False"}], "detailColumns":["ACCOUNT.NAME","SUBJECT","CREATED_DATE","AGE", /analytics/ Fetch the specified "OPEN","CLOSED"],"currency":null,"aggregates":["RowCount"], "groupingsDown":[{"name":"CONTACT2.COUNTRY_CODE","sortOrder": reports/<reportId>/ run instance of the GET N/A "Asc","dateGranularity":"None"}], "groupingsAcross": instances/<instanceId> specified report. [{"name":"OWNER", "sortOrder":"Asc","dateGranularity":"None"}]}}' Reports and Dashboards REST API Cheatsheet Dashboards Examples Get a List of Recently Used Dashboards Get Dashboard Results To get a list of recently used dashboards, use GET on the Dashboard To get dashboard metadata, data, and status, use GET on the Dashboard List resource. Results resource. curl -s -H 'Authorization: Bearer token ...' https://na1.salesforce.com/ curl -s -H 'Authorization: Bearer token ...' https:// services/data/v37.0/analytics/dashboards na1.salesforce.com/ Here’s an example of the dashboard information that might be returned. services/data/v37.0/analytics/ { dashboards/01ZD00000007S89MAE "id" : "01ZD00000007QeuMAE", Here’s an example of the result information that might be returned. "name" : "Adoption Dashboard","statusUrl" : "/services/data/v37.0/analytics/ { dashboards/01ZD00000007QeuMAE/status","url" : "componentData" : [ { "/services/data/v37.0/analytics/ "componentId" : "01aD0000000a36LIAQ", dashboards/01ZD00000007QeuMAE" "reportResult" : { }, { // Report result data omitted for brevity. id" : "01ZD00000007QevMAE", }, "name" : "Global Sales Dashboard","statusUrl" : "status" : { "/services/data/v37.0/analytics/ "dataStatus" : "DATA", dashboards/01ZD00000007QevMAE/status","url" : "errorCode" : null, "/services/data/v37.0/analytics/ "errorMessage" : null, dashboards/01ZD00000007QevMAE" "errorSeverity" : null, } "refreshDate" : "2014-04-10T20:37:43.000+0000", Refresh a Dashboard "refreshStatus" : "IDLE" To refresh a dashboard, use PUT on the Dashboard Results resource. } curl -s -H 'Authorization: Bearer token ...' } ], https://na1.salesforce.com/services/data/v37.0/analytics/ "dashboardMetadata" : { dashboards/01ZD00000007S89MAE -X PUT "attributes" : { "dashboardId" : "01ZD00000007S89MAE", The response contains the status URL for the refreshed dashboard. "dashboardName" : "Simple Dashboard", { "statusUrl" : "/services/data/v37.0/analytics/ "statusUrl" : "/services/data/v37.0/analytics/ dashboards/01ZD00000007S89MAE/status", dashboards/01ZD00000007S89MAE/status" "type" : "Dashboard" } }, Get Dashboard Status "canChangeRunningUser" : false, To get the status of a dashboard, use GET on the Dashboard Status resource. "components" : [ { "componentData" : 0, curl -s -H 'Authorization: Bearer token ...' "footer" : null, https://na1.salesforce.com/services/data/v37.0/analytics/ "header" : null, dashboards/01ZD00000007S89MAE/status "id" : "01aD0000000a36LIAQ", The response contains the status for each component, along with the "properties" : { refresh date and time. The components are listed in the order in which "aggregateName" : "s!AMOUNT", they were refreshed. "maxRows" : null, { "sort" : { "componentStatus" : [ { "column" : "TYPE", "componentId" : "01aD0000000J7M7", "sortOrder" : "asc" "refreshDate" : "2014-03-10T17:26:07.000+0000", }, "refreshStatus" : "IDLE" "visualizationProperties" : { }, }, { "visualizationType" : "Bar" "componentId" : "01aD0000000J7M9", }, "refreshDate" : "2014-03-10T17:26:08.000+0000", "reportId" : "00OD0000001g2nWMAQ", "refreshStatus" : "IDLE" "title" : null, }, { "type" : "Report" "componentId" : "01aD0000000J7MB", } ], "refreshDate" : "2014-03-10T17:26:09.000+0000", "description" : null, "refreshStatus" : "IDLE" "developerName" : "Simple_Dashboard", } ] } "filters" : [ { "name" : "Amount", Reports Error Codes "options" : [ { "alias" : null, HTTP Error "endValue" : null, Error Message Code "id" : "0ICD00000004CBiOAM", "operation" : "greaterThan", 400 Badly formatted metadata body in POST. "startValue" : null, 400 Filter validation error. "value" : "USD 2000000" 400 Missing metadata in POST body for filters. } ], "selectedOption" : null 400 No selected report columns. } ], 400 Too many report columns, aggregates, or formulas. "id" : "01ZD00000007S89MAE", "layout" : { 403 Any limit error. "columns" : [ { 403 API disabled for org. "components" : [ 0 ] } ] 404 Invalid instance. }, 404 Invalid report ID. "name" : "Simple Dashboard", "runningUser" : { 415 Unsupported media type. "displayName" : "Allison Wheeler", 500 Report instance metadata changed. "id" : "005D00000016V2qIAE" 501 Invalid historical report format. } } 501 Invalid report format. } Dashboards Error Codes Dashboard-level error messages are returned in the response