The following components are required to install Essential Architecture Manager.

• Protege. This is the core modelling tool platform for Essential AM. The "Full Protege" package is recommended.
  
• Essential Widgets. A set of extension components from the Essential Project that are plugged into Protege. These include:
  • AutoTextWidget
    
  • ReportTabWidget
    
• JDBC Drivers. The relevant JDBC driver for the database server that you are using.
• Apache Tomcat. The application server environment for running the Essential Viewer software.
• Essential Viewer
  
• Essential Meta Model. The core meta model and base repository for Essential Architecture Manager.

Having downloaded the essential_architecture_manager.zip from the Download section, please check that you have the software pre-requisites available.

Unpack the essential_architecture_manager.zip file, which will contain 7 files;

• essential_widgets.zip
  
• essential_viewer.war
  
• essential_metamodel.zip
  
• shutdown_protege_server.bat (only used for Windows installations)
• COPYING.txt (the license for Essential Architecture Manager)
• README.txt
• releaseNotes.txt

Before starting the install of Protege, confirm whether or not a JVM has been installed. From a command prompt, type:

java -version

The resulting message from Java should show a JVM version at or above version 1.5.x. If a JVM is already present that meets the required version, there is no need to install the JVM that is provided with Protege.

If you have not already installed Protege, install it by running the installation program.

The following steps should be followed to install Protege on a Microsoft Windows Platform.

• Run the install_protege.exe file.
  
• Select the option to install "Everything" as this will include the optional tab widgets that may prove useful at a later date, e.g. Prompt, Jambalaya.
• Select the installation folder, preferably take the default in Program Files\Protege_x.x.x
• Select the JVM that Protege should use. If from Step 3, a suitable JVM (version 1.5 or above) has already been installed, select that JVM.
  • Select either from the list show or find the version discovered in Step 3 using the "Choose Another" button. This may require investigation of the Java Control Panel in the Windows Control Panel. NOTE: You must select the specific java.exe file to use.
• Select 'Next' until the installation completes.

Run the Protege installer for your platform and follow these steps:

• Select the option to install "Everything" as this will include the optional tab widgets that may prove useful at a later date, e.g. Prompt, Jambalaya.
• Select the installation folder, preferably take the default
  
• Select the JVM that Protege should use. If from Step 3, a suitable JVM (version 1.5 or above) has already been installed (this will be the case on Mac OS X), select that JVM.
  • Select either from the list shown or find the version discovered in Step 3 using the "Choose Another" button.
• NOTE: You must select the specific java.exe file to use.
• Select 'Next' until the installation completes.

4.3 Configure Protege

Please open Protege now.

• Go to the 'File' menu and select 'Preferences'.
• Un-select the option 'Sort class tree (Classes Tab)' to ensure that the Essential Meta Model class hierarchy is shown in the correct order.
• Click OK and exit Protege.

This configuration is not required in Protege 3.3.1 and the preference is not available

Microsoft Windows platforms: Extract essential_widgets.zip to the /plugins directory (where is the location where you installed Protege in Step 3).

All other platforms: unpack or uncompress essential_widgets.zip.

This will create a directory, called com.enterprise_architecture.essential.widgets, in which the Essential Widgets are stored.

Microsoft Windows: This will be in the /plugins directory already (assuming you extracted it directly to this directory). If you have extracted the ZIP file anywhere else, simply copy the directory as follows for all other platforms.

All other platforms: Simply copy the com.enterprise_architecture.essential.widgets folder into /plugins.

Install the required JDBC drivers as per the instructions supplied with them. The Protege server will use these to connect to the database that will hold the repository. To enable Protege to see these drivers:

• Copy the .jar file for your JDBC driver to the folder as driver.jar
• If driver.jar is already being used, use driver0.jar, driver1.jar or driver2.jar

If you need the option to use more than 3 different types of database server to hold different repositories managed by the same server (i.e. you need more than 3 JDBC drivers):

