If you are updating your version of Exago, please consult this guide to be notified of any potential breaking changes. Note that if you are updating from more than one version behind the current one, then the information from that section and all sections above it will apply to you. If your version is not listed, then we do not support a direct update path to the latest version. Please file a support ticket.
Note: To ensure a smooth upgrade when overwriting a previous installation, ensure that the web server (IIS/Apache/Nginx), the Monitoring Service, and any Scheduling Services are turned off before running the installer.
When updating from v2018.1 and earlier, the following topics may require your attention.
The new Tutorial Mode feature relies upon User Preferences. Depending on your User Preference Storage Method you may or may not need to take action:
With v2018.2 there are new configuration settings for Exago. Below we’ve listed those that are enabled by default and may warrant consideration or action as you upgrade:
<Showtipsexpressview> & <Showtutorialexpressview> - These settings enable the new Tutorial Mode feature. They are True by default but will have no impact if your User Preference Storage Method is set to None. Be sure to set values for the Parameter userId or disable these features.
See the section Configuration Changes below for a complete list.
When updating from a preview release of v2018.1, please consider the following information.
Note: If you were not given a preview version of v2018.1, and you are upgrading from a general release version, then you can safely disregard this information.
Preview versions of v2018.1 included several changes to the way ExpressViews were stored on the file system. The general release of v2018.1 reverted some of these changes. As a consequence, ExpressViews created in a preview version are no longer valid. These will have to be recreated.
When updating from v2017.3 and earlier, the following topics may require your attention.
Special Cartesian Processing is now disabled by default when creating a new configuration file. This change was made to better support certain database-processing features.
If you are starting a new configuration, please be aware that reports with Cartesian products with Special Cartesian Processing set to Default will now behave differently on execution. To retain the legacy behavior, either set the Admin Console flag back to True, or set each report-level flag to True (instead of Default).
Vertical Table transformations are now done in the database instead of in application memory. This results in much faster processing as well as the ability to use database-processing features, such as Advanced Joins, with transformed tables.
If you are experiencing issues you can revert to the legacy behavior by setting the configuration file flag <canjointransformobjectsindb> to False.
Certain application settings now require editing the <WebApp>\web.config
file directly instead of the appSettings.config
file. If you use a non-default web.config file, make sure that you are tracking your changes so that future upgrading and scaling can occur without error.
The .NET API method ReportObjectFactory.SaveToApi()
has been altered. This method used to return bool
to indicate whether the save succeeded or failed. This method now returns void
. If the save failed it throws an exception with the details of the failure.
Ensure that you wrap calls to this method within try-catch blocks and properly handle exceptions.
The installer will install the new Monitoring Service as a separate service instead of overwriting the existing one. If installing over an existing installation, the installer will detect and halt any older services running against the monitoring executable.
In order to prevent older services from restarting on system startup, you should remove or disable them. Otherwise there can be multiple services running against the same installation, which will cause duplicate entries to be written to the monitoring database.
This command line command can be used to delete specified monitoring services:
sc delete ExagoMonitoringService.full_version_number
sc delete ExagoMonitoringService.v2017.2.1.117
Application settings files for the web service and schedulers may be overwritten when updating. If the webservice appSettings is overwritten, REST may be disabled. Make sure to back up your appSettings files before running the installation. Files include:
<SCHEDULER>/eWebReportsScheduler.exe.config <WEBSERVICE>/appSettings.config
Application settings files for the web application and monitoring service will not be overwritten.
When updating from v2017.2 and earlier, the following topics may require your attention.
If you use Application Themes, also see Application Theme Updates for relevant style changes.
Upon updating to this version, existing REST web applications will be unauthorized, and most REST calls will fail until action is taken.
The REST web service no longer uses the "Password" field to generate the authorization header key. The new "REST Key" field supplants the Password field for this purpose.
The REST Key field is blank by default upon installation. For security reasons, the Password and REST Key should NOT be the same key. Either migrate the old "Password" to the new field and choose a different Password, or choose a new REST Key and make sure that the new authorization header is being sent.
In the Admin Console you can click the Generate button in the REST Key field to generate a randomized REST key. This is NOT the encoded version - it must still be encoded according to the authentication method in use.
See REST Authentication for more information.
Users will now see an error message when attempting to launch Exago BI in Internet Explorer 10. Please advise your users to upgrade to a supported browser.
When updating from v2017.1 and earlier, the following topics may require your attention.
Dashboards created or saved in version 17.2 are not compatible with older versions of Exago BI. Old dashboards will be updated to the new format when they are saved in the Dashboard Designer. Back up your dashboards in case of the need for a rollback.
The Dashboard Viewer has undergone significant overhaul. Dashboard action events created for previous versions may no longer work as expected. These should be retested and modified if necessary.
Note: The Resizable Dashboards action event will no longer work in version 2017.2.
When using the OnParameterValueChange action event, the clientInfo.parameterValuesCtrl object will no longer be available in the context of dashboards.
Users will now see an error message when attempting to launch Exago BI in Internet Explorer 9. Please advise your users to upgrade to a supported browser.
Nine new functions were added, including four aggregate functions and five miscellaneous functions. Additionally, the built-in functions have had their descriptions overhauled, and their arguments have also been given names and descriptions.
This has some implications for how custom functions are created in the configuration and/or the API.
If you build functions in the API, please note that the MinArgs and MaxArgs properties of UdfFunction objects are no longer valid. Instead specify argument information in the ArgumentsJson property. See .NET API General Reference and Config File XML Reference for more information.
The functions MonthName, QuarterName, and QuarterNumber were added as custom functions in the configuration file. This is to provide administrators with the ability to customize how these functions work.
Many icons and CSS have been updated to a new color scheme. If you use the default Basic application theme or any of the default icons and CSS, please be aware that you may have to make changes in your styling to reflect the new look.
Several new ExpressView themes were added to the application, and several miscellaneous themes have been updated as well. If you use folder management, you will have to manually update these files in your database.
The data fields pane for ExpressViews, Dashboards, and Advanced/Express/Crosstab Reports has been consolidated into a single pane in the left most application toolbar (underneath the Reports Tree icon). The settings to enable the Data Fields Search Bar for Dashboards and ExpressViews were consolidated into one setting. See Configuration Changes for more information.
Application themes may require some adjustment to match the new layout.
As always, please be aware that you should turn on Column Metadata if you are to enable the Data Fields Search Bar.
The Monitoring database schema has been tweaked. The SystemStatistics table has had a new TransactionId
column added to associate memory and CPU rows across common transactions. This was done to facilitate a vertical table transform, in order to report off both memory and CPU usage in the same report or chart.
When the monitoring service is restarted after updating, it will assess the schema in the monitoring service's Monitoring.sqlite table and add the TransactionId column. The scheduler and web application local databases will not be altered. The service will henceforth record a TransactionId for scheduler statistics. No existing monitoring data will be modified.
If, for some reason, the table cannot be altered, the monitoring service will abort.
The SystemStatistics table schema should be altered in the configuration file to reflect this change. You can add the TransactionId column to an existing definition, or create a new vertical definition for the table:
<entity>
<entity_name>SysStats</entity_name>
<db_name>SystemStatistics</db_name>
<!--<datasource_id></datasource_id>-->
<object_type>table</object_type>
<key>
<col_name>transactionId</col_name>
</key>
<transform>
<col_name>type</col_name>
<val_name>value</val_name>
<non_transform_col>
<col_name>timestamp</col_name>
<data_type>8</data_type>
</non_transform_col>
<non_transform_col>
<col_name>hostId</col_name>
<data_type>0</data_type>
</non_transform_col>
<non_transform_col>
<col_name>transactionId</col_name>
<data_type>0</data_type>
</non_transform_col>
</transform>
</entity>
When updating from v2016.3 and earlier, the following topics may require your attention:
Standard Reports have been renamed to Advanced Reports throughout the application. 'Standard' has been changed to 'Advanced' in the following areas:
The config file keys under General and Roles/General have changed from "showstandardreports" to "showadvancedreports." Existing configs with showstandardreports will load just fine.
New API enumerations are available: wrApiAction.NewAdvancedReport supersedes wrApiAction.NewReport. wrReportType.Advanced supersedes wrReportType.Standard. Please adjust your code accordingly.
The 'Main Menu' section of the home page has been redesigned. Several icons have undergone changes, and there is now no logo in the upper left corner. If you are using a custom application theme, you may have to make some changes to your css and images.
The 'Browse Reports' menu is more easily collapsible. Additionally, its expanded or collapsed state is preserved per user, via a new user preference.
ExpressViews now support custom theme files, which have the extension .wrtev. These are JSON files, unlike previous themes. To create a custom theme, style an ExpressView, then hold Alt-Ctrl-Shift and press the Save icon. The theme is saved to the Reports folder, but you can move it to the Themes folder if you wish; it is accessible from either location. The theme type "ExpressView" has been added to the relevant folder management methods.
If you are using a folder management assembly to store report and theme data, you need to manually add the file {Exago}\Themes\Legacy.wrtev to your theme storage. This is the default ExpressView theme. Otherwise users will encounter errors with ExpressViews.
A new way to filter reports, called Top N or Top/Bottom, has been added and is enabled by default. If you want to disable this feature, change the admin setting Filter Settings > Show Top N Filters to False.
When updating from v2016.2 and earlier, the following topics may require your attention:
A new feature in this version is the ability for Admins to add downloadable Application Themes, which change the overall look of Exago for all users. A side effect of this feature is that the file paths for CSS and images has changed. After updating to this version, any custom CSS or images will still be in the old locations, and will have to be moved.
The Css and Images folders are now located in separate theme folders in the file path "Exago root"\ApplicationThemes\. The default Exago theme is called Basic. Move your custom Css and Images folders into the Basic sub-folder within the ApplicationThemes file path. You may need to re-check your CSS to ensure you're using relative paths, not absolute. Then check the following setting to ensure that the Basic theme is selected:
( Feature/UI Settings Application Theme Selection ) <csstheme>
You may still not be able to see your custom images. If so, please see the next section.
Additional note: If you are using custom CSS to hide the default Exago logo, please note that the element type has changed from an img to a div. In your stylesheet, you'll now need to use this selector: div.wrMainCompanyLogo
When you update to this version, Exago will default to the new SVG icon set. There are several considerations of note.
SVG icons may not be compatible with all browsers or operating systems. Compatible browsers include Google Chrome, Firefox 3.0+, Internet Explorer 9.0+, Edge, Safari, and most mobile browsers. If your users cannot see the new icons, you can switch back to the PNG icons by toggling this setting to False:
( Feature/UI Settings Use SVG for Application Icons ) <usesvgforappicons>
If you were using custom icons, then Exago will no longer be looking in their location, and you will see the default icons instead. Either create SVG versions of your custom icons and place them in the default theme path below, or switch back to the PNG icons using the setting above.
"Exago root"\ApplicationThemes\Basic\Images\svg
If you decide to use the new SVG icons, you should not have to alter any custom CSS or Action Events, since the images are identified by html element tags, not filenames.
The new ExpressView designer features a data field search bar by default. If you leave this enabled, it is highly recommended to set the column metadata for available data objects in order to reduce the frequency of database queries.
To set object metadata using the Admin Console, expand Data > Objects, and then double-click on an Object, or select the Object and press (Edit). This will open the Objects tab.
Press the Column Metadata button to open the Column Metadata editor. Then press the Read Schema button. This will automatically add metadata for every column in the data object. Press OK to close the editor.
Next, set the Schema Access Type to Metadata. Alternately, you can use the following setting to enable this option for every data object (this will cause errors if a data object is missing metadata):
( Other Settings Global Schema Access Type ) <schemaaccesstype>
Press Apply or OK to save your changes. Do this for every data object.
The Geocharts feature which was present since v2013.2 has an additional requirement if you are implementing your application under a new domain name.
Our mapping features use the Google Maps API. Historically, this was a free solution. However, in June 2016, Google began to require paid licenses for commercial usage. If you had mapping enabled prior to June 2016, and you are not planning on implementing your application under a new domain name, this section does not affect you because you have been grandfathered in.
If you intend to implement legacy maps under a new domain name, then you must acquire a Google Maps API License in order to use this feature. See this page for details. Your license must include the Google Maps Javascript API.
To install your license file, place your license key in the following setting in the Admin Console:
( Feature/UI Settings Geochart Map Key ) <geochartmapkey>
There are additional steps needed in order to enable the new Google Maps wizard.
First, you need to download and install a polygon file. This is a free download located on our support site. The file is named 'MapPolygonDataBase.sqlite'. Once you've obtained this file, place it in the following location in your install path (if the folder does not exist, create it):
"Exago root"\Mapcache
This file may receive periodic updates to support additional regions. Please check back occasionally to see if an update has been posted. To install an update, simply overwrite the file with the new version.
Next, the new wizard uses the Google Maps API, which requires a paid license for commercial use. You must acquire a Google Maps API License in order to enable this feature. See this page for details. Your license must include the Google Maps Javascript API and the Google Maps Geocoding API.
To install your license file, first toggle the following setting to True:
( Feature/UI Settings Show Google Maps Wizard ) <showgooglemapwizard>
Then place your license key in the following setting in the Admin Console:
( Feature/UI Settings Google Map Key ) <googlemapkey>
Database aggregation is a new feature which aims to improve report performance by performing some aggregate calculations in the database, rather than in the application.
In order to use this feature, you must ensure that all One-to-Many joins in your configuration are properly identified. One-to-Many joins are incompatible with database aggregation. If Exago does not recognize the joins as such, you will see incorrect values without any warning.
The Data Source Metadata Discovery tool cannot identify whether joins are One-to-Many. By default it sets all joins as One-to-One. If you used this tool to autofill your Objects and Joins, you must take the following precautions before enabling Database Aggregation.
To set your joins using the Admin console, expand Data > Joins, and then double-click on the Join, or select the Join and press (Edit). This will open the Joins tab.
In the Relation Type drop-down menu, select One To Many. Then press Apply or OK to save your changes. Do this for every One-to-Many join.
New reports added using any New Report Wizard will no longer automatically add interactive column sorts for each data field in the layout. Previously created reports will be unaffected. This change was made to better support database aggregation out of the box. Due to technical limitations, reports with interactive sorts or filters will not see any performance improvement from database aggregation.
The .NET API constructors for EntityColumnMetadata were changed to support the additions to column metadata. The following overloads are now available (new params are highlighted):
public EntityColumnMetadata(string columnName)
public EntityColumnMetadata(string columnName, string columnType, string mnemonicName, string columnDescription, string filterColumnName, string sortAndGroupByFormula, ConditionalBoolean isVisible, ConditionalBoolean isFilterable, ConditionalBoolean isSortable)
public EntityColumnMetadata(string columnName, string columnType, string mnemonicName, string columnDescription, string filterColumnName, string sortAndGroupByFormula, ConditionalBoolean isVisible, ConditionalBoolean isFilterable, ConditionalBoolean isSortable, EntityColumnSource columnSource, string columnValue)
Old constructor overloads are no longer valid. If you are implementing this class, please update your code. For more information about the added features, please see the Column Metadata Enhancements article on our support site.
For more detailed description see What’s New in v2018.2.
The following section details the changes made to the configuration xml file.
Added to <general>
Added to <general>
Removed from <general>
Added to <entity>
Added to <join>
Added to <role> • <rolegeneral>
Added to <role> • <security>
Added to <general>
Added to <general>
Removed from <general>
Added to <general>
Removed from <general>
Added to <function>
Removed from <function>
Added to <general>
Removed from <general>
Added to <general>
Added to Scheduler configuration file
Added to <general>