Exago Logo
Search
Generic filters
Exact matches only

JavaScript API

The Exago JavaScript (JS) API allows Exago functionality to be embedded directly into HTML <div> containers.

<div>s can inherit code and styles from the host application. Since CSS cascades down to Exago as well as up to the parent app, a single base of styles can be used, rather than separate ones for the host app and for Exago. The Exago DOM is accessible from the host application, so custom scripting is possible without being limited to Action Events.

Background

The JS API implements asynchronous calls to Exago BI in the client browser. Besides the advantages of embedding in <div>s and interacting programmatically, the API allows for multiple calls without needing to generate a new session for each one. As sessions are created once per page load, this can increase the feeling of responsiveness in the host application.

As the JS API runs on the client-side, it is not standalone. Session objects are still required to be generated, either with the .NET or REST Web Service API. 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 multiple JS API objects cannot be active on the same page.

The JS API object provides a set of functions that are used to implement elements of Exago BI functionality.

Note

API Actions and active reports should not be set when using the JS API as doing so may produce errors within the API session. Any desired actions, such as executing a report or editing a report on the page, should be done using the appropriate JavaScript API functions instead.

Setup and Configuration

These steps describe how to configure the environment to use the JS API, as well as how to implement it in an application.

  1. Create the Session
  2. Instantiate the JS API object

1. Create the Session

  1. Use the .NET API or REST Web Service API to set up the session. Make all configuration changes there, as these settings cannot be changed once the JS API object is loaded.

    .NET API

    Instantiate an API object with one of the available constructors.
    Example:

    Api api = new Api("appPath");

    REST Web Service API

    The Id is the session ID (sid) that will be needed for subsequent REST Web Service API calls. Save the value of the ApiKey property, as it will be needed to instantiate the JS API object in step 2.
    POST http://server/webservice_virtual_path/rest/sessions with this payload:

    {
      "AppUrl": "UrlParamString",
      ...
      "Id": "1234-5678-9012-3456",
      ...
    }
  2. Set the WebAppBaseUrl property to the virtual directory where Exago BI is installed:

    .NET API

    api.SetupData.WebAppBaseUrl = "http://server/Exago/";

    REST Web Service API

    Do either one of the following:

    • PATCH /Rest/Settings?sid={sid}. This method requires the session be established first in step 1. Payload:
      {
       "WebReportsBaseUrl" : "http://server/Exago"
      }
    • Add to the web service config file ({WebService}/Config/WebReportsApi.xml):
      <webreportsbaseurl>http://server/Exago/</webreportsbaseurl>

    In contrast to the .NET and REST Web Service APIs, the JavaScript API has no concept of an Active Report or an API Action. Instead, the action and report are specified by calling the individual JS function calls.

    Note

    A side-effect of this is that per-session report changes cannot be made in memory, since the JS API function can only act on saved reports. Changes will need to be saved to storage before execution.

  3. Once the session is ready, get the ApiKey if not saved in step 1.1 (skip this step if you already have the ApiKey). This encodes the session settings to pass to the JS API. This API key will need to be passed to the page as it will be used in client side JavaScript calls.

    .NET API

    return api.GetApiKey();

    REST Web Service API

    GET Rest/Sessions/{sid}, then get the ApiKey property from the response object:

    {
     ...
     "ApiKey": "encodedAlphanumericApiKey"
    }

