Microsoft Azure is a cloud infrastructure for hosting files, databases, virtual machines, and web applications. Exago supports various forms of integration with Azure.

• Virtual Machine — Exago can be installed on a Windows virtual machine on Azure.
• App Service — The Exago Web Application, REST Web Service API and .NET API host apps can be installed as Azure app services. An Azure Virtual Machine is also required for remote report execution when utilizing an Azure App Service.
• File Storage — Exago data can be stored and accessed from Azure storage containers.

These methods can be implemented independent of each other. However, Web App integration and VM integration are usually redundant with each other, and most Web App solutions should also implement Azure file storage. This guide will walk through how to set up each of these solutions.

Which solution should I use?

Azure virtual machines are the preferred implementation method for production environments. App Services should only be used for testing and demonstration—not in production.

App Service

Caution

Deploying the Exago Web Application in an Azure App Service also requires a separate Azure Virtual Machine and the Exago Scheduler Service for handling chart and map rendering. Consider using an Azure Virtual Machine for the entire deployment instead. See Configuring Remote Report Execution Host for Azure App Service Deployments for more information.

The following Azure resources are required:

 App Service plan

 App Service

Note

You may require a Storage Account to run Exago as a scalable app. See File Storage for details.

This section is divided into three parts:

• Hosting Exago BI in an App Service
• Using Exago Web Service API in an App Service
• Using the .NET API with Azure

Hosting Exago BI in an App Service

Note

This walk-through requires a local Exago installation. See the Exago Installation Guide for details.

1. In your Azure Dashboard, create a new App Service container or navigate to an existing one.

   

2. In the App Service, navigate to Deployment Credentials. Add a username and password. This will allow you to FTP into your app service to transfer files.
3. Next, you'll need an FTP application. Open a connection using the deployment credentials created in step 2. Copy your local Exago BI web app installation directory to the app service container.

   

4. In the App Service, navigate to Application Settings. Set the following:
   • .NET Framework version: v4.0 or Later
   • Managed Pipeline Version: Integrated
5. Under Virtual applications and directories create a virtual directory path to the installation directory and check the Application check box.

   

6. Click Save to save your settings.
7. Configure the Remote Report Execution Host as a Virtual Machine.
8. Test your installation and by navigating to the WebAppUrl\virtual path to Exago App Service\Admin.aspx page (Admin Console).

If you will use Azure Blob Storage to store the config file, follow the File Storage instructions before setting the base config. We also recommend setting up a state server either with SQL Server or another database when running Exago in an Azure App Service. Review the Setting Up a State Server article or the Exago Support Team for assistance.

Using Exago Web Service API in an App Service

Note

This walkthrough requires either a local Exago Web Service API installation, or a downloadable ZIP file containing the WebServiceApi directory. See the Installing and Configuring the Web Service article for details.

1. Copy the contents of the local Exago installation's WebServiceApi folder to the app service container.
2. Under Virtual applications and directories create a virtual directory path to the WebServiceApi directory and check the Application check box.
3. Click Save to save your settings.
4. In Azure, edit the WebServiceApi\Config\WebReportsApi.xml file as follows:

   <apppath>virtual path to Exago App Service</apppath>
   <webreportsbaseurl>virtual path to Exago App Service</webreportsbaseurl>

   Note

   Include a trailing slash for both the apppath and webreportsbaseurl elements.

5. In the WebServiceApi\appSettings.config file, add a new key to enable the REST service.

   <appSettings><add key="ExagoREST" value="TRUE" /></appSettings>

   The result should be the following:

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

6. To prevent front end access without authentication outside of the API, in the Admin Console, navigate to General > Main Settings > set Allow direct access to Exago (bypassing API) to False. Click OK. Test your installation by navigating to the WebAppUrl\Exago\Api.aspx page. An 'Unauthorized access. Please contact your administrator' error message should appear.
7. To test that the path was set correctly, navigate to WebAppUrl\virtual_path_to_Exago_App_Service\Api.aspx. A test file listing avaiable supported operations in the API should appear.
8. To prevent unauthorizedAdmin Console access to prevent users from inadvertently reaching it, delete WebAppUrl\Exago\Admin.aspx and WebAppUrl\Exago\Bin\admin.aspx.cdcab7d2.compiled.

   Tip

   Make a backup of the files before deletion in case Admin Console may be needed later.

