The Exago JavaScript (JS) API allows Exago functionality to be embedded directly into HTML div containers.
Divs can inherit code and styles from the host application. Since CSS cascades down to Exago, as well as up to the parent app, this allows you to maintain a single base of styles rather than separate ones for the host app and for Exago. And the Exago DOM is accessible from the host application, so custom scripting is possible without being limited to Action Events.
The JS API implements asynchronous calls to Exago functionality in the client browser. Besides the advantages of being able to embed in divs and interact programmatically, the API also allows for multiple calls to happen without needing to generate a new session for each one. As sessions are created only once per page load, this can increase the feeling of responsiveness in the host application.
Because the JS API runs on the client-side, it is not standalone. You are still required to generate session objects with either the .NET or REST APIs. Session objects must include any relevant user permissions and configuration settings.
A parameter called the ApiKey encodes the session object in a string, which is passed from the server-side API to the JS API. The JS API then initializes a JS API object, which is analogous to an Exago user session.
Note: JS API objects are static and single-use. They cannot persist between page loads, and you cannot have multiple JS API objects active on the same page.
The JS API object provides a set of functions that are used to implement elements of Exago functionality.
These steps describe how to configure your environment to use the JS API, as well as how to implement it in an application.
First you need to use the .NET or REST API to set up security and permissions for the session. Make all your configuration changes here, as these settings cannot be changed once the JS API object is loaded.
Set the WebAppBaseUrl property to the virtual directory where Exago BI is installed:
api.SetupData.WebAppBaseUrl = "http://server/Exago/";
Do one of the following:
{ "WebReportsBaseUrl" : "http://server/Exago" }
<webreportsbaseurl>http://server/Exago/</webreportsbaseurl>
The JS API has no concept of an Active Report or an API Action, so do not set these as they will have no effect. The action and report are specified by the individual JS function calls.
Note: A side-effect of this is that you cannot make per-session report changes in memory, since the JS API function can only act on saved reports. You will need to save any changes to disk instead.
When the session is ready, get the ApiKey. This encodes the session settings to pass to the JS API.
return api.GetApiKey();
GET "Rest/Sessions/{sid}", then get the ApiKey property from the response object:
{ ... "ApiKey": "encodedAlphanumericApiKey" }
Note: This is not the UrlParamString / AppUrl.
Load the JS API library into the host web application via a script tag:
<script src="http://server/Exago/WrScriptResource.axd?s=ExagoApi"></script>
Note:WrScriptResource.axd
is not a file on the file system, it is a virtual file that contains the necessary scripts to load the API."http://server/Exago"
is the URL to the virtual path of your Exago web application.
Using the ApiKey, initialize a JS API object.
var api = new ExagoApi(ExagoBaseURL, ApiKey, onLoadCallback, [showErrorDetail]);
Note: ApiKeys are one-use. Multiple instances are not supported nor necessary. Functions can be called against the object for the duration of the session.
The following functions are available for loading and managing Exago functionality.
Note: Functions can only be used once the JS API is fully loaded. Wait for the onLoadCallback to indicate that the API is ready.
Caution: Due to a known issue, the callbacks mentioned in the following JavaScript API functions only work as described as of v2018.1.12+ or v2018.2+.
Load the full User Interface in a div.
Parameter | Description |
container | Div container to place the full UI into |
Note: The Full UI being loaded will block almost all other actions, so while the Full UI is displayed on screen, the host application cannot perform any other actions such as executing reports or creating new reports.
Execute a report or dashboard to a specific output type in a defined container.
Parameter | Description |
container | Div container to place the executed report into |
exportType | html|pdf|csv|excel|rtf |
reportPath | Relative path to report to execute Example: "MyFolder\\MyReport" |
udf (pre-v2019.1) | Optional: Report UDF information for use with folder management |
udfOrOptions (v2019.1+) |
Optional: Report UDF information for use within folder management or a Report Options object for modifying reports before execution
|
updateCallback (container, updateType) | Optional: Callback to execute when the execution status changes, called when the report execution is starting and again when it is ready to be viewed
|
errorCallback (container, errorMessage) => string |
Optional: Callback to execute in the event an execution blocking error occurs
Return value: See errorCallback return values below. |
Execute a report, and return its output to the successCallback function. Report is not interactive.
Parameter | Description |
exportType | html|pdf|csv|excel|rtf|json |
reportPath | Relative path to report to execute Example: "MyFolder\\MyReport" |
udf | Report UDF information for use with folder management |
successCallback (executionData) |
Callback to execute when execution request returns
|
errorCallback (errorMessage) |
Optional: Callback to execute in the event an error occurs.
Return value: See errorCallback return values below. |
const container = ... const exportType = ... const reportPath = ... api.ExecuteStaticReport(exportType, reportPath, null, (executionData) => { if (exportType == "excel" || exportType == "rtf" || exportType == "pdf") container.innerHTML = "<iframe src="' + api.GetBaseAddress() + executionData + '"></ iframe>"; else container.innerHTML = executionData; }, (errorMessage) => { container.innerHTML = errorMessage; });
Open the schedule report wizard for a report.
Parameter | Description |
container | Div container to place the scheduled report wizard into |
reportPath | Relative path to report to schedule Example: "MyFolder\\MyReport" |
udf | Optional: Report UDF information for use with folder management |
errorCallback (container, errorMessage) => string |
Optional: Callback to execute in the event an error occurs, such as the scheduler being disabled
|
Open the schedule report manager.
Parameter | Description |
container | Div container to place the scheduled report manager into |
errorCallback (container, errorMessage) => string |
Optional: Callback to execute in the event an error occurs, such as the scheduler being disabled
|
Load the report tree as JSON, returned to the successCallback method.
Parameter | Description |
successCallback (reportTree) |
Callback to execute once the report tree has been loaded.
|
errorCallback (errorMessage) |
Optional: Callback to execute in the event an error occurs
|
Load the report designer for a report.
Parameter | Description |
container | Div container to place the report designer into |
reportPath | Relative path to report to edit Example: "MyFolder\\MyReport" |
udf | Optional: Report UDF information for use with folder management |
errorCallback (container, errorMessage) => string |
Optional: Callback to execute if the report fails to load
|
Load the report designer for a new report.
Parameter | Description |
container | Div container to place the report designer into |
reportType | advanced|express|dashboard|chained|expressview |
Disposes the contents of a container and resets the system state to be aware of what containers are open.
Parameter | Description |
container | Div container to dispose |
Disposes the contents of a page, removing any event listeners added to the page and performing other cleanup necessary for complete removal of the ExagoAPI instance. After calling DisposePage(), the ExagoAPI instance should be considered "closed." Any new Exago JavaScript API calls must be performed on a new ExagoAPI instance.
Returns whether or not a specified report type is allowed for the session.
Parameter | Description |
reportType | advanced|express|dashboard|chained|expressview |
Returns an array of the report types allowed for this session.
function RunReportJS() { var container = document.getElementById("ExagoDiv"); api.ExecuteReport(container, "html", "Examples\\ClientReport"); }
Note: Container divs must be empty or disposed before loading. Additionally, you should specify size and position constraints for each div.
div#ExagoDiv { width: 1200px; height: 600px; position: relative; }
It is important to properly dispose of containers when they are finished being used by explicitly calling the DisposeContainerContent(container) method.
Optionally, an OnDisposeContainer callback can be defined that will execute when a container has been disposed either implicitly or explicitly. This allows the host application to safely reset the container to whatever state necessary, or remove the container from the page entirely. When a user encounters an error that prevents the requested action, e.g., ExecuteReport(...), the container will auto-dispose and execute the OnDisposeContainer callback if one is defined.
Example:
api.OnDisposeContainer = function(container) { container.parentElement.removeChild(container); };
(v2018.2+)
Once an ExagoAPI instance has been instantiated, DisposePage() must be called before instantiating subsequent ExagoAPI instances. DisposePage() will dispose the contents of an entire page, thereby disposing each instantiated container. Furthermore, it will remove any event listeners added to the page by the ExagoApi instance and perform other cleanup necessary for complete removal of the ExagoAPI instance.
After calling DisposePage(), the ExagoAPI instance should be considered "closed." Any new Exago JavaScript API calls must be performed on a new ExagoAPI instance.
Whenever an error occurs that prevents the JS API action from updating a container (such as an undefined report name in a call of ExecuteReport), the following will happen:
Clicking on the error dialog’s dismiss button will close the dialog and call DisposeContainerContent(). The container’s content will be closed, the inner HTML will be cleared, and the OnDisposeContainer callback will be called.
As of v2019.1+, the following interfaces are available for managing and modifying report settings at runtime.
Allows information for the modification of filters and parameters of a report to be passed to the udfOrOptions parameter of the ExecuteReport function. If this interface is passed to ExecuteReport the updateCallback and errorCallback parameters of this function will be ignored; however, they may be specified within this interface if necessary.
Note: All properties in the wrJsApiExecuteReportOptions object are optional.
Property | Description |
Udf | The UDF information used to load the report if required |
UpdateCallback (container, updateType) => void |
Callback to execute when there has been an update in the status of the report execution |
ErrorCallback (container, errorMessage) => string |
Callback to execute in the event an error occurs |
NewFilters | An array of wrJsApiExecuteReportFilter objects defining the new filters to add to the report before execution begins |
PromptingFilterValues |
An array of prompting filter values to modify before execution begins
Note: It is assumed that the value provided by the given item will be the final value for the filter before the report executes. As such, any filter with a value modified by an item in this array will not prompt the user upon execution. |
Parameters |
A list of wrJsApiExecuteReportParameter objects defining the non-hidden parameters to add or modify before execution begins |
Defines the necessary information for a new filter. To be passed to wrJsApiExecuteReportOptions in order to add new filters to a report prior to execution.
Property | Description |
FilterText |
The filter string (e.g., "Employees.FirstName" or "=MonthName({Employees.BirthDate})") Note: This must take the form of a data field, formula, or parameter. |
Operator |
The condition used to match the data values to the specified filter value or values type wrJsApiFilterOperator =
|
PromptFlag |
Select whether or not to prompt the user for a value upon report execution
|
AndFlag |
Set to True to insert an AND condition after this filter, set to False to insert an OR condition after this filter
|
GroupWithNextFlag |
Select whether or not to group this filter with the filter following it
|
Values |
The values to add to the filter Note: Can be a string, number, or date, or an array of any of these types if multiple values are required (e.g., for "Between" and "OneOf" filters). |
Title |
The name of the filter
|
Defines the necessary information to pass a value to a prompting filter for Advanced Reports. To be passed to wrJsApiExecuteReportOptions in order to set prompting filter values of a report prior to execution.
Property | Description |
FilterText | The filter text used to identify which filter to modify |
Index |
Optional: In the case of multiple filters having the same FilterText, the index into the matching group of filters
|
Operator |
Optional: Reassign the condition used to match the data values to the specified filter value or values type wrJsApiFilterOperator =
|
Values |
The values to add to the filter Note: Can be a string, number, or date, or an array of any of these types if multiple values are required (e.g., for "Between" and "OneOf" filters). |
Defines the necessary information to pass a value to a prompting filter for Dashboards and Chained Reports, also known as "composite reports". To be passed to wrJsApiExecuteReportOptions in order to set prompting filter values of a report prior to execution.
Property | Description |
Index |
The index of the filter as it appears in the prompting UI, beginning at 0 (zero) and increasing by 1 for each following filter |
Operator |
Optional: Reassign the condition used to match the data values to the specified filter value or values type wrJsApiFilterOperator =
|
Values |
The values to add to the filter Note: Can be a string, number, or date, or an array of any of these types if multiple values are required (e.g., for "Between" and "OneOf" filters). |
Defines the necessary information to add or modify non-hidden parameters. To be passed to wrJsApiExecuteReportOptions in order to add or set parameter values of a report prior to execution.
Property | Description |
Name |
The name of the non-hidden parameter to modify Note: This value must not contain the '@' symbol. |
Value |
The value to give to the parameter Note: Can be a string, number, or date depending on the parameter's datatype. |
PromptText |
The text that will display when prompting the user for a value Note: If this field is set to a null value, the parameter will be considered non-prompting. |