2. JS API Object

  1. 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.

  2. Using the ApiKey, instantiate an ExagoApi JavaScript API object. There are two constructors available:

    Constructor 1

    var api = new ExagoApi(ExagoBaseURL, ApiKey, onLoadCallback, [showErrorDetail]);
    • ExagoBaseURL — URL to the installation of Exago BI
    • ApiKey — key generated when the session was created
    • onLoadCallback — function to execute once the JS API has been fully loaded and is ready for use
    • Optional: showErrorDetail — set to true to see more detailed application error messages. (Default: False).
    Example
    new ExagoApi("https://exago.example.com", "tCq0n6dMl6kQEbgofptKsdinMINJpqsClF5kVnzz2wcgcEfGjYE8eEeKjR3NBkjayZY%2fbs7RLTcpH9EtDyhRBA%3d%3d", () => {
          console.log("Exago is ready for further API calls!");
        }, true);

    Constructor 2 v2019.1.22+ v2019.2.8+

    This constructor contains an additional OnError() callback function. The definitions below are written using TypeScript syntax.

    var api = new ExagoApi(options: wrExagoApiOptions);

    This constructor takes one argument, an object of type wrExagoApiOptions. wrExagoApiOptions objects are defined by the following interface:

    interface wrExagoApiOptions {
        WebEndpoint: string;
        ApiKey: string;
        OnLoad: () => void;
        OnError?: (err: wrJsApiError) => void;
        OnDisposeContainer?: (container: HTMLElement) => void;
        ShowErrorDetail?: boolean;
        IncludeCredentials?: boolean;
    }
    • WebEndPoint — URL to the installation of Exago BI
    • ApiKey — key generated when the session was created
    • OnLoad() — function to execute once the JS API has been fully loaded and is ready for use
    • OnError()optional: function to execute if the loading of the JS API fails. Takes one argument, an object of type wrJsApiError which simply represents an error message if loading of the API fails. A wrJsApiError object is defined by the following interface:
      interface wrJsApiError {
          Message: string;
      }
    • OnDisposeContaineroptional: function to execute when the <div> containing Exago is no longer needed and can be disposed. Takes one argument of type HTMLElement object, the ID of the containing <div>. This is the recommended way of passing this function to the ExagoApi object. For more information, see Disposing Containers below.
    • ShowErrorDetailoptional: true if full error messages should be displayed to the end user in the browser, false if they should be saved to the log only
    • IncludeCredentials v2019.2.29+ v2020.1.13+ v2021.1.1+optional: determines the credentials mode to use for any XHR or fetch request.
      Request Type IncludeCredentials Value Result
      fetch omitted or true credentials property of the Request object is set to include
      fetch false credentials property of the Request object is set to same-origin
      XHR true withCredentials property of the XMLHttpRequest object is set to true
      XHR false withCredentials property of the XMLHttpRequest object is set to false
    OnError()

    The OnError() callback function will be called under the following conditions:

    • Any HTTP 4xx or 5xx status code is returned from any XHR or fetch request involved with initialization

    There are several use cases for the OnError() callback function, such as (but not limited to):

    • An expired ApiKey is passed
    • An incorrect WebEndPoint is passed
    • In a cross-origin environment, cookieless sessions are not enabled
    • The Exago application server is down
Example
new ExagoApi({
	WebEndpoint: "https://exago.example.com", 
	ApiKey: "tCq0n6dMl6kQEbgofptKsdinMINJpqsClF5kVnzz2wcgcEfGjYE8eEeKjR3NBkjayZY%2fbs7RLTcpH9EtDyhRBA%3d%3d",
	ShowErrorDetail: true,
	OnLoad: () => {
		console.log("Exago is ready for further API calls!");
	},
	OnError: () => {
		console.log("There was an error loading Exago"); 	}, });

Note

ApiKeys are single-use. Multiple instances are not supported nor necessary. Functions can be called against the object for the duration of the session.

Functions

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 onLoadCallback() or OnLoad() 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+.

LoadFullUI(container)

Load the full web application user interface in to a <div> container.

Argument Description
container <div> container to place the user interface 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 Exago functions such as executing reports or creating new reports.

ExecuteReport(container, exportType, reportPath, [udfOrOptions], [updateCallback], [errorCallback])

ExecuteReport(container, exportType, reportID, [udfOrOptions], [updateCallback], [errorCallback], true) v2020.1.23+ v2021.1.11+

ExecuteReport(container, exportType, reportPath, [udfOrOptions], [updateCallback], [errorCallback], false)v2020.1.23+v2021.1.11+

Execute a report to a specific output type in a defined container.

Argument Description
container Div container to place the executed report into
exportType html|pdf|pdfsnapshot (v2021.2+)|csv|excel|rtf
reportPath Relative path to report to execute
Example: “MyFolderMyReport”
reportId v2020.1.23+v2021.1.11+ The content ID of the report from the Storage Management database. When using this option, the useReportId argument must be passed as true.
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

Note

If the wrJsApiExecuteReportOptions object is passed to this parameter, the updateCallback and errorCallback parameters will be ignored and ExecuteReport will change its behavior based upon the contents of the object being passed. For more information, please see the Interfaces section below and the JavaScript API: Filters and Parameters article.

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

  • Parameter ‘container’: The same container HTMLElement that was passed in to the call
  • Parameter ‘updateType’: The type of update as a string, either

The parameter ‘updateType’ will assume one of these string values:

  • “executionstart”: The report has been loaded and is starting execution, or
  • “initialcontentload”: The execution viewer has been loaded and populated with at least the first page of the report, if executing an Advanced Report or ExpressView to HTML)

Note: This callback will occur once for each status change unless errors occur.

errorCallback (container, errorMessage) => string Optional: Callback to execute in the event an execution blocking error occurs

  • Argument ‘container’: The same container HTMLElement that was passed in to the call
  • Argument ‘errorMessage’: The error text

