DEV Community

Cover image for [Bonita UI Designer] creating Custom widget for BPMN Visualization
Marcin Michniewicz
Marcin Michniewicz

Posted on • Updated on

[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
Create 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>
Enter fullscreen mode Exit fullscreen mode
  • 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);
      }
    });
}
Enter fullscreen mode Exit fullscreen mode
  • Define property: bpmnXmlString
    bpmnXmlString

  • Add the new asset: bpmn-visualization.js

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

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:

UID Page Design

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. diagramAPI
  2. We need to link these variables to proper elements:
    • Select setup:
      • Available values: processesAPI
      • Displayed key: name
      • Returned key: id
      • Value: diagramId Select setup
    • Custom Widget (bpmnVisualization) setup:
      • BPMN xml string: diagramAPI Custom Widget setup
    • 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.
Bonita Studio Model

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:
UID Page Preview

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.

Top comments (0)