• Modify the file: /protege.lax to add the path to your JDBC driver JAR file (including the jar file itself) to the lax.class.path property.

If you do not already have Tomcat (or an alternative Java Application Server that can run Java Servlets) installed, please install it by running the installation program for your platform.

Like Protege, Tomcat requires Java v1.5 or above. For simplicity, select the same JVM that was selected Essential Architecture Manager Installation Guide during the Protege installation. In this case when prompted by the Tomcat installer, select the path to the folder "jre".

When the repository is published from the Essential Modeler (Protege running an Essential project) to the Essential Viewer, a snapshot of the repository is sent to a Servlet running on Tomcat. The repository can get large, so Tomcat must be configured to accept large amounts of data being sent to it.

Edit the /conf/server.xml file as follows:

• Find the tag entry for the HTTP 8080 connector
• Add the maxPostSize="0" attribute and value to this tag such that it looks like:

	maxHttpHeaderSize="8192"
	maxThreads="150"
	minSpareThreads="25"
	maxSpareThreads="75"
	enableLookups="false"
	redirectPort="8443"
	acceptCount="100"
	connectionTimeout="20000"
	disableUploadTimeout="true"
	maxPostSize="0" />

Deploy the essential_viewer.war to your Tomcat (or other Java Server). You can do this by:

• Copying essential_viewer.war to the /webapps directory
  
• Deploying the essential_viewer.war via the Tomcat Manager web page.

Both the meta-model and the model for Essential Architecture Manager are contained in the repository which is controlled from a Protege project file, and has the file extension, .pprj

Create a directory to hold the meta-model and model configuration files. In stand-alone mode, we recommend using the file-based datastore for the repository. This directory will also contain the data files for the model and meta-model. Create a directory for your repository, e.g.

• /EssentialAM/Repository

Unpack the file essential_metamodel.zip and copy the files into your new repository directory. The file that you will open with Protege is essential_baseline_v1.pprj.

8.1 Setup Protege and Essential Environments

The Protege server is itself controlled by a Protege project called the 'metaproject'. This project tells the Protege server about all the projects that it is be hosting, which users are defined and which projects the users can access. Once all the server software components have been defined, the following steps should be run on the physical server in order to define the metaproject.

A default metaproject is installed with Protege and the Protege server is configured to use this out-of-the-box. We decided to use this default metaproject to make the installation of the server simpler - and for this reason, the Essential Project does not provide a customised starter metaproject. However, if you wish to change the default location of this metaproject so that it can be managed alongside your Essential Architecture Manager repository or you just wish to move it to a completely different area of your filesystem,  you will need to do the following:

• Copy the metaproject.pprj, metaproject.pins and metaproject.pont files from /examples/server/ to the new location, e.g. the /EssentialAM/Repository directory if moving it to be alongside your repository (Assuming that your repository is installed in /EssentialAM/Repository).
• Update the run_protege_server.bat (on Windows) or run_protege_server.sh (on Mac OS X, Linux, Unix etc.) file and change the METAPROJECT variable so that it refers to the file you created in above.

 

8.2 Meta Project Definition

 

• Define the Groups [which work like Roles] that will be allowed to access the server. As a minimum, create:
  • Architects a group for all architects who are able to read and update models
  • Viewer a group for users who only have read access to the models.
• Define the users by creating a new instance for each user that will be using the Essential Modeller. Although passwords are visible to administrators of the metaproject they are obfuscated when clients use them. Add the Group that this user belongs to [i.e. the roles that this user can play] by selecting the appropriate groups in the Allowed Group field or by adding members to the Group. Make sure to add your own user account to the AdminGroup. 
  

The World group can be left in the ontology.

 

 

 

