Flowable Modeler Maven Plugin

Beu om telkens opnieuw BPMN en andere modellen uit Flowable Modeler naar je codebase te downloaden?
Op zoek naar een manier om deze modellen automatisch te importeren en exporteren?
Gebruik de XTi Flowable Maven Plugin!

Het probleem: Flowable Modeler en je Java codebase

Iedereen die met Flowable Modeler werkt kent het probleem wel: snel een procesmodel aanpassen, downloaden, in je codebase plaatsen en verder ontwikkelen. De roundtrip tussen Flowable Modeler en je Java IDE maakt echter dat je na elke aanpassing telkens opnieuw een file moet downloaden vanuit de Flowable Modeler UI.

Daarnaast is het up-to-date blijven met modellen die ook door collega's worden bewerkt tijdrovend, en stop je de BPMN en andere files allicht liever in je git repository, zodat ze samen met je code geversioneerd en gebranched kunnen worden.
Verschillende versies van modellen in parallel onderhouden is ook geen evidentie aangezien Flowable Modeler enkel sequentiële versies ondersteunt.

De oplossing: Maven plugin

Onze Flowale Modeler Maven Plugin (https://github.com/XT-i/flowable-modeler-maven-plugin) automatiseert de integratie tussen je codebase en Fowable Modeler.

Hierdoor kan je :

Automatisch modellen vanuit je codebase importeren in een Flowable Modeler instantie (BPMN, CMMN, DMN én Forms)
De modellen geautomatiseerd downloaden om aangebrachte wijzigingen in je codebase te verwerken

De plugin ondersteunt alle modellen - BPMN proces modellen, CMMN case modellen, DMN decision tables en Form definities (deze kunnen via de Flowable UI zelf momenteel niet gedownload of geïmporteerd worden!)

Deze blogpost biedt stap voor stap de configuratie en het gebruik van de plugin aan, wil je ineens aan de slag dan kan je de volledige voorbeeld pom file als referentiepunt gebruiken voor je Spring Boot applicatie geïntegreed met Flowable Modeler.

Voorbereiding: Flowable Modeler starten

Als voorbereiding starten we Flowable Modeler zelf. Heb je al een Flowable Modeler instantie beschikbaar dan kan je deze gebruiken - verderop vind je hoe je URL en login gegevens kan configureren.

Als je nog geen runnende instantie hebt dan is de all-in-one docker image die Flowable op dockerhub onderhoudt (https://hub.docker.com/r/flowable/all-in-one) een prima startpunt.
Bij elke run verdwijnen de modellen doordat een in-memory database gebruikt wordt, maar aangezien we die gaan downloaden en nadien terug kunnen importeren is dit prima:

docker run -p 8080:8080 flowable/all-in-one

De start duurt eventjes, nadien kan je op http://localhost:8080/flowable-modeler met username "admin" en password "test" inloggen en vind je een lege modeler instantie terug.
Deze login-gegevens zijn ook ingesteld als standaardwaardes voor de maven plugin - hierdoor is geen bijkomende configuratie vereist.

Configuratie

We gaan in dit voorbeeld uit van een Spring Boot applicatie, makkelijkste startpunt daarvoor is de Spring Boot Initializer: https://start.spring.io/. Onderaan deze blogpost vind je de voorbeeld pom.xml ter referentie

Aangezien de Flowable Modeler Maven Plugin (nog) niet in de centrale maven repository te vinden is, moet je de repository manueel toevoegen aan de pom.xml file van je project:

<pluginRepositories> <pluginRepository> <id>io.cloudrepo.xti.opensource</id> <url>https://xti.mycloudrepo.io/public/repositories/opensource</url> </pluginRepository> </pluginRepositories>

Daarnaast moet je uiteraard de plugin zelf nog refereren in je project, momenteel is de huidige versie 0.2.0-SNAPSHOT:

<build> <pluginManagement> <plugins> <plugin> <groupId>com.xti.flowable</groupId> <artifactId>flowable-modeler-maven-plugin</artifactId> <version>0.2.0-SNAPSHOT</version> </plugin> </plugins> </pluginManagement> </build>

Testen of de plugin ook effectief gevonden wordt kan als volgt:

mvn com.xti.flowable:flowable-modeler-maven-plugin:0.2.0-SNAPSHOT:download-models

Output zou er dan ongeveer als volgt moeten uit zien:

[INFO] Scanning for projects... [INFO] [INFO] ------------------------------------------------------------------------ [INFO] Building demo-project 0.2.0-SNAPSHOT [INFO] ------------------------------------------------------------------------ [INFO] [INFO] --- flowable-modeler-maven-plugin:0.2.0-SNAPSHOT:download-models (default-cli) @ demo-project --- [INFO] Downloading models from Flowable Modeler [INFO] Flowable @ http://localhost:8080 [INFO] Logging in with username 'admin' [INFO] Models file system: /home/vanrogu/flowable-maven-plugin-demo/src/main/resources [INFO] Using file naming strategy based on model NAME [INFO] Downloading BPMN models [INFO] Downloading CMMN models [INFO] Downloading DMN models [INFO] Downloading FORM models [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 1.860 s [INFO] Final Memory: 20M/304M [INFO] ------------------------------------------------------------------------Dit betekent een geslaagde login op Flowable Modeler, maar nog geen modellen om te downloaden.
Verderop gaan we in detail in op het gebruik van de plugin.

Als je tenslotte in je ~/.m2/settings.xml file volgende kleine extra configuratie doet ...

<pluginGroups> <pluginGroup>com.xti.flowable</pluginGroup> </pluginGroups>
... kan dat ook wat korter:

mvn flowable-modeler:download-models

Parametrisatie

Zonder verdere aanpassingen gebruik je de standaard configuratie, met volgende defaults waardes:

	Omschrijving	Default waarde
Flowable
url	URL van de Flowable installatie (zonder "/flowable-modeler" pad) Vereiste is dat én /flowable-modeler én /flowable-idm geïnstalleerd zijn	http://localhost:8080
username	Username waarmee ingelogd wordt op Flowable Modeler	admin
password	Password voor de opgegeven gebruiker	test
Modellen
types	types modellen die de plugin behandelt	alle beschikbare (BPMN, CMMN, DMN, FORM)

Files
path	Relatief pad tov project baseDir waar de modellen in geschreven worden	/src/main/resources
bpmn File Extension	Extensie te gebruiken bij het exporteren van proces-modellen (".bpmn20.xml", ".bpmn.xml", ".bpmn", ...)	.bpmn20.xml
cmmn File Extension	Extensie te gebruiken bij het exporteren van case-modellen (".cmmn.xml", ".cmmn", ...)	.cmmn.xml
dmn File Extension	Extensie te gebruiken bij het exporteren van decision modellen (".dmn", ".dmn.xml", ...)	.dmn
form File Extension	Extensie te gebruiken bij het exporteren van form definities (".form", ".form.json", ...)	.form
file Name Strategy	Naamgeving van de file: NAME: gebruikt de naam van het model (in lijn met download name vanuit Flowable Modeler (met escaping van spaties als underscores) bv: "Order_To_Quote.bpmn20.xml" KEY: gebruikt de key van het model bv: "order-to-quote.bpmn20.xml"	NAME

Wil je van één of meer van deze parameters afwijken dan kan je dit in je pom.xml opnemen:
(Merk op dat het geen zin heeft om alle parameters te hernemen, enkel diegene die je wil aanpassen)

<build> <pluginManagement> <plugins> <plugin> <groupId>com.xti.flowable</groupId> <artifactId>flowable-modeler-maven-plugin</artifactId> <version>0.2.0-SNAPSHOT</version> <configuration> <url>http://localhost:8080</url> <username>admin</username> <password>test</password> <path>src/main/resources</path> <types> <type>BPMN</type> <type>CMMN</type> <type>DMN</type> <type>FORM</type> </types> <bpmnFileExtension>.bpmn20.xml</bpmnFileExtension> <cmmnFileExtension>.cmmn.xml</cmmnFileExtension> <dmnFileExtension>.dmn</dmnFileExtension> <formFileExtension>.form</formFileExtension> <fileNameStrategyOption>NAME</fileNameStrategyOption> </configuration> </plugin> </plugins> </pluginManagement> </build>

Gebruik

Er zijn 2 goals in de Flowable Modeler Maven Plugin:

download-models: dit exporteert alle modellen vanuit Flowable Modeler naar je filesystem
import-models: dit importeert de modellen van je filesysteem naar Flowable Modeler

Goal "download-models"

Als je een lege Flowable Modeler instantie hebt, en je runt de download goal van de plugin:

mvn flowable-modeler:download-models

Dan zou de output er als volgt moeten uit zien:

[INFO] Scanning for projects... [INFO] [INFO] ------------------------------------------------------------------------ [INFO] Building demo-project 0.2.0-SNAPSHOT [INFO] ------------------------------------------------------------------------ [INFO] [INFO] --- flowable-modeler-maven-plugin:0.2.0-SNAPSHOT:download-models (default-cli) @ demo-project --- [INFO] Downloading models from Flowable Modeler [INFO] Flowable @ http://localhost:8080 [INFO] Logging in with username 'admin' [INFO] Models file system: /home/vanrogu/flowable-maven-plugin-demo/src/main/resources [INFO] Using file naming strategy based on model NAME [INFO] Downloading BPMN models [INFO] Downloading CMMN models [INFO] Downloading DMN models [INFO] Downloading FORM models [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 1.860 s [INFO] Final Memory: 20M/304M [INFO] ------------------------------------------------------------------------Geslaagde login op Flowable Modeler, maar nog geen modellen om te downloaden.

Als je dan een procesmodel tekent en bewaart in Flowable Modeler, en de plugin goal terug uitvoert dan wordt dit model gedownload:

mvn flowable-modeler:download-models

[INFO] Scanning for projects... [INFO] [INFO] ------------------------------------------------------------------------ [INFO] Building demo-project 0.2.0-SNAPSHOT [INFO] ------------------------------------------------------------------------ [INFO] [INFO] --- flowable-modeler-maven-plugin:0.2.0-SNAPSHOT:download-models (default-cli) @ demo-project --- [INFO] Downloading models from Flowable Modeler [INFO] Flowable @ http://localhost:8080 [INFO] Logging in with username 'admin' [INFO] Models file system: /home/vanrogu/flowable-maven-plugin-demo/src/main/resources [INFO] Using file naming strategy based on model NAME [INFO] Downloading BPMN models [INFO] [ ADDED ] process-test | Test Process | src/main/resources/processes/Test_Process.bpmn20.xml [INFO] Downloading CMMN models [INFO] Downloading DMN models [INFO] Downloading FORM models [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCE [INFO] ------------------------------------------------------------------------ [INFO] Total time: 1.826 s [INFO] Final Memory: 19M/303M [INFO] ------------------------------------------------------------------------

In dit voorbeeld is een proces met de naam "Test Process" gemaakt, merk op dat de naamgeving gelijk loopt met diegene die Flowable Modeler voorstelt als je de "Download" knop gebruikt.
Verder worden de modellen in een structuur gedownload onder src/main/resources, volgens default naamgeving voor de Spring Boot integratie van Flowable (dus subfolders"processes", "cases", "dmn" en "forms")

Tenslotte zie je ook "ADDED" als status voor het model staan - zo zie je dat dit om een model gaat dat nog niet op het filesystem bestond.
Voer je de download een tweede maal uit dan krijg je:

[INFO] [ UNCHANGED ] process-test | Test Process | src/main/resources/processes/Test_Process.bpmn20.xml

Maak je een aanpassing in het model en download je opnieuw dan wordt dit:

[INFO] [ UPDATED ] process-test | Test Process | src/main/resources/processes/Test_Process.bpmn20.xml

Op deze manier kan je zien of modellen effectief aangepast zijn of niet.

Voor alle andere model-types is dit gelijklopend. Een voorbeeld met wat meer modellen ziet er dan als volgt uit:

[INFO] Scanning for projects... [INFO] [INFO] ------------------------------------------------------------------------ [INFO] Building demo-project 0.2.0-SNAPSHOT [INFO] ------------------------------------------------------------------------ [INFO] [INFO] --- flowable-modeler-maven-plugin:0.2.0-SNAPSHOT:download-models (default-cli) @ demo-project --- [INFO] Downloading models from Flowable Modeler [INFO] Flowable @ http://localhost:8080 [INFO] Logging in with username 'admin' [INFO] Models file system: /home/vanrogu/flowable-maven-plugin-demo/src/main/resources [INFO] Using file naming strategy based on model NAME [INFO] Downloading BPMN models [INFO] [ ADDED ] process-test-2 | Another Test Process | src/main/resources/processes/Another_Test_Process.bpmn20.xml [INFO] [ UNCHANGED ] process-test | Test Process | src/main/resources/processes/Test_Process.bpmn20.xml [INFO] Downloading CMMN models [INFO] [ UNCHANGED ] case-test | Test Case Model | src/main/resources/cases/Test_Case_Model.cmmn.xml [INFO] Downloading DMN models [INFO] [ ADDED ] dmntest2 | Test DMN 2 | src/main/resources/dmn/Test_DMN_2.dmn [INFO] [ UNCHANGED ] dmntest | Test DMN | src/main/resources/dmn/Test_DMN.dmn [INFO] Downloading FORM models [INFO] [ UNCHANGED ] test-form | Test Form | src/main/resources/forms/Test_Form.form [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 2.282 s [INFO] Final Memory: 20M/312M [INFO] ------------------------------------------------------------------------

Goal "import-models"

Modellen op je filesysteem kan je terug importeren in Flowable Modeler, de makkelijkste manier om dit te testen is om de modellen te verwijderen uit Flowable Modeler, of om de docker container af te sluiten en terug op te starten.
De modellen die je gedownload had kan je op volgende manier terug importeren:

mvn flowable-modeler:import-models

Dit geeft volgende bevestiging:

Deze actie kan je perfect maken als je een bepaalde branch van je codebase hebt uitgechecked, en aanpassingen wil maken aan de modellen op die branch.
Op deze manier wordt de Flowable Modeler een tijdelijke omgeving waarvoor je geen backup e.d. moet voorzien aangezien alle modellen mee in je versioneringssysteem kunnen opgenomen worden, en terug geïmporteerd in een modeleringsomgeving wanneer nodig.

Command-line vs Build-lifecycle execution

Tot hiertoe hebben we de werking van de plugin commandline aangetoond. Voor het importeren van modellen is dit allicht de normale gebruikswijze, het downloaden van modellen zou je in bepaalde situaties misschien in je build cycle willen opnemen.

Via klassieke maven configuratie kan je de plugin bijvoorbeeld koppelen in de "generate-resources" fase van je build (voorbeeld zonder aanpassing van standaard parameters configuratie):

<build> <plugins> <plugin> <groupId>com.xti.flowable</groupId> <artifactId>flowable-modeler-maven-plugin</artifactId> <version>0.2.0-SNAPSHOT</version> <executions> <execution> <id>execution-upon-generate-resources</id> <phase>generate-resources</phase> <goals> <goal>download-models</goal> </goals> </execution> </executions> </plugin> </plugins> </build>

Als je nu bv je build runt met

mvn install

dan worden de modellen tijdens de build gedownload. Dit zou in een aantal situaties nuttig kunnen zijn:

bij elke lokale development build bij te blijven met de modellen in je private Flowable Modeler instantie
bij elke lokale development build bij te blijven met modelwijzigingen van collega's in een gedeelde Flowable Modeler instantie
vanuit je CI/CD pipeline (bv Jenkins) de laatste model-updates in je codebase te betrekken

Let wel: bij de laatste 2 scenario's loop je telkens de kans dat onverwachte toevoegingen of wijzigingen in de Flowable Modeler modellen impact hebben op je build kwaliteit!

Opmerkingen

Features en beperkigen

Form definities kunnen via de huidige Flowable Modeler UI (in tegenstelling tot de andere modellen) niet gedownload en geïmporteerd worden - via deze plugin kan dit wel!
Flowable Modeler zelf bevat nog enkele vervelende bugs - oa een leeg casemodel kan niet geïmporteerd worden via de UI - ook de plugin faalt hierop aangezien deze tegen dezelfde Flowable UI API werkt.

Status & feedback

Huidige versie van de plugin is 0.2.0-SNAPSHOT - allicht kunnen er nog enkele bugs opduiken.
Feedback, bug reports, feature requests via GitHub (https://github.com/XT-i/flowable-modeler-maven-plugin) zijn zeer welkom!

Voorbeeld pom.xml file

Deze pom.xml file bevat alle configuratie die in deze blogpost aan bod kwam, en kan als startpunt dienen voor je eigen project:

<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.2.4.RELEASE</version> <relativePath/> </parent> <groupId>com.xti.demo</groupId> <artifactId>demo-project</artifactId> <version>0.0.1-SNAPSHOT</version>  <repositories> <repository> <id>io.cloudrepo.xti.opensource</id> <url>https://xti.mycloudrepo.io/public/repositories/opensource</url> </repository> </repositories> <properties> <java.version>1.8</java.version> </properties> <dependencies>  <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency>  <dependency> <groupId>org.flowable</groupId> <artifactId>flowable-spring-boot-starter</artifactId> <version>6.5.0</version> </dependency>  <dependency> <groupId>com.h2database</groupId> <artifactId>h2</artifactId> <scope>runtime</scope> </dependency>  <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> <exclusions> <exclusion> <groupId>org.junit.vintage</groupId> <artifactId>junit-vintage-engine</artifactId> </exclusion> </exclusions> </dependency> </dependencies> <build> <pluginManagement> <plugins> <plugin> <groupId>com.xti.flowable</groupId> <artifactId>flowable-modeler-maven-plugin</artifactId> <version>0.2.0-SNAPSHOT</version> <configuration> <url>http://localhost:8080</url> <username>admin</username> <password>test</password> <path>src/main/resources</path> <types> <type>BPMN</type> <type>CMMN</type> <type>DMN</type> <type>FORM</type> </types> <bpmnFileExtension>.bpmn20.xml</bpmnFileExtension> <cmmnFileExtension>.cmmn.xml</cmmnFileExtension> <dmnFileExtension>.dmn</dmnFileExtension> <formFileExtension>.form</formFileExtension> <fileNameStrategyOption>NAME</fileNameStrategyOption> </configuration> </plugin> </plugins> </pluginManagement> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> </plugin> <plugin> <groupId>com.xti.flowable</groupId> <artifactId>flowable-modeler-maven-plugin</artifactId> <executions> <execution> <id>execution-upon-generate-resources</id> <phase>generate-resources</phase> <goals> <goal>download-models</goal> </goals> </execution> </executions> </plugin> </plugins> </build> </project>

XTi Blog