Listing all articles in The Residual World under the category 'Tools' :

What Would a TRAK View Look Like in a Graph Database? Part 1

by Nic Plum on Monday 31 August, 2015 - 15:38 GMT

Posted in Architecture FrameworkTRAKStandardsTools

Tags: complianceconformancegraphiso42010standardtraktripletuple

The trouble with using a lot of the enterprise architecture tools is that they were originally developed for software development. This means that they tend to focus on / provide functionality for the expression of objects rather than relationships and they typically use software notation to describe the relations, for example the UML. If you are primarily interested in relationships it is then quite hard to exploit and query the relationships. There is also the inevitable problem with the readability of the result particularly for the non-technical and non-software audience who haven’t grown up with, say, UML Class diagrams.

TRAK is defined in a solution-agnostic way and specifies that all the relationships must be 1) visible; 2) labelled so that the assertions / tuples can be read as simple sentences e.g.

  • System. A is configured with B. Software, or
  • Argument. D supports Claim. Y

This means that it is easer to read. It is still up to the implementer and the notation (an Architecture Description Language in ISO/IEC/IEEE 42010 terminology) how this appears when visualised. You might, for example, get the following. A UML Representation of a TRAK Tuple

This isn’t too bad to read thanks to the TRAK requirements to make everything explicit but if you want to follow relationships and display the results you typically have to dive under the hood create a query that has multiple table joins. Even then the result is a table which isn’t the best way of presenting a structure. If you wanted to recurse down a structure to display something and its parts you might not be able to do this without knowing how many levels you needed to traverse to retrieve the results.

It soon gets all too difficult which is a shame because having created the relationships the real power over a ‘flat’ diagram is the ability to query them to answer questions.

Is there another way? In a nutshell, yes. A TRAK view is defined as a set of assertions / tuples / triples. In mathematical terms these are ‘graphs’ and now you can get graph databases that store graphs rather than tables. It’s therefore a straightforward exercise to create a TRAK view in a graph database using the governing TRAK viewpoint (which constrains what tuples can be shown) and the TRAK metamodel as the ‘domain model’ for reference.

I’m in the process of evaluating the free community edition of the Neo4J graph database. The plan is to create a complete architecture description within Neo4J to show how it might look as a set of graphs. Neo4J is pretty straightforwards and the reference manual, online training and free e-books are valuable. I wanted to produce the equivalent of a TRAK architecture description that is already online so I’m porting the one that was used to support the formal conformance assessment of TRAK against ISO/IEC/IEEE 42010:2011.  This particular TRAK architecture description makes a lot of use of the MVp-04 Assurance Viewpoint since it describes a structured set of claims (of compliance), arguments and evidence.

This has been achieved using the CSV import capability of Neo4J to import the elements and their properties. For example the import of the TRAK requirement elements was achieved using:

LOAD CSV WITH HEADERS FROM “file:///requirements.csv” AS row
CREATE (n:Requirement)
SET n = row,
n.`object ID` = toInt(row.`object ID`),
  n.`AD exchange element owning ID` = row.`AD exchange element owning ID`,
  n.`AD exchange element owning organisation`=row.`AD exchange element owning organisation`,
  n.`reference URL` = row.`reference URL`,
  n.`sequence ID`=toInt(row.`sequence ID`),
  n.`requirement ID`=row.`requirement ID`,
  n.`compliance level` = row.`compliance level`,
  n.`requirement paragraph` = row.`requirement paragraph`,
  n.`requirement scope` = row.`requirement scope`,
  n.`requirement type` = row.`requirement type`,
  n.`requirement priority` = row.`requirement priority`,
  n.name = row.name,
  n.description = row.description,
  n.`requirement owning org` = row.`requirement owning org`,
  n.`element author`= row.`element author`,
  n.`created date` = row.`created date`,
  n.`modified date` = row.`modified date`
SET n :Requirement:`Architecture Description Element`

CREATE CONSTRAINT ON (reqt:Requirement) ASSERT reqt.`object ID` IS UNIQUE

All the different TRAK metamodel elements have been imported similarly and connected together, e.g.

