The Essential Integration Server is an extension to Enterprise Architecture Manager that manages import and export integrations from and to external information sources - from Excel Spreadsheets to external repositories. This tutorial introduces Essential Integration Server and how to use it to import information into Essential Architecture Manager

When you already have a significant amount of information about your architecture captured, importing that information into Essential Architecture Manager enables you to quickly populate the model with this pre-existing information.

Information from any source - ideally XML - can be imported into and exported from Essential Architecture Manager. In addition, the Essential Integration Server enables on-going synchronisation of information held in Essential Architecture Manager with the external information source. This has been used, for example to import regular updates of part of the architecture, capturing changes, introducing new elements and enabling candidates for deletion from the model to be identified. Each run of the integration timestamps the new and updated instances in the model.

Integration

Importing into Essential Architecture Manager requires that you define an integration between the your external data source and the Essential Meta Model for the meta classes of which you wish to import instances. Even if your data source is a spreadsheet, the columns in that spreadsheet represent classes in the source meta model and these must be mapped to the classes in the Essential Meta Model.

It is vital during the integration that the integrity of the Essential Architecture Manager repository is maintained. To ensure this, the integration operates on the Java API of Protege - enabling it to make all the necessary underlying connections and updates to the repository as instances are added and related. The Protege Script Tab is used to allow scripts - which don't need to be compiled - to define the steps required to correctly map the external information into the Essential Architecture Manager repository.

How to define an integration

The Essential Integration Server provides a platform for dynamically generating the integration scripts from the source external information. To define the integration:

• Analyse the source data, and establish the mapping to the Essential Meta Model
• Define an XSL script that generates the Protege API script to perform the mapping and create / update instances in Essential
• Upload your XSL integration script and source data to the Essential Integration Server
• Modify the index.html file of Essential Integration Server to define this new integration and hyperlink that will invoke the Repository Integration Service using a REST-style service invocation.
• Go to the homepage of the Essential Integration Server and select the required integration
• Download the generated script files
• Run these scripts in Protege Script Tab

Define XSL Integration

A library of useful operations for creating and updating instances in the Essential Meta Model is provided in the file standardFunctions.txt.

This file uses the Jython script language, and provides the basic features of Python. Following the example XSL file, execute this library file to define the functions that it contains. Test this XSL to ensure that it generates a valid and correct script.

By default, these XSL scripts are uploaded to the WebContent/IntegrationScripts/XSL directory of the Essential Integration Server. This location is controlled by a Servlet parameter.

Synchronisation References

The Essential Integration Server provides the capability to synchronise your external data source with the Essential Architecture Manager repository. As your source data changes over time, you can re-run the integration to update the Essential repository. New instances are identified and created and each update/creation is timestamped so that candidates for deletion from Essential Architecture Manager can be identified. Such candidates are not deleted during the integration process.

To capture these, the external_repository_reference is used. If your data source already has unique identifiers, e.g. repository instance IDs, use these. For spreadsheets and the like, you could use the worksheet and row number as the instance reference.

Upload Your Source to Import

By default, the source information files (e.g. XML) are uploaded to the WebContent/IntegrationScripts/XML directory of the Essential Integration Server. This location is controlled by a Servlet parameter.

Invoking the Repository Integration Service

The Essential Integration Server includes a Repository Integration Service that is invoked using a REST-style service invocation. A simple HTML file is used to make the requests to this service, which on completing the integration responds with a web page of either the generated integration scripts or an error message.

Modify the packaged index.html to describe the import source that you are using and modify the hyperlink to specify the following HTML GET parameters:

• xslFile - the filename of the integration XSL file for the required integration
• scriptFile - the prefix of the resulting Python script file(s) to be run against the repository
• externalRepository - the filename of the external repository extract XML document (your existing data source).

Download the Generated Scripts

Clicking on the link you defined in index.html, will run the Repository Integration Service. On success, it will return a page with links to the script file(s) that it has created. Due to a limitation of the Bean Scripting Framework, each individual script must be less than 64K in length. To cater for this the Repository Integration Service splits the script that it has generated into 'bite-size' chunks and defines a top-level script file that invokes each 'bite-size' script in turn.

Save each of the generated script files to your local workstation and run the top-level script (suffixed _all) in the Protege Script Tab in your Essential Architecture Manager repository.

More Information About the Essential Integration Server

• To learn more about how to install the Essential Integration Server, please see the Install Guide.
• For more information about how to get started with using the server and how to deploy your own import scripts, please see the Using the Essential Integration Server Tutorial.
• For additional support in the development of custom imports from your existing information sources, professional services from the Essential Project Team are available. Please use the Services Enquiry form for more information.