Creates, reads, updates, and deletes reports and report states

visualization_and_reports

2024.10

2023.10

2024.09

2024.07

2024.08

2024.03

The Visual Analytics API provides simplified ways to perform basic tasks with reports.  Tasks include exporting a report as a PDF file, or as a package file, or exporting an image of a part of the report.

Visual Analytics

2023.03

2022.09

Create a report while applying the specified operation(s). The new report may be generated with a specific name and location by denoting the resultFolder and resultReportName in the body of the request. If neither of these are specified in the body, the a report named "Report" is generated in the location /folders/folders/@myFolder.

Example of a request that includes an addPage operation.


Example of a request that includes an addData operation.


Example of a POST request that includes an changeData operation.


Example of a POST request that includes an applyDataView operation.


Example of a request that includes an addObject operation to add a bar chart to the report.


Example of a request that includes a setParameterValue operation.


A request object is the root object contained in the body of requests for put and post endpoints. It specifies the destination of the resulting report as well as the operations to be performed on the report.


The request details identifying the operations to be performed on the new report.

Example of a response that includes an addPage operation.


Example of a response that includes an addData operation.


Example of a response for a POST request that includes a changeData operation.


Example of a POST response that includes an applyDataView operation.


Example of a response that includes a setParameterValue operation.


This object represents the response to a request and contains the individual responses for each of the requested operations.


Content-Type

Location

A tag that identifies this revision of the new report.

Etag

The last modified timestamp for the report.

Last-Modified

Example of a request that includes an addData operation that was unable to find the data.


This is a bad request. The request is not properly formed or the body is missing required fields.

Example of an error for a request where the folder to save the report was not found.


Error

application/vnd.sas.error

Example of an error for a request where the file specified to save the report already exists.


A report with the same name already exists in the destination folder.

Create a report while applying the specified operation(s)

A margin value that is applied to all four margins of the page. It is nonnegative number, integer, or floating point, which is followed by the unit. The unit can be one of several two-letter abbreviations, such as "in", "cm", "mm", "pt", "px", "em", and "ex".

margin

The paper size designation for print format rendering of reports.

paperSize

The strategy for handling name collision when saving the result file.  The value `replace` means overwrite any pre-existing file. The value `rename` specifies that the service should modify the requested name to be unique, such as by appending a number to the name. The default value is `rename`.

replacementStrategy

The name of the report object to render in the exported file. If this is left empty, the image will be a rendering of the first page of the report. Report objects include visual elements like graphs, tables, visual containers that the author has created in the layout, and complete pages. Specifying the object by its label makes it more convenient for the report author or viewer and does not to expose the internal names of objects in the model. However, if the client knows the internal identifier of a report object, it can be used instead of the label.

reportObjectLabelForImage

A list of report object names for the objects to include in the exported file. If left empty, the result is dependent on the type of the export.  For some types of export, omitting report objects means that the entire report will be processed. Report objects include visual elements like graphs and tables, visual containers that the author has created in the layout, and complete pages. Labels are not forced to be unique because they can be edited by the user. The design makes it more convenient for the report author or viewer and does not to expose the internal names of objects in the model. However, if the client knows the internal identifier of a report object, it can be used instead of the label.

reportObjectLabels

Information about the PDF that is requested.

exportPdfRequest

Information about package that is to be exported. The reportObjects property can be used to reduce the size of the resulting package. The default is to include all visual elements and pages in the report. <p> If the folder is not specified, the package is retained for a time, but will not be visible in file selection windows, such as in SAS Drive. It is cached temporarily by the Report Packages service for a period of time sufficient for clients to check the status of the package job and download it.

exportPackageRequest

Information about the image that is to be exported. It is to be determined whether the entire body is optional, since in the first iteration of this operation, defaults can be supplied by the system for all of the fields.  If an empty body is supplied in the request, a representative normal layout image of the default size is rendered of the first page of the report. The report is saved with a generated name in the personal folder of the caller's identity.

exportImageRequest

Information about visual element data that is to be exported. The reportObject property is required to export information about the underlying data. <p> If the folder is not specified, the package is retained for a time, but will not be visible in file selection windows, such as in SAS Drive. It is cached temporarily by the Report Data service for a period of time sufficient for clients to check the status of the package job and download it.

exportDataRequest

After creation of the job, the maximum number of seconds it will be allowed to run before timing out.  The default maximum is a system configuration value. This option allows the maximum to be modified for this request, but its value cannot exceed a system-configured maximum limit.  There is no guarantee that all background processes can be terminated when time-out is exceeded, but an attempt will be made where it is possible.

jobTimeout

Number of seconds to wait before returning from the initial POST to start the job. The default value is effectively zero, meaning to return the running job to the client as soon as it is created. Specifying a positive value instructs the server to wait on the running job for the specified number of seconds because the client expects the job to finish quickly. This allows the client to avoid having to poll for completion. It should be used cautiously because job durations are unpredictable.

waitSeconds

