A web publication platform for an ArchiMate model

Introduction

As an independent Enterprise Architect (EA) consultant I often get the question what the possibilities are for publishing the repository content over the web. Of course in EA there is the possibility to generate a HTML version of the model but in most cases my customers demand extra functionality like key word search or a discussion module.

In my current assignment for the National Health Broker in The Netherlands the introduction of a webbased solution was evident. One of the most important product of this organisation is the architectural documentation of the interfaces of the broker component. The organisation itself is quite small but the external stakeholders like software suppliers, software developers and policy makers is large.

In the current situation the architectural documentation is published in pdf documents. Keeping these documents up to date and correctly linked and integrated with each other is a tedious job. Introduction of an Architecture Repository based on ArchiMate 2.0 and EA helped us a lot. The web-based solution  is however an essential part of the solution. This article describes solution we introduced: the Web Publication Platform.

Implementation model

Because the current solution is the implementation of an ArchiMate 2.0 architecture model we use limited data entities from the EA repository. The model is  rather large, over 3500 elements and 5000 associations. In the image below the most important elements are displayed and described.

·         Packages are extensively used for grouping and sorting elements and diagrams

·         Diagrams are used for given summary views of the entities to various stakeholders

·         Elements are used to describe the architectural entities. Therefore we use the notes, alias, key word attributes and extra entities which are mentioned below

·         Associations for modelling the associations between the elements

·         Attributes for data modelling in data objects and artficats within ArchiMate (this is an extension on the methodology)

·         Tagged values for extra describing attributes of the elements

·         Linked files, because the broker has to keep track of legislation and standardisation constraints which are maintained by other organisations hyperlinks to webpages are essential.

For the implementation of the WPP we decided to use an Open Source Framework for content and form management. It is unnecessary to start from scratch developing a solution. Not only implementing the forms for the architecture repository the form factory solution has a web based interface for the governance of its own (form) entities.  In the image below an overview of the functionality

The form factory has various form types that can be used to display information from a relational database. Since the EA repository is also a relational database the interface to the database is implemented in a number of SQL statements and are connected to a form type. The Form Factory engine now handles the request made by the user when using the web application.  The views are summarized below:

·         Lists and sublists are used to display multiple elements in a screen and make selections to display in detail views

·         Detail views to display elements and diagrams including links to associations, attributes and tagged values etc.

·         Explorer view is a combination of a tree view and a detail view

·         Discussion platform for adding comments to elements by authorized stakeholders

·         Search, for key words in combination with a number of filter options

In the image below a sample of an explorer view screen

Some challenges

When implementing the interface to the repository we faced a number of difficulties. We used two architecture principles that limited our options:

·         All governance modelling and administrative activies are done by architects via the desktop application of Sparx. The WPP is only used for publication of the information not for modification.

·         There are no modifications made to the EA database (eap file). Therefore no tables for the form factory component are implemented in this database.

Below a number of specific challenges are briefly described

Configuring the Form Management System

Because of the second principle we faced the problem that in one detail screen (for example the element detail) we have to display information from two databases in one screen. The Form Factory was not configured for this constraint. Therefore we introduced an abstract class where the sql statements are combined with a connection string so before the sql statement is executed to retrieve the data the connection to the right database is opened. In the code snippet below an

       Public Function Detail(entity As String, id As String) As String

            Dim strRet As String

            Dim strSql As String

            Select Case entity.ToUpper

                Case "ELEMENT"

                    Me.ViewerHtml("<H1>Details element</H1>")

                    Me.ViewerDetail("SELECT name as elementnaam, stereotype, note as toelichting, '<a href=FrmDetail.aspx?module=package&id=' & package_id & '>Module informatie</a>' as [module] FROM [t_object] WHERE [object_id]=" & id)

                    Dim strCon As String

                    strCon = "SELECT start_object_id, '<img src=images/' & t_object.stereotype & '.png >' as logo, connector_type as type, t_object.name as element FROM [t_connector], [t_object] WHERE [t_connector].start_object_id = t_object.object_id AND [end_object_id]=" & id

                    strCon += " UNION "

                    strCon += "SELECT end_object_id, '<img src=images/' & t_object.stereotype & '.png >' as logo, connector_type as type, t_object.name as element FROM [t_connector], [t_object] WHERE [t_connector].end_object_id = t_object.object_id AND [start_object_id]=" & id

                    strCon += " ORDER BY 2, 3 "

                    Me.ViewerList(strCon, "FrmDetail.aspx?module=element&id=", "<H2>Associaties</H2>")

                    Me.ViewerList("SELECT t_diagram.diagram_id, t_diagram.name as diagramnaam FROM [t_diagramobjects], [t_diagram] WHERE [t_diagramobjects].diagram_id = [t_diagram].diagram_id AND [t_diagramobjects].object_id=" & id & " ORDER BY 2 ", "FrmDetail.aspx?module=diagram&id=", "<H2>Weergegeven in diagrammen</H2>")

                    Me.ViewerList("SELECT object_id, filename as bestandsnaam, '<a target=_blank href=' & filename & ' >Open bestand</a>' as link FROM [t_objectfiles] WHERE [object_id]=" & id, "", "<H2>Gekoppelde bestanden</H2>")

                    Me.ViewerList("SELECT ID, name as naam, container as [afkomstig van], lowerbound as mincard, upperbound as maxcard, notes as toelichting FROM [t_attribute] WHERE [object_id]=" & id, "", "<H2>Attributen</H2>")

                    Me.ViewerList("SELECT propertyid, property as eigenschap, value as waarde, notes as toelichting FROM [t_objectproperties] WHERE property LIKE 'Vz%' AND [object_id]=" & id, "", "<H2>Extra items</H2>")

                    If ViewerFactoryHelper.IsDiscussieLid() Then

                        Me.ViewerList("SELECT ea_discussion_id, EA_DISCUSSION.datum, EA_DISCUSSION.onderwerp, EA_DISCUSSION.toelichting, '<a class=''ddbutton'' href=cmsForm.aspx?formid=50315&ea_discussion_id=' & ea_discussion_id & ' >Detail en Reageer</a>' as link FROM EA_DISCUSSION WHERE EA_DISCUSSION.element_id = " & id & " ORDER BY 1 DESC", "", "<h2>Gestarte discussies over dit element</h2>", ConfigurationManager.AppSettings("connectionstring"))

                        Me.ViewerHtml("<a class='ddbutton' href='cmsForm.aspx?formid=50301&element_id=" & id & "' >Start Nieuwe discussie over dit element</a><br>")

                    End If

                Case Else

                    MyBase.objSB.Append("Niet gevonden")

            End Select

            strRet = MyBase.objSB.ToString()

            Return strRet

        End Function

