From CPI IFlow to diagram with iflow-plotter

[r_herrmann]

In one of my last blogposts I described how you can create a (vector-)graphic of the IFlow's diagram with a few manual steps. In that article I also talked about the fact that the steps can certainly be simplified with a little programming work. That is exactly what I have done - and now I would like to introduce the tool "iflow-plotter" to you.

What is the iflow-plotter?

The iflow-plotter is a command line tool that allows you to create a (flow) diagram from a previously downloaded IFlow (=zip-file) with only one command. It is written in NodeJS and is available as NPM-package.

How to install it

Since the iflow-plotter is an NPM package, it can be easily installed with the following command in the terminal (CMD, Powershell, Bash, ...):

npm i iflow-plotter -g

Note: The basic prerequisite is, of course, that NodeJS/NPM is already installed on your computer as a runtime environment. If this is not the case, you can read here (for Windows users) or here (for macOS users) or here (for Linux users) how to install NodeJS.

How to use it

Usage is pretty simple. First, download the IFlow as zip file:



Then open the terminal and run the following command:

iflow-plotter my-iflow-file.zip

That's it! Just call the app and pass the filename (or if it's stored in another folder - the full path to the file) as parameter. Just some seconds later you will find the diagram graphics in the current working directory of your terminal session.

Demo

Advanced usage

In addition to the very simple call to the iflow-plotter shown above, other additional parameters can be added. All of these parameters are optional. The following table shows the possible parameters:

Parameter	Description	Example usage
-f	Can be used to set the output format. Possible values: pdf, svg, png, bpmn If you want to output two formats just pass the parameter twice.	-f png -f png -f svg
-s	Scale factor. Default is: 1. A higher scale factor results in higher resolution if png is used as output format.	-s 1.5
-o	Defines the output directory for the graphics files. If not set, the current/working dir of the console window is used.	-o "C:\temp" -o "/mnt/target"
-d	Activates the debug mode (which results in more detailed output/logs in the console window)	-d

Example: If you want export diagrams for the IFlow file "myflow.zip" in PDF- and PNG-format to the folder C:\Export with a scalefactor of 2.5 then you have to call iflow-plotter as follows:

iflow-plotter myflow.zip -f pdf -f png -s 2.5 -o "C:\Export"

Q & A

Perhaps you now have a question or two in mind. To counteract this, I have already collected a few questions and answers. (You are welcome to ask further questions in the comments section at the end of the blog).

• Do I really need to install NodeJS?
  
  
  
  • Yes, the tool is written in NodeJS thus having the Node runtime installed is a must.
  
  
  
  


• Why did you write the program in NodeJS and not in C# or Groovy (like your other tools)?
  
  
  
  • Two reasons: Firstly, I haven't found a really good, free BPMN library for .NET and secondly, I wanted to practice a bit of NodeJS again. In addition, I find the simple installation via NPM very elegant, so I didn't have to worry about hosting or writing an installer script.
  
  
  
  


• You use the Node module "bpmn-to-image" in the iflow-plotter. This is already a console tool and can plot BPMN diagrams. Why do I need iflow-plotter then?
  
  
  
  • It is true that bpmn-to-image does much of the iflow-plotter's work. However, the iflow-plotter takes on additional tasks. It unpacks the BPMN xml from the IFlow zip file, takes care of file names and patches the IFlow BPMN XML. (There are one or two standard attributes missing so that the diagram is rendered nicely).
  
  
  
  


• Does the tool cost money?
  
  
  
  • No, it's free (and licensed via MIT license).
  
  
  
  


• Can I have the source code?
  
  
  
  • Sure, you can find the sources on Github.
  
  
  
  

 

Conclusion & Ideas

In the last blog I wrote a call to create a tool like the iflow-plotter. Now I was too impatient again and did it myself... 😉 Nevertheless, I have a few ideas that could be based on the iflow-plotter. How about integrating it into a Git pipeline to automatically generate the diagram when an IFlow is committed? Or what about an extension of the plotter, to automatically generate more detailed documentation? I think there is still a lot of potential/ideas that can be tapped. Maybe you have an idea or feel motivated to implement something? I look forward to your feedback!

[flow]

Hi Raffael,

 

what a nice little tool.

It would be nice to have a draw.io compatible output as well :).

 

Best regards,

Florian

[r_herrmann]

Hi florian.wallburg ,

please run "npm -g update iflow-plotter". This will install the new vesion 1.0.4 which has "bpmn" as additional output format. (E.g. iflow-plotter myflow.zip -f bpmn) The resulting .bpmn-file can be imported into BPMN 2.0 compatible software like bpmn.io.