9. Test that Admin Console is no longer accessible by navigating to WebAppUrl\Exago\Admin.aspx. A 404 error page should appear.
10. Test that REST is enabled by utilizing an advanced REST client such as Advanced REST Client. Make a POST request to WebAppUrl\virtual_path_to_Exago_App_Service\rest\rest\sessions.

    Header Name	Header Value
    Accept	application/json
    Content-Type	application/json
    Authorization	The REST authorization key. Review the Introduction to REST article for more information.

    Copy the AppUrl received in the response and append it to the end of the browser's URL WebAppUrl\virtual path to Exago App Service\ The Exago front end should load, proving that the application can only be reached through the API.
11. Configure the Remote Report Execution Host as a Virtual Machine.

Using the .NET API with Azure

Exago .NET API based host applications must be compiled locally before being uploaded to the Azure app container. References to the WebReports.dll library should be updated manually, and the program recompiled, when upgrading to a new Exago version.

Set your API constructor to use the previously set Exago virtual path:

Api api = new Api(@"/exago/virtual/path");

Important

.NET host apps can only access virtual paths (and not URL paths). Therefore they must be located in the same App Service container as the Exago web app.

Exago utilizes the virtual directory passed in the first argument of this constructor to locate the required .dll libraries to load Exago. In cases where the virtual directory is not specified within the API constructor (e.g., if Exago is installed on the root of the .NET host application), then a reference to the Microsoft.WindowsAzure.Storage.dll library will need to be added manually to the host application.

File Storage

Exago can be integrated with Azure cloud storage for storage and live access to reports, templates, config, and other data files.

The following Azure resources are required:

 Storage account

 Blob storage

The following Azure resource is optional:

 Files storage

Important

The Web Application, Scheduler Service, Web Service API and any cloud storage mechanisms must share at least one security protocol in common otherwise they will not be able to communicate with each other. For more information, refer to the Application Settings article.

Blob storage is a "flat" file system, which stores every file at the root level. To make use of this system, Exago emulates a directory structure using file names. Standard and premium blockblobstorage accounts are supported with Exago.

File storage is a directory-based system. Files are placed into directories, which can have sub-directories.

For pre-v2021.1, reports can be stored in File storage or Blob storage. Config files, templates, themes, and temp files must be stored in blob storage. For v2020.1+, only config files and temp files are stored locally. Reports, templates and themes are stored in a Storage Management database.

In your Azure Dashboard, begin by creating a new Storage account or navigating to an existing one.

This section is divided into three parts: Config file storage, Reports storage, and Temporary files storage (which includes themes and templates). If you are implementing Exago as a scalable app, you must set all three to static locations.

Config File

An Exago installation contains a configuration file, usually called WebReports.xml, which tells the application where to store Reports and Temp files.

First, in the Storage account, navigate to Access Keys. Record the two connection strings.

Azure Connection String

An Azure Connection String is a formatted string which contains your Azure account name and a unique alphanumeric key. It is used to give applications access to your storage account. The string uses the following format:

DefaultEndpointsProtocol=https;AccountName=acctName;AccountKey=encryptedalphanumerickey;

Next, there are two places which you need to specify the location of the configuration file:

1. The appSettings.config file in the web app install directory.
2. If you're using the .NET API, a parameter in the API constructor method.

appSettings.config

Exago BI contains a file called appSettings.config in the root folder of the install directory. This file is used for custom app settings which are automatically imported into Web.config during runtime.

This file may also be used to specify other important environmental conditions, such as security protocols and input sanitation rules. More information about all available settings can be found in the Application Settings article.

Note

Do not edit Web.config file. It is automatically generated by Exago, and any changes will be overridden.

To set the config file location, add the following key to the appSettings.config file:

Important

The connection strings used for report, configuration file and temporary file storage must be unique.

<add key="ExagoConfigPath" value="pathtype=azure;credentials='Azure Connection String';storagekey=config"/>

