Viewer Upgrading

Upgrading installs the same components in the same location as the existing installation.

You can upgrade Essentials and the HTML5 Viewer independently—you can upgrade only Essentials, or only the Viewer, or both Essentials and the Viewer. To use certain features, you may have to upgrade both Essentials and the viewers.

For best results, we recommend upgrading both Essentials and the HTML5 Viewer.

To find out the Essentials version that Geocortex Viewer for HTML5 4.14.0 works with best, see Geocortex Essentials Requirements.

Usually, viewers are upwardly compatible—after you upgrade the software, your viewers still work. Occasionally, improvements to the software break upward compatibility. In this case, you may have to perform some additional steps to complete the upgrade. For information, see HTML5 Viewer Versions that Require Additional Steps.

Upgrade Methods

The method that you use to upgrade a viewer depends on how you installed the viewer:

Upgrade the Viewer Using the Post Installer

If you installed a viewer framework manually, you cannot use this method to upgrade the viewer. See Upgrade the Viewer Manually.

Upgrading the template removes the old template. This means that the viewers are unusable between the time you upgrade the template and the time you upgrade the configured viewers—they cannot be launched or edited during this time.

Step 1: Before You Begin

  1. Download the Geocortex Viewer for HTML5 installation package for the version of the HTML5 Viewer that you want to upgrade to.

    For instructions, see Download the Geocortex Viewer for HTML5.

  2. Read HTML5 Viewer Versions that Require Additional Steps to find out if you need to perform any additional steps as part of the upgrade.

    Sometimes you must perform additional steps before you upgrade the Viewer, so it is important to read this section before you begin the upgrade.

  3. Based on what you read for the previous step, perform any additional steps that must be done before you begin the upgrade.

    If you customized the viewer by modifying its CSS files, be sure to back up the files before upgrading to version 2.10 or newer. Customized viewer CSS files should be located in a Resources\Styles\Custom directory to ensure that they are not overwritten during an upgrade. For more detailed information, see Customizing the Viewer in the Shells module description in the Geocortex Viewer for HTML5 Help.

Step 2: Upgrade the Viewer Template

To upgrade a viewer template, you use the Post Installer's Upgrade function. The Upgrade function partially automates the process of upgrading the viewer files that are deployed to the web server.

When you upgrade a viewer, you want to take advantage of the new features and improvements that the new template offers. At the same time, you want to preserve any changes that you have made to the viewer, such as customizations to HTML, CSS, JavaScript, or image files. The Upgrade function examines each file in your existing viewer so your customizations can be preserved:

By default, the Upgrade function deploys the upgrade to the same location as the existing viewer. Deploying to the same location ensures that the viewer's URLs stay the same, so you do not need to update the launch links and URLs that you provide to users. You can change the location if you want. If you deploy the viewer to a different location, you will have to update the launch links and URLs that you provide to users.

The Upgrade function creates a backup of the existing viewer.