LOAD CSV WITH HEADERS FROM “file:///claim_about_requirement.csv” AS row
MATCH (claim1:Claim {`object ID`: toInt(row.Start_Object_ID)})
MATCH (reqt1:Requirement {`object ID`: toInt(row.End_Object_ID)})
MERGE (claim1)-[r:`about`]->(reqt1)
ON CREATE SET r.`connector ID` = toInt(row.`connector ID`);

CREATE CONSTRAINT ON (conn:`about`) ASSERT conn.`connector ID` IS UNIQUE

TRAK also has elements to represent Architecture View so its easy to relate the elements and the connectors to the view(s) that show them.

In Neo4J queries match patterns (think of these as paths through the underlying architecture description - the sets of tuples). Suppose for example I want to show the structure of the standard itself. Off the top of my head I don’t know how deep the structure is but this doesn’t matter since the Cypher query language allow me to recurse to the bottom.

The query to show the requirement structure is simply:

MATCH (a:Standard {name:'ISO/IEC/IEEE42010:2011 Systems and Software Engineering - Architecture Description'})
MATCH (a) -[r:`has part`*1..]->(b)
RETURN a,b, r

which simply tells Neo4J to start with the topmost node - a TRAK ‘Standard’ and then look for all the outgoing ‘has part’ relationships for as many levels as needed and then return the nodes and relationships. The result of this is shown below.

Equivalent TRAK MV-03 - Structure of ISO/IEC/IEEE 42010:2011 (Partial)

Display full size image.

Finding orphan nodes with no relationships is as simple as:

MATCH (node)
WHERE NOT ((node)—())
RETURN node;

It’s not yet TRAK-compliant. I’ve still got to figure out how to get the cascading style sheet to display the TRAK metamodel element type (‘label’ in Neo4J) but it’s already a very useful tool to exploit the relationships made. This is with Neo4J out of the box as a bare database i.e. with no application built on top of it. It ought to be relatively straightforwards for a software engineer to extend this to implement the TRAK viewpoint definitions and visually query the database. Or I should add that it is if you’ve got a simple and explicit metamodel because it’s easy to square this with the graphs produced. If all you’ve got is a more indirect and complicated one enforced via a UML profile it’s a much harder task and you can’t then easily verify the result against the original views in the modelling tool.

Comments

Comment on this article

Improving Consistency for Tools - ‘TRAK. Implementation. Architecture Description Elements’ Document

by Nic Plum on Monday 05 September, 2011 - 15:03 GMT

Posted in Architecture FrameworkTRAKTools

Tags: architecture descriptionconsistencydocumentexchangeimplementsolutionstandardtool

There is a constant need to reduce the scope for inconsistency in any architecture description. TRAK is no different. TRAK has been defined in a way that is free of implementation and using natural language wherever possible. One of the pitfalls of this is the possibility that names will be implemented inconsistently in tools. For example, the attribute ‘start date’ might be called ‘start date’, ‘start_date’, ‘startDate’, ‘Start Date’ and so on. The danger in this is that upon exchange the receiving tool might not recognise this if it is using, say, ‘startDate’.

I’ve therefore created a document titled ‘TRAK. Implementation. Architecture Description Elements’. To put it into context a couple of diagrams (produced using the OmniGraffle stencil for TRAK):

Context - the TRAK. Implementation. Architecture Description Elements documents is part of the set of documents that improves consistency of exchange of an AD

The TRAK. Implementation. Architecture Description Elements Document is Part of the set of Documents that Improves Consistency of Exchange of an Architecture Description

The TRAK. Implementation. Architecture Description Elements document responds to the logical TRAK Metamodel definition.

The TRAK. Implementation. Architecture Description Elements Document Responds to the Logical Definition of the TRAK Metamodel

The document is at http://sourceforge.net/projects/trak/files/Implement%20TRAK/

The purpose of this document is therefore to standardise the naming of the architecture description elements used in any implementation of TRAK, whether graphical or text-based.

In addition to naming this document also specifies the formats used for attributes such as text, language labels, geographic location and uniform resource identifier. It also identifies the allowed values where an enumerated list specified for an attribute.

None of this guarantees successful exchange - in a UML modelling tool there will be an extra wrapping applied through XMI which might be at a different version in the sending and receiving tool and in addition even if an element has the same name it might mean something completely different in each. This document is therefore one part of a set of normative measures needed to maximise the chances of successful interoperability between a pair of tools.

