Scroll

JavaScript API

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 can allow 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.

Background

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.

Setup and Configuration

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

Create the Session

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:

.NET

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

REST

Do one of the following:

  • PATCH /Rest/Settings?sid={sid}, Payload:
    { "WebReportsBaseUrl" : "http://server/Exago" }
  • Add to the web service config file ({WebService}/Config/WebReportsApi.xml):
    <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.

.NET

return api.GetApiKey();

REST

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

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

Example

// REST example using jQuery
$.ajax({
  method: "POST",
  url: "http://localhost/webservice/rest/sessions",
  dataType: "json",
  contentType: "application/json; charset=utf-8",
  headers: { "Authorization": "Basic Og==" },
  success: function(data) {
    LoadJsApi(data.ApiKey);
  }
});

NOTE: This is NOT the UrlParamString / AppUrl.

JS API Object

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]);
  • 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
  • showErrorDetail - Optional: Set True to see more detailed application error messages. (Default: False).

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.

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 the onLoadCallback to indicate that the API is ready.

LoadFullUI(container)

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.

 

ExecuteReport(container, exportType, reportPath, [udf], [successCallback], [errorCallback])

Execute a report 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 Optional: Report UDF information for use with folder management
successCallback Optional: Callback to execute when request has been completed
errorCallback Optional: Callback to execute in the event an error occurs

 

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

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 Callback to execute when execution request returns
errorCallback Optional: Callback to execute in the event an error occurs

 

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

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 Optional: Callback to execute when the scheduler is not enabled and the schedule wizard cannot be started

 

ScheduleReportManager(container, [errorCallback])

Open the schedule report manager.

Parameter Description
container Div container to place the scheduled report manager into
errorCallback Optional: Callback to execute when the scheduler is not enabled and the schedule manager cannot be started

 

LoadReportTree(successCallback, [errorCallback])

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

Parameter Description
successCallback Callback to execute once the report tree has been loaded
errorCallback Optional: Callback to execute in the event an error occurs (the error text is passed as a parameter)

 

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

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 Optional: Callback to execute if the report fails to load

 

NewReport(container, reportType)

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

 

DisposeContainerContent(container)

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

 

IsAllowedReportType(reportType)

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

Parameter 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", "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;
}

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, ie. ExecuteReport(...), the container will auto-dispose and execute the OnDisposeContainer callback if one is defined.

Example

api.OnDisposeContainer = function(container) {
  container.parentElement.removeChild(container);
};

Hidden Article Information

Article Author
Exago Development
created 2017-07-28 15:00:39 UTC
updated 2017-12-13 20:44:08 UTC

Labels
no labels yet!
Have more questions? Submit a request