Upgrading a viewer template removes the existing template.

  1. In the Post Installer, click Configure Viewer Templates in the side panel.

  2. In the Installed Templates area, click the template that you want to upgrade.

    The template management buttons show.

    Location of the Upgrade button for upgrading a viewer template

  3. Click Upgrade.

  4. Browse to the location where you extracted the installation package.

    If a dialog box appears that says "If you have deployed a viewer for this template, please select its location in the next step. If not, just press Cancel." and you have previously deployed a viewer for the template you are attempting to upgrade, click OK and browse to the deployed viewer. By default, this will be inside the C:\inetpub\wwwroot\ folder.

  5. Select the template file, Geocortex.Essentials.HTML5Viewer.Template.[version].vte, and then click Open.

    The Upgrade Template dialog box opens.

    Example of the Upgrade Template dialog box

  6. Viewer Location: If the folder location given in the Viewer Location box is not where you want to deploy the upgrade, click Browse, select the folder where you want to deploy the upgrade, and then click OK.

    By default, the Viewer Location box shows the location where the viewer was installed. If you moved the viewer after installing it, you will have to change the location.

  7. Backup Location: If you want to change the folder where the upgrader puts the backup of the old viewer, click Browse, select the folder where you want to put the backup, and then click OK.

  8. Modified Files: If there are modified files, review each file and indicate whether you want to keep the existing version of the file or overwrite the existing file with the new version.

    A file appears in the list only if there are software updates in the new version of the file, and you have customized the existing version of the file. This step gives you the opportunity to merge your modifications into the new file before the upgrader overwrites the installed file, thus preserving your customization.

    Alternatively, you could merge the software updates into the existing file and use the Keep Existing action. The easiest approach is to merge into whichever file has the most changes.

    1. Merge your modifications to the new file using one of the following methods:

      • If you have WinMerge installed, click the Compare button to review the differences between the two files in WinMerge, and then use WinMerge's Merge function to merge your customization into the new file. Save your merges.

      • If you do not have WinMerge installed, perform your merges manually by copying and pasting your customizations into the new file using a text editor. Save the file.

    2. In the Post Installer, set the file's action to Overwrite  .

      Overwrite replaces the installed version of the file with the new version.

      To change the action from Keep Existing to Overwrite, click the Keep Existing button . .

  9. Click Upgrade Template.

    The old template is removed and the new template is installed.

  10. When the success message displays, click OK.

    The Upgrade Template dialog box closes. You have completed the template upgrade.

You are now ready to upgrade the viewers that are configured in your sites. Click Finish and follow the prompts to close the Post Installer.

Step 3: Upgrade your Configured Viewers

After you upgrade the viewer template, you must upgrade the viewers that are configured in your sites. You cannot run or edit the viewers until you have upgraded them to use the new template.

Geocortex Essentials Manager has an Upgrade Viewers function that enables you to upgrade all your configured viewers with a single click. Alternatively, you can upgrade viewers individually.

You can Upgrade all of your Configured Viewers at One Time or Upgrade a Single Viewer.

Upgrade all of your Configured Viewers at One Time

To upgrade all of your configured viewers at one time:

  1. Do one of the following:

    If Manager is Closed

    1. Launch Manager.

      You will be prompted to upgrade your viewers.

    If Manager is Open

    1. In Geocortex Essentials Manager, click the Sites tab.If another site is open for editing, click Save Site and then Close Site to return to the Sites list.

    2. Click the Upgrade Viewers hyperlink on the Sites tab.

      Location of the Upgrade Viewers hyperlink

  2. Make sure the HTML5 Viewer checkbox is selected and click OK.

    If you click Cancel instead of OK, you can upgrade the viewers later using the Upgrade Viewers hyperlink on the Sites tab.

  3. When the Done message shows, click Close.

    The Upgrade Viewers dialog box closes. You have completed upgrading your HTML5 viewers. You can now run your viewers and edit them in Manager.

Upgrade a Single Viewer

To upgrade a single viewer:

  1. If Manager is closed, launch Manager and click Cancel when you are prompted to upgrade your viewers.

  2. When you are ready to upgrade a viewer, edit the viewer.

    You will be prompted to upgrade the viewer.

  3. Click Upgrade.

    Manager upgrades the viewer.

Step 4: Perform Additional Steps

  1. If you have additional steps to perform after upgrading, do them now.

    See HTML5 Viewer Versions that Require Additional Steps.

Upgrade the Viewer Manually

The following instructions upgrade a manual installation of the Geocortex Viewer for HTML5. The instructions given here retain the manual nature of your deployment—this procedure does not integrate your viewers with Essentials.

