This tutorial introduces what is involved in writing your own analysis reports for Essential Architecture Manager. Essential Viewer provides a framework for rapidly building new reports using XSL to deliver HTML-based perspectives on your Essential Architecture Manager repository, deriving and inferring important knowledge from the information that you've captured, using Protege.

Pre-requisite skills

Essential Viewer's analysis reporting framework has been built to provide an environment where new analysis reports can be rapidly written and deployed as discrete components. The framework is based on XSLT and this can be supplemented by more advanced programming languages, such as JSP as required.

Some knowledge of HTML, XML, XSL and XPath is very helpful when authoring new analysis reports but expert knowledge of these is not required for most requirements. The bundled reports provide good examples of how the reports are authored and the simple schema for the reports' source XML data means that a small set of XSL and XPath statements are used repeatedly.

Any Java-server compatible approach can be used to deliver new analysis reports but using XSL as the front end of the report means that you can take advantage of the common headers, footers, report view history components.

Getting started

The first step is to plan your report and understand the requirements that you have for it. What areas of the model do you need to analyse? How would you like to present this information?

Having decided on what your report will do, you need to establish which Essential Meta Model classes and relationships that you need for your report. Use Protege to explore the relationships that you are interested in and then the meta model documentation to find the classes and slots (the attributes of the classes). It is these that you use to get the information for your report.

It is often useful to explore the model in Protege to understand how the classes and relationships that you need to use work. Walking through the report by hand in Protege is very helpful in understanding what navigation your report will have to perform.

Explore similar reports

Now that you understand what the report needs to look like and which Essential Meta Model classes and relationships you need to use, you are ready to start putting the report code together. At this stage - even if you have gained some experience in writing Essential Viewer reports - to have a look at how similar reports, that are already in Essential Viewer, have been built. This helps not only with the HTML coding but also to show some of the more tricky XSL queries that you might need.

Report page concepts

The XSL framework of Essential Viewer is implemented by two Java servlets (one for HTML, one for SVG) that use XSL style sheets to generate HTML pages from the XML snapshot of the Essential Architecture Manager repository. These servlets manage a page-visit history and pass the required parameters to each XSL template as required.

Each HTML page that is produced, consists of the following components:

• header - the header at the top of the page which includes place-holders for additional links, e.g. to your organisation's Intranet.
• history - a drop-down list of the reports that you have viewed in your current session.
• body - the contents of the report
• footer - the footer that is included on each page.

In this way, the header, footer and page history are managed by the framework, enabling you to focus on putting together the body of your analysis report.

To include the header, history and footer on your report, simple include the XSL templates for these components in your report page as follows:

In this example, the template, "Page_Body", is defined in this XSL file to produce the body contents of the analysis report.

These commonly used templates, such as the header and footer are stored in the common folder of the Essential Viewer. To include these in your report XSL, make sure to use the following statements:

Mock up your report in HTML

Possibly the trickiest part of defining any report is getting the formatting of it correct in the HTML. To minimise this, use a graphical HTML authoring tool to mock up the report and define the HTML that you will need your XSL to generate. You might even start with a saved copy of the HTML produced by a similar, pre-defined report.

Processing the report XML

Essential Viewer reports are created by analysing the XML snapshot of the Essential Architecture Manager repository that you make by publishing the repository with the Essential Architecture Reporting Tab in Protege. This snapshot is sent to Essential Viewer and you will want to take a copy of this XML document - reportXML.xml - while you are developing your report. The document is located:

/webapps/essential_viewer/reportXML.xml

The schema for this XML is a cut-down version of the Protege Experimental XML format that uses only the instances in the knowledge base. You can download an annotated schema from http://www.enterprise-architecture.org/xml/essential_report.xsd.

There are only a few XML tags that you need to be familiar with to develop any report. However, note that each of these tags is namespaced using the pro: prefix whenever you refer to it. The tags that you will be using are:

