Widgets

CMDBuild provides a set of default widgets — visual controls placed in the top-right area of the form — that manage process progression through the current activity.

Widgets are rendered as buttons labeled according to their configuration. They are defined as Extended Attributes (as specified in the XPDL standard) using the TWE editor.

The following data types are used throughout this reference:

Standard types: integer, string, date, float, boolean
CMDBuild custom types: lookup (id + type + description), lookups (lookup array), reference (id + idclass + description), references (reference array)

CMDBuild natively supports a set of widgets, each identified by a Widget type. When activated, a widget opens a dedicated modal window that allows specific operations to be performed: browsing and selecting cards, composing emails, generating reports, uploading attachments, starting new workflows, and more.

Parameters can be either static values or dynamic expressions referencing the current execution context via the client: and flow: prefixes. Widgets can also produce output — typically card references, URLs, or serialized strings — which are written to process variables and made available to subsequent activities.

Common configuration

In addition to their specific parameters, all widgets share a set of common parameters described below.

ButtonLabel (string) — The label displayed on the button that opens the widget within the activity form.

Active (boolean) — When set to false, the widget is not rendered. This is useful for conditionally showing or hiding a widget based on a CQL expression.

AlwaysEnabled (boolean) — When set to true, the button remains clickable regardless of the form's validation state, for example even when mandatory fields have not yet been filled in.

General notes

The client: prefix is used to access the current value of a process variable before the workflow advances to the next step. The flow: prefix is used to access process variable values within the flow context. String parameters that accept CQL expressions must be enclosed in single quotes when they represent literal values (e.g. ClassName = 'User'), or written without quotes when referencing a variable (e.g. ObjId = client:Requester).

Link Cards

Displays a paginated list of all cards belonging to a class, with optional geographical map view.

Widget type: Widget_linkCartds

Input parameters

ClassName — string
ButtonLabel — string
SingleSelect — integer
set to 1 to allow single-row selection only (radio button instead of checkbox)
NoSelect — integer
set to 1 to disable row selection
Required — integer
set to 1 to require at least one row to be selected
Filter — string
accepts a CQL expression (e.g., Filter = "from Person where Id = {client:Customer.Id}")
DefaultSelection — string (optional)
CQL query used for automatic selection when the widget opens
AllowCardEditing — integer (optional)
set to 1 to add a card edit icon
DisableGridFilterToggler — boolean (optional)
set to "true" to hide the Disable filter button

Output parameters

CheckArray — references

Create Modify Card

Widget type: Widget_createModifyCard

Displays an existing card (if ObjId is specified) or allows creating a new card in the specified class.

This widget accepts three input configurations.

Configuration 1 — create a new card by class name

ClassName — string
ButtonLabel — string
ReadOnly — integer

Configuration 2 — open a card from a reference

Reference — reference
ButtonLabel — string
ReadOnly — integer

Configuration 3 — open a specific card by class name and ID

ClassName — string
ObjId — long
ButtonLabel — string
ReadOnly — integer

Output parameters

Reference — reference

Notes

The client: prefix is required to access a variable before the workflow advances to the next step
ReadOnly = 1 displays the card in read-only mode

Example:

ClassName = 'User'
ObjId = client:Requester
ButtonLabel = 'Create or modify User'

Create Report

Widget type: Widget_createReport

Allows generating a report.

Input parameters

ReportType — string
must be set to 'custom'
ReportCode — string
corresponds to the Code attribute of the report in the Report schedule
ButtonLabel — string
ForcePDF — integer
forces PDF output
ForceCSV — integer
forces CSV output
Parameter-1 ... Parameter-n — parameters required by the report

Output parameters

ReportURL — string

Manage Email

Widget type: Widget_manageEmail

Allows composing emails — from a template or from scratch — that will be sent when the process advances. When the widget is opened, the mailbox is checked for new incoming messages.

Input parameters

ButtonLabel — string
Template*1 ... Template*n — name of the email template used to generate the email
Condition*1 ... Condition*n — CQL condition that enables email creation with the corresponding template
NotifyWith*1 ... NotifyWith*n — name of the template used to send a notification email

Output parameters

None.

Open Note

Widget type: Widget_openNote

Displays a page with an HTML editor for inserting notes.

Input parameters

ButtonLabel — string

Notes

Cannot be used in the first process activity.

Open Attachment

Widget type: Widget_openAttachment

Displays a page for uploading an attachment to the current process.

Input parameters

ButtonLabel — string

Notes

Cannot be used in the first process activity.

Calendar

Widget type: Widget_calendar

Displays a calendar with selected dates.

Input parameters

ButtonLabel — string
ClassName — string
class from which to collect the dates to display
Filter — string
optional CQL filter applied to ClassName
EventStartDate — date
attribute to use as the event start date
EventEndDate — date (optional)
attribute to use as the event end date
EventTitle — string
attribute whose value is displayed as the event label in the calendar
EventType — string
attribute to use as the event type
EventTypeLookup — string
Lookup used for event types; typically the LookupType of the EventType attribute
DefaultDate — string
attribute to use as the calendar opening date

Preset From Card

Widget type: Widget_presetFromCard

Populates the current activity with data retrieved from a selected card.

Input parameters

ButtonLabel — string
ClassName — string
name of the source class; can be used as an alternative to Filter
Filter — string
CQL filter to restrict the source cards
AttributeMapping — string
maps activity attributes to card attributes using the format a1=c1,a2=c2 (comma-separated assignments)

Start Workflow

Widget type: Widget_startWorkflow

