This guide serves as a step-by-step walkthrough for installing and configuring the REST Web Service, verifying that it is working properly, and briefly demonstrating how it works.

Install the Web Service API

Download the Exago installer that corresponds with your version of the Exago application. 

Windows

Run the installer with administrative privileges. Click the center button to install the Web Service API.

Click Next, then on the Select Installation Location screen, do the following:

1. Select a Web Site.
2. Enter a virtual directory path. This will be the URL that REST requests are made to. This is different from the Exago Web App virtual path.

   Note

   We will refer to this path by the placeholder text web_service_virtual_path.

3. Select a physical directory path to install the files. This should not be inside a managed directory such as Program Files or Windows.

   Note

   We will refer to this path by the placeholder text web_service_physical_path.

Click Next and wait for the installation to conclude. Then click Finish.

Tip

If the installation failed, then the installer may have been trying to install to a location without sufficient privileges, or overwrite files which were locked by a system process. Try again with a different file path.

Continue with the Set up the App Pool section below

Linux

Run the Linux installer. For full details, read the Installing Exago on Linux article. Once the installer completes, continue with the Check the Connection section below.

Set up the App Pool

1. Open IIS (Internet Information Services). In the left pane, expand the Web Site that you selected in the installation, then locate and select the virtual path you selected for the Web Service API.

   Also write down the virtual path of the Exago Web Application, for later.

   Note

   We will refer to this path by the placeholder text web_app_virtual_path.

2. In the right pane, click Advanced Settings....
3. For Application Pool, click the ellipsis [...] icon on the right, then select an app pool with .NET CLR version 4.0 and Pipeline Mode: Integrated. (This is often the same app pool as the Web Application.) Click OK.
4. For Enabled Protocols, enter "http" (without quotes) if it is not already there. Click OK.
5. In the left pane, click Application Pools. Write down the identity of the app pool you just selected. If it is "ApplicationPoolIdentity", write down IIS_IUSRS instead.

Set up File Permissions

1. Navigate to the Web Service API physical directory path (the installation path).
2. Right-click the folder and select Properties. Then click the Security tab.
3. Click Edit, then Add. Type the app pool identity into the "Enter the object names to select" field, then click OK.
4. Select this identity, then in the Permissions pane, select the Allow checkbox for Full Control.
5. Click OK, then click OK again to save your changes.

Check the Connection

1. In a supported web browser, enter the following URL:

   http://localhost/web_service_virtual_path/Api.asmx

   Note

   localhost depends on the website name and port number of the IIS Web Site that the Web Service was installed to.

If you can successfully navigate to this page, then the web server is configured correctly. If not, check your web server, network, and firewall settings, or contact your network administrator.

Point the Web Service to Exago

1. In the Web Service API directory, open the following file in a text editor:

   web_service_physical_path/Config/WebReportsApi.xml

2. Locate the <apppath> node and enter the Web Application's virtual path (not the Web Service)in between. The virtual path should be either an IIS virtual directory (e.g., /Exago), which is preferred, or a hard path (e.g., C:\Program Files\Exago\ExagoWeb), typically used for testing purposes.

   <apppath>/Exago</apppath>

3. Next, add the <webreportsbaseurl> node to the file, if it doesn't already exist, and set its property to the virtual directory where Exago BI is installed ("http://server/Exago/"):

   <webreportsbaseurl>http://server/Exago/</webreportsbaseurl>

4. Save the file, then restart the Web Server.
5. In your web browser, refresh the Api.asmx page.
6. Click InitializeApi
7. Click Invoke

   The web service path is configured correctly if the resulting page looks similar to the following:

   <string xmlns="http://www.exagoinc.com/">
   8GIXsZca2PHBlS3k2J/7gfwKggMdftbRkro0zIXTjMFSUlj03cBe3cvel+DGUbWjRbgNt3srJ8f0GYXwgaD/QQ==
   </string>

   If the page looks like the following, then the web service cannot locate the Exago Web Application:

   <string xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.exagoinc.com/" xsi:nil="true"/>

   Check that the path was entered correctly in the configuration file, and that there is a working route between the two services.

8. Once you have successfully connected, locate and delete the following file in the Web Service API directory:

   web_service_physical_path/Bin/api.asmx.cdcab7d2.compiled

   This will disable the outdated SOAP API and Api.asmx test file.

Enable REST

1. In the Web Service API directory, open the following file in a text editor:

   web_service_physical_path/appSettings.config

2. Locate the <appSettings> node and add the following text in between:

   <add key="ExagoREST" value="True" />

   The result should be the following:

   <?xml version="1.0"?>
   <appSettings>
     <add key="ExagoREST" value="True" />
   </appSettings>

3. Restart the web server again.

Test Creating a Session