Return value: See errorCallback return values below.

useReportId v2020.1.23+v2021.1.11+ When calling a report by its Storage Management content ID, set this value to true. When calling a report by its report path, set this value to false.

Note

Exago recommends calling reports by their ID in all versions that support doing so.

ExecuteStaticReport(exportType, reportPath, udfOrOptions , successCallback, [errorCallback])

Execute an Advanced Report, and return its output to the successCallback function. Report is not interactive.

Note

This function is only compatible with Advanced Reports.

Argument Description
exportType html|pdf|csv|excel|rtf|json
reportPath Relative path to report to execute
Example: “MyFolderMyReport”
udf pre-v2019.1 Report UDF information for use with folder management
udfOrOptions v2019.1+ Report UDF information for use within folder management or a Report Options object for modifying reports before execution

Note

If the wrJsApiExecuteStaticReportOptions object is passed to this parameter, the sucessCallback and errorCallback parameters will be ignored and ExecuteReport will change its behavior based upon the contents of the object being passed. For more information, please see the Interfaces section below and the JavaScript API: Filters and Parameters article.

successCallback (executionData) Callback to execute when execution request returns

  • Parameter ‘executionData’: a string containing the executed report’s data is passed as a parameter, whose formatting depends on the specified exportType. If the export type is “html”, “csv”, or “json”, the returned string will contain all of the data in the corresponding format. If the export type is “pdf”, “excel”, or “rtf”, the returned string will be partial URL to the file, e.g. “ExecuteExport.aspx?eid=…”. See the below example for prefixing the returned partial URL with the base address.
errorCallback (errorMessage) Optional: Callback to execute in the event an error occurs.

  • Parameter ‘errorMessage’: The error text.

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;
     });

ScheduleReportWizard(container, reportPath, [udf], [errorCallback], [successCallback])

Start the Schedule Report Wizard for the specified report.

Note

The optional successCallback is available in v2021.1.14+.

Argument 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

  • Parameter ‘container’: The same container HTMLElement that was passed in to the call
  • Parameter ‘errorMessage’: The error text

Return value: see errorCallback return values below.

ScheduleReportManager(container, [errorCallback], [successCallback])

Open the Schedule Manager.

Note

The optional successCallback is available in v2021.1.14+.

Argument 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

  • Parameter ‘container’: The same container HTMLElement that was passed in to the call
  • Parameter ‘errorMessage’: The error text

Return value: see errorCallback return values below.

LoadReportTree(successCallback, [errorCallback])

Load the report tree as JSON, returned to the successCallback method.

Argument Description
successCallback (reportTree) Callback to execute once the report tree has been loaded.

  • Argument ‘reportTree’: A JSON object representing the report tree.
errorCallback (errorMessage) Optional: Callback to execute in the event an error occurs

  • Argument ‘errorMessage’: The error text

EditReport(container, reportPath, [udf], [errorCallback], [successCallback])

Load the report designer for a report.

Note

The optional successCallback is available in v2021.1.14+.

Argument Description
container Div container to place the report designer into
reportPath Relative path to report to edit
Example: “MyFolderMyReport”
udf Optional: Report UDF information for use with folder management
errorCallback (container,

errorMessage) => string

Optional: Callback to execute if the report fails to load

  • Parameter ‘container’: The same container HTMLElement that was passed in to the call
  • Parameter ‘errorMessage’: The error text

Return value: see errorCallback return values below.

NewReport(container, reportType, [successCallback])

Create a new report in the corresponding Report Designer. For pre-v2020.1, passing advanced to the reportType argument will start the New Report Wizard.

Note

The optional successCallback is available in v2021.1.14+.

Argument Description
container Div container to place the report designer into
reportType advanced|express|dashboard|chained|expressview

DisposeContainerContent(container)

Disposes the contents of a container and resets the system state to be aware of what containers are open.

Argument 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.

IsAllowedReportType(reportType)

Returns whether or not a specified report type is allowed for the session.

Tip

CrossTab Reports are a type of Advanced Report.

Argument Description
reportType advanced|express|dashboard|chained|expressview

GetAllowedReportTypes()

Returns an array of the report types allowed for this session.

Example:
function RunReportJS() {
   var container = document.getElementById("ExagoDiv");
   api.ExecuteReport(container, "html", "ExamplesClientReport");
 }

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;
 }

Disposing Containers

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); };

Disposing Pages 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.