To upgrade a manual installation of the HTML5 Viewer:

  1. Download the installation package for the new version of the viewer.

    Follow the instructions in Download the Geocortex Viewer for HTML5.

  2. Create a backup of your existing Viewer by copying the deployment folder to a safe location.

    By default, the HTML5 Viewer is deployed to the following folder:

    C:\inetpub\wwwroot\Html5Viewer

  3. Remove the current Viewer application from IIS:

    1. Launch Internet Information Services (IIS) Manager.

    2. In the Connections panel, expand the hierarchy and select the website where the HTML5 Viewer is deployed.

      By default, the Viewer is deployed to the Default Web Site.

    3. In the Actions panel, click View Applications.

    4. Right-click the HTML5 Viewer's application and select Remove.

    5. When you are prompted to confirm, click OK.

    6. Close IIS Manager.

  4. In the file system, delete the contents of the deployment folder.

  5. Extract the files from Viewer.zip to the deployment folder.

    Viewer.zip is provided in the installation package.

  6. Update the siteUri element in all three viewer configuration files to point to the correct site.

    For instructions, see Point a Manually Installed Viewer to Your Site.

  7. Manually copy any configuration changes from your files in the backed up copy of the Resources\Config\ folder to the upgraded Resources\Config\ configuration files.

    Because the structure of the JSON configuration changes in new versions of the viewer, you should not overwrite the entire configuration file. Use a tool like WinMerge to detect your custom configuration and changes to the configuration file structure.

  8. Test the configuration files by launching each layout in a browser.

    For instructions, see Launch a Manually Installed Viewer.

  9. Manually add any changes you made to your viewer's Index.html, Handheld.html, Tablet.html, and any other host files.

  10. If you changed any other viewer files, such as CSS, JavaScript, or image files, copy the changes from the backup files to the new deployment.

  11. Copy any other required resources from your backed up Resources\ subfolders to the newly deployed Resources\ subfolders.

  12. Save the files and test them.

HTML5 Viewer Versions that Require Additional Steps

The viewer upgrade process replaces the viewer's Framework.js file with a new, secure version. After you have upgraded the viewer using the Post Installer, you may have to perform one of the following tasks to complete a successful upgrade to Geocortex Viewer for HTML5 4.14.0:

Upgrading from the following versions of the Geocortex Viewer for HTML5 may require additional steps:

Upgrade the HTML5 Viewer from Version 2.5.2 or Older

Starting in Geocortex Viewer for HTML5 2.6, you can configure the currency type when you select the Currency format for the chart's category, series source, and series aggregator. By default, the currency type is based on the location of the Essentials server. For example, if the server is in the USA, the currency type is US dollars.

If a chart's data is stored in a different currency than the currency of your server's locale, you must edit the chart and set the three new Currency settings to the correct currency type. This ensures that the viewer interprets the chart's data correctly. For information on setting the Currency format for a chart's category, see Category Setup (Horizontal Axis). For information on setting the Currency format for a series source and series aggregator, see Series Setup (Vertical Axis).

Upgrade the HTML5 Viewer from Version 2.4.1 or Older

As of version 2.5, the Geocortex Viewer for HTML5 cache manifest no longer exists. Instead, all content within the following folders will be made available offline in the Geocortex Mobile App Framework:

If you have customized your cache manifest file, ensure all of your content is within these two folders so it will be available in the Geocortex Mobile App Framework. The existing cache manifest is located in the viewer's virtual directory at:

Resources\Config\CacheManifestConfig.xml

After you have ensured all of your content has been made available, we recommend that you delete the CacheManifestConfig.xml file for each viewer.

We recommend that you delete all .manifest.xml files from the virtual directory for each of your viewers. For example:

C:\Program Files (x86)\Latitude Geographics\Geocortex Essentials\Default\REST Elements\Sites\MySite\Viewers\MyViewer\VirtualDirectory\MyViewer.manifest.xml

Upgrade the HTML5 Viewer from Version 2.3.3 or Older

This section applies to you only if you are upgrading from a version of the viewer older than 2.4 and you have not performed the steps for Geocortex Viewer for HTML5 Security Update 2015-03-26.

