Microsoft Azure is a cloud infrastructure for hosting files, databases, virtual machines, and web applications. Exago supports various forms of integration with Azure.
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.
Azure virtual machines are the preferred implementation method for production environments.
Note
App Services should only be used for testing and demonstration—not in production.
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:
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-v2020.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.
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.
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:
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 configuration file and temporary file storage must be unique.
<add key="ExagoConfigPath" value="pathtype=azure;credentials='Azure Connection String';storagekey=config"/>
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.
.NET API host apps cannot access the appSettings.config file. Instead, use one of the following two methods to specify a config file location:
Api api = new Api("/exago/virtual/path", "configFn.xml", "pathtype=azure;credentials='Azure Connection String';storagekey=config");
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.
For versions v2020.1+, setup the Storage Management system for storing reports, templates and themes.
If upgrading from a previous version of Exago, review these articles:
If this is a new installation, review these articles:
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:
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:
wrtemp
but any container name, except for those used for configuration storage may be used by providing a storagekey
in the connection string in step 2.Important
The connection strings used for 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';
wrtemp
blob containertype=azure;credentials='DefaultEndpointsProtocol=https;AccountName=acctName;AccountKey=encryptedalphanumeric';storagekey=ourExagoTempFiles;
ourExagoTempFiles
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.
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.
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.
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:
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:
Note
This walk-through requires a local Exago installation. See the Exago Installation Guide for details.
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.
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.
<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
andwebreportsbaseurl
elements.
<appSettings><add key="ExagoREST" value="TRUE" /></appSettings>
The result should be the following:
<?xml version="1.0"?> <appSettings> <add key="ExagoREST" value="True" /> </appSettings>
Tip
Make a backup of the files before deletion in case Admin Console may be needed later.
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 WebAppUrlvirtual path to Exago App Service The Exago front end should load, proving that the application can only be reached through the API.
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.