[Bonita UI Designer] creating Custom widget for BPMN Visualization
Tags: opensource, processanalytics, digitalprocessautomation, bonitasoft
Published: 2021-05-19 14:18:37

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](https://process-analytics.github.io/bpmn-visualization-js/api/index.html) 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](https://process-analytics.github.io/bpmn-visualization-js/api/index.html) 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](https://github.com/process-analytics/bpmn-visualization-js).



Create a Custom Widget
======================

Launch UI Designer

Create the new Artifact of type Custom Widget
![Create Custom Widget](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/9uun3uruh1sbxf1xb267.png)


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
![bpmnXmlString](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/nq4xa4nlt6b5r53em31t.png)

-   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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/44odcg23ybamupkbbnnd.png)



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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/13k19tnlz8v7wo1c766z.png)


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 ](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/4d0khli1269ntvm3cupx.png)
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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/tufyv45n77jatwf7ygz5.png)
    -   Custom Widget (bpmnVisualization) setup:
        -   BPMN xml string: `diagramAPI`
![Custom Widget setup](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/9iq7k68ajgizs5ftvb81.png)
    -   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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/4ibtlvpnt50j0atbs04a.png)

*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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/9dewm524kez0gx2pni5g.png)



**WORTH TO NOTE:**

The Open Source Apache-2.0 rendering library: [BPMN Visualization](https://github.com/process-analytics/bpmn-visualization-js) is highly customizable.
You can check the examples [here](https://cdn.statically.io/gh/process-analytics/bpmn-visualization-examples/master/examples/index.html).

To preview the code of the mentioned examples, go directly to the [bpmn-visualization-examples repository](https://github.com/process-analytics/bpmn-visualization-examples).