Camunda to ASCIIDoctor documentation generator

Community Community Extensions
1

Hello my name is John Schuster,

I’m working on a Pet project. I would like to generate ASCIIDoctor markdown documentation from the BPMN file.

Diagram users would enter custom properties like (order, title, failure, resolution) for some of the elements of the BPMN file.

My project would read the BPMN file and extract the (Id, order, title, failure, resolution) and generate a text file that is written in the ASCIIDoctor text format.

I have been working on this on-and-off for the last month and I’m stuck. My project is on GitHub at https://github.com/GeekMustHave/Camunda-ADOC

The first part of the project on GitHub was to see if a could create an internal BPMN, it was just for testing.

The second part, I think I’ve managed to create a camunda moddle object and I tried to read through the elements and look at the keys. What I’m having trouble with is trying to read through the moddle object and just get a list of element ID’s.

my index.js is documented with my attempts.

I appreciate any assistance at this point.

2

Please ask questions related to the bpmn.io projects on the respective forum at https://forum.bpmn.io/.

Cheers,
Thorben

3

@GeekMustHave I threw together a little sample from previous code i have used for the same goal.

It uses Vertx and JS:

Instead of using Moodle, I use the Camunda Model API (Java) so you get the java “powers” and can interact with the BPMN in the same syntax that the camunda engine uses

See the readme for deploying and examples.

You can extend the setup by modifying the app/templates/myTemplate.ftl template file, the app/bpmn/myProcess.bpmn file, and the app/entryPointVerticle.js file. I have code commented the JS file so you see what is going on.

Enjoy!

4

@thorben thank you for the response.

I did ask similar questions on the BPMN.IO forum.

I did, and got some helpful suggestions to get me past the “How do I start this” phase."

In this project, I’m going to use the Camunda Moddle extensions and thought some input from this group may provide some guidance.

Thanks

5

Stephen, very nice!! This is going to come in helpful for some much-needed knowledge.

My Camunda-ADOC is being written in JavaScript because of the client only having JavaScript support folks.

The folks using this project will be technical support and analysts.This client doesn’t easily allow other EXE, DLL’s to be installed or run. To them, everything is a virus first and a valuable tool last. This side project isn’t funded. The enables it to be open source. However, NODE, JavaScript and a number of other related frameworks and JS libraries are approved.

If my studies here your templates would require the Camunda BMPN API to be spun up on a server, and configured, along with the BPMN community engine?

I have gotten a few steps further in my stand-alone utility with help from some folks at Postman and Google-foo.

Thanks for your response.

6

you can package the entire into into a single executable Java Jar. It is completely self-contained.
It runs Java + Javascript. (it is basically running javascript on the JVM). In they are running Node, they must be okay with JVM… ;). The app does not require th camunda engine/server. It just uses the java library: model API which is the lib camunda uses for transversing the bpmn XML.

If they want a desktop version, here is another variation that i did today:

(still a WIP)

7

@GeekMustHave did you make progress?

8

Yes, after some research and sample coding I have gotten the NODE app to collect an array of elements from the BPMN file.

All of the additional documentation information from the user created camunda properties are also collected.

I can generate an ADOC file that has nicely formatted documentation. I’m working on formatting.

The GITHub repository has my research code and notes in it right now.

https://github.com/GeekMustHave/Camunda-documentation-generator

The next item is to generate a small SVG file for each element in the diagram

for example

“$type”: “bpmn:UserTask”,
“id”: “Task_1yzt5bc”,
“name”: “Clicks on Immunization Link in\nCC360”,

Needs to generate an SVG that looks like

image

Here is an example of what I’m trying to generate…