You may have to perform one of the following steps to complete a successful upgrade to Geocortex Viewer for HTML5 4.14.0. Perform the step after you have upgraded the viewer. The viewer upgrade process replaces the viewer's Framework.js file with a new, secure version.

The steps are:

Load Configuration from the Same Domain

HTML5 viewers 2.4 and newer do not load configuration files that are hosted on the same domain as Essentials if the URLs have different origins. For example, the following URL fails to launch an HTML5 viewer version 2.4 because the viewer's configured domain, https://myserver, does not match the configuration's domain, https://myserver.mydomain.com, even though they map to the same machine:

https://myserver/Html5Viewer/Index.html?configBase=https://myserver.domain.com/Geocortex/Essentials/...

If your environment is configured to produce URLs with two or more domains that do not match, you must update the URLs's configuration to work with new versions of the HTML5 viewer. We recommend that you use fully qualified domain names in your URLs, even if you do not use CORS or a proxy.

If your Essentials installation is configured for CORS, or your server is behind a reverse proxy, you must update the configuration. See Set Up Cross-Origin Resource Sharing (CORS) and Run Essentials Behind a Reverse Proxy.

You can configure the URLs that viewers and REST endpoints use from the viewer's RestManagerAppSettings.xml file and Essentials' web.config file. Configuring these URLs also updates the viewer launch links that appear in Manager.

To update the viewer launch links in Manager:

  1. Run an XML editor or text editor as an administrator.

    You can use Notepad, a text editor included with Windows.

  2. Update the HTML5 viewer's base launch link:

    1. Open the RestManagerAppSettings.xml file in the editor.

      For a typical Essentials installation, the file is located here:

      C:\Program Files (x86)\Latitude Geographics\Geocortex Essentials\[instance]\REST Elements\Manager\App_Data\RestManagerAppSettings.xml

    2. Within the viewer's ViewerFramework element, update the Url attribute to use a fully qualified domain name. For example: 

      <ViewerFramework ProductID="..." TemplateID="Html5Viewer_4_14" Url="http://myserver.mydomain.com/Html5Viewer" />

    3. Save the file.

  3. Update the Essentials URL:

    1. Open Manager's web.config file in the editor.

      For a typical Essentials installation, the file is located here:

      C:\Program Files (x86)\Latitude Geographics\Geocortex Essentials\Default\REST Elements\Manager\web.config

    2. Within the appSettings element, find the add element for the EssentialsUrl key.

    3. Update the value attribute to use a fully qualified domain, for example: 

      <add key="EssentialsUrl" value="http://myserver.mydomain.com/Geocortex/Essentials/REST/sites" />

    4. Save the file.

Load Configuration from Another Domain

Starting in version 2.4, if you configured cross-origin resource sharing (CORS) in Essentials, you must configure the viewer with a trusted domain where Essentials is hosted. The trusted domains list is configured in each of a viewer's host files (Index.html, Handheld.html, and Tablet.html). You must configure the trusted domains for each viewer. For instructions, see Configure Your Essentials Domain in Your Viewers .

Roll Back a Viewer that was Upgraded Using Essentials

If you upgraded a viewer using Essentials, and then decide that you want to roll back to the older version, follow the instructions below to remove the new version and restore the old version.

The following instructions do not apply to manually installed Viewers.

Viewer Backups

To restore a viewer, you must have a copy of the folder where the viewer was deployed in the web server. If you upgraded the viewer using the Post Installer's Upgrade function, a backup is made automatically. For an instance of Essentials called Default, viewer backups created by the Upgrade function are in the following folder:

C:\Program Files (x86)\Latitude Geographics\Geocortex Essentials\Default\Backups

When the Post Installer's Upgrade function is used to upgrade a HTML5 viewer, a site's old configuration settings get backed up as well. You can find the configuration settings for the old viewer at this location:

C:\Program Files (x86)\Latitude Geographics\Geocortex Essentials\Default\REST Elements\Sites\Your Site\Viewer\VirtualDirectory\Resources\Config\Default