• knowledge_base - the root node of the repository snapshot. This is normally only used by the top-level template of your report to start analysing all of the instances in the repository.
• simple_instance - each instance of the classes in the Essential Meta Model is stored as a simple_instance tag, including relationships. The set of simple_instance tags is the set of all the instances in the repository. Every simple_instance has the following elements:
  • name - the 'internal' Protege instance ID for the simple_instance. These are the repository unique identifiers for each instance and should not be modified by hand.
  • type - this specifies the name of the class that this is an instance of, e.g. an Application Service instance will have a type = Application_Service
• own_slot_value - The attributes and relationships for each class, that are stored in Protege slots, are captured using the own_slot_value tags. Each simple_instance has one or more own_slot_values but only where there are values stored in the slot. Empty slots on an instance have no own_slot_value tag in the simple_instance. These slot_values work in the same way for every slot on every class and have the following elements
  • slot_reference - the name of the slot (attribute on the class) that is being used
  • value - the value that this slot has on this simple_instance. In addition, the value has a value_type attribute that specifies the type data that is stored in the slot. However, this value_type is very rarely used as you will normally already know the nature of each slot that you need to use in the report.
    

Every Essential Meta Model class that is part of the EA_Class hierarchy will have a own_slot_values with slot_references of "name" and "description", which are frequently used to display details of an instance in your report. See the XML extract, above. To access these, use XSL statements like the following (one of the common templates that can be used to render the real name of an instance):

This example also demonstrates how instances are 'selected' from the XML, using the '[...]' predicates. e.g. to select an instance using it's repository ID, the XPath is (you will be using this sort of thing a lot!):

/node()/pro:simple_instance[pro:name=$theInstanceID]

Common templates

There are a number of templates provided in the common/ section of Essential Viewer for doing commonly required tasks, e.g. return the visible name of an instance from it's internal repository ID, as shown in the example above, or render an HTML table showing the Strategic Planning details of an instance.

Defining links to other reports

By linking to other reports in the Essential Viewer, you can provide drill-downs and cross-references. These links are defined as HTML hyperlinks and uses the following set of request parameters, which ensures that the right report is invoked and that the page-view history is maintained.

• XML - the repository XML document that should be used as the source information about the repository
• XSL - the XSL stylesheet that is to be run to produce the next analysis report page
• PMA - Parameter 1 that can be passed to the XSL stylesheet
• PMA2 - (optional) Used by some reports to control hiding/unhiding of items on the report and available for use as required by reports
• PMA3, PMA4 - (optional) Additional optional parameters available for use by reports as required.
• LABEL - the name of the report that you are linking TO. You can add the name of the item that the analysis report is about as show in the following example.

Testing your reports

We recommend that you use a good XML tool with XSLT debugging support as you develop your new reports. These will help you with identifying the right XPath and also for stepping through the processing of the report XML to build your report.

You will need to use a copy of the Essential Viewer XML repository extract to test your new report. Make a copy of the following file and use this as your test XML source. As your repository grows, you may wish to remove many of the instances from the XML document to cut the document down to a more manage-able size.

/webapps/essential_viewer/reportXML.xml

Deploying your new analysis report

When you've completed the testing of your new report and are ready to deploy it, follow the instructions in this article, Installing New or Updated Essential Viewer Reports. Your new report is now ready to use!

Graphical reports with SVG

Use a combination of two XSL files, one XSL for the page body HTML (which uses the standard headers and footers) with an HTML object statement to include a second XSL that renders just the SVG.

More complex graphical layouts

XSL provides a very productive approach to developing the analysis reports. However, for more complex layouts, in particular where the complete report contents needs to be understood before it can be laid out or rendered, XSL will not always be the easiest solution.

In such cases, you can use Java Server Pages (JSP) to perform more complex layout calculations using some of the supporting Java classes that are provided in the Essential Viewer such as the NodesArcService.

Additional Support

• For additional support in the development of custom analysis reports, professional services from the Essential Project Team are available. Please use the Services Enquiry form for more information.