Fields

---

Fields

The fields configuration is required when a form component is part of the widget. Each key is the field's unique name, referenced from form verticals and sections. Field names must also align with the payload keys of the associated service.

"fields": {
  "issue_title": {
    "label": "Title",
    "data": "title",
    "type": "textinput",
    "tooltip": "Enter a short descriptive title",
    "validation": {
      "required": true,
      "maxLength": 100,
      "errorMessage": "Title is required and must be under 100 characters"
    }
  },
  "issue_priority": {
    "label": "Priority",
    "type": "select",
    "options": ["Low", "Medium", "High"]
  },
  "issue_owner": {
    "label": "Owner",
    "type": "person",
    "data": "owner",
    "readonly": true
  }
}

Field properties

Property	Type	Required	Description
id	string	no	Unique identifier for the field. Used as the key when collecting form submission values. Falls back to name if not set.
name	string	no	Name identifier used in form state and change tracking. Falls back to id if not provided. Should be unique within the form.
label	string	no	Human-readable label displayed alongside the field.
type	string	no	Input type determining which component is rendered. See Field types. Defaults to textinput.
value	any	no	Initial or pre-populated field value. Use an array for dropbox and fileDropBox types; string or boolean for all others.
options	array<string>	no	List of selectable option values. Required for select and radio types.
tooltip	string	no	Helper text displayed alongside the field label to guide the user.
readonly	boolean	no	When true, the field is always rendered read-only even when the form is in edit mode.
hidden	boolean	no	When true, the field is hidden. Can also be controlled dynamically via visibility or conditional.
visible	boolean	no	Inverse of hidden. When false, the field is excluded from rendering. Prefer hidden or conditional for dynamic control.
data	string, array, or object	no	Data key(s) to select from the current dataset and present in the field. See Data selection.
services	array<string>	no	Service definition names called to load data into the graph before the field value is resolved.
loadingLabel	string	no	Text displayed in the field while its service is loading (e.g. "Loading...").
iconSelect	string	no	Data key pointing to an icon URL within the node data (e.g. "typeIcon"). Used with ICON_RENDERER.
dropMode	boolean	no	When true, enables the field as a drop target for drag-and-drop rows or items.
dropItemIdentifier	string	no	Property key used to uniquely identify dropped items in a dropbox field (e.g. "objectId"). Prevents duplicates.
preTransformer	object	no	JSON template applied to transform dropped items before storing in a dropbox field. Use {{key}} placeholders replaced with item properties.
validation	object	no	Validation rules applied on form submission. See Validation.
conditional	object	no	Declarative show/hide and enable/disable logic based on another field's value. See Conditional.
visibility	object	no	Alternative visibility control resolved against graph/dataset node values. See Visibility.
edit	object	no	Settings specific to edit mode. See Edit.
datahandler	object	no	Advanced data processing using a registered datahandler plugin. See Datahandler.
cellRenderer	object	no	Built-in or custom cell renderer for display. See Cell renderer.
valueFormatter	object	no	Transforms the raw value before display (e.g. relative date formatting). See Value formatter.
settings	object	no	Miscellaneous rendering and behaviour settings. See Settings.

Field types

Type	Description
textinput	Single-line text input (default when type is omitted).
textarea	Multi-line text input.
date	Date picker input.
checkbox	Boolean checkbox input.
radio	Radio button group. Requires options.
select	Dropdown select. Requires options.
person	Person/user display. Rendered read-only via PersonRenderer.
dropbox	Drag-and-drop item drop zone. Value is an array of dropped objects.
fileDropBox	File drag-and-drop or click-to-upload zone. Value is an array of File objects.
dynamic	Read-only display type for dynamically computed values.

Data selection

The data property specifies which value(s) to pull from the current dataset node.

Simple string — selects a single key:

"data": "title"

Array — selects multiple keys for multi-value display:

"data": ["title", "state"]

Object — advanced selection with dataset scoping or edge/node control:

"data": {
  "select": "title",
  "datasets": ["contextNode"],
  "isEdge": false
}

Array items can also be objects with additional filtering:

Property	Type	Description
select	string	Data key to select from the node.
rangeSelect	string	Key in the node containing range values.
nodeCondition	string	Cytoscape selector to restrict which nodes this selection applies to. Cannot be combined with datasets.
datasets	array<string>	Dataset names to scope this selection to.
isEdge	boolean	When true, selects from edges instead of nodes (object form only).

Validation

"validation": {
  "required": true,
  "minLength": 3,
  "maxLength": 50,
  "errorMessage": "Please enter between 3 and 50 characters"
}

Property	Type	Description
required	boolean	Field must have a non-empty value before the form can be submitted.
numeric	boolean	Value must be a valid number.
minLength	number	Minimum character length.
maxLength	number	Maximum character length.
errorMessage	string	Custom message shown when validation fails. Falls back to a built-in message if not provided.