1. Open a REST client application (such as Advanced REST Client or Postman)
2. For Method, select POST. Enter the following Request URL:

   http://localhost/webservice_virtual_path/rest/sessions

   If your config file is not "WebReports.xml", then use the following URL:

   http://localhost/webservice_virtual_path/rest/sessions?config=fileName

   Note

   fileName is case sensitive without the ".xml" or ".xml.enc" file extension.

3. Enter the following request headers:

   accept: application/json
   content-type: application/json
   authorization: Basic Og==

4. Click Send.

If the request succeeded, you will receive a Response Code: 201 Created, and the following text in the response payload:

{
  "AppUrl": "UrlParamString",
  ...
  "Id": "1234-5678-9012-3456",
  ...
}

When you have successfully returned a 201 response code and a valid body, find the AppUrl and Id fields, and copy down their values. You can safely ignore the other fields for now.

Note

We will refer to the Session ID by the placeholder text 1234-5678-9012-3456.

Troubleshooting

500 Internal Server Error
"reason" : "Unauthorized" or "Invalid length for a Base-64 char array or string"

• Authorization header is wrong. See "Adding Authorization" for details.

500 Internal Server Error
"reason" : "Unable to load configuration"

• Configuration file URL parameter is incorrect.

500 Internal Server Error
<HTML response payload>

• Request URL path is misspelled or mistyped, or REST is not enabled.

404 Not Found
<HTML response payload>

• Method is incorrect (should be POST), or Request URL path is incorrect.

Connection Refused

• Server is down or behind a firewall. Make sure the web server restarted properly after enabling REST.

Test Modifying a Session

Now you can familiarize yourself with the functionality of the REST interface. Let's make a simple change to the session, such as changing the language to Spanish.

1. In the REST client, change the Method to PATCH. Change the request URL to the following:

   http://localhost/webservice_virtual_path/rest/settings?sid=1234-5678-9012-3456

   The sid is the "Id" returned from the initial POST /sessions request.

2. Enter the following text in the request payload:

   {
     "General" :
     {
       "LanguageFile" : "es-mx,es-mx-getting-started,es-mx-tooltips"
     }
   }

3. Click Send.

If the request succeeded, you will receive a Response Code: 204 No Content, with an empty payload.

Troubleshooting

500 Internal Server Error
"reason" : "setupD is null"

• Session ID is incorrect.

500 Internal Server Error

• JSON may not have been formatted correctly. Examine the "reason" field in the response payload to see the specific error message.

Optional: Verify the Settings Change

1. Change the method to GET. Click Send.

If the request succeeded, you will receive a Response Code: 200 OK, and the following text in the response payload:

{
  "LanguageFile" : "es-mx,es-mx-getting-started,es-mx-tooltips",
  ...
}

If this value still shows "en-us,en-us-getting-started,en-us-tooltips", then you may have mistyped "LanguageFile" in the PATCH request. Verify that the property name was spelled and capitalized correctly.

Test Launching a Session

1. Locate the UrlParamString (AppUrl) that you copied down from the initial POST /sessions request.
2. In a web browser, navigate to the following URL:

   http://localhost/web_app_virtual_path/UrlParamString

   (Where everything after /web_app_virtual_path/ is the UrlParamString).

If everything succeeded, the browser should launch the Exago user interface in Spanish.

Troubleshooting

• Your config file is using a temp directory that is different from that of the default (in WebReports.xml), or you may have accidentally used the wrong web reports app path (such as for an older installation of Exago).

Note on Session Closure

Once the session has been launched in the browser, it has been converted to a user session, and can no longer be accessed or modified by the REST API. To demonstrate, you can attempt to access the session again using the session ID and any endpoint. You will receive a 500 error if you attempt to modify a closed session.

Adding Authorization

Note

If you have multiple config files, they all need to be secured in this manner, or else someone could simply bypass authorization by specifying a different config file upon session creation.

1. Open the Admin Console and select the config file from the dropdown menu in the top-left:

   http://localhost/web_app_virtual_path/Admin.aspx

2. In General > Other Settings, enter a REST Key, or click Generate Key to create a random one. (Optional) Add a User Id as well.
3. Click Apply or Okay.
4. Generate the authorization header based on these two fields.
   1. Navigate to http://base64encode.org/ or use another way to encode a string in base 64.
   2. Enter the following in the form: UserId:RestKey These are the User Id and Rest Key values added in the previous step. Note the colon (:) in between. If you left the User Id blank, use :RestKey instead.
   3. Click Encode. Copy down the resulting string.
5. In the REST client, replace "Og==" with the encoded result string in the Authorization header.

   authorization: Basic EncodedAuthString

6. Change the method to POST and set the Request URL to the following:

   http://localhost/webservice_virtual_path/rest/sessions

   (Append ?config=fileName if necessary.)
7. Click Send

If the request succeeded, you will receive a Response Code: 201 Created. You have successfully added Basic authorization. For an alternative authorization method, see ExagoKey Authorization.