<?xml version="1.0" encoding="utf-8"?>
<!-- created with bpmn-js / http://bpmn.io -->
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="112" height="92" viewBox="255 274 112 92" version="1.1"><g class="djs-group"><g class="djs-element djs-shape" data-element-id="ServiceTask_15iz3md" style="display: block;" transform="translate(261 280)"><g class="djs-visual"><rect x="0" y="0" width="100" height="80" rx="10" ry="10" style="stroke: black; stroke-width: 2px; fill: white;"/><text class="djs-label" style="font-family: Arial, sans-serif; font-size: 12px; fill: black;"><tspan x="29.8359375" y="29.5">Verifies </tspan><tspan x="10" y="43.5">CC360 to MPI-</tspan><tspan x="24.5" y="57.5">API route</tspan></text><path d="m 12,18 v -1.71335 c 0.352326,-0.0705 0.703932,-0.17838 1.047628,-0.32133 0.344416,-0.14465 0.665822,-0.32133 0.966377,-0.52145 l 1.19431,1.18005 1.567487,-1.57688 -1.195028,-1.18014 c 0.403376,-0.61394 0.683079,-1.29908 0.825447,-2.01824 l 1.622133,-0.01 v -2.2196 l -1.636514,0.01 c -0.07333,-0.35153 -0.178319,-0.70024 -0.323564,-1.04372 -0.145244,-0.34406 -0.321407,-0.6644 -0.522735,-0.96217 l 1.131035,-1.13631 -1.583305,-1.56293 -1.129598,1.13589 c -0.614052,-0.40108 -1.302883,-0.68093 -2.022633,-0.82247 l 0.0093,-1.61852 h -2.241173 l 0.0042,1.63124 c -0.353763,0.0736 -0.705369,0.17977 -1.049785,0.32371 -0.344415,0.14437 -0.665102,0.32092 -0.9635006,0.52046 l -1.1698628,-1.15823 -1.5667691,1.5792 1.1684265,1.15669 c -0.4026573,0.61283 -0.68308,1.29797 -0.8247287,2.01713 l -1.6588041,0.003 v 2.22174 l 1.6724648,-0.006 c 0.073327,0.35077 0.1797598,0.70243 0.3242851,1.04472 0.1452428,0.34448 0.3214064,0.6644 0.5227339,0.96066 l -1.1993431,1.19723 1.5840256,1.56011 1.1964668,-1.19348 c 0.6140517,0.40346 1.3028827,0.68232 2.0233517,0.82331 l 7.19e-4,1.69892 h 2.226848 z m 0.221462,-3.9957 c -1.788948,0.7502 -3.8576,-0.0928 -4.6097055,-1.87438 -0.7521065,-1.78321 0.090598,-3.84627 1.8802645,-4.59604 1.78823,-0.74936 3.856881,0.0929 4.608987,1.87437 0.752106,1.78165 -0.0906,3.84612 -1.879546,4.59605 z" style="fill: white; stroke-width: 1px; stroke: black;"/><path d="m 17.2,18 c -1.788948,0.7502 -3.8576,-0.0928 -4.6097055,-1.87438 -0.7521065,-1.78321 0.090598,-3.84627 1.8802645,-4.59604 1.78823,-0.74936 3.856881,0.0929 4.608987,1.87437 0.752106,1.78165 -0.0906,3.84612 -1.879546,4.59605 z" style="fill: white; stroke-width: 0px; stroke: black;"/><path d="m 17,22 v -1.71335 c 0.352326,-0.0705 0.703932,-0.17838 1.047628,-0.32133 0.344416,-0.14465 0.665822,-0.32133 0.966377,-0.52145 l 1.19431,1.18005 1.567487,-1.57688 -1.195028,-1.18014 c 0.403376,-0.61394 0.683079,-1.29908 0.825447,-2.01824 l 1.622133,-0.01 v -2.2196 l -1.636514,0.01 c -0.07333,-0.35153 -0.178319,-0.70024 -0.323564,-1.04372 -0.145244,-0.34406 -0.321407,-0.6644 -0.522735,-0.96217 l 1.131035,-1.13631 -1.583305,-1.56293 -1.129598,1.13589 c -0.614052,-0.40108 -1.302883,-0.68093 -2.022633,-0.82247 l 0.0093,-1.61852 h -2.241173 l 0.0042,1.63124 c -0.353763,0.0736 -0.705369,0.17977 -1.049785,0.32371 -0.344415,0.14437 -0.665102,0.32092 -0.9635006,0.52046 l -1.1698628,-1.15823 -1.5667691,1.5792 1.1684265,1.15669 c -0.4026573,0.61283 -0.68308,1.29797 -0.8247287,2.01713 l -1.6588041,0.003 v 2.22174 l 1.6724648,-0.006 c 0.073327,0.35077 0.1797598,0.70243 0.3242851,1.04472 0.1452428,0.34448 0.3214064,0.6644 0.5227339,0.96066 l -1.1993431,1.19723 1.5840256,1.56011 1.1964668,-1.19348 c 0.6140517,0.40346 1.3028827,0.68232 2.0233517,0.82331 l 7.19e-4,1.69892 h 2.226848 z m 0.221462,-3.9957 c -1.788948,0.7502 -3.8576,-0.0928 -4.6097055,-1.87438 -0.7521065,-1.78321 0.090598,-3.84627 1.8802645,-4.59604 1.78823,-0.74936 3.856881,0.0929 4.608987,1.87437 0.752106,1.78165 -0.0906,3.84612 -1.879546,4.59605 z" style="fill: white; stroke-width: 1px; stroke: black;"/></g><rect x="0" y="0" width="100" height="80" class="djs-hit" style="fill: none; stroke-opacity: 0; stroke: white; stroke-width: 15px;"/><rect x="-6" y="-6" width="112" height="92" class="djs-outline" style="fill: none;"/></g></g></svg>

I got this SVG by copy-pasting it into a blank BPMN document.

I’m doing research but have not had good luck on this so far

How to generate something like this using the JS libraries?

1 Like
9

@StephenOTT the link you shared ( StephenOTT/vertx-bpmn-model-doc-generator ) looks great!

Do you know of any similar projects or perhaps you implement some enhancements?

I’m looking for a solution to generate process documentation (image of a diagram, list of the diagram elements, list of all the attributes, list of subprocesses, etc.). I’m thinking of a PDF or markdown as the final output.

The biggest challenge is to collect all the elements ordered according to the diagram flow and display them in a text form including their attributes and calculations/decisions that happen inside an element.

The more such examples I see, the better :slight_smile:

@GeekMustHave How is your project doing? All your links to github are 404 now.

10

@jadviga how do you define “ordered according to the diagram flow” ?

Given parallel activities, looping, embedded processes, etc, having a Table of Contents / Index for Activity ID would usually fit better.

When you generate the BPMN image you can apply overlays that fit your administrative need. See the overlays as an example: GitHub - StephenOTT/Cammand: Alternative UI to Camunda BPM Webapps (Tasklist, Cockpit, and Admin) + More! where there is an overlay that shows if there is content in the Documentation field of the Element. In your case you could show the Activity ID (which is unique per .bpmn file).