# Executing Reports with the API

There are two different ways to use the Exago APIs to perform report execution. This guide discusses the main differences and provides examples for both types in each API.

API Action is the most comprehensive way to run executions, and supports all types of reports. This is the only way to run composite reports such as Dashboards and Chained Reports. This method launches an Exago session into the browser via URL, and thus usually requires the use of an iFrame. This also means that all interactive Report Viewer or ExpressView (v2016.3+) features are supported.

GetExecute executes reports on the back-end and returns bare HTML, JSON, CSV, or binary data. This only supports simple report types, Advanced, Express, and CrossTab Reports. Using this method you do not have to launch any visible instance of Exago for the user, and can simply use it as a calculation engine.

> Note: GetExecute was previously referred to as Direct Execution.

> Note: GetExecute methods are not supported by Remote Execution.

# Overview

| Launch Method | Supported Report Types | .NET Supported Output Types | SOAP Supported Output Types | REST Supported Output Types
API Action | Redirect browser frame to Exago session URL | All types | Interactive Report Viewer, Dashboard Viewer, ExpressView designer, or PDF, RTF, Excel, CSV
GetExecute | Data returned directly to calling method | Advanced, Express, Crosstab reports, ExpressViews | HTML, CSV, PDF, RTF, Excel, JSON | HTML, CSV, PDF, RTF, Excel | HTML, CSV, PDF, RTF, Excel, JSON

# API Action

API sessions in Exago have a property called action type, which determines what part of Exago should be launched when the session is opened. Action types include executing a report, loading a report into the editor, loading a report into the scheduler, opening a section of the UI, etc.

> Note. API Action is also referred to as GetUrlParamString, because this is the general term for the methods which return the session redirect URL.

To tell the session to execute a report, set the action type to ExecuteReport.

Actions which load reports, such as Execute or Edit, work on the active report object. This is another property that must be set. This is done differently for each API: details are in the included examples.

> NOTE. For security reasons, always set the action type and the active report explicitly. Although setting an active report defaults to execute, if a report fails to load and an action has not been specified, Exago will launch into the full UI. This could cause users to have unintended levels of access.

Once you've finished setting the session variables, call GetUrlParamString(). This finalizes the session and creates a single-use URL string. This is done differently for each API; details are in the included examples. The URL is used to direct a browser window or iFrame to an Exago instance where the specified action takes place. The user can then interact with the report like normal.

See the following sections for examples. Variable names and arguments are placeholders.

## .NET

First create an API session and load a report object.

    // a .net api object is a specific session; methods act on that session
    WebReports.Api.Api netApi = new WebReports.Api.Api(appPath);
    Report myReport = (Report)netApi.ReportObjectFactory.LoadFromRepository(reportPath);

Set the desired output type.

    myReport.ExportType = wrExportType.Html;

Then save the report object back to the API.

    netApi.ReportObjectFactory.SaveToApi(myReport);

Set the API action to execute.

    netApi.Action = wrApiAction.ExecuteReport;

Finally, call GetUrlParamString to get the session URL.

    // note: this terminates the session
    string url = netApi.GetUrlParamString(homePage);

## REST

When using the REST API, the initialization call creates a session ID string, which is a required URL parameter in all subsequent method calls. Note that the session URL is generated immediately, and altered dynamically as modifications are made to the session.

To use REST, create the session and pass the session variables. Take note of the sessionId and UrlParamString.

POST /sessions

Payload:

    {
     "Page": homePage,
     "ApiAction": "ExecuteReport",
     "ExportType": "Html",
     "ReportSettings":
     {
      "ReportPath": reportPath
     }
    }

Response (some params omitted):

    {
     "sid": sessionId,
     "AppUrl": urlParamString
    }

## SOAP

When using the SOAP API, the initialization call creates a session ID string, which is a required parameter in all subsequent method calls.

First create an API object and initialize an API session.

    // a soap api object is not a specific session; it's an accessor for the methods
    WebServiceApi.Api soapApi = new WebServiceApi.Api();
    // initialize a session and save the id to memory
    string sessionId = soapApi.InitializeApi();

Set the active report.

    // all methods require the session id parameter
    soapApi.ReportObject_Activate(sessionId, reportPath);

Set the API action to execute.

    soapApi.SetAction(sessionId, (int)wrApiAction.ExecuteReport, null);

Finally, call GetUrlParamString to get the session URL.

    string url = soapApi.GetUrlParamString(sessionId);

# GetExecute

There are four provided GetExecute methods. Each return a different data representation of the report. Not every API supports every data type; see the Overview for details.

- GetExecuteHtml Typically used for web viewing
- GetExecuteCsv Plain-text format readable by spreadsheet applications
- GetExecuteData Byte array of binary data
- GetExecuteJSON (v2016.3+) Typically used for asynchronous client-server communication

Since GetExecute does not require loading the Exago UI, there is no need to call GetUrlParamString.

See the following sections for examples. Variable names and arguments are placeholders.

## .NET

First create an API session and load a report object.

    // a .net api object is a specific session; methods act on that session
    WebReports.Api.Api netApi = new WebReports.Api.Api(appPath);
    Report myReport = (Report)netApi.ReportObjectFactory.LoadFromRepository(reportPath);

Then call the appropriate GetExecute method for the desired data type.

    string reportHtml = myReport.GetExecuteHtml();

## REST

When using the REST API, the initialization call creates a session ID string, which is a required URL parameter in all subsequent method calls. Note that the session URL is generated immediately, and altered dynamically as modifications are made to the session.

First create an API session. Take note of the session ID.

POST /sessions

Response (some params omitted):

    {
     "Id": sessionId
    }

Then execute the selected report. Supported types are HTML, CSV, PDF, RTF, Excel, JSON.

POST /reports/execute/{type}?sid="sid"

Payload:

    {
     "ReportPath": reportPath
    }

Response (some params omitted):

    {
     "ExecuteData": rawReportData
    }

## SOAP

When using the SOAP API, the initialization call creates a session ID string, which is a required parameter in all subsequent method calls.

First create an API object and initialize an API session.

    // a soap api object is not a specific session; it's an accessor for the methods
    WebServiceApi.Api soapApi = new WebServiceApi.Api();
    // initialize a session and save the id to memory
    string sessionId = soapApi.InitializeApi();

Set the active report.

    // all methods require the session id parameter
    soapApi.ReportObject_Activate(sessionId, reportPath);

Then call the appropriate Report_GetExecute method for the desired data type. Supported methods are Report_GetExecuteHtml and Report_GetExecuteData.

    string reportHtml = soapApi.Report_GetExecuteHtml(sessionId);

#