Installation

A new version of the Essential Viewer component of Essential Architecture Manager is delivered as pack in an Essential Architecture Manager installer application. This pack contains a Java Web Archive (WAR) ready to be deployed to your Java application server. This article describes how to install and deploy a new version of this web application.

Updates to individual reports may also be provided as ZIP archives of the updated XSL, JSP etc. files. This article does not describe how to install such updates. Details of how to update analysis report files is provided in this article.

 

Preparation

To install a new version of the Essential Viewer web application, you should not need to stop any running applications. However, if you encounter any issues with the installation of the new version of the web application (e.g. the new version will not deploy or the web application will not respond), please restart your application server after completing step 2, below.

 

Process

The installation process is simple:

  • Run the Essential Viewer update installer

1. Customised Viewer Reports

The update installer will make a backup of your existing Essential Viewer installation before installing the updated Viewer. Any new Essential Viewer analysis reports you have created or any of the standard reports that you have edited, are saved to the backup and can be re-deployed to the new Essential Viewer when the update has completed. The backup directory will be in [TOMCAT_INSTALL]/webapps/essential_viewer_[last version number]_back.
Please review the new report files when you have completed the update in case any of the reports that you have edited have been changed as part of the update.

2. Install Essential Viewer

Essential Install Welcome PanelDownload the Essential Architecture Manager update installer, which will guide you through the rest of the installation process. The following sections in this guide provide additional detail about the options for the installer and the questions that it will ask.

To run the installer:

Double click on the Essential Update JAR File.

If, for some reason the installer is not recognised as an executable JAR file, use the following command at command prompt/terminal window:

java -jar essentialupdate.jar
You will now see the welcome panel of the installer and will be guided through the install process.

3. Select the Essential Viewer Packages to Install

Essential Install Select Packs PanelThe Essential Architecture Manager installer is divided into packages, enabling the installer to be used for installation possibilities.
Select the Essential Viewer pack ONLY. Note: the update scripts pack is required and cannot be un-selected.

4. Specify Apache Tomcat Locations

Essential Plugins Path PanelEssential Architecture Manager includes plugins that must be installed into your Protege and Apache Tomcat installations.
The installer will ask you to specify the location of your Apache Tomcat (or alternative Java Web Application Server). An attempt to automatically find Apache Tomcat in typical installation locations will be made. If the installer cannot find your Apache Tomcat installations, please use the 'Browse...' button to specify the folder in which it is installed.
When you select an location for either Protege or Apache Tomcat, the installer will verify that location to ensure that you have selected a valid folder.
If you want to share your Essential Viewer with others in your organization, you can deploy the Essential Viewer to an instance of Tomcat that is running on a network server, if you can navigate to the Tomcat directory on the network server, do so from the 'Browse...' button for the Tomcat location field.

5. Select Location for Uninstaller and Install Summary

Essential Install Uninstall Path PanelThe installer will create an un-install program for the Essential Viewer update.
 
Next, specify to the target location where the installer should put the Essential Architecture Manager Uninstaller. The installer will create a directory to put this in the folder that you specify, e.g.
/EssentialAM

7. Finished

Essential Install Finished PanelThe installer will now install the new version of Essential Viewer and the uninstaller to the locations that you have specified in the above steps.
Essential Install Done PanelWhen the installation has completed successfully, you can create an automated installer to repeat this installation configuration on other Essential Viewer machines. Select the 'Generate an automated installation script' option and specify the name and location of your automated install script.
See the Automated Installer article for how to use this installation script.

Tomcat (or your preferred Java Application Server) should overwrite the existing version of Essential Viewer. If you encounter any problems with this (such as the Essential Viewer application not being updated), please un-deploy your existing version of Essential Viewer before deploying the upgrade. Performing the installation while Apache Tomcat is still running has proved to be more reliable than updating the application with Tomcat stopped.