Telerik Report Viewer and Telerik Reporting REST Service
Most of the Telerik Report Viewers can connect to a running Telerik Reporting REST Service to request and get report documents rendered server-side. In this article we will use the HTML5 Report Viewer for clarity. The information regarding the communication between the viewer and the service is valid for the other Report Viewers as well.
The HTML5 Report Viewer is a client-side widget served by a running instance of Telerik Reporting REST Service. The state of the report displayed in the viewer is preserved between requests by the Reporting REST Service and having reports' cache storage is obligatory.
To configure the Reporting REST service cache you can choose between the available storage implementations - REST Service Storage Settings. The cache storage settings must be considered with the type of hosting of the Reporting REST Service.
The Communication Between the Report Viewer and the Reporting REST Service
The following actions are performed on displaying a report in a viewer that utilizes a Telerik Reporting REST Service for rendering the reports. For example, in the HTML5 Report Viewer:
- On loading the page with the HTML5 Viewer, the viewer sends a request to the Reporting REST service to cache a viewer with a unique clientId;
- The client-side report source (report description as a string and parameters collection in a JSON formatted string) is sent to the Reporting REST service in a request for information about visible parameters;
- The Reporting REST service resolves the received string description to a valid server-side report source object through its report source resolver set in the service's configuration. Then the service returns JSON serialized information about the report's ReportParameters collection. The HTML5 Viewer generates its Parameters Area based on the information for visible report parameters, their types, and default|initial values;
- The client-side report source (report description as a string and parameters collection in a JSON formatted string) is sent to the Reporting REST service in a request for registering the report instance on the server;
- The Reporting REST service resolves the received string description to a valid server-side report source object through its report source resolver set in the service's configuration. Then the service caches the server-side report source with a unique instanceId for the current clientId;
- The viewer sends a request for creating a document with the appropriate rendering format. The service adds a cache entry for the document with a unique documentId for the current instanceId;
- The client (HTML5 Viewer) awaits the report processing and rendering on the server to end. The viewer requests the state of the document and the number of rendered pages on an even interval from the Reporting REST service.
- When the first page is ready, the viewer requests the page and it is displayed. The polling continues until all document pages are ready. Additional requests for resources as images may follow. All pages and resources are cached by the service.
The communication between the HTML5 Viewer and Reporting REST Service happens via AJAX requests. More details about the type of each request to the service can be found in the REST API.
If you connect a WinForms ReportViewer or WPF ReportViewer to a Reporting REST Service instance, there will be a new ClientId generated on each request sent by the desktop viewer.
On each interaction with the report in the HTML5 Viewer, the service accesses the cache storage provided in the service's configuration (ReportServiceConfiguration property). The current client ID, instance ID, and document ID are used to locate the correct resources for the report and return them to the viewer.
The Reporting REST Service storage assets expire. The expired assets are cleaned by the service periodically. More details about the storage structure and assets handling may be found in the blog post Telerik Reporting REST Service Storage Revealed.
The created cache records expiration period, as well as other service settings, may be set up using an implementation of the IReportServiceConfiguration interface as service configuration. See the How to implement the ReportsController in an application and the How to Add Telerik Reporting REST ServiceStack to Web Application help articles accordingly for implementation details.
Important cache management-related properties of the IReportServiceConfiguration:
-
ClientSessionTimeout property Gets or sets a value in minutes indicating how long a client(viewer) session will be preserved in the service storage after the last interaction initiated by this client. When this timeout expires, operations with the viewer will not be possible - there must be registered a new client(viewer). The entries of expired clients are removed automatically when a new HTML5 Viewer(client) is registered in the cache storage. The value should be positive. The zero (
0) value is invalid. -
ReportSharingTimeout property Gets or sets a value in minutes indicating how long a rendered report document from a client will be available to be reused, by the current and other clients which request the same report document. Two report documents are considered the same when they both comply with the following conditions:
- Use the same Report definition. For example, the same TRDP report file;
- Use the same Report Parameter values;
- The Interactive Actions are with the same state. For example, the Toggle Visibility is either in expanded or collapsed state, or the Sorting is in the same order;
- Are rendered in the same Export Format.
When a report is rendered once for a given set of the above requirements, it can be reused for the time specified as
ReportSharingTimeout. Setting theReportSharingTimeoutto0(zero, default) will cause each client request for a report to produce a new report document instead of reusing an already rendered document.
When you navigate to reports via NavigateToReportAction the Reporting engine always creates a new instance of the target report.