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. 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.
HideInCreation — boolean
When set to true, the widget is hidden when a new card is being created.
HideInEdit — boolean
When set to true, the widget is hidden when a card is being modified.
Inline — boolean
When set to true, the widget is rendered as an inline fieldset within the form rather than as a button opening a modal window.
InlineBefore — string
When Inline is enabled, specifies the name of an attribute whose fieldset the widget will be placed before.
InlineAfter — string
When Inline is enabled, specifies the name of an attribute whose fieldset the widget will be placed after.
InlineClosed — boolean
When set to true, the inline fieldset is rendered in a collapsed state by default.
Output — string
The name of the process variable where the widget's output is saved. Applies when the widget is used inside a process.
Required — boolean
When set to true, the widget is mandatory.
ViewRule — string
A script that defines the visibility rule of the widget.

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_linkCards

Input parameters

ClassName — 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
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
ReadOnly — integer

Configuration 2 — open a card from a reference

Reference — reference
ReadOnly — integer

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

ClassName — string
ObjId — long
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
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

Template_1 ... Template_n — string
name of the email template used to generate the email
Condition_1 ... Condition_n — string
CQL condition that enables email creation with the corresponding template
NotifyWith_1 ... NotifyWith_n — string
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.

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.

Notes

Cannot be used in the first process activity.

Calendar

Widget type: Widget_calendar

Displays a calendar with selected dates.

Input parameters

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

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

WorkflowCode — string
name of the process to start

Configuration 2 — start workflows filtered by CQL

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

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]
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

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 be replaced:

{js:JoinJS} evaluates the extended attribute variable as a JavaScript expression, joining FirstJS and SecondJS with #
{js:FirstJS} and {js:SecondJS} each combine a field from the QueryRequester CQL result with a static extended attribute variable
{cql:QueryRequester...} references a server-side variable called Requester
{cql:QueryRequester.Office_value} retrieves the description of the Office reference rather than its ID (which would be just Office)
{server:Request} explicitly states the server namespace to access a server-side variable

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