errorCallback return value

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:

  • If errorCallback is not defined, an alert dialog will appear with the error message (or a placeholder error message, if the URL parameter ‘showerrordetail’ is set to false).
  • If errorCallback is defined, it will first be called. If errorCallback returns a string (either the original error message or a custom message), an alert dialog will appear with the given string, or a placeholder error message if the URL parameter ‘showerrordetail’ is set to false.
  • If errorCallback does not return a string, or the string is empty, no alert dialog will be shown and the DisposeContainerContent() method will run immediately.

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.

Interfaces v2019.1+

The following interfaces are available for managing and modifying report settings at runtime.

wrJsApiExecuteReportOptions

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

wrJsApiExecuteStaticReportOptions

Allows information for the modification of filters and parameters of a non-interactive report to be passed to the udfOrOptions parameter of the ExecuteStaticReport function. If this interface is passed to ExecuteStaticReport the successCallback and errorCallback parameters of this function will be ignored; however, they may be specified within this interface if necessary.

Note

All parameters in the wrJsApiExecuteStaticReportOptions object are optional.

Parameter Description
Udf The UDF information used to load the report if required
SuccessCallback (execution) => void
Callback to execute when the report execution succeeds
ErrorCallback (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

  • When executing an Advanced Report, an array of wrJsApiPromptingFilterValue objects should be passed
  • When executing a Dashboard or Chained Report, an array of wrJsApiCompositePromptingFilterValue objects should be passed

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 modify before execution begins.

wrJsApiExecuteReportFilter

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 =

  • “EqualTo” (Default)
  • “NotEqualTo”
  • “LessThan”
  • “LessThanOrEqualTo”
  • “GreaterThan”
  • “GreaterThanOrEqualTo”
  • “StartsWith”
  • “NotStartsWith”
  • “EndsWith”
  • “NotEndsWith”
  • “Contains”
  • “NotContains”
  • “Between”
  • “NotBetwen”
  • “OneOf”
  • “NotOneOf”
PromptFlag Select whether or not to prompt the user for a value upon report execution

  • Defaults to False
AndFlag Set to True to insert an AND condition after this filter, set to False to insert an OR condition after this filter

  • Defaults to True
GroupWithNextFlag Select whether or not to group this filter with the filter following it

  • Defaults to False
Values The values to add to the filter. 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).

Note

All date values must be passed as JavaScript Date objects (e.g., var date = new Date(‘December 17, 1995 03:24:00’);.

Title The name of the filter

  • Defaults to an empty string (“”)

wrJsApiPromptingFilterValue

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

  • Defaults to 0 (zero)
Operator Optional: Reassign the condition used to match the data values to the specified filter value or values type wrJsApiFilterOperator =

  • “EqualTo”
  • “NotEqualTo”
  • “LessThan”
  • “LessThanOrEqualTo”
  • “GreaterThan”
  • “GreaterThanOrEqualTo”
  • “StartsWith”
  • “NotStartsWith”
  • “EndsWith”
  • “NotEndsWith”
  • “Contains”
  • “NotContains”
  • “Between”
  • “NotBetwen”
  • “OneOf”
  • “NotOneOf”
Values The values to add to the filter. 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).

Note

All date values must be passed as JavaScript Date objects (e.g., var date = new Date(‘December 17, 1995 03:24:00’);.

wrJsApiCompositePromptingFilterValue

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 =

  • “EqualTo”
  • “NotEqualTo”
  • “LessThan”
  • “LessThanOrEqualTo”
  • “GreaterThan”
  • “GreaterThanOrEqualTo”
  • “StartsWith”
  • “NotStartsWith”
  • “EndsWith”
  • “NotEndsWith”
  • “Contains”
  • “NotContains”
  • “Between”
  • “NotBetwen”
  • “OneOf”
  • “NotOneOf”
Values he values to add to the filter. 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).

Note

All date values must be passed as JavaScript Date objects (e.g., var date = new Date(‘December 17, 1995 03:24:00’);.

wrJsApiExecuteReportParameter

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.

With multi-value parameters introduced in v2021.2.2, the Value property supports an array of values for those parameters that are already mutli-value. Use the REST Web Service API or .NET API to change a Parameter between single or multi-value.

Property Description
Name The name of the non-hidden parameter to modify. This value must not contain the ‘@’ symbol.
Value The value, or array of values to give to the parameter. Can be a string, number, or date depending on the parameter’s datatype.

Caution

If the parameter is single-value, passing an array to this property throws an error message.

PromptText The text that will display when prompting the user for a value. If this field is set to a null value, the parameter will be considered non-prompting.
Was this article helpful?
0.5 out of 5 stars
5 Stars 0%
4 Stars 0%
3 Stars 0%
2 Stars 0%
1 Stars 100%
How can we improve this article?
Please submit the reason for your vote so that we can improve the article.
Table of Contents