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

Export a package for the report or report objects in compressed (zip) format. The returned content contains the report source files, plus the results of data queries and image rendering, constituting all that is needed for remote viewing of the report.

The user's language, which is used in both rendering and caching. For technical details, see "/tools.ietf.org/html/rfc7231#section-5.3.5"  It affects the language of reports if they have been translated. This setting overrides any other user preference that has been set, such as the "offline process locale" preference in Visual Analytics. If this header is not set and there is no user preference, the language is the default language of the service.

Accept-Language

A "format locale" that is distinct from the user's language (Accept-Language). Its syntax is similar to Accept-Language. It is honored in running of queries and formatting of values. This setting overrides any other user preference that has been set, such as the "regional locale for formats" preference in Visual Analytics. If this header is not set and there is no user preference, the format locale is the default locale of the service.

Accept-Locale

Identifier of an existing report resource. Report identifiers are generated by the Reports API when reports are created.

reportId

This parameter lists the labels of the report objects to include in the request. Multiple object labels are separated by commas. The labels can be quoted to avoid problems with spaces and special characters. If this is left empty, the result varies depending on the type of output. Report objects include visual elements like graphs, tables, and visual containers that the author has created in the layout, as well as 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.

reportObjects

Successful execution. Response is the package in a compressed format.

Last-Modified

The operation could not be completed before the wait period expired. This redirect (See Other) continues the process of waiting for the result.  It is used to provide liveness to the browser transmit queue.  Note that although this practice of redirecting is common, clients that cannot follow a redirect must either not use this method or specify a longer `wait` period.

A URI back to this service to wait for a pending result.

Location

This is an example of Bad request GET export data call


Error

application/vnd.sas.error

Content-Type

Provided if a location would be meaningful in the error context.

This is an example of  export data job request


Export a report package

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

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.


request

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


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
Accept-Language	string	false	The user's language, which is used in both rendering and caching. For technical details, see "/tools.ietf.org/html/rfc7231#section-5.3.5" It affects the language of reports if they have been translated. This setting overrides any other user preference that has been set, such as the "offline process locale" preference in Visual Analytics. If this header is not set and there is no user preference, the language is the default language of the service.
Accept-Locale	string	false	A "format locale" that is distinct from the user's language (Accept-Language). Its syntax is similar to Accept-Language. It is honored in running of queries and formatting of values. This setting overrides any other user preference that has been set, such as the "regional locale for formats" preference in Visual Analytics. If this header is not set and there is no user preference, the format locale is the default locale of the service.

Status	Meaning	Description
200	OK	Successful execution. Response is the package in a compressed format.	Headers	Schema
303	See Other	The operation could not be completed before the wait period expired. This redirect (See Other) continues the process of waiting for the result. It is used to provide liveness to the browser transmit queue. Note that although this practice of redirecting is common, clients that cannot follow a redirect must either not use this method or specify a longer `wait` period.	Headers	Schema
400	Bad Request	There was an error in the request.	Headers	Schema
403	Forbidden	Forbidden error.		Schema
404	Not Found	Not found Error		Schema

Export a report package

Request Samples

Response Samples

Path Parameters

Query Parameters

Header Parameters

Responses