Sparx EA: Embedding Diagrams within an Enterprise Wiki


Series Overview

I’ve been working a lot with Sparx Enterprise Architect and ArchiMate over the past few years, and although I am a big fan of formalized modelling using ArchiMate I’ve found myself frustrated with some of the limitations of the Sparx EA tool.

Over a small series of posts I’m intending to share a few of the tricks I’ve developed over time to address these frustrations.  These posts are fairly technical in nature, and address the usage of Sparx EA as an architecture tool, as opposed to the practice of defining the architecture itself.  The other posts in this series are below;

Problem Overview

Often, exposing the knowledge of an architecture stored within the Sparx EA model and making this available to other users within an organisation involves more than simply deploying the HTML extract and sharing a link.

For most organisations, the Sparx HTML extract isn’t the first place users would look for content about the architecture. In recent times it has become common for a lot of the general (non-structured) information about an architecture to be stored in an enterprise wiki, such as Atlassian Confluence.

This results in some complexity for an architect that is maintaining the architecture model and authoring diagram views in Sparx EA, but publishing the output to the enterprise wiki.  Specifically, there is no  alternative but to paste static diagram images from a point-in-time into the wiki. This solution is pragmatic, but images quickly fall out-of-synch as the model evolves.

Ideally it would be possible to embed content from the Sparx HTML extract directly in the wiki, however this also provides some challenges

  • Sourcing images from the Sparx HTML extract for the enterprise wiki is not practical, as the generated image filenames change each time the content is generated
  • Embedding Sparx HTML pages within an enterprise wiki is problematic, as the generated HTML relies on JavaScript and XML data sources. This causes technical challenges related to iframe script restrictions, and browser restrictions for cross-origin resource requests for XML files.

Approach

The solution I’ve been using for this problem relies on a bit of post-processing of the Sparx HTML extract files using PowerShell, to produce the following artifacts;

  • A copy of all diagram images, with the filename set to be the GUID of the diagram.
  • A new HTML file (without any reliance on JavaScript) to display the image and provide a click-through link to the correct (dynamic) diagram in the Sparx HTML site.

Within the enterprise wiki, an iframe can then be used to render the simpler HTML content for users. This has a few advantages over the use of screenshots;

  • Content is automatically updated in the wiki each time the Sparx HTML extract is generated
  • Users are encouraged to interact with the Sparx EA model more often, where they can discover more detail about the view being displayed

Implementation

The sample post-processing script can be downloaded from the following link;

To execute the function, simply provide the root location of the Sparx EA HTML extract as a parameter.

  • Process-SparxHTML -extractPath “C:\Temp\HTMLExtract”

Once the extract has been deployed, an iframe can be configured in a wiki to use the diagram pages created in the post-processing script, using the following url as the source.  The GUID needs to be replaced with the Diagram GUID (without the { } brackets) for the diagram you’d like to embed.

  • https://your.sparx.host/DiagramImages/GUID.html

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s