I discovered and fell in love (a bit) with Markdown whilst working for the University of Sussex. My previous employer (which is now my current employer, long story) used Google Drive/Docs, and the University subscribed to Office 365. I ended up getting particularly frustrated with having to go back and use Microsoft Word, so decided to go back to basics (plus, Markdown feels techy, and I miss being a “proper” techie). Markdown allows you to style and structure a plain text file, it’s a useful tool to write in a simple way, concentrating on the content, not the design. I use Microsoft Visual Code Studio to write/preview Markdown, although other editors are available.
JArchi is the scripting language for Archi, the open source, open implementation of the ArchiMate language. Users can download JArchi by supporting Archi on Patreon. It allows a user to develop JavaScript like scripts to interact with an Archi model.
I had been looking at how I can produce documentation directly from Archi, rather than have to copy and paste and manually write the documentation, and was exploring what I could achieve when combining Markdown, Archi and JArchi.
I have developed a JArchi script to Export to Markdown, and have uploaded this to GitHub Gists.
Currently sitting at version 3.4 (at the time of writing this), this script will:
- iterate through each element added to a view to build a table of contents,
- export a PNG,
- include the content of any “note” elements which don’t have relationships to other elements as an Introduction
- iterate through each element (again) to:
- use the name of the element and it’s type as a header
- build a table of all properties on the element,
- build a table of all relationships on the element, their types and hyperlinks to their related elements (as well as name and documentation on the links),
- include the element’s documentation,
- include any related “note” elements as quotes and then
- iterate through any nested elements.
- prompt the user to save the files in a location of their choosing.
It’s probably (definitely) not the most efficient code out there, but it does the job! Hopefully others may find it useful.
Example Output
Export to Markdown[^1]
- Introduction
- Export to Markdown.ajs <<Script>> (Artifact)
- [archi] jArchi Plugin (Application Function)
- jArchi Plugin <<Software>> (Artifact)
- [archi] Export to Markdown (Application Function)
- Microsoft VSCode (Application Component)
- MS VSCode <<Software>> (Artifact)
- Automatic documentation generation (Goal)
- Support Archi on Patreon (Requirement)
- Documentation <<Folder>> (Artifact)
- Core Archi (Diagram Model Group)
Introduction
Export to Markdown: JArchi Script Example
Export to Markdown.ajs <<Script>> (Artifact)
Relationships
| From | Relationship | To | Name | Description |
|---|---|---|---|---|
| Export to Markdown.ajs <<Script>> | Realization Relationship | [archi] Export to Markdown (Application Function) |
C:\Users\steve\AppData\Roaming\Archi4\scripts\Import-Export\Export to Markdown.ajs
Can be downloaded from Github Gist:
[archi] jArchi Plugin (Application Function)
Properties
| Website | Licence |
|---|---|
| https://www.archimatetool.com/blog/2018/07/02/jarchi/ | Open Source (HUMANS) |
Relationships
| From | Relationship | To | Name | Description |
|---|---|---|---|---|
| [archi] jArchi Plugin | Composition Relationship | [archi] Export to Markdown (Application Function) | ||
| [archi] jArchi Plugin | Influence Relationship | Support Archi on Patreon (Requirement) |
jArchi is a JavaScript-based scripting plug-in built on the Nashorn engine. This means that the end-user can write code, or simple scripts, using JavaScript, and this is then translated into the underlying Java code that drives Archi.
jArchi Plugin <<Software>> (Artifact)
Relationships
| From | Relationship | To | Name | Description |
|---|---|---|---|---|
| jArchi Plugin <<Software>> | Realization Relationship | [archi] jArchi Plugin (Application Function) |
C:\Program Files\Archi4\plugins\com.archimatetool.script.commandline_0.4.3.201902121146.jar C:\Program Files\Archi4\plugins\com.archimatetool.script.premium_0.4.1.201902121146.jar C:\Program Files\Archi4\plugins\com.archimatetool.script_0.4.3.201902121146.jar
[archi] Export to Markdown (Application Function)
Properties
| Website | Licence |
|---|---|
| https://gist.github.com/smileham/578bbbb88dc0ed5a1403f3b98711ec25 | Open Source |
Relationships
| From | Relationship | To | Name | Description |
|---|---|---|---|---|
| [archi] Export to Markdown | Access Relationship | Export to Markdown.md <<Markdown>> (Artifact) | ||
| [archi] Export to Markdown | Access Relationship | Export to Markdown.png <<Image>> (Artifact) | ||
| [archi] Export to Markdown | Influence Relationship | Automatic documentation generation (Goal) |
Microsoft VSCode (Application Component)
Properties
| Website | Licence |
|---|---|
| https://code.visualstudio.com/ | Open Source (MIT) |
Relationships
| From | Relationship | To | Name | Description |
|---|---|---|---|---|
| Microsoft VSCode | Access Relationship | Export to Markdown.md <<Markdown>> (Artifact) | ||
| Microsoft VSCode | Access Relationship | Export to Markdown.png <<Image>> (Artifact) |
Visual Studio Code is a streamlined code editor with support for development operations like debugging, task running and version control. It aims to provide just the tools a developer needs for a quick code-build-debug cycle and leaves more complex workflows to fuller featured IDEs.
MS VSCode <<Software>> (Artifact)
Relationships
| From | Relationship | To | Name | Description |
|---|---|---|---|---|
| MS VSCode <<Software>> | Realization Relationship | Microsoft VSCode (Application Component) |
C:\Program Files\Microsoft VS Code
Automatic documentation generation (Goal)
Support Archi on Patreon (Requirement)
Only supporters of ArchiTool on Patreon can access the binary download of the jArchi plugin (as well as other exclusive content)
Documentation <<Folder>> (Artifact)
Relationships
| From | Relationship | To | Name | Description |
|---|---|---|---|---|
| Documentation <<Folder>> | Composition Relationship | Export to Markdown.png <<Image>> (Artifact) | ||
| Documentation <<Folder>> | Composition Relationship | Export to Markdown.md <<Markdown>> (Artifact) |
Local folder to store EA documentation.
Export to Markdown.md <<Markdown>> (Artifact)
Markdown formatted documentation of the Export to Markdown Archi view.
Export to Markdown.png <<Image>> (Artifact)
PNG format image of Export to Markdown Archi view.
Core Archi (Diagram Model Group)
Develop Enterprise Architecture Model (Business Process)
[archi] Archi 4.3.3 (Application Component)
Properties
| Website | Licence |
|---|---|
| https://www.archimatetool.com/ | Open Source (MIT) |
Relationships
| From | Relationship | To | Name | Description |
|---|---|---|---|---|
| [archi] Archi 4.3.3 | Assignment Relationship | [archi] jArchi Plugin (Application Function) | Plugin | |
| [archi] Archi 4.3.3 | Serving Relationship | Develop Enterprise Architecture Model (Business Process) |
Archi fulfils the needs of most Enterprise Architects and associated stakeholders, and has been designed to elegantly provide the main features required for ArchiMate modelling and is used globally by banks, insurance companies, industry, EA consultants, training organisations, universities, and students. It is the world’s most popular ArchiMate modelling tool and is downloaded between two and three thousand times every month.
Desktop Computer (Device)
Relationships
| From | Relationship | To | Name | Description |
|---|---|---|---|---|
| Desktop Computer | Assignment Relationship | Archi 4.3.3 <<Software>> (Artifact) | ||
| Desktop Computer | Assignment Relationship | jArchi Plugin <<Software>> (Artifact) | ||
| Desktop Computer | Assignment Relationship | Export to Markdown.ajs <<Script>> (Artifact) | ||
| Desktop Computer | Assignment Relationship | MS VSCode <<Software>> (Artifact) | ||
| Desktop Computer | Assignment Relationship | Documentation <<Folder>> (Artifact) |
A device is a physical IT resource upon which system software and artifacts may be stored or deployed for execution. — ArchiMate 3
Smileham: The usage of ArchiMate and Archi models should be derived from the questions that you want to answer. When I first began modelling, I wanted to seperate the logical server (node) from the physical or virtual server (device) on which they were executing. This seperation allows an architect to query the model to find where all particular makes/models/configurations of physical devices are used in the architecture.
Archi 4.3.3 <<Software>> (Artifact)
Relationships
| From | Relationship | To | Name | Description |
|---|---|---|---|---|
| Archi 4.3.3 <<Software>> | Realization Relationship | [archi] Archi 4.3.3 (Application Component) |
C:\Program Files\Archi4
[^1]: Generated: Sat Mar 09 2019 19:56:49 GMT+0000 (GMT)
Nice work. Thanks for sharing!
Phil
LikeLike