The user-visible file name of the output when it is saved in a folder on the server. If the resultFolder is provided and no resultFilename is specified on the request, the service gives the file a default name. On a running or completed job, the file name is either the requested name, optionally modified by the system to avoid name conflicts, or if the request specified no file name, it is the name generated by the system.

resultFilename

The URI of the folder in which the output file should be created.  Specifying a folder URI allows the result to be visible in user interfaces that show files, and it puts the lifetime of the result file in the control of the client.  If the result folder is not specified, the result file is transient; the system can clean up results on its own schedule, and it retains control of the lifetime of the file. The client can specify placeholder "/folders/folders/@myFolder" to save it in the user's personal folder. If the folder is specified and does not exist, it is an error.

resultFolder

exportImageOptions

Options for generating and downloading a data file in one of several formats. Supported formats are csv, tsv and xlsx. 

exportDataOptions

Options for executing the action.  May describe output characteristics or control parameters. Not all properties are applicable to every action.

exportPdfOptions

An object representing a job that is run asynchronously for this service.

exportPdfJob

exportPackageJob

exportImageJob

exportDataJob

The expected media type for the final output of the job. This is not the media type of the initial response object from starting an asynchronous job; rather, the final output has a media type like `image/svg+xml`, `text/csv` or `application/pdf`.

resultMediaType

The input resource URI report for the action job.  This is copied from the export request's report information, specifically the report id in the request path.

jobInputReport

The links to get further status or results of the export job.  The expected link relations are "self", "delete", "result", and "deleteContent". The `self` link is used to requery the state of the running job. The result link is present only if the job completed and produced a result file that can be downloaded. The "deleteContent" is present only if result content is deletable by the client.

exportJobLinks

The links to get further status or results of the image export job. The expected link relations are "self", "delete", "result". The `self` link is used to requery the state of the running job. The result link is present only if the job completed and produced a result file that can be downloaded.

exportImageJobLinks

Timestamp when job began processing.   It is in the standard internet format.

creationTimestamp

Depending on whether the job stopped or is still running, the meaning varies. If the job completed, it is the time at which the job stopped. If the job is still running, it is the time at which the job is stopped, calculated from the time of the original export request and the value of the "timeout" duration. It is in the standard internet format.

endTimestamp

Status of the overall job. If multiple results were requested, each individual result contains a separate status set.

jobState

A minimal set of properties describing a report object. Useful for obtaining the correct information needed to refer to the objects in API parameters.

reportObjectDescriptor

A standard collection or list of descriptor objects that contain key information about the visible objects in a report, such as tables, crosstabs, graphs, etc.

reportObjectCollection

A link to a related operation or resource.

Link

The standard object for the top level resource of the service.  Contains a list of link objects.

apiList

request

response

This object defines a single operation to be performed on a report.

operation

The response to an operation being performed.

operationResponse

Operation reponse for changing a data source on a report

changeDataOperationResponse

Operation reponse for adding a data source to a report

addDataOperationResponse

Operation reponse for applying a data view to a report

applyDataViewOperationResponse

Operation to apply a data view to a report

applyDataViewOperationRequest

Operation to add a data source to a report

addDataOperationRequest

Operation to change a data source on a report

changeDataOperationRequest

addObjectOperationRequest

addPageOperationRequest

Operation to set a parameter value on a report

setParameterValueOperationRequest

Operation response for adding an object to a report

addObjectOperationResponse

Operation response for setting a parameter value on a report

setParameterValueOperationResponse

Operation response for adding a page to a report

addPageOperationResponse

Representation of an apply data view operation on a request.

applyDataViewRequest

The object and layout of the object in a report.

object

Representation of an add data operation on a request.

addDataRequest

Representation of a change data operation on a request.

changeDataRequest

parameter

data

The object and placement of the object in a report. One of either the object property or the reportObject property are required. Both are not allowed.

Name	Type	Required	Description
id	string	false	The id of the request, usually a UUID.
version	integer	false	This media type's schema version number.
resultFolder	string	false	The URI of the folder in which to save the resulting report. If not specified and a new report is being created, the default value of "/reports/reports/@myFolder" is used.
resultReportName	string	false	The name of the resulting report. If not specified and a new report is being created, the default value of "Report" is used along with a resultNameConflict policy of "rename".
resultNameConflict	string	false	The name conflict resolution strategy. If not specified, the default behavior of "abort" is used when updating a report and the default behavior of "rename" is used when creating a new report. Allowed values: abortrenamereplace
operations	array [anyOf]addDataOperationRequestchangeDataOperationRequestapplyDataViewOperationRequestaddPageOperationRequestaddObjectOperationRequestsetParameterValueOperationRequest	false	This object defines a single operation to be performed on a report.

Status	Meaning	Description
201	Created	The new report was successfully created.	Headers	Schema
400	Bad Request	This is a bad request. The request is not properly formed or the body is missing required fields.	Headers	Schema
404	Not Found	The result report folder does not exist.	Headers	Schema
409	Conflict	A report with the same name already exists in the destination folder.	Headers	Schema

Create a report while applying the specified operation(s)

Request Samples

Response Samples

Request Body

Responses