This article describes how to install meta model update packs.

Update Packs

Updates to the Essential Meta Model are provided as Python scripts that are run from within the Script Console Tab. Each script will make the required additions and updates to the meta model in your Essential Architecture Manager Protege project. In some cases, the update pack will also create instances in the model.

Before you start

When constructing a meta model update script, every effort is made to ensure that the update will be compatible with all Essential Meta Models. Extensive testing is performed against the baseline repositories and repositories that have applied meta model extension packs. However, the Essential Meta Model is open-source and easily extended and it is possible that an update pack may have adverse affects on custom extensions that have been made or fail to complete because of custom extensions. In such cases, please contact the Essential Project Team for support.

Before you start applying the update pack, please ensure that any new edits to the Essential repository are saved and that you have backed up your repository.

Applying the Update Pack

Each update pack is applied by using the following form of command on the Script Tab console command line:

execfile("<FULL PATH TO SCRIPT>/<update_pack_script>")

where <FULL PATH TO SCRIPT> is the full path to the folder where you have stored the script and <update_pack_script> is the name of the script to use.

Note that in the path, you should use the '/' for path separators, even on Windows platforms, since Protege is a Java-based system.

Once the update has completed, a success message will be reported on the Script Tab command line. This message will normally also advise you to check the Form layout of selected classes that have been updated to account for any extensions and custom layouts that might have been used. After the update has been applied, if you notice any layout anomalies, these can be easily resolved by opening the Forms tab in Protege, selecting the affected class and then dragging the required fields on the form to the desired layout.

Running Large Meta Model Update Scripts

A 64KB script file size limit from the underlying scripting engine means that larger meta model updates must be split into smaller chunks to be run individually. This article describes how to use large meta model update scripts to apply updates and provides troubleshooting advice.

Apply-all Script

To make it easier to apply the chunked update script, an 'apply all' script is provided that executes each chunk in sequence. Simply run the 'apply all' script and the full update is applied.

Set path

The apply-all script needs to know where you have stored all the script chunks when you unpacked the update pack. Before executing the apply-all, you must edit the path to specify the full path to the folder in which you have stored the update script chunks.

By default, this is set to 'YOUR_FULL_PATH/' and if you do not edit this, a help message will be displayed and the apply-all will terminate.

Replace 'YOUR_FULL_PATH/' with the full path to the location of the folder containing your scripts, including the last '/' character. e.g.

path = "C:/Essential/UpdatePack/"

Note that even on Windows platforms, you need to use the '/' character as a path separator and the '"' characters are required.

Run the update

Once you have updated the path variable, save the apply-all and open your Protege project containing the Essential repository that is to be updated.

Ensure that the Script Console tab is enabled. If it is not, enable it by using the Project->Configure menu and selecting the Script Console Tab from the list of available tab plugins.

At the command prompt, enter the following command:

execfile("<PATH TO APPLY-ALL>/<apply-all>")

and press enter.
Where <PATH TO APPLY-ALL> is the full path the folder containing the apply-all script and <apply-all> is the apply-all script.

Depending on the nature of the update, which may include complex tasks that need to be applied to every meta class in the meta model, updates can take several minutes to run.

Troubleshooting

If the update script has been running for many minutes and Protege appears to have completely hung, check the console output for error messages. In particular, memory exceptions. Large scripts can require significant amounts of memory and may require the maximum heap size for Protege's Java Runtime Environment to be increased, e.g. to 2048MB, using the -Xmx Java parameter.

On Microsoft Windows platforms, the memory configuration is controlled in the Protege Properties. On Mac OS/X, this parameter is set in the info.plist file in the Protege application contents. On other platforms, the run_protege.sh file should be edited to update the -Xmx parameter.

If the apply-all script is still failing to complete, you can run each chunk of the update individually, in sequence. Indeed, you may prefer to run the update in this manner as the memory requirements are reduced and progress is easier to track. To run each chunk individually, use the following command at the Script Console command line:

execfile("<FULL PATH TO UPDATE PACK>/update_script_00.py")

where <FULL PATH TO UPDATE PACK> is the full path to the folder where the update pack scripts have been stored.

Starting with chunk 00, run chunk 01, 02 and so on until all the chunks have been applied. NOTE: It is important that the chunks are run in the correct sequence. Running a chunk out of sequence may cause the update to fail.

If the update script reports any errors or exceptions, please run each script chunk individually to identify where the exception or error has occurred. Please contact the Essential Project Team for support.