The Visual Analytics API enables you to perform some basic tasks with reports, such as the following:
- Export all or part of a report as PDF with options to customize the appearance of the printed document.
- Export all or part of a report as an image or images.
- Export a report package that can be used by a client application to display a report when the client is offline.
- Export the data for an object in a report in a given format (such as comma-separated values).
In addition, the /visualAnalytics/reports endpoint provides programmatic access to common functionality
for manipulating a report. While using this endpoint, these tasks (or operations) are defined
in the body of a request by one or more operation objects. These operations are performed
sequentially on the report and all must succeed in order for any of operational updates to be
persisted.
Here are some examples of typical usages of this API:
- Create a new report, adding one or more data sources along with one or more visual objects.
- Create a new report from an existing report, adding one or more visual objects.
- Update an existing report, adding one or more visual objects.
- Update an existing report, applying a previously saved data view.
The following are the currently supported operations.
- addData: Add a data source to a report.
- changeData: Change a data source on a report.
- applyDataView: Apply a data view to a report.
- addPage: Add a new page to a report.
- addObject: Add a new visual object to a report.
- setParameterValue: Set a parameter value on a report.
On a POST request, a new report is always created if the request is successful. The operations
defined in the request body are performed on that report sequentially. The new report is
persisted only if all the specified operations are successfully performed on the report.
On a PUT request, an existing report can be updated or an existing report can be used as the
source for creating a new report. The source report is specified using the reportId on the
URL of the request. Whether updating an existing report or creating a new report from an existing
report, all the operations on the request must succeed in order for the update to be persisted. The presence
of the below properties in the root object of the body of the request defines the request objective
of creating a new report. The absence of these properties indicates that the source report should
be directly updated.
"resultFolder: /folders/folders/@myFolder"
"resultReportName: NewReport"
"resultNameConflict: replace"
If specifying a new report to be created for a PUT request, each of the result properties
listed above has a default value and can be omitted. Only one of the resultFolder property or
the resultReportName property is required to specify that a new report should be created in this
scenario. The other properties if omitted, use their default value.
Definitions, Resources, and Media Types
Shared Media Types
The visualAnalytics API uses several media types that are shared by most SAS APIs.
application/vnd.sas.report
Documents in the format used by SAS Visual Analytics are called reports. The vnd.sas.report media type contains information about a saved report. It does not directly contain the content of the report.
application/vnd.sas.api
Contains top-level links for an API. See
application/vnd.sas.api
The GET / response API object includes basic actions that are identified by their relation properties. See the example response of the Root API for a list of links and their relation names.
application/vnd.sas.error (v2)
The standard SAS error format. This is returned for most 400 and 500-level responses, and it is an optional member of the "job" media types.
application/vnd.sas.error (v2)
External Media Types
The visualAnalytics API uses the following external media types:
application/pdf
The PDF file structure is an industry-standard format for printing documents. Modern browsers and PDF viewing applications are able to render them.
application/zip
The media type of compressed "SAS package" files.
image/svg+xml
SVG images are XML strings following the SVG protocol. Modern browsers are able to render them. Neither this service, nor a client, should need to parse this string.
For more information see wikipedia or https://www.w3.org/Graphics/SVG/.
Internal Media Types
Type: application/vnd.sas.visual.analytics.report.export.pdf.request
This object is used to make a PDF export request that runs as a background process. It is the request body of POST that starts the task and returns immediately. The response body is a
application/vnd.sas.visual.analytics.report.export.pdf.job that contains a link used to poll the progress of the job.
The print options for rendering the PDF are not exactly the same as the options for the Report Renderer API. The options are named to match what is used in the VA SDK.
Type: application/vnd.sas.visual.analytics.report.export.pdf.job
The response from starting a job to export a PDF of a report, or from requerying the status of a PDF export job.
Type: application/vnd.sas.visual.analytics.reports.request+json
The request to perform one or more operations on a report. The details of the operations to be performed are contained in one or more report operation objects in the body of the request.
Type: application/vnd.sas.visual.analytics.reports.results+json
The response from successfully performing one or more operations on a report. The details of the response are operation dependent and contained in the report operation object in the body response. The array of operation responses in the body of the response correspond to the array of operations in the request.
Type: application/vnd.sas.visual.analytics.reports.error+json
The response from performing one or more operations on a report where an error has occurred. The details of the error(s) are in the response body and are operation dependent. The array of operation responses in the body of the response correspond to the array of operations in the request. Any messages related to specific operations in the request are contained in the specific response for that operation.