Enhanced BPMN automated Documentation ASCIIDoctor

Hello, my name is GeekMustHave. https://GeekMustHave.com

I love using the BPMN.IO and have gotten some other folks interested in it.

I would like to write a utility that allows for documenting each of the objects in a BPMN diagram.

I have “Thrown” together a work document to start this effort.


The BPMN file appears to be an XML file.

Is there a XML schema document or additional documentation that could help me parse this XML?

My Goal is to get a list of participants, lanes, then objects (Exclusive gateway, Task,…).

If I could read the BPMN and load the list of objects into a database (Access) then the business folks could add the documentation to complete the process.

The Access application would generate a complete set of documentation in ASCIIDoctor format which can be turned into Web page, PDF or Booklet.

I will be publishing this project on GitHub as an open project.

Any direction or suggestions are welcomed.

Hi @GeekMustHave ,

is this what you are looking for: https://github.com/bpmn-io/bpmn-moddle/tree/master/resources/bpmn/xsd?

BTW, your process models won’t work.

Each pool represents one process which needs a connection of sequence flows from the start to the end. The message flows would not transport the token from one process to the other.

You have to connect the gaps in the pools with sequence flows as well. See the Pizza Collaboration at the end of this page: https://camunda.com/bpmn/ as a correct example.

Hope this helps, Ingo

To give a bit of background to @Ingo_Richtsmeier answer:

BPMN is a standard and we are merely toolkit providers (offering a quite decent toolkit for modeling and viewing it). There are others out there doing the same, too.

The standard comes with an XML descriptor but what you may need is the BPMN meta-model to understand the relationship between elements. The BPMN 2.0 spec document explains the meta-model pretty well, it is some pages to digest though :wink:. We’ve implemented the meta-model, as part of bpmn-moddle to read and write the XML.

On another note you could checkout bpmn-js-token-simulation, one of our side projects.

It allows you and business stakeholders to simulate created flows in order to understand the underlying semantics:


Thank you, I’m just getting started in BPMN. After a few blog posts and example diagrams I think I’ve gotten better but, still not “good at it”. If you have any links for beginners that would much appeciated.

Special thanks for the link for the XSD, that is helpful.

Thank you for the download link to the “Spec document” I will need to markup some sections of this to help me get started.

After doing a little more Google-Foo I have run into some interesting projects relating to BPMN.

I think I am going to do some research here and come up with a project for doing some form of documentation from the BPMN file.

Maybe you can start here: https://camunda.com/bpmn/reference/ (it’s very verbose for a document called ‘reference’)

Yep, this is a BIG document. :wink: I signed up for the Udemy course of BPMN by Ilya Eremenko.

I just download the Camunda Modeler and noticed the property panel on the right side.

Right now after I export the BPMN to an SVG file, I load the SVG into Inkscape to add a Title(s) and Description.(s)

After I save the SVG and render it in a browser I see the Title-Text I entered when I hover over one of the objects. This is especially nice when reviewing the process with someone.

I was working on a node module to read the SVG and extract the Title and Description into an ASCIIDoctor markdown file.

The problem with editing the SVG is that my updates to Title and Description would get overwritten every time I exported a new SVG, which happens frequently.

Is there some property item or documentation item in the Properties Panel that I can change in Camunda that will find it’s way into the SVG as the Title or Description?

I’m continuing research with the BPMN-JS and the “Properties” and Color" examples.

Do you mean exporting from the Camunda Modeler? Can you elaborate a bit? In which file did you put your title and description? Which file are you importing into the Modeler?

I start with Camunda draw up a new BMPN diagram, I export it to SVG format.

I open up inkscape and load the SVG file to add a Title and Description and resave the SVG formatted file.

I open the SVG file in Chrome and when I hover over the objects that I added a title, the title shows up as a tool tip.

Is there a way in Camunda to add the Title and Description so when the BPMN is exported to SVG the title and description are in the SVG file.

Why would you like to export to SVG in the first place? The whole point of having BPMN + a toolkit to display it is to keep the meta-data (such as the title) while keeping the diagram editable at the same time.