Having defined the Essential Architecture Manager repository project to the Protege Meta Project, we need to add the Annotations Project for Essential Architecture Manager to the Meta Project. The Annotations Project manages collaboration capabilities including tracking all changes to the repository and is created automatically by Protege when you choose to show the collaboration panel. If you have not already enabled the Collaboration in your Essential Architecture Manager repository project, see the Enabling Collaboration article for how to do this.

Using the Annotations Project is optional but recommended for multi-user installations. You can create the Annotations Project after you have completed this Meta Project configuration. Protege Server will raise warnings if it cannot find the specified Annotations Project but you can continue to work with your repository in multi-user mode when Protege cannot find the annotations project.

 

11.1 Defining Essential AM Server Service Dependencies

Where a database-based repository is used, the Essential Server will not start up correctly if it cannot establish a connection to the database that is now hosting the repository. To help with the automatic startup of the Essential Server, define a dependency between the Essential AM Server service and another service, such as your database server instance (if it is co-located with Essential) or with Tomcat (used for the Essential Viewer):

• Start->Run->regedit32
• Go to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EssentialAM Server
  • Click Edit -> New Multi Size String Value (REG_MULTI_SZ)
  • Value name must be 'DependOnService' [without the ' ']
  • Double click to edit its data value and a dialog asking for data values will appear.
  • Enter the name of the service that Essential depends on - 1 per line
    • For MySQL, enter MySQL
    • For Tomcat, enter Tomcat5
• Exit from regedit
• Check that the dependency appears correctly in the Control Panel, Services entry for the Essential AM Server.

Before starting the install of Protege, confirm whether or not a JVM has been installed. From a command prompt, type:

java -version

The resulting message from Java should show a JVM version at or above version 1.5.x. If a JVM is already present that meets the required version, there is no need to install the JVM that is provided with Protege.

If you have not already installed Protege, install it by running the installation program.

The following steps should be followed to install Protege on a Microsoft Windows Platform.

• Run the install_protege.exe file.
  
• Select the option to install "Everything" as this will include the optional tab widgets that may prove useful at a later date, e.g. Prompt, Jambalaya.
• Select the installation folder, preferably take the default in Program Files\Protege_x.x.x
• Select the JVM that Protege should use. If from Step 1, a suitable JVM (version 1.5 or above) has already been installed, select that JVM.
  • Select either from the list show or find the version discovered in Step 3 using the "Choose Another" button. This may require investigation of the Java Control Panel in the Windows Control Panel. NOTE: You must select the specific java.exe file to use.
• Select 'Next' until the installation completes.

Run the Protege installer for your platform and follow these steps:

• Select the option to install "Everything" as this will include the optional tab widgets that may prove useful at a later date, e.g. Prompt, Jambalaya.
• Select the installation folder, preferably take the default
  
• Select the JVM that Protege should use. If from Step 1, a suitable JVM (version 1.5 or above) has already been installed (this will be the case on Mac OS X), select that JVM.
  • Select either from the list shown or find the version discovered in Step 1 using the "Choose Another" button.
• NOTE: You must select the specific java.exe file to use.
• Select 'Next' until the installation completes.

4.3 Configure Protege

Please open Protege now.

• Go to the 'File' menu and select 'Preferences'.
• Un-select the option 'Sort class tree (Classes Tab)' to ensure that the Essential Meta Model class hierarchy is shown in the correct order.
• Click OK and exit Protege.

This configuration is not required in Protege 3.3.1 and the preference is not available

Microsoft Windows platforms: Extract essential_widgets.zip to the /plugins directory (where is the location where you installed Protege in Step 3).

All other platforms: unpack or uncompress essential_widgets.zip.

This will create a directory, called com.enterprise_architecture.essential.widgets, in which the Essential Widgets are stored.

Microsoft Windows: This will be in the /plugins directory already (assuming you extracted it directly to this directory). If you have extracted the ZIP file anywhere else, simply copy the directory as follows for all other platforms.

All other platforms: Simply copy the com.enterprise_architecture.essential.widgets folder into /plugins.