Properties' definitions

<< Click to Display Table of Contents >>

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

Properties' definitions


Properties in a Widget will allow you to access (both to obtain and update) business information of your process data model, and it will promote the use of configurable parameters, so that a Widget is entirely a reusable UI building block in any of your different processes and activities.

For information about how to add or edit a property, refer to the Widget Editor user interface explained.


Property type

You will need to define what data type is valid for a property so that the Bizagi Studio user can configure it accordingly.

Bizagi Forms designer will automatically filter and validate that a correct data type value is assigned to this property (for instance, if this property is an XPath, then you will be able to select only an XPath from your data model).


Some properties will require further configuration (sub-properties).


The following table lists the property type possibilities:


Property's type value

What it is for

Further configuration

Simple data binding (XPath-to-simple)

For string, integers, Boolean, and other simple type attributes which are stored in your data model (XPath).

Keep in mind that if you want to use this property, make sure that it is explicitly called XPath.

If you are using more than 1, then the first one you use should still be called XPath, and additional ones may be called Xpath2, Xpath3, etc.

Choose a specific data type for that XPath from these possibilities:

Text (string)

Number (number)

Boolean (boolean)

Date (date)

File upload (upload)

Image (image)

File Upload ECM (uploadecm)

Entity data binding (XPath-to-entity)

For a pointer reference to another Entity of your data model (XPath).

Collection data binding (XPath-to-collection)

For a collection of records given by a 1-n relationship. Seen as a Bizagi collection in your data model (XPath).

Business rule (rule)

For a business rule's return value.

This option is especially powerful since it will allow you to retrieve any value calculated by the server through a simple or sophisticated (i.e, using Component library) Bizagi rule.

Make sure that this rule is executed in an asynchronous manner, and use it as described in the section below.


int: for non-XPath integer values (the information is not in your data model).

boolean: for non-XPath boolean values (the information is not in your data model). When using Booleans, keep in mind that you always need to define a default value.

string: for non-XPath string labels (the information is not in your data model).

localizable-string: for non-XPath string labels which will be presented in multi-language (the information is not in your data model).



Each property type is set in its internal attribute called bas-type.

You may set a properties' caption to be localized (its display name), and setting if these are required or not (true/false), is set in its internal attribute called required.

For detailed information about the properties file definition, refer to the Widget structure.


To define the properties that you consider should be configurable in a Widget, include or edit properties considering their type and possibilities.



Properties are defined at the myWidget.json file in the Widget's structure.

You may see that a property is defined separately in the JSON structure for: design (includes its configuration), and runtime.

The image below shows the definition of a "My property" property for design:




Properties use

Refer to these pointers below to use your properties in runtime (coded in the myWidget.js implementation file).


Loading properties and their values

Loading the properties for runtime access is already provided by the default starting Widget template.

By use of

var properties =;

you may directly start to use any of your properties defined and their value by use of:




Obtaining the value of the main XPath property is done as


Default values for properties

If you need to use a default value (e.g or make sure a preset information is used), consider the following in your implementation file.

var displayName = properties.displayName || "Default display name";

In the example above, if the displayName property was not explicitly set in the forms designer, we use the "Default display name" text.


Asynchronous properties (of the type "rule")

When using properties of the type rule, it is most commonly useful to access their returned values in an asynchronous manner ("async": "true" in their runtime definition).

To access this property and its value in runtime, use:

var self = this;

self.getPropertyValue("dataRule").done(function(data) {

 bizagi.log("data", { data: data.value });


Notice that in this example above, our rule property is called dataRule.



The getPropertyValue(propertyName) method is a deferred object which handles a promise (for the asynchronous treatment).

For more information about this concept, refer to


Additional notes

Recall that the XPath property (with this exact same name), will allow you to define if some values are to be bound directly to your data model. But, you may use and define more than 1 XPath (multiple bound information from the data model) per Widget. If this is your case, then, it is strictly required that the first bounded information is called XPath.

Properties may have sub-properties. Include sub-properties by using subproperties and having the same structure as a property.