In the code you can see a number of statements in combination with a connectionstring. The sql statements are also very informative because it gives an idea of how the information is retrieved from the repository. The viewer functions like ViewerHTML are used to call the right formtype in the form factory engine.

Exporting diagrams

One of the powerful aspects of EA is the diagramming tool in combination with the relational database to store the information. Reason to re use the diagrams in the WPP, but how to export the diagram’s from EA to a file readable in a web application.

The automation or scripting interface of EA offered a solution that was easy to implement. We export all the diagrams to a png file in a certain folder on a disk and this folder is published over FTP to the implementation of the WPP application. The code to export the diagrams is given below (the script can also be found on the WPP website.

option explicit

!INC Local Scripts.EAConstants-VBScript

' WARNING Change this constant for your own Export Directory

public const DirName = "c:\testbert"

sub OnProjectBrowserScript()

                ' Get the type of element selected in the Project Browser

                dim treeSelectedType

                treeSelectedType = Repository.GetTreeSelectedItemType()

                ' Handling Code: Uncomment any types you wish this script to support

                ' NOTE: You can toggle comments on multiple lines that are currently

                ' selected with [CTRL]+[SHIFT]+[C].

                select case treeSelectedType

                               case otPackage

                                               ' Code for when a package is selected

                                               dim thePackage as EA.Package

                                               set thePackage = Repository.GetTreeSelectedObject()

                                               ExportDiagrams(thePackage)

                                               Session.Prompt "Diagrams exported to " & DirName, promptOK

                               case else

                                               ' Error message

                                               Session.Prompt "This script does not support items of this type.", promptOk

                end select

end sub

Sub ExportDiagrams(objPackage)

    Dim objProject as EA.Project

    Dim objDiagram as EA.Diagram

    set objProject = Repository.GetProjectInterface()

    For Each objDiagram In objPackage.Diagrams

        Repository.OpenDiagram(objDiagram.DiagramID)

        objProject.SaveDiagramImageToFile(DirName & "\" & objDiagram.DiagramID & ".png")

        Repository.CloseDiagram(objDiagram.DiagramID)

    Next

    Dim objChild

    For Each objChild In objPackage.Packages

        ExportDiagrams(objChild)

    Next

End Sub

OnProjectBrowserScript

The export diagram routine in the code does the job. We loop through a collection of diagrams in a package and each diagram is saved with the objProject.SaveDiagramImageToFile() method. The parameters and naming is connected to the naming convention in the WPP implementation.

The open source solution

For this WPP platform we decided to publish it as an Open Source Solution in the hope that a community of users will emerge to continue the development of this solution. This means that the code can be downloaded from the WPP website. This WPP website is by the way an example of a architecture repository view based on the form factory framework. It is actually a WPP publication of a sample repository in an eap file in combination with some extra information pages about the product.

More information

More information about the WPP is available at the WPP website: http://wpp.interactory.nl . Please subscribe to the community and use the material in your own situation. Also take part in the forums to report bugs or discuss new functionality. In the blog section I with regularly describe functionality etc. When you want to have more information about modelling in ArchiMate or the usage of architecture repository please contact me via the contact page of the wpp website.