Troubleshooting Widgets

<< Click to Display Table of Contents >>

Navigation:  Bizagi Studio > Process wizard > Define Forms > Extending or customizing Forms > Creating Widgets >

Troubleshooting Widgets


There are different levels to troubleshoot or debug your Widget.  

Before troubleshooting in Bizagi and by all means, you should first make sure:


1. That your code works, separately from Bizagi

This means having previously ensured in a separate demo.html file, that the code used by your Widget is working.


2. That within the Widget Editor, the Widget simulates just fine

Note that when creating a Widget through the Widget Editor, you have the possibility to simulate its behavior as it will be in Bizagi.

Through the simulation options, recall that the simulation tools provide a built-in console which prints error messages present when running the Widget.

For more information, refer to Simulation of your Widget.


Additional aspects to consider

In order to troubleshoot your Widget inside of Bizagi, consider the below aspects to narrow down where problems may lie.


1. BWG file consistent?

Once you generate a Widget as a .bwg output, make sure that no errors are shown when you install your Widget into your Bizagi project.

You do this by registering the Widget in Bizagi Studio, and making sure that this step does not show any error messages either when registering it for the first time, or updating it.

If there are any errors, it is most likely that you will need to review your Widget’s structure to make sure that all referenced files are imported.


2. Loads in Forms Designer?

After a successful installation of your Widget, make sure that it displays properly when you include it into one of your forms (through the Forms Designer).

By including the Widget (that is, dragging and dropping it) into the form, you should be able to see:

That the form immediately draws whatever the Widget is supposed to draw.

Though dynamic behaviors (such as on-click events) may not be available, Bizagi will display the reserved space by the Widget in the form.

That the properties panel loads up correctly all the properties you defined for design, that are up for configuration.


If you include the Widget and either the Forms designer freezes, it does not properly display it, or the rest of the design of it gets altered, then it means that the Widget has errors and some of its information is not working as expected.

This may be caused either by: incomplete definition of its properties, or a faulty implementation (a single line of code throwing an error may result in such alterations).

In this case, do not save the form.

You may also want to delete the installed Widget and upload it again with the necessary adjustments, and rely strongly on the simulation features of the Widget Editor.


3. Loads on the Simulation and on runtime, but not doing what is supposed to?

Finally, and once the Widget at least displays correctly, you can test it in the Work Portal.

This also applies if the simulation of your Widget is not working as expected but only if the Widget has no syntax errors.



Recall that you may use your browser’s debugging and developer options (frequently shown with the F12 key, and as described in the section below) which include the same traces options such as console.log() that write directly into the browser's JS console (supported in Chrome, Mozilla but not in Internet Explorer).




When testing it on the Work portal on runtime, we recommend relying on the browser's debugging tools to test and troubleshoot Widgets.

Google Chrome is strongly recommended for this purpose because of its helpful tools (though it is required as well that you test the Widget in Internet Explorer and all supported devices/browsers).


For instance, you may include debugger clauses inside the lines of code in your Widget, for a quick and easy alternative to adding breakpoints.

By simply opening the developer tools' console (i.e, using F12 in Chrome) you will be taken directly to debugging breakpoints:




Alternatively you may debug the Widget in the browser, either directly when using the Widget Editor or when it is already part of your Bizagi project, by follow these other instructions:


1. Include at the end of your implementation file, a line having:

//# sourceURL=MyWidget.js  




2. Make sure you build the Widget file, include it in your project and configure it and use it in an activity form.

Then, execute the process to view the behavior in Chrome.

For more information about this step, refer to the Widgets Management.


3. Use the developer options as shown when pressing F12, when running the Widget in Chrome (specifically when opening the form of the activity in which you have the Widget).


4. Go to the Sources tab to open the source file that has your implemented function.

You may open and search for the MyWidget.js source by pressing CTRL + P (or CTRL + O) and by entering the name of the MyWidget.js file:




When clicking on the MyWidget.js result, the code of your implementation will load.


5.  Place breakpoints as appropriate, in the very first line (or any line) inside of the function that displays your Widget.

Recall that the function that is called upon when displaying the Widget can be: getEditableControl, getReadOnlyControl, getGenericControl, or renderComplex, accordingly to your scenario (if the Widget was set as editable, read-only, or if this is irrelevant).




Once you have at least one breakpoint, click on the refresh icon located at the top right corner, in order to only refresh that given form you are standing at.

Upon a refresh, you will see Chrome pausing the execution at the breakpoint so that you can use regular step-over and step-into debugging options.



Recall that you may also type directly into the browser's JS console the jQuery sign ($) and a dot to use IntelliSense, in order to verify that the jQuery library is loaded up and avoid conflicts:





It is strongly recommended: that you are or become familiar with browser debugging and further developer options, in order to be able to diagnose specific problems of your Widget, and that you acknowledge that debugging options should be temporary only (you need to make sure that these are afterward removed).

A final Widget released to production should never include such clauses due to security and performance best practices.


Additional options and further information may be looked up directly in Chrome's debugging help links, such as:



Any change you perform on the Widget and you wish to try out in Bizagi directly, will require that you refresh the browser.

It should not be necessary to restart your application server nor clear the cache of the browser; however you will need to explicitly refresh it (F5).