Conditional

Controls visibility and enabled state based on another field's current value. Evaluated on every form change.

"conditional": {
  "dependsOn": "issue_type",
  "showWhen": ["Bug", "Defect"]
}

Property	Type	Description
dependsOn	string	The name (or id) of the field whose value drives this field's state.
showWhen	array<string>	Values of dependsOn that make this field visible. Hidden when value is not in the list.
hideWhen	array<string>	Values of dependsOn that hide this field.
enableWhen	array<string>	Values of dependsOn that enable this field. Disabled when value is not in the list.
disableWhen	array<string>	Values of dependsOn that disable this field.

Visibility

Alternative visibility mechanism resolved against graph/dataset node values (as opposed to conditional which operates on sibling field values within the form).

"visibility": {
  "dependsOn": "status",
  "dependsOnValue": ["Open", "InProgress"]
}

Property	Type	Description
dependsOn	string	The field id or name whose value determines visibility.
dependsOnValue	string or array<string>	The value(s) dependsOn must equal for this field to be shown. Any other value hides the field.

Edit

Settings applied specifically when the form is in edit mode.

Property	Type	Description
postUpdateNodeSelect	array<string>	Names of additional fields to refresh in the graph nodes after this field's value is changed.

Datahandler

Used for advanced data processing such as rollup calculations. Datahandlers are registered via custom resource plugins.

"datahandler": {
  "name": "rollup",
  "datahandlerProps": {
    "edgeStatement": "[type='VPMInstance']",
    "nodeStatement": "[type='VPMReference']"
  }
}

Property	Type	Required	Description
name	string	yes	Name of the registered datahandler. Currently supported: rollup.
datahandlerProps	object	no	Additional options passed to the datahandler.
datahandlerProps.edgeStatement	string	no	Cytoscape selector to filter specific edges before processing.
datahandlerProps.nodeStatement	string	no	Cytoscape selector to filter specific nodes before processing.

Cell renderer

Applies a built-in or custom renderer for the field's display value.

"cellRenderer": {
  "name": "AUTO_COLOR_RENDERER",
  "cellRendererProps": {
    "styleProp": "background",
    "customColorMappings": [
      { "value": "High", "color": "#FF0000" },
      { "value": "Low", "color": "#00AA00" }
    ]
  }
}

name value	Description
AUTO_COLOR_RENDERER	Colours the cell based on value mappings or numeric ranges.
PERSON_RENDERER	Renders a person/user chip with avatar.
ICON_RENDERER	Renders an icon based on the field value.

cellRendererProps

Property	Type	Description
styleProp	string	AUTO_COLOR_RENDERER only. How colour is applied: "color" (text) or "background".
colorize	boolean	ICON_RENDERER only. When true, the icon is colourized.
customColorMappings	array	AUTO_COLOR_RENDERER. Maps specific values or numeric ranges to colours.
customColorMappings[].value	string	The cell value to match.
customColorMappings[].color	string	Colour to apply. HEX values (e.g. #FF0000) automatically compute a matching foreground colour.
customColorMappings[].range	object	Numeric range to apply a colour to (upperLimit, lowerLimit, inclusive).
customIconMappings	array	ICON_RENDERER. Maps specific values to icon keys.
customIconMappings[].value	string	The data value to match.
customIconMappings[].icon	string	Icon key (e.g. "wux-ui-3ds-flag").
customIconMappings[].iconFamily	string	Icon family: "DSFontIcon" or "entypo".
customIconMappings[].color	string	Colour for the icon (e.g. "#FF0000").

Value formatter

Transforms the raw field value before display.

"valueFormatter": {
  "name": "relativeDate"
}

Property	Type	Required	Description
name	string	yes	Name of the registered value formatter (e.g. "relativeDate").
valueFormatterProps	object	no	Additional configuration options passed to the formatter.

Settings

Miscellaneous rendering and behaviour options.

Property	Type	Description
showFullName	boolean	person type. When false, the full name is shown only in a tooltip. Defaults to true.
dragAllAtOnce	boolean	When true, drags all related field data in one operation, including data from additionally selected rows.
usesAlternateOid	boolean	When true, makes the dataset data draggable.
styleCellValue	object	Applies inline CSS styling to the cell value.
renderAsMultiValue	boolean	When true, renders the value as a list of multiple values.
dateFormat	string	Date format pattern string (e.g. "YYYY-MM-DD").
dateFormatOptions	object	Locale-aware date formatting via Intl.DateTimeFormat. Alternative to dateFormat.
dateFormatOptions.locale	string	BCP 47 locale tag (e.g. "en-US", "fr-FR").
dateFormatOptions.options	object	Intl.DateTimeFormat options object with year, month, day string values.
fallbackValues	array<string>	Ordered list of data keys to try if the primary value is empty.