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.
Download the Exago installer that corresponds with your version of the Exago application. 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:
Click Next and wait for the installation to conclude. Then click Finish.
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.
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".
In the right pane, click Advanced Settings....
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 App). Click OK.
For Enabled Protocols, enter "http" (without quotes) if it is not already there. Click OK.
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.
Navigate to the Web Service API physical directory path (the installation path). Right-click the folder and select Properties. Then click the Security tab.
Click Edit, then Add.... Type the app pool identity into the "Enter the object names to select" field, then click OK.
Select this identity, then in the Permissions pane, select the Allow checkbox for Full Control. Click OK, then click OK again to save your changes.
In a supported web browser, enter the following URL:
http://localhost/webservice_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 localhost does not work, you can try 127.0.0.1 instead.
If you can successfully navigate to this page, then IIS is configured correctly. If not, check your IIS, network, and firewall settings, or contact your network administrator.
In the Web Service API directory, open the following file in a text editor:
web_service_physical_path/Config/WebReportsApi.xml
Locate the <apppath></apppath>
nodes and enter the Web App (NOT the Web Service) virtual path in between:
<apppath>http://localhost/web_app_virtual_path</apppath>
Save the file. Then restart the IIS Web Server.
In your web browser, refresh the Api.asmx page.
Click InitializeApi, then 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 App:
<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.
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.
In the Web Service API directory, open the following file in a text editor:
web_service_physical_path/appSettings.config
Locate the <appSettings></appSettings>
nodes 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>
Then restart the IIS web server again.
Open Advanced REST Client, Postman, or another REST client application.
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.
Enter the following request headers:
accept: application/json content-type: application/json authorization: Basic Og==
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.
500 Internal Server Error
"reason" : "Unauthorized" or "Invalid length for a Base-64 char array or string"
500 Internal Server Error
"reason" : "Unable to load configuration"
500 Internal Server Error
<HTML response payload>
404 Not Found
<HTML response payload>
Connection Refused
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.
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.
Enter the following text in the request payload:
{ "General" : { "LanguageFile" : "es-mx,es-mx-getting-started,es-mx-tooltips" } }
Click Send.
If the request succeeded, you will receive a Response Code: 204 No Content, with an empty payload.
500 Internal Server Error
"reason" : "setupD is null"
500 Internal Server Error
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.
Locate the UrlParamString (AppUrl) that you copied down from the initial POST /sessions request.
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. ¡Olé!
An error has occurred. Please contact your administrator.
Error reading configuration file.
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.
Open the Exago Web App configuration file in a text editor (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).
web_app_physical_path/Config/ConfigFile.xml
Or 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
Under Other Settings, add a REST Key, or click Generate to create a random one. (Optional) Add a User Id as well.
Click Apply or Okay.
Now you need to generate the authorization header based on these two fields.
Go to the website http://base64encode.org/ or use another way to encode a string in base 64.
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.
Click Encode as UTF-8. Copy down the resulting string.
In ARC or Postman, replace "Og==" with the encoded result string in the Authorization header.
authorization: Basic EncodedAuthString
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.)
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.
Make sure that all your config files have a REST Key.