The ScopeSET Support and Community Portal
         
View all tags
Tags:    No tags associated yet.

HowTo generate Wikis and integrate them with JSPWiki

Overview

This guide outlines how to export Wikis from OpenaAmeos and integrate them with JSPWiki. Notable features are
  • navigable diagrams
  • support for JSPWiki's change tracking

In this guide, we assume that you have a properly configured Tomcat and JSPWiki and you have access to the filesystem it is installed on. To simplify matters, we further assume that Tomcat is installed on the same machine as OpenAmeos (in this guide C:\Tomcat6.0), although this is not a precondition. If it is not, you need to manually copy the generated files to the proper location on the Tomcat server machine. Better yet, mount the JSPWiki data directory onto the machine which generates the Wiki pages.

Preconditions

We presently use raw HTML code to embed SVGs into Wiki pages. Raw HTML needs to be enabled in C:\Tomcat6.0\webapps\JSPWiki\WEB-INF\jspwiki.properties:

jspwiki.translatorReader.allowHTML =true 

Since we assume that most wikis for this purpose are served on an intranet, the security issue of allowing raw HTML should be negligible.

Additionally, the diagrams need to be served from a defined URL, in this guide, we generate the diagrams into C:\Tomcat6.0\webapps\svg - by doing so, the svg directory contents are automatically served by Tomcat. If you don't want to have user generated content in the Tomcat path, you can put them into any other directory which is available through http. Make sure that the IMG_URL parameter in the Wiki template is set accordingly (see below).

Generating the diagrams

In the OpenAmeos script manager, go to Documents -> Product Scripts -> Reports -> All_Diagrams.

  • Set the Export  format to SVG, the Target_Directory to C:\Tomcat6.0\webapps\svg, the PNG_Width parameters are irrelevant for SVG.
  • For InternetExplorer, set the Export format to PNG, IE does not support native SVG embedding.

Generating the wiki pages

Next, go to  Code -> Product Scripts ->Languages -> JSPWiki.

  • Set the General/Output to parameter to the path which serves your wikis, i.e. C:\Data\JSPWiki, this needs to correspond to your jspwiki.fileSystemProvider.pageDir parameter in jspwiki.properties.
  • Set the IMG_URL parameter either to a full or relative URL by which the SVGs can be accessed. In our example, we can set it to ../svg.
  • Finally, set the IMG_WIDTH to an appropriate pixel value, i.e. 1000 and run the script.

Accessing and changing wikis

Your wiki pages should now be accessibly through a URL like http://localhost:8080/JSPWiki/Wiki.jsp?page=Main - note that OpenAmeos does not generate the main page because this will most likely be a manually edited introduction page. The left sidebar does however show the basic pointers into the content of the current wiki structure.

Note that the diagrams are navigable, clicking on a class brings up the corresponding page.

Assuming that after a while, you have the changed the model a bit you will then regenerate the wiki into the same directory. The generator's merger will then automatically create new  JSPWiki page versions for those pages which have actually changed. This means that you can track model changes through JSPWiki's change log mechanism.

CB:/displayDocument/JSPWikiChangeTable.png?object_comment_id=44

If you generate into a local directory which is then copied to a server, make sure you always generate into the same directory, don't modify that directory manually and copy the entire directory to the server, overwriting any content there. If you manually modify the wiki on the server, you cannot copy. In this case, you need to mount the servers directory onto the machine which generates the wiki so that the generators merger can handle the modifications.

CodeBeamer integration

JSPWiki pages and diagrams can also be uploaded to a CodeBeamer server (an example is the ACD metamodel wiki). In this case, the upload is implemented by a Java application which utilizes CodeBeamer's API. Similar to JSPWiki this also allows the tracking of changes in a model based on the diffs on the generated wikis. Please contact us for further details on the CodeBeamer integration.

Limitations

  • Presently, the SVG embedding should work in most browsers, except in InternetExplorer. For IE, set the IMG_TYPE in the JSPWiki template to PNG
  • The content of the Wiki is currently limited to class modeling, the template (see templates\uml\tdl\Languages\JSPWiki) can be easily extended.
  • The merger does not handle deletes or renames, i.e. although a page may no longer be linked, it might still appear from a search result. Renames will appear as new pages, leaving the old pages still in the filesystem

Future enhancements

We plan to provide functionality which allows to edit certain sections in a wiki (i.e. textual descriptions) and load them back into an OpenAmeos model. The objective is not to modify a model structurally through a wiki, but primarily changing exiting texts or adding comments.

At this time, the wikis already contain pseudo-blocks which tie a text to its source object ID in the model. The current idea is to parse the wikis, extract changed text and use the ID to put it back into the model. We're open to ideas and suggestions how to improve the editing usability on the Wiki side (i.e. how to better show what can be edited and what cannot).

Credits

The wiki export templates were originally contributed by EADS Astrium.