The backup configurations have the file extension .backup.YYYYMMDD, where YYYYMMDD is the date that the backup was made.

Compatibility Issues

A minor release may introduce breaking changes in the configuration settings. Incompatible configuration is automatically fixed by the software during the upgrade process, but it must be manually fixed if you are downgrading. To test your site's configuration for backwards compatibility, we recommend that you install both versions of the viewer, attempt to view your site through both of them, and compare the configuration settings side by side.

You can use a tool like DiffChecker.com to visualize the configuration changes.

Restore the Viewer

To restore a previous version of the viewer:

  1. In the file system, locate the folder that contains the backup of the viewer that you want to restore.

    If you upgraded the viewer using the Post Installer's Upgrade function, the backups are in the following folder:

    C:\Program Files (x86)\Latitude Geographics\Geocortex Essentials\Default\Backups

    The folder Default name may be different depending on the name of your instance of Essentials.

  2. Download the old template from the VertiGIS Studio Support.

    See Download the Geocortex Viewer for HTML5 for instructions.

  3. Launch the Post Installer.

    • Windows Server 2012 or Windows 8, and Newer Versions:

      On the Start menu, type Post Install, and then click Post Installer.

    • Windows Server 2008 or Windows 7:

      In the Start menu, click All Programs | VertiGIS | Geocortex Essentials [Version] [Instance] | Post Installer.

      [Version] is the Essentials version number. [Instance] is the instance name, if Essentials is installed as a named instance. The default installation does not have an instance name.

  4. Select Configure Viewer Templates in the side panel.

  5. In the Installed Templates area, click the template that you want to roll back.

    The template's management buttons display.

  6. Click Remove, and then click Yes to confirm.

    The removed viewer remains in the IIS webroot folder after this operation. If you wish to deploy to the same folder, you can go into the file system and manually rename or remove the viewer folder.

  7. Install the old template.

    See Install the Viewer Framework Using a Viewer Template for instructions.

  8. Copy the backup of the old viewer to the folder in the web server where you just deployed the viewer template.

  9. Reload Manager and navigate to the Viewers page.

  10. Ensure the viewer Launch URL matches the name of the folder where you just deployed the viewer template.

    If you deployed the old template to the same folder, the viewer may still reference the deleted template. In this case, the viewer does not display a Launch URL. To change the template that the viewer references, click Edit next to the viewer and point the viewer to your preferred viewer template.

    Select Template dialog box

  11. Revert to your site's backed up viewer configuration files.

    If you upgraded your viewer template using the upgrader in the Post-Installation Configuration, the old versions of your viewer configuration files are backed up in the configuration folder. For a typical installation of Essentials, you can locate the configuration folder at this location:

    C:\Program Files (x86)\Latitude Geographics\Geocortex Essentials\Default\REST Elements\Sites\Your Site\Viewer\VirtualDirectory\Resources\Config\Default

    The backup configurations have the file extension .backup.YYYYMMDD, where YYYYMMDD is the date that the backup was made.

    1. Move any active .json.js configuration files to another folder on your system for safe keeping.

      This may include files with Preview.json.js in the file name.

    2. Remove the .backup.YYYYMMDD suffix from the remaining files.

      For more information, see Viewer Backups.

  12. Open the viewer in a web browser and verify that it works.

Troubleshooting

If your rolled-back viewer does not open or states that the viewer configuration is invalid or malformed, we recommend examining the configuration of the viewer and a backup configuration of the site before it had been upgraded. If you upgraded an HTML viewer template using the Post Installer's Upgrade function, you can compare your new configuration with the backup copies of your old configuration files. See Viewer Backups for information.

You can also generate a new viewer using the template that has just been installed. If the new viewer launches properly and the old one does not, compare the two viewer configurations to determine what the problem is. You can use a tool like DiffChecker.com to visualize the configuration changes.