-
Notifications
You must be signed in to change notification settings - Fork 4
UML (webSequence PlantUML)
ITI has used WebSequence to draw up some UML sequence diagrams. When we did this we would save the source we used in a text box in the word / pdf document under the Figure. We would export a PNG from Websequence web tool and paste that into the document. By saving the source inline, we assured the source would not get lost and would be there for us if we needed to adjust the figure. We figured exposing the code to the reader was not a problem, but it was not necessarily the goal.
We chose to extract out the source text and save that in the media folder, and save a high fidelity image from a UML tool in the media folder.
We chose to use PlantUML, as that is as standardized UML language (useful for many UML diagrams, not just sequence diagrams). WebSequence is close, but slightly different. This means that when taking what was WebSequence, we must adjust it a little.
The filename extension for the PlantUML script will be ".pu" (alternative is ".plantuml". we just chose the shorter one).
We include a link by the figure to the .pu file with the PlantUML script. We could have shown the script in a box, but we decided that benefit is not as helpful as the link. We might one day automate the rendering of the graphic from the PlantUML script, but at this point in the project there is little to be gained by that automation, and that automation would add a quality risk and a reliability risk. By rendering the graphic by hand during authoring we have a persistable graphic that is reliable.
- online tool for rendering diagrams from PlantUML code http://plantuml.com/plantuml
- good details on PlantUML syntax with examples https://plantuml.com/sequence-diagram
Given the pattern we have chosen for graphics is "Figure_" followed by the figure number and dash. Thus Figure 26.4.2.4.2-1 would create two files in the media folder
media/Figure_26.4.2.4.2-1.pngmedia/Figure_26.4.2.4.2-1.pu
This is likely not complete, just notes from what we needed at the time.
example: Volume1/ch-26 -- Figure 26.4.2.4.2-1
The original webSequence script needs the following fixes
- Add "@startuml" as the first line of the text script
- Add "@enduml" as the last liine of the text script
- Replace where we used the webSequence feature of the "->+" with the plantUML feature of a double plus "++" after the actor to be activated.
participant "Document \n Metadata \n Notification \n Recipient" as recipient
subscriber->+notificationbroker:Subscribe
deactivate notificationbroker
...
with
@startuml
participant "Document \n Metadata \n Notification \n Recipient" as recipient
subscriber->notificationbroker++:Subscribe
deactivate notificationbroker
....
@enduml
we chose to remove the UML code from the html, and include a "note" link to the UML code for download from the media folder. Therefore we remove the inline websequence code (the example below had that websequence code inside a table, others might be rendered differently.)
where before we have
<h5 id="26.4.2.1.2">26.4.2.1.2 Unexpected Notification Process Flow</h5>
<img src="media/slfjsdlf-lsjfls.png" alt="" />
<p class="figureTitle">Figure 26.4.2.1.2-1: Interaction Diagram for Unexpected Notification Use Case</p>
<table cellspacing="0" cellpadding="0">
<tr>
....
we change it to
<h5 id="26.4.2.1.2">26.4.2.1.2 Unexpected Notification Process Flow</h5>
<p class="figureTitle">
<img src="media/Figure_26.4.2.1.2-1.png" alt="" />
Figure 26.4.2.1.2-1: Interaction Diagram for Unexpected Notification Use Case
</p>
<p class="note">
<a href="media/Figure_26.4.2.1.2-1.pu">UML source for Figure 26.4.2.1.2-1</a>
</p>
Note that the IG publisher can automatically render PlantUML. It requires that the plantuml file be saved in the image-source folder as a .plantuml (yes, it prefers the long extension).
To get the image of the plantuml to show up in your html, you just call for the SVG
<div>
{%include usecase1-processflow.svg%}
</div>
<div style="clear: left"/>