• credentials: Your Azure Credentials Connection String.
• storagekey: The prefix of a blob container used to store the config file.

Caution

When both the REST Web Service API and cloud config storage are being used, the ExagoConfigPath node must be included in both the REST Web Service API and Web Application appSettings.config files.

API

.NET API host apps cannot access the appSettings.config file. Instead, use one of the following two methods to specify a config file location:

1. Place the config key within the host application's web.config or app.config.
2. Or pass the connection string in the API constructor method:

Api api = new Api("/exago/virtual/path", "configFn.xml", "pathtype=azure;credentials='Azure Connection String';storagekey=config");

• storagekey: The prefix of the blob container used to store the config file.
• configFn: The name of the config file.

Caution

When both the REST Web Service API and cloud config storage are being used, the ExagoConfigPath node must be included in both the REST Web Service API and Web Application appSettings.config files.

Reports Storage

pathtype=azure;credentials='Azure Connection String';storagekey='reports';usefilestorage=false

Temporary Files Storage

Azure allows an App Service to be scaled up to multiple instances on separate servers. When implementing this configuration, take the following safeguards in order to prevent loss of user data.

Each instance of Exago BI has its own local temp directory, whose path can (optionally)  be specified in the Temp Path setting in the config file (defaults to %INSTALLDIR%\Temp).

In a scalable configuration, initial user calls will reach one instance, storing temp files on that server, but subsequent calls may reach a separate instance, which will not have those temp files in its local directory. There are two solutions to resolve this issue:

• Temp Cloud Service
• Azure Affinity Cookie

Temp Cloud Service

This is Exago's built-in solution for handling multiple instances. Specifying a Temp Cloud Service causes each instance to push its temporary files to a shared Blob container. Then if a subsequent user call reaches a separate instance, that instance will pull the relevant files from the Blob to its local temp directory. Temp files may only be stored in blob storage.

To set up an Azure storage resource for temporary files:

1. Create a container for temporary files with the Azure Storage Explorer. The default container name is wrtemp but any container name, except for those used for report or configuration storage may be used by providing a storagekey in the connection string in step 2.
2. Set the Admin Console > General > Main Settings > Temp Cloud Service to a formatted connection string.

   Important

   The connection strings used for report, configuration file and temporary file storage must be unique.

The connection string uses the following format:

pathtype=azure;credentials='Azure Connection String';

to save temporary files to the default blob container named wrtemp or

pathtype=azure;credentials='Azure Connection String';storagekey=tempFileStorageKey

to save temporary files to a blob container named tempFileStorageKey.

Examples:

type=azure;credentials='DefaultEndpointsProtocol=https;AccountName=acctName;AccountKey=encryptedalphanumeric';

type=azure;credentials='DefaultEndpointsProtocol=https;AccountName=acctName;AccountKey=encryptedalphanumeric';storagekey=ourExagoTempFiles;

Azure Affinity Cookie

Azure supports setting Affinity Cookies, which track which server instance each user is connected to and cause all calls within the session to reach the same instance.

In your app service, navigate to Application Settings. Set ARR Affinity to On.

Virtual Machine

Exago can be hosted on a Windows-based Azure Virtual Machine. Installing Exago on a VM differs only marginally from installing it on a local machine. Therefore, this guide will not go into depth on this method. For a full installation and setup guide, see the Exago Installation Guide.

You can interact with a VM using either a remote desktop application or a command shell application.

Remote Desktop

1. Using Remote Desktop Connection or another remote desktop application, view your VM as a desktop environment.
2. Use a Web Browser to download the Exago Installer from our support site.
3. Run the installer as Administrator and install Exago.
4. Configure Exago (see Install and Configure).

Command Shell

1. On a local machine, use the above steps 2-4 to create a temporary Exago installation.
2. Remote into your VM using Windows PowerShell or another command shell application.
3. Copy the Exago directory to a directory on your VM.
4. Configure Windows and IIS (see Manual Application Installation).

After configuring IIS, open up the Exago port using a Windows Firewall inbound exception rule. You can then access Exago through the VM's IP address. Set up DNS and data security as desired.