Enhanced BPMN automated Documentation ASCIIDoctor

GeekMustHave · February 16, 2018, 2:08am

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.

GeekMustHave · February 16, 2018, 2:13am

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.

Ingo_Richtsmeier · February 16, 2018, 10:44am

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

GeekMustHave · February 18, 2018, 3:17am

Yep, this is a BIG document. 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.

philippfromme · February 19, 2018, 9:47am

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?

GeekMustHave · February 19, 2018, 11:58am

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.

nikku · February 19, 2018, 12:30pm

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.

GeekMustHave · February 19, 2018, 8:16pm

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

The SVG needed to draw one object at a time to be included in the Markdown documentation.
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.
The description which is a much lengthier definition of the object to be included in the Markdown application
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.

GeekMustHave · February 22, 2018, 12:36pm

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.

Can the BPMN diagram be read and parsed into a JavaScript object?
I need to be able to pull the (Elelemnt Documentation), Order, Title
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.

philippfromme · February 23, 2018, 8:09am

Hey,

answering your two questions:

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;

  // ...
});

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.

GeekMustHave · February 24, 2018, 12:10am

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

Thanks

GeekMustHave · March 25, 2018, 8:54pm

@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
F:\myDev\Cammunda-SVG\bpmn-js\node_modules\min-dom\dist\index.js:244
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.

philippfromme · March 26, 2018, 6:15am

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

GeekMustHave · March 26, 2018, 12:45pm

I’m using it in Node / Javascript.

philippfromme · March 27, 2018, 6:34am

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

GeekMustHave · March 27, 2018, 11:01am

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.

philippfromme · March 27, 2018, 12:43pm

Any headless browser will do.

I’m still not sure what exactly you want to do. If you only want to read information from the BPMN file you don’t need bpmn-js at all. You can use bpmn-moddle which bpmn-js uses internally. bpmn-moddle can be executed in Node.js.

In regards to examples I already posted a simple example of accessing elements and their properties.

GeekMustHave · March 27, 2018, 3:16pm

I’m already using BPMN-Moddle and getting the Element names.

I want to read the BPMN file and using the Moddle definitions get a single element back, let’s say type: bpmn:serviceTask, ID: Task_1b3yiqx

Here is that element in the definitions block

{
          "$type": "bpmn:ServiceTask",
          "id": "Task_1b3yiqx",
          "name": "Verifies \nCC360 to MPI-API route",
          "documentation": [
            {
              "$type": "bpmn:Documentation",
              "text": "The API gateway verified that CC360 and MPI are allowed to communicate and how to route the request."
            }
          ],
          "extensionElements": {
            "$type": "bpmn:ExtensionElements",
            "values": [
              {
                "$type": "camunda:Properties",
                "values": [
                  {
                    "$type": "camunda:Property",
                    "name": "order",
                    "value": "50"
                  },
                  {
                    "$type": "camunda:Property",
                    "name": "title",
                    "value": "Gateway routes request to MPI Server"
                  },
                  {
                    "$type": "camunda:Property",
                    "name": "failure",
                    "value": "Unable to complete onboarding"
                  },
                  {
                    "$type": "camunda:Property",
                    "name": "remedy",
                    "value": "Call HS-ESB support desk"
                  }
                ]
              }
            ]
          }
        },

Then I want to create an SVG for one element, then save the SVG file. which looks like

Task_1b3yiqx

I used your example code and got stuck at element not found error.

I know there is more framework code around your example but I don’t know where to look.

philippfromme · March 28, 2018, 9:07am

If you want to get the SVG of an element there is no way around using bpmn-js. Otherwise you’d have to implement your own functionality that creates the SVG from an element without depending on a browser.

The example I posted only works in an actual browser. You can use this example as a starting point and add those few lines.

GeekMustHave · March 28, 2018, 11:47pm

Thank you. I knida expected that bpmn-js was going to be required.

I don’t mind using a browser to get these small SVGs generated.

The "implement my own functionality for creating SVG " sounds outside of my JS skill level right now.