Starts a new workflow. Also referenced as Widget_workflow.

This widget accepts two input configurations.

Configuration 1 — start a workflow by code

ButtonLabel — string
WorkflowCode — string
name of the process to start

Configuration 2 — start workflows filtered by CQL

ButtonLabel — string
FilterType — string
Filter — string
CQL filter to select cards from a CMDBuild table; the result set must match the names of the processes to start

Output parameters

processRef — ReferenceType

Custom Form

Widget type: Widget_customForm

Manages a form or a row grid, with support for adding, removing, and modifying rows.

Input parameters

ButtonLabel — string
ModelType — [form | class | function]
defines the structure source:
- form — JSON item array
- class — attributes of a class
- function — function input parameters
Layout — [grid | form]
form renders as a CMDBuild card; grid renders as a row series
DataType — [raw_json | raw_text | function]
defines the data initialization source:
- raw_json — JSON item array
- raw_text — well-structured text string
- function — output values of a function
ReadOnly — [true | false]
Required — [true | false]
AddDisabled — [true | false]
DeleteDisabled — [true | false]
ImportDisabled — [true | false]
ModifyDisabled — [true | false]
SerializationType — [json | text]
output serialization format
KeyValueSeparator — string
AttributesSeparator — string
RowsSeparator — string

Output parameters

Output — string variable

manageEmail — Template String Reference

Widget_manageEmail supports template strings for composing dynamic email content. When the widget is opened, the mailbox is checked for new incoming messages.

Parameters

Input parameters

ButtonLabel — string
One or more email definition blocks, each containing:
- ToAddresses — string template
  recipient addresses
- CcAddresses — string template
  carbon copy addresses
- Subject — string template
  email subject
- Content — string template
  email body (HTML)
- Condition — string template
  JavaScript expression; if evaluated as false, the email is not generated
Additional optional parameters containing queries or JavaScript expressions
ReadOnly — flag
marks the email as read-only

Output parameters

None.

Notes

The ReadOnly flag is treated as a boolean: a boolean true, a positive integer, or a non-empty string are all considered true.

Template string namespaces

In template strings, variables use the syntax {namespace:localname}. If the namespace is omitted, it defaults to server.

client:name, client:name.Id, client:name.Description — form variable
for Lookup or Reference attributes, append .Id or .Description to specify which value to retrieve
server:name — process variable from the previous step
xa:name — extended attribute variable
expanded as a template; variables with namespace js and cql are excluded from expansion
user:id, user:name — ID and name of the connected user
group:id, group:name — ID and name of the connected group
js:name — extended attribute variable evaluated as a JavaScript expression
cql:name.field — extended attribute variable evaluated as a CQL query; the result field is identified by field

Email block definition

For a single email:

ToAddresses="..."
CcAddresses="..."
Subject="..."
Content="..."

For multiple emails, append a numeric suffix to each parameter:

ToAddresses1="..."
CcAddresses1="..."
Subject1="..."
Content1="..."

ToAddresses2="..."
CcAddresses2="..."
Subject2="..."
Content2="..."

Example 1

ToAddresses="foo@example.com"
Subject="{cql:QueryRequester.Description} - {client:Request}"
QueryRequester="select Description,Email,Office from Employee where Id = {cql:SillyQuery.Id}"
SillyQuery="select Id from Employee where Id={client:Requester}"

ToAddresses is set to the static address foo@example.com
Body is empty
Subject uses two variables:
- {cql:QueryRequester.Description} retrieves the Description field from the QueryRequester CQL result
- {client:Request} is replaced with the corresponding form value
QueryRequester selects an Employee card and exposes the fields Description, Email and Office
Inside QueryRequester, {cql:SillyQuery.Id} is resolved first, using the result of SillyQuery, which in turn uses {client:Requester} from the form — nested queries are supported

Example 2

Content="The requester, {js:JoinJS}, belonging to the office {cql:QueryRequester.Office_value} requests: {server:Request}"
JoinJS="{js:FirstJS}+"#"+{js:SecondJS}"
FirstJS="{cql:QueryRequester.Description}.slice(0,{xa:SplitLength})"
SecondJS="{cql:QueryRequester.Description}.slice({xa:SplitLength})"
SplitLength=2
QueryRequester="select Description,Email,Office from Employee where Id = {Requester}"

This is an example of higher complexity.

In the body there are three variables which must by replaced:

{js:JoinJS} values the extended attribute variable like a javascript expression, splitting with # the variables FirstJS and SecondJS, always valued through javascript
{js:FirstJS} and {js:SecondJS} include both a variable taken from a field of CQL query QueryRequester and a static variable taken from the ones of the extended attribute
{cql:QueryRequester\...} includes a reference to a server side variable called Requester
{cql:QueryRequester.Office_value} uses the Office reference description instead of its ID (that would be just Office)
{server:Request} takes a server side variable (as Requester), but it also states the namespace

Widget list​

Common configuration​

General notes​

Link Cards​

Create Modify Card​

Create Report​

Manage Email​

Open Note​

Open Attachment​

Calendar​

Preset From Card​

Start Workflow​

Custom Form​

manageEmail — Template String Reference​

Parameters​

Notes​

Template string namespaces​

Email block definition​

Example 1​

Example 2​

Widget list

Common configuration

General notes

Link Cards

Create Modify Card

Create Report

Manage Email

Open Note

Open Attachment

Calendar

Preset From Card

Start Workflow

Custom Form

manageEmail — Template String Reference

Parameters

Notes

Template string namespaces

Email block definition

Example 1

Example 2