[Bonita UI Designer] creating Custom widget for BPMN Visualization

Abstract

The Bonita platform offers a graphical web UI editor called Bonita UI Designer. If you use Bonita UI Designer to develop forms and pages for a process application on the Bonita BPMN platform, you may want to create custom widgets - and this is an article that offers some ideas and instructions.

Specifically, you will see how easy it is to create a preview for the Bonita BPMN model in a UI Designer Page.

Note that the DiagramAPI used in this example is only available in Enterprise Edition. Nevertheless, you can use any BPMN diagram file created externally, to present it and use process analytics API to show some additional informative layers.

What will be described through the guide?

We will first create a custom widget, then place it in the UI Designer Page. Then we will create some variables and API calls to obtain the desired process. Finally, we will put it all together and pass the chosen process to the widget, so it is rendered and visible.

To render the BPMN model in this example we will use the Open Source Apache-2.0 library called BPMN Visualization. Find more information about this library in the GitHub repository: BPMN Visualization.

Create a Custom Widget

Launch UI Designer

Create the new Artifact of type Custom Widget

Type bpmnVisualization as Custom widget name and click Create.

You will land in the WIDGET EDITOR.
Few things to be done here:

• Template: replace default template div with

<div id="bpmn-container"></div>

• Controller: your function should look like one below

function ($scope) {
    //initialize rendering library (added in the assets)
    const bpmnVisualization = new bpmnvisu.BpmnVisualization(window.document.getElementById('bpmn-container'));

    //load diagram when ready
    $scope.$watch('properties.bpmnXmlString', function() {
      var bpmnXml = $scope.properties.bpmnXmlString;
      if (bpmnXml) {
        bpmnVisualization.load(bpmnXml);
      }
    });
}

• Define property: bpmnXmlString
  

• Add the new asset: bpmn-visualization.js

  • Type: JavaScript
  • Source: External
  • URL: https://unpkg.com/bpmn-visualization@{version}/dist/bpmn-visualization.js

Application Page

Create the new Artifact of type Application Page

For the name, you can use bpmnVisualization, click Create.
You will land in the PAGE EDITOR.

The final page should look like that:

The layout is really up to you, feel free to adjust anything you wish.

The core elements to make it work are as follow:

1. Variables:
   • diagramId - Type String — it will hold the id of the chosen process diagram.
   • processesAPI - Type ExternalAPI, API URL: ../API/bpm/process?f=activationState=ENABLED&p=0&c=10&o=version%20desc — it will hold available/accessible processes.
   • diagramAPI - Type: External API, API URL: ../API/bpm/diagram/{{diagramId}} — it will hold the String representation of BPMN xml definition.
2. We need to link these variables to proper elements:
   • Select setup:
     • Available values: processesAPI
     • Displayed key: name
     • Returned key: id
     • Value: diagramId
   • Custom Widget (bpmnVisualization) setup:
     • BPMN xml string: diagramAPI
   • Optionally we can set up the input, on the right side of the Select, to show us the currently chosen diagramId:
     • Value: diagramId
     • Type: text

We are all set!

Preview

For the preview purpose, I have created a simple process called: Work travel in the Bonita Studio.

Please make sure the user with who you are testing has required permissions:
an entry in Process Manager mapping concerning the desired process(to be checked in Bonita Portal).

Once we click on the Preview button in UI Designer we should see the page where we can choose the process.
I have simply chosen Work travel, and the output looks like this:

WORTH TO NOTE:

The Open Source Apache-2.0 rendering library: BPMN Visualization is highly customizable.
You can check the examples here.

To preview the code of the mentioned examples, go directly to the bpmn-visualization-examples repository.