Script API

info

This content is intended for advanced Studio users.

Script API is a JavaScript API exposed on the Form renderer instance. It provides programmatic access to form fields, elements, values, validation, composition saving, page navigation, and more.

warning

Script API requires deep JavaScript knowledge, and scripts are generally harder to develop and maintain than dependencies defined in Form builder. Use dependencies where they are sufficient.

Access Script API by calling getScriptApi() on the renderer element reference after the onFormRendered event fires:

const scriptApi = fr.getScriptApi();

Values

Methods for reading and writing field values, variable values, and typed field values.

getFieldValue

Returns the value of a form field.

getFieldValue(tagOrPath, multiIndex, searchWithinContainerTag, containerMultiIndex, simpleValue)

Parameter	Type	Required	Default	Description
tagOrPath	string	Yes	—	Alias, path, or tag of the form field.
multiIndex	number	No	0	Index of the value.
searchWithinContainerTag	string	No	—	Tag of the parent container to search from.
containerMultiIndex	number	No	0	Index of the parent container instance.
simpleValue	boolean	No	true	When true, returns the label for CODED_TEXT fields for backwards compatibility.

Returns: Object | undefined

getFieldSearchValue

Returns the current search input value of a coded text field.

getFieldSearchValue(tagOrPath, multiIndex, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Default	Description
tagOrPath	string	Yes	—	Alias, path, or tag of the form field.
multiIndex	number	No	0	Index of the value.
searchWithinContainerTag	string	No	—	Tag of the parent container to search from.
containerMultiIndex	number	No	—	Index of the parent container instance.

setFieldValue

Sets the value of a form field.

setFieldValue(tagOrPath, value, prop, multiIndex, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Accepted values	Required	Default	Description
tagOrPath	string	—	Yes	—	Alias, path, or tag of the form field.
value	string, number, or array	—	Yes	—	Value or values to set.
prop	string	Property names	No	value	Property name of the form field.
multiIndex	number	—	No	—	Index of the value.
searchWithinContainerTag	string	—	No	—	Tag of the parent container to search from.
containerMultiIndex	number	—	No	0	Index of the parent container instance.

setDateField

Sets the value of a date field.

setDateField(tagOrPath, year, month, day, multiIndex, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Default	Description
tagOrPath	string	Yes	—	Alias, path, or tag of the form field.
year	number	Yes	—	Year value.
month	number	Yes	—	Month value.
day	number	Yes	—	Day value.
multiIndex	number	No	0	Index of the value.
searchWithinContainerTag	string	No	—	Tag of the parent container to search from.
containerMultiIndex	number	No	0	Index of the parent container instance.

setDateTimeField

Sets the value of a date-time field.

setDateTimeField(tagOrPath, year, month, day, hour, minute, multiIndex, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Default	Description
tagOrPath	string	Yes	—	Alias, path, or tag of the form field.
year	number	Yes	—	Year value.
month	number	Yes	—	Month value.
day	number	Yes	—	Day value.
hour	number	Yes	—	Hour value.
minute	number	Yes	—	Minute value.
multiIndex	number	No	0	Index of the value.
searchWithinContainerTag	string	No	—	Tag of the parent container to search from.
containerMultiIndex	number	No	0	Index of the parent container instance.

setTimeField

Sets the value of a time field.

setTimeField(tagOrPath, hour, minute, multiIndex, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Default	Description
tagOrPath	string	Yes	—	Alias, path, or tag of the form field.
hour	number	Yes	—	Hour value.
minute	number	Yes	—	Minute value.
multiIndex	number	No	0	Index of the value.
searchWithinContainerTag	string	No	—	Tag of the parent container to search from.
containerMultiIndex	number	No	0	Index of the parent container instance.

setProportionField

Sets the value of a proportion field.

setProportionField(tagOrPath, numerator, denominator, multiIndex, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Default	Description
tagOrPath	string	Yes	—	Alias, path, or tag of the form field.
numerator	number	Yes	—	Numerator value.
denominator	number	Yes	—	Denominator value.
multiIndex	number	No	0	Index of the value.
searchWithinContainerTag	string	No	—	Tag of the parent container to search from.
containerMultiIndex	number	No	0	Index of the parent container instance.

clearValue

Clears a specific value from fields that support selection values.

clearValue(tagOrPath, valueCode, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form field.
valueCode	string	Yes	Code of the value to clear.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

clearValues

Clears all values on the form.

clearValues()

clearFormElement

Clears the value of a form element. If the element is a container, clears all children.

clearFormElement(tagOrPath, options, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
options	ScriptApiClearOptions or string	Yes	Clear options or the parent container tag.
containerMultiIndex	number	No	Index of the parent container instance.

resetFormElement

Resets a form element to its default value.

resetFormElement(tagOrPath, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

getVariable

Returns the name and value of a variable.

getVariable(variableName)

Parameter	Type	Required	Description
variableName	string	Yes	Name of the variable.

Returns: Variable

setVariableValue

Sets the value of a specific variable.

setVariableValue(variableName, value)

Parameter	Type	Required	Description
variableName	string	Yes	Name of the variable.
value	any	Yes	Value to set.

clearVariableValue

Clears the value of a specific variable.

clearVariableValue(variableName)

Parameter	Type	Required	Description
variableName	string	Yes	Name of the variable.

formatDate

Formats a date value using a specified format string.

formatDate(date, format)

Parameter	Type	Required	Description
date	Date or number	Yes	The date to format.
format	string	Yes	Format string. See Event types.

Visibility and state

Methods for showing, hiding, enabling, disabling, and toggling form elements and individual input items.

showFormElement

Shows a form element. If the element is a container, shows all children.

showFormElement(tagOrPath, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

hideFormElement

Hides a form element. If the element is a container, hides all children.

hideFormElement(tagOrPath, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

hideAndClear

Hides a form element and clears its value.

hideAndClear(tagOrPath, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

toggleElement

Toggles a form element between hidden and visible states.

toggleElement(tagOrPath, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

disableFormElement

Disables a form element. If the element is a container, disables all children.

disableFormElement(tagOrPath, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

enableFormElement

Enables a form element. If the element is a container, enables all children.

enableFormElement(tagOrPath, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

showValue

Shows a specific input item.

showValue(tagOrPath, valueCode, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
valueCode	string	Yes	Code of the input item.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

hideValue

Hides a specific input item.

hideValue(tagOrPath, valueCode, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
valueCode	string	Yes	Code of the input item.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

hideClearValue

Hides and clears a specific input item simultaneously.

hideClearValue(tagOrPath, valueCode, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
valueCode	string	Yes	Code of the input item.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

disableValue

Disables a specific input item on a form element by code value.

disableValue(tagOrPath, valueCode, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
valueCode	string	Yes	Code of the input item to disable.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

enableValue

Enables a specific input item on a form element by code value.

enableValue(tagOrPath, valueCode, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
valueCode	string	Yes	Code of the input item to enable.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

Input items

Methods for adding, removing, and replacing coded text and form element input items, including setting values by label.

addFormElementInput

Adds input items to a form component of type DV_TEXT or DV_CODED_TEXT.

• For DV_TEXT: provide a plain text string.
• For DV_CODED_TEXT: provide an object or array of objects with label and code.

addFormElementInput(tagOrPath, inputItem, insertIndex, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
inputItem	{label: string; code: string}, array, or string	Yes	Input item or items to add.
insertIndex	number	No	Index at which to insert the item.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

removeFormElementInput

Removes a form element input item by code value.

removeFormElementInput(tagOrPath, inputItemCode, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
inputItemCode	string	Yes	Code of the input item to remove.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

addCodedTextInput

Adds an input item to a coded text field.

addCodedTextInput(tagOrPath, inputItemValue, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form field.
inputItemValue	InputItem	Yes	Input item object { label: string, code: string }.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance. Defaults to 0 if searchWithinContainerTag is set.

removeCodedTextInput

Removes a coded text input item by code value.

removeCodedTextInput(tagOrPath, inputItemCode, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form field.
inputItemCode	string	Yes	Code of the input item to remove.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

setCodedTextInputItems

Replaces all existing input items in a coded text field with a new set.

setCodedTextInputItems(tagOrPath, inputItems, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
inputItems	InputItem[]	Yes	Replacement input items.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

setCodedTextInputs

warning

Deprecated. Use addFormElementInput instead.

getFieldInputs

Returns input items (code/value pairs) for a form field. Returns an empty array if no model or value set is found.

getFieldInputs(tagOrPath, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form field.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

Returns: array

setCodedTextFieldByLabel

Sets the value of a coded text field by label. If multiple items share the same label, the first one is set.

setCodedTextFieldByLabel(tagOrPath, value, multiIndex, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form field.
value	string	Yes	Label value to set.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

setOrdinalFieldByLabel

Sets the value of an ordinal field by label. If multiple items share the same label, the first one is set.

setOrdinalFieldByLabel(tagOrPath, value, multiIndex, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form field.
value	string	Yes	Label value to set.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

setScaleFieldByLabel

Sets the value of a scale field by label. If multiple items share the same label, the first one is set.

setScaleFieldByLabel(tagOrPath, value, multiIndex, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form field.
value	string	Yes	Label value to set.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

removeValue

Removes a specific value from DV_ORDINAL, GENERIC_ORDINAL, DV_CODED_TEXT, GENERIC_CODED_TEXT, DV_TEXT (with values), or GENERIC_INPUT_TEXT (with values).

removeValue(tagOrPath, inputItemCode, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form field.
inputItemCode	string	Yes	Code of the input item to remove.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

Multiplicity and containers

Methods for managing container instances, expand and collapse states, and multiplicity buttons.

setMultiplicity

Sets the exact number of instances rendered for a form element. More convenient than setting both min and max when you need a specific count.

setMultiplicity(tagOrPath, multiplicity, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
multiplicity	number	Yes	Exact number of instances to render.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

setMinMultiplicity

Sets the minimum multiplicity of a form element.

setMinMultiplicity(tagOrPath, minMultiplicity, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
minMultiplicity	number	Yes	Minimum multiplicity value.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

setMaxMultiplicity

Sets the maximum multiplicity of a form element.

setMaxMultiplicity(tagOrPath, maxMultiplicity, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
maxMultiplicity	number	Yes	Maximum multiplicity value.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

duplicateModel

Duplicates the model of a form element.

duplicateModel(tagOrPath, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

Returns: ModelDuplicate

removeModel

Removes a model or field from the form.

removeModel(tagOrPath, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form field.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

expandFormElement

Expands a container element. Optionally targets a specific multi-container instance.

expandFormElement(tagOrPath, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
multiIndex	string	Yes	Index of the container instance to expand.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

collapseFormElement

Collapses a container element. Optionally targets a specific multi-container instance.

collapseFormElement(tagOrPath, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
multiIndex	string	Yes	Index of the container instance to collapse.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

expand

warning

Deprecated. Use expandFormElement instead.

collapse

warning

Deprecated. Use collapseFormElement instead.

showContainerMultiButtons

Shows the multiplicity buttons on a container element.

showContainerMultiButtons(tagOrPath, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
multiIndex	string	Yes	Index of the container instance.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

hideContainerMultiButtons

Hides the multiplicity buttons on a container element.

hideContainerMultiButtons(tagOrPath, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
multiIndex	string	Yes	Index of the container instance.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

Validation

Methods for validating the form, pages, and individual elements, checking element state, clearing errors, and applying custom validation rules.

validateForm

Validates the entire form and returns a validation result with an errors map.

validateForm(showErrors)

Parameter	Type	Required	Description
showErrors	boolean	No	Specifies whether to show errors on fields.

Returns: Object

validatePage

Validates a page and shows validation errors on it.

validatePage(pageId)

Parameter	Type	Required	Description
pageId	string	Yes	ID of the page.

Returns: boolean

validateElement

Validates a form element and optionally shows errors on the field.

validateElement(tagOrPath, searchWithinContainerTag, containerMultiIndex, showErrors)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.
showErrors	boolean	No	Specifies whether to show errors on the field.

Returns: boolean

isElementValid

Validates a form element and returns the result without showing errors.

isElementValid(tagOrPath, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

Returns: boolean

isPageValid

Validates a page and returns the result.

isPageValid(pageId)

Parameter	Type	Required	Description
pageId	string	Yes	ID of the page.

Returns: boolean

isFormDirty

Returns true if the user has interacted with the form.

isFormDirty()

Returns: boolean

isEmpty

Returns true if the specified element has no value.

isEmpty(tagOrPath, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form field.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

Returns: boolean

isNotEmpty

Returns true if the specified element has a value.

isNotEmpty(tagOrPath, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form field.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

Returns: boolean

clearValidationErrors

Clears validation errors from a form element.

clearValidationErrors(tagOrPath, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

clearPageValidationErrors

Clears validation errors on a page.

clearPageValidationErrors(pageName)

Parameter	Type	Required	Description
pageName	string	Yes	Alias, path, or tag of the page element.

requireFormElement

Marks a form element as required or optional.

requireFormElement(tagOrPath, value, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
value	boolean	Yes	true to mark as required, false to mark as optional.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

setPatternValidation

Applies a custom regex pattern validation and error message to a field.

setPatternValidation(tagOrPath, pattern, errorMessages, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Path or tag of the form element.
pattern	string	Yes	Regex pattern.
errorMessages	string or Record<string, string>	Yes	Error message or language-keyed map, e.g. { en: 'Error', fr: 'Erreur' }.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

removePatternValidation

Removes a custom regex validation from a field.

removePatternValidation(tagOrPath, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

addValidator

Attaches a custom validator function to a field. The validator runs on every value change and must return true when the value is invalid, or false / null when it is valid.

addValidator(tagOrPath, validator, options)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form field.
validator	(value: unknown) => boolean | null	Yes	Validator function. Return true for invalid, false or null for valid.
options	object	No	See options below.

options

Key	Type	Required	Description
errorTranslation	string or Record<string, string>	No	Error message, or language-keyed map e.g. { en: 'Invalid', de: 'Ungültig' }. Defaults to 'Field invalid'.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

markDirty

Marks a form field as dirty and triggers validation. Use this to programmatically surface validation errors before the user interacts with the field.

markDirty(tagOrPath, options)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form field.
options	object	No	See options below.

options

Key	Type	Required	Description
multiIndex	number	No	Index of the field instance.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

markPristine

Marks a form field as pristine, resetting its dirty state. Validation errors that are only shown after user interaction are hidden.

markPristine(tagOrPath, options)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form field.
options	object	No	See options below.

options

Key	Type	Required	Description
multiIndex	number	No	Index of the field instance.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

Events and listeners

Methods for registering and removing field-level and variable-level event listeners, and for destroying all event handlers on the instance.

addListener

Registers an event listener on a form element.

addListener(tagOrPath, eventType, callbackFn, optionsParam)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
eventType	string	Yes	See Event types.
callbackFn	OnChangeFieldValue	No	Callback function.
optionsParam	ScriptApiListenerOptions	No	See Types.

removeListener

Removes an event listener from a form element.

removeListener(tagOrPath, eventType)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
eventType	string	Yes	See Event types.

addListenerForVariable

Registers an event listener on a specific variable.

addListenerForVariable(variableName, eventType, callbackFn)

Parameter	Type	Required	Description
variableName	string	Yes	Name of the variable.
eventType	string	Yes	See Event types.
callbackFn	OnChangeFieldValue	No	Callback function.

Returns: Array<Observable>

destroy

Destroys all event handlers on the form element.

destroy()

dispatchCustomEvent

Outputs an object { type: "CUSTOM_EVENT", payload: {} } from the form-renderer element, that can be captured by the parent application via the eventDispatched output.

dispatchCustomEvent(payload)

Parameter	Type	Required	Description
payload	unknown	Yes	Output payload.

Composition

Methods for saving, updating, and reading the composition, managing save lifecycle hooks, and setting composition-level metadata.

saveComposition

Saves the composition to the server.

saveComposition(validate, incomplete, requestParams)

Parameter	Type	Required	Default	Description
validate	boolean	No	true	Validates the form before saving.
incomplete	boolean	No	false	Saves the composition as incomplete.
requestParams	object	No	—	Additional request parameters: comment, committerName, committerId, termMappingsFor, lifecycleState, locale.

Returns: Promise

updateComposition

Updates an existing composition on the server.

updateComposition(validate, incomplete, requestParams)

Parameter	Type	Required	Default	Description
validate	boolean	No	true	Validates the form before updating.
incomplete	boolean	No	false	Updates the composition as incomplete.
requestParams	object	No	—	Additional request parameters: comment, committerName, committerId, termMappingsFor, lifecycleState, locale.

Returns: Promise

getComposition

Returns the current composition instance.

warning

Changes made to the returned instance are also applied to the saved composition.

getComposition()

Returns: object

addPreSaveHook

Registers a callback that executes before each save or update.

addPreSaveHook(hookName, callbackFn, hookOptions)

Parameter	Type	Required	Description
hookName	string	Yes	Name of the hook.
callbackFn	function	No	Callback function.
hookOptions	PreSaveHookOptions	No	See Types.

addPostSaveHook

Registers a callback that executes after the composition is saved.

addPostSaveHook(hookName, callbackFn)

Parameter	Type	Required	Description
hookName	string	Yes	Name of the hook.
callbackFn	function	Yes	Callback function.

addTag

Adds a tag to the composition.

addTag(name, value)

Parameter	Type	Required	Description
name	string	Yes	Tag name.
value	string	Yes	Tag value.

setFormSubmissionType

Sets the submission type of the form.

setFormSubmissionType(submissionType)

Parameter	Type	Required	Description
submissionType	SubmissionType	Yes	CREATE or UPDATE.

setFormLanguage

Sets the language of the form.

setFormLanguage(language)

Parameter	Type	Required	Description
language	string	Yes	Language code to set.

Navigation

Methods for navigating between pages and scrolling to specific elements.

goTo

Navigates to a specified page or summary page by ID.

goTo(pageId)

Parameter	Type	Required	Description
pageId	string	Yes	ID of the page or summary page to navigate to.

goToNext

Navigates to the next page.

goToNext()

goToPrevious

Navigates to the previous page.

goToPrevious()

scrollToElement

Scrolls to a form element. If the element is not found, the method completes without action.

scrollToElement(tagOrPath, searchWithinContainerTag, containerMultiIndex, scrollOptions)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.
scrollOptions	ScrollIntoViewOptions	No	Controls scroll behaviour.

Field metadata

Methods for reading field and form-level metadata, managing labels, annotations, feeder audit, image areas, and terminology.

getFieldModel

Returns the model instance of a form field.

getFieldModel(tagOrPath, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form field.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

Returns: FormElement

getValueRef

Returns the model instance of a form element.

warning

Changes made to the returned instance are also applied to the form element model.

getValueRef(tagOrPath, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

Returns: FormElement or FormElement[]

getFieldPosition

Returns the position of a field in the form.

getFieldPosition(tagOrPath, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form field.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

Returns: number

getFormInfo

Returns metadata about the current form.

getFormInfo()

Returns: FormInfo

getSummaries

Returns an array of summary objects, each containing name, id, and an array of tags.

getSummaries()

Returns: array

getOrdinalNumberValue

Returns the selected ordinal number of an ordinal field.

getOrdinalNumberValue(tagOrPath, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form field.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

Returns: number | undefined

getScaleNumberValue

Returns the selected scale number of a scale field.

getScaleNumberValue(tagOrPath, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form field.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

Returns: number | undefined

setFieldLabel

Sets the label of a form field.

setFieldLabel(tagOrPath, value, language, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Default	Description
tagOrPath	string	Yes	—	Alias, path, or tag of the form field.
value	string or number	Yes	—	New label value.
language	string	Yes	en	Locale for the label.
searchWithinContainerTag	string	No	—	Tag of the parent container to search from.
containerMultiIndex	number	No	0	Index of the parent container instance.

setAnnotation

Sets an annotation on a model.

setAnnotation(tagOrPath, key, value, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
key	string	Yes	Annotation key.
value	string	Yes	Annotation value.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

removeAnnotation

Removes an annotation from a model.

removeAnnotation(tagOrPath, key, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form element.
key	string	Yes	Key of the annotation to remove.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

getFeederAudit

Returns the FeederAudit for the given template.

getFeederAudit(templateId)

Parameter	Type	Required	Description
templateId	string	No	Template ID.

Returns: FeederAudit

setFeederAudit

Sets a FeederAudit parameter and its value.

setFeederAudit(param, value, templateId)

Parameter	Type	Required	Description
param	string	Yes	FeederAudit parameter to set.
value	string, number, object, or array	Yes	Value of the parameter.
templateId	string	No	Template ID.

getImageAreas

Returns image map areas defined on an Interactive image field. Returns undefined if more than one model is defined for the field.

getImageAreas(tagOrPath, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form field.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

Returns: ImageArea[]

setImageAreas

Sets new areas for an Interactive image field. If the field is not of type DV_CODED_TEXT, the method completes without action.

setImageAreas(tagOrPath, areas, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the field.
areas	ImageArea[] or Object[]	Yes	New areas to render on the image.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

getTerminologySelectedValues

Returns the selected terminology values for a field.

getTerminologySelectedValues(tagOrPath, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form field.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

Returns: Observable

setTerminologyParameter

Sets a terminology parameter on a form field.

setTerminologyParameter(tagOrPath, paramName, paramValue, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the form field.
paramName	string	Yes	Name of the terminology parameter.
paramValue	string	Yes	Value of the terminology parameter.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

Widgets

Methods for interacting with custom widgets embedded in the form.

sendActionToWidget

Sends an action to a widget.

sendActionToWidget(tagOrPath, action, value, searchWithinContainerTag, containerMultiIndex)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the widget.
action	object	Yes	Action to send to the widget.
value	object	Yes	Value to send alongside the action.
searchWithinContainerTag	string	No	Tag of the parent container to search from.
containerMultiIndex	number	No	Index of the parent container instance.

setWidgetConfig

Sets the configuration of a widget.

setWidgetConfig(tagOrPath, config)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the widget.
config	object	Yes	Configuration object for the widget.

API and data

Methods for calling API connectors and data connectors, executing AQL queries, retrieving views, and refreshing data sources.

callApi

Calls a predefined API connector or data connector by name.

callApi(apiName, apiCallName, force)

Parameter	Type	Required	Description
apiName	string	Yes	Name of the API connector or data connector.
apiCallName	string	Required for API connectors	Name of the API call.
force	boolean	No	Bypasses the cache and forces a fresh call. Defaults to true.

Returns: Promise

executeAql

Executes an AQL query.

executeAql(aql, params, force)

Parameter	Type	Required	Description
aql	string	Yes	The AQL query to execute.
params	Map<string, any>	No	Map of query variable values.
force	boolean	No	Invalidates the cache when true.

Returns: Promise

getAqlView

Retrieves an AQL view by name.

getAqlView(viewName)

Parameter	Type	Required	Description
viewName	string	Yes	Name of the AQL view.

Returns: Promise

getApiRequestPayload

Returns the API request payload for a given API connector and call. Variables in the payload are not resolved at retrieval time.

getApiRequestPayload(apiName, apiCallName)

Parameter	Type	Required	Description
apiName	string	Yes	Name of the API connector or data connector.
apiCallName	string	No	Name of the API call.

Returns: unknown

setApiRequestPayload

Sets the API request payload for an API connector or data connector.

good to know

When using this method with a data connector, the second parameter (apiCallName) can be an empty string or undefined.

setApiRequestPayload(apiName, apiCallName, payload)

Parameter	Type	Required	Description
apiName	string	Yes	Name of the API connector or data connector.
apiCallName	string	Yes	Name of the API call.
payload	unknown	Yes	Payload for the API request.

Returns: unknown

extractDataFromApiResponse

Extracts a value from an API response by key.

extractDataFromApiResponse(response, keyName)

Parameter	Type	Required	Description
response	any	Yes	The API response object.
keyName	string	Yes	Key to extract from the response.

Returns: any

refreshData

Re-fetches data for a widget or field with a defined data source.

refreshData(tagOrPath, searchWithinContainerTag)

Parameter	Type	Required	Description
tagOrPath	string	Yes	Alias, path, or tag of the widget or field.
searchWithinContainerTag	string	No	Tag of the parent container to search from.

Frequently asked questions (FAQs)

What is Script API?

Script API is a JavaScript API exposed on the Form renderer instance that lets you interact with a rendered form programmatically — reading and setting field values, showing or hiding elements, managing multiplicity, saving compositions, navigating pages, and more.

When can I start using Script API?

Script API is safe to use after the onFormRendered event fires. Calling it before that point may produce unexpected results.

How do I access Script API?

Call getScriptApi() on the form-renderer element reference. In framework-agnostic apps: fr.getScriptApi(). In Angular: this.formRenderer.nativeElement.getScriptApi().

When should I use Script API instead of dependencies?

Use Script API for cases that cannot be expressed as dependencies in Form builder — for example, complex conditional logic that depends on external application state, or interactions requiring asynchronous operations. Dependencies are simpler to maintain and should be preferred where they are sufficient.

How do I get the value of a field?

Use getFieldValue(tagOrPath). For type-specific reads such as ordinal or scale fields, use getOrdinalNumberValue or getScaleNumberValue respectively.

How do I show or hide a field programmatically?

Use showFormElement and hideFormElement. To hide and clear the value at the same time, use hideAndClear. To toggle between hidden and visible, use toggleElement.

How do I save a composition from Script API?

Use saveComposition(validate, incomplete, requestParams). The method returns a promise. Pass false as the first argument to skip validation before saving.

How do I replace the input items in a coded text field?

Use setCodedTextInputItems to replace all existing items with a new set. To add items without replacing existing ones, use addFormElementInput.

How do I control how many instances of a container are rendered?

Use setMultiplicity to set an exact count, or use setMinMultiplicity and setMaxMultiplicity to set bounds independently.