I heard @thomas.beale mentioning his wish to have diagrams generated directly from the computable specifications. This might enable him to skip using UML tools that he doesn’t like.
I’ve created a simple UML diagram generator and browser.
Sample class with enum:
Larger diagram:
You can also create your own custom diagrams:
(Recreation of “The Archetype Package Overview” found at specifications site)
Thanks to @pieterbos and @thomas.beale for helping me with AOM BMM files.
See more at NeoEHR
That is indeed interesting!
Some specific reactions:
Hash<String,EVENT_ACTION> in the TP spec. UML can’t understand this, and we use a trick to show it in the UML as a qualifier (the little box where it says ‘key:String’), and the UML exttractor inserts the ‘Hash<>’ into the output used in the specs.The above are mostly to do with (I think) on the fly diagram generation. Some of them are surprisingly readable, e.g. ENTRY. Obviously we could create a set of custom diagrams that would go close to mimicking what we have now.
Anyway, this is a first draft, and it’s lot better than PlantUML output the last time I looked at it. There might well be a path to leaving the UML tooling behind if this can be perfected a bit further.
@NeoEHR thanks for making the effort on this, it’s a great piece of work, and I think we should get everyone to have a look and think about how we might evolve our documentation in the future. In fact, a presentation to SEC would be a good idea, if you are prepared to do that.
(BTW, for the record I don’t mind using the MagicDraw UML tool - its one of the best tools around. The problem is UML itself, and well, tool licensing of course…).
Thank you for the feedback.I believe I can implement some of the improvements. It is not always PlantUMLs fault - it is the way I used it (or didn’t use it e.g. Grouping inheritance arrow heads).
I’ll list custom diagrams on the schema pages. I recreated the one I mentioned in less than 5 minutes. It is raw - without using hand written arrangement directions.
LOCATABLE is a good candidate for the custom diagram.
I’ll look into HashMaps. I’ve seen how they are used on the existing diagrams but didn’t have time to look for a solution.
p.s.
AsciiDoctor natively supports PlantUML diagrams.
I’ll be glad to present this to the SEC.
This is good stuff, I will certainly follow it’s progress! It looks promising.
Can those diagrams be embedded in a web page?
I do use UML a lot and sometimes the UML portal doesn’t have the best navigation for the models and some are difficult to find. .Software Engineering Portal
Other times I need 3 or 4 diagrams open at the same time, when working on mappings or creating tests, so opening several diagrams in the same canvas would be something nice.
Thank you @pablo!
Yes. These diagrams are generated as SVGs. They can also be generated as PNGs.
Edit: They are generated as PlantUML source files and turned into SVG to display on the site. PlantUML command line tool can be used to turn them into SVG/PNG in one call.
PlantUML diagrams are supported in most documentation tools (e.g. AsciiDoctor, GitHub,…)
These diagrams will not be able to compete for looks with hand crafted ones. But they will always beat them on speed.
The idea is to have most of the diagrams generated automatically and create custom diagrams for the important ones. Custom here means you list the classes you wish to include (one line per class as shown on one of the images on my site).
The advantage of custom diagrams is that the content (properties,…) of the included classes are re-generated if they change. No need to change the custom diagram for that.
Super cool: I might have a use case for those on my openEHR Toolkit https://toolkit.cabolabs.com/
I don’t really care much about looks, what it important for me is usability and correctness. I work hours a day navigating UMLs in the specs, which is painful, but if there is something that has all the UMLs and I can click an navigate, then get back, that would save hours of my life, literally!
For me the most common use case is: I need a diagram of COMPOSITION and it’s associated classes, then I need to navigate the model down to the DATA_VALUE (and subclasses), then I need to got up again in the hierarchy.
Another use case, which is a little more complex, is navigating the AOM and AOP alongside with the RM, knowing which classes of the AOM/AOP constraint which classes of the RM (which is useful for my current task of defining test cases for conformance of data validation). If you can link the two models AOM/AOP and RM, that would be magic!
Custom diagrams for me would be spreads with multiple packages in a single diagram, like a reference. There are some in the current UML site generated by Thomas, like:
COMPOSITION:
https://specifications.openehr.org/releases/UML/latest/index.html#Diagrams___18_1_83e026d_1433773264253_175551_6601
Keep it up!
I’ve added two new handcrafted diagrams:
I took some liberty in grouping classes closer together.
I didn’t get Grouped inheritance arrows working.
I will also have to leave HashMaps as they are. There is no element in PlantUML to add the “key” box to a class. The “key” part is already shown as part of the HashMap<String,…> so no information is lost compared to the original.
I’ve also fixed showing enumerations with ancestors. Well there is only one at the moment.
Apart from the colour scheme, which I’m not mad on, that’s really pretty good - and you managed to get the notes as well!
Now, just a reality check on doing this as a real replacement for the current UML… we would need to solve:
- I’m sure some later PlantUML version will solve thisSo I would suggest that we see this as a 6month+ project to get to actual replacement, which I am starting to think would be possible. Which gives the community some time to get used to the new approach and new possibilities - e.g. diagrams on the fly outside the specs is an interesting possibility.
In the mean time, we could maybe home in on a visual style we like. One personal preference I have, which is in the current UML, is that inheritance lines are a light colour, while association/composition lines are dark. This emphasises structure over inheritance. In PlantUML it is obviously easy to play with all these styles.
Once again, great work…
OK. I switched the styles.
Will we need to generate diagrams with different color themes 
It goes without saying that others should have their say on visual styles - I was just stating this particular one because it has a reasonably obvious impact on diagrams…
It was painful to use the right relative paths for the “!include” statements in the handcrafted diagrams. So I simplified it to only require to specify the class name.
Old:
New:
I also simplified how the relationships are specified. Line coloring is added during the processing.
Would some other custom diagrams from the original specifications be helpful to anybody?
Or you can follow the above example and write your own. Send it to me and I will add it to the site.
One diagram with all the data types 
Data types and Data types with packages.
Maybe AOM constraints diagram will be helpful too.
Enjoy the diagrams @pablo.
And I simplified how relationship are specified. You don’t have to specify them at all 
Generator figures them out from what is included in the diagram.
New version of “Archetype Overview” is now:
Can it be any simpler?
Good stuff Borut!
Just noted the DV_INTERVAL is not showing lower/upper fields.
Thank you for reporting this.
DV_INTERVAL doesn’t have these fields but the diagram is missing its ancestor “Interval” where these fields are.
I have published a fix.
The generator doesn’t include “simple types” to keep the diagrams smaller.
There is an exception to this rule: if a simple type inherits from another simple type then the ancestor is included.
DV_INTERVAL is not a simple type and “Interval” is. I had to add a “+” to the DV_INTERVAL include line to tell the generator to include a simple type ancestor for it:
include dv_interval +
Please let me know if you find another such class.
Those foundation types are tricky 
All the diagrams for AOM 2.0.6, AOM 2.1.0, AOM 2.2.0, AOM 2.3.0 are now published.
I added many new features and fixes so that the diagrams are as informative as possible.
Thanks to @thomas.beale for writing the AOM BMM files.
@thomas.beale, perhaps already discussed this, but before we generate .adoc or .svg from BMM, we’ll also need to port all descriptions from current UMLs to BMMs.
@NeoEHR nice work!
Right - there is a fair bit of work to do all this properly. One part is making a new UML extractor output stage to generate BMMs; currently we only generate out adoc files, although it is pretty much all the same info.