There are a couple of things still left to do, not the least of which is figure out how to specify privacy marking / security descriptor schemes. If anyone knows of any good standards-like sources for these please let me know.

Any constructive comments via the Sourceforge Tracker set up for implementation of TRAK at https://sourceforge.net/tracker/?group_id=393432&atid=2376222

Comments

Comment on this article

Forums

Things that You Think That Are Going to be Simple Never Are

by Nic Plum on Friday 19 August, 2011 - 14:48 GMT

Posted in Architecture FrameworkTRAKTools

Tags: applescriptapplicationbugdevelopdrawingimplementipadmacomnigraffleopensourcesourceforgestencilsupporttooltrak

This is a bit of a tale, and not an unusual one at that. It concerns the development of a stencil for the Omni Group’s OmniGraffle drawing application which is available for both Mac and iPad. I’m a long time user of OmniGraffle Pro (at least 8 years) as well the the Mac (still have my original Mac Iici working) and OmniGraffle is just an easy to use and intuitive means of producing good drawings. All of the stuff in the defining TRAK documentation is produced using it.

Anyway, thought it might be an idea to have a stencil of the stereotypes and relationships to be able to knock up a quick TRAK architecture view when I felt it merited it (rather than firing up a bigger modelling tool such as Sparx Enterprise Architect). It’s all about horses for courses.

The OmniGraffle Stencil for TRAK Implements the TRAK Definition

The OmniGraffle Stencil for TRAK Implements the TRAK Definition

The Beginning - Fumblings

Not knowing anything about developing a stencil I simply created the blocks needed for the TRAK views and added a set of connectors for the relationships having labelled them. Then I discovered on loading the stencil that OmniGraffle presents the bare connectors separately from the labels for those connectors so there were many connectors in the stencil all seemingly the same. Started again. This time I just had 2 connectors and a text label for each relationship. This cut down the noise but I discovered that on the iPad version it wasn’t easy to use these as it didn’t seem to allow you to drag the label onto the connector and for the 2 to remain locked together as it would do on the desktop version. Started again. This next version had separate connectors, each with it’s own label but this time I grouped the label with the line and this indeed stopped the stencil from displaying them separately.

Sharing

Now I felt I was starting to get the hang of it. The obvious choice was to lodge this onto Sourceforge with all the other TRAK stuff so I created a new project (trakomnigraffle) and then discovered the front end of Sourceforge had changed so much I no longer knew where to go to do what in setting it up. This looks to be a consequence of security and an earlier attack on Sourceforge this year. Then I remembered GraffleTopia. This is a site that holds stencils and templates for OmniGraffle. Even better it’s moved on apace such that when looking for a stencil in OmniGraffle, including the iPad, it will display results from GraffleTopia for download/installation. Sounds good so I duly submitted the stencil. It appeared last Friday on the 12th August so very pleased. The ability to see how many downloads is nice. Sure enough I found it does appear within the desktop and iPad versions and you can download it from the iPad version. For whatever reason it throws an error in OmniGraffle Pro when you select it for downloading. I then had to spend time submitting a bug report.

I know that OmniGraffle supports user data in terms of a set of keys and data values. It seemed therefore sensible to implement the attributes for the various elements in the TRAK metamodel. This would allow more information to be captured and it looked likely to offer a path through which a XML export could be produced with these which would allow a sensible conversion or import via XMI into a UML modelling tool. I then updated the stencil so that each object has the right set of attributes. Great - making progress! I then update the Sourceforge site and go to the GraffleTopia site to upload the new version only to find that it doesn’t support the workflow involved with an update -

it’s a new stencil or nothing. Great - now I’ve got an older version that’s easier to find within the tool than the current master. In response I sent an email to the site owner but it was clear this wasn’t going to change overnight. Not quite as I’d hoped.

Update: Have now found the link to edit and resubmit new versions of the stencil so can only assume it was stupidity and/or blindness on my part. The good news is that GraffleTopia and Sourceforge are in sync!

More Ideas, More Problems