The customer (State of Michigan) doesn’t use BPMN. They can view and share SVG’s without any difficulties.

I agree that any changes to the BPMN should be done using the BPMN format. My intent is to go in that direction.

My documentation project was going to read the generated SVG to get

  1. The SVG needed to draw one object at a time to be included in the Markdown documentation.
  2. The Title which is a short description of the object to be included in the Markdown documentation
    Bonus: When viewing the SVG in a browser, the title appears as a hover-over tooltip helping to define the object just a little better.
  3. The description which is a much lengthier definition of the object to be included in the Markdown application
  4. I have also added a Camunda property (order) which is 10,20,30,40with the intent this would be used to order in which the item(s) document should be printed.

I can include the SVG file in a markdown document and it displays just fine. Can’t say the same for a BPMN file.

Special thanks to @nikku for putting me on the right path. I was trying to do the solution to BMPB-AutoDoc by using the SVG rather than the BPMN. It was a"Learning experience" or a fail depending on your point of view,

The new direction is to use Camunda base to add text into the (Element Documentation) and add two new(Properties) 1. order, 2.title to any object on the BPMN diagram I want to be documented.

For example I might have an object on the BPMN that is a (userTask) with text that is “Perform Review”.

(Element Documentation} Review content of the request, determine if it is a duplicate, contact requester, backfill missing information in a note. Determine if the request should proceed.

The new properties would have been entered as:

(order) 60 <— Used to print documentation in your specified order
(title) Review and update content, a decision to proceed

On the generated ASCIIDoc file I would have a table with any objects that were enhanced with documentation.

Col1 | Col 2 | Col3 | Col4
(order) (svg) (title) (Element documention}

60 | SVG Image of the user task object | Review and update content, a decision to proceed | Review content of the request, determine if it is a duplicate, contact requester, backfill missing information in a note. Determine if the request should proceed.

There is a ton of NODE info on various modules for BPMN and a dev guide that has been useful but I seem to be missing the glue to hold this together.

My “Glue” questions are.

  1. Can the BPMN diagram be read and parsed into a JavaScript object?
    I need to be able to pull the (Elelemnt Documentation), Order, Title

  2. Can SVG for a single object be generated from the BPMN?

Again, if I headed down the wrong path I am open to any suggestions.


answering your two questions:

  1. That is what bpmn-js does when importing a BPMN diagram. You can simply retrieve your element from the element registry and access its business properties through its business object:
var modeler = new Modeler({
  // ...

modeler.importXML(xml, function(err, warnings) {
  var elementRegistry = modeler.get('elementRegistry');
  var myElement = elementRegistry.get('myElement').businessObject;

  // ...
  1. You can only export the entire diagram using #saveXML. However, you can use the element registry to get an elements SVG, too:
var myElementGraphics = elementRegistry.getGraphics('myElement');

// ...

You could use that as a starting point for building a saveElementSVG functionality.

Hope that helps.

This is excellent. Gives me something to dig into this weekend.


@philippfromme Well it’s been a little more than a week and I’ve gotten the documentation part wired up.

I have installed the BPMN-JS and run all the tests, all passed.

Now I’m trying to start small with a file named gen-svg.js shown below

var Modeler = require("./lib/Modeler");

var modeler = new Modeler({


What I’m getting back is

PS F:\myDev\Cammunda-SVG\bpmn-js> node gen-svg.js
var proto = Element.prototype;
ReferenceError: Element is not defined

I don’t want to render anything I just want to generate an SVG for a single element in the diagram.

I’m looking at the examples but I am lost here.

Any guidance is appreciated.

In what environment are you executing your script? bpmn-js only works in the browser.

I’m using it in Node / Javascript.

Thats not possible, sorry. You could alternatively use a headless browser.

Ok, a headless browser it is. I understand there are a few of them. Is there one that is easier to work with?

The code to generate the small SVG’s would still be written in Javascript using the headless browser?

Which one of the examples would be a good example of loading a BPMN and allowing access to the elementRegistry and businessObject.