Having all these attributes as user data is good. Trouble is I then thought it’d be nice to be able to copy the attributes and perhaps the values from one object to another. No problems - this is a job for AppleScript (a venerable but very useful scripting technology that operates across the Mac platform and has done so for many many years) which could automate this. Luckily I have a decent debugger but even so it wasn’t going well owing partly to ignorance or forgetting things on my part not having used it for a while. I had to call on support from the ‘Support Ninjas’ at OmniGraffle and each time I’ve managed to move it forwards. I’ve now got to the stage where I can populate a set of shapes with a set of TRAK attributes. Even better it recognises if there is a key with data that exists and asks whether it should continue and wipe this data out for that key or just skip this item. You can see it’s getting ever more complicated which I suppose is the penalty for user-friendliness. Unfortunately it hit a problem when testing for a key name that doesn’t exist. After another response from the OmniGraffle Support Ninjas it seems there is a bug with the AppleScript object in OmniGraffle which causes it to return an undefined object and causes a runtime error. I have been directed to a workaround but it’s going to take a while to get my head around this.

Then it occurred to me that it’d make sense to have the type shown on the object to be determined from a key labelled ‘stereotype’ within each object. This way I wouldn’t be dependent on someone spelling the type correctly. I found that you can then display the value using the string <%UserData stereotype%> which then means by setting the value of this user data key it’s easy to change the type displayed to the user. I knew that only the Pro version supports the editing of these user data keys but had been assured by the OmniGraffle Support Ninjas that whilst the iPad and plain OmniGraffle applications couldn’t edit them they wouldn’t strip them out. But could they understand them?

Yes and no it seems. OmniGraffle behaves as OmniGraffle Pro does in that you can see the type names in the stencil and on the drawing canvas. OmniGraffle for iPad however doesn’t parse the user data whilst displaying the stencil and the result was 30-odd objects having no visible type only the <%UserData stereotype%> string. Not good!  Of course for the iPad you don’t have a mouse only fingers and therefore you can’t hover a finger and therefore I had no tool-tip text to save the day. The iPad application does, however, parse the user data and display the object type when you drop it onto the drawing canvas.The desktop versions display a tool-tip for the type or the relationship name making it easy to pick the right thing. Up until this point you’re just guessing. Sent another support request to the OmniGraffle Support Ninjas pointing out this inconsistency. In doing so I discovered that OmniGraffle doesn’t, for whatever reason, display the tool-tip text on mouse-over an object. Added this to the support request.

Update: iPad version failing to parse/display user data whilst object is in the stencil is now a confirmed bug. OmniGraffle not displaying note content as a tool-tip on mouse-over has been raised for debate within the OmniGraffle development team.

What to do in the meantime? I didn’t want to have to produce a second template just for the iPad. Equally I wanted to make use of the stereotype key to keep things consistent. In the end I added a workaround of changing ‘Name’ on each object to things like ‘a system’, ‘an architecture task’ so that there was again visibility of the object type.

The net result shown in the iPad is:
The OmniGraffle Stencil for TRAK - shown in an iPad

OmniGraffle Stencil for TRAK Available for Use on an iPad

Where Are We Then?

The OmniGraffle Stencil for TRAK provides objects with which to construct TRAK architecture description views

OmniGraffle Stencil for TRAK Provides Objects With Which to Construct TRAK Architecture Description Views


The OmniGraffle Stencil for TRAK provides:

  • a set of graphic objects corresponding to the TRAK metamodel stereotypes
    • each graphic object has the TRAK attributes (editable in OmniGraffle Pro)
  • a set of connectors corresponding to the TRAK metamodel relationships
  • a drawing identification / version box
  • available for Mac and iPad platforms
  • downloadable within the OmniGraffle application itself - but see below
  • available on GraffleTopia

The latest version of this is always on the Sourceforge trakomnigraffle project site. The GraffleTopia version is at version 1 still.

When I solve the problems with AppleScript there will then be an easy means to:

  • copy and pasted an object’s attributes (with no value)
  • copy and paste and object’s attributes and their values

Of course any drawing application has limitations when it comes to architecture description since it’s hard to keep it consistent and to enforce or check things like correct relationships being made. It is, however, a useful step and a useful addition to the family of implementations of TRAK and with more work should provide a migration path into a dedicated modelling tool. It has it’s place. As with TRAK it has just to be good enough or adequate - we’re not aiming for perfection!

It has, however, taken a lot, lot longer than I’d originally thought.

 

Comments

Comment on this article

All articles/posts © of the respective authors

Site design and architecture © 2010 - 2011 Eclectica Systems Ltd.