This article describes the scripting functionality which can be used for data manipulation and validation in forms for objects and process tasks.

1 Introduction
2 Script Scope
- 2.1 Properties of 'scope'
- 2.2 scope.data
  - 2.2.1 Check situation
- 2.3 scope.situation
  - 2.3.1 Check situation
- 2.4 scope.model
  - 2.4.1 Field Properties
    - 2.4.1.1 Sample script: onChange handler for form validation and user input
      - 2.4.1.1.1 Example: onChange handler for form validation and user input
  - 2.4.2 Data Types – Field Properties
  - 2.4.3 Data Type-Specific Properties
    - 2.4.3.1 STRING
      - 2.4.3.1.1 Dynamic lists (Selection)
    - 2.4.3.2 NUMBER
    - 2.4.3.3 DATETIME
      - 2.4.3.3.1 Sample Script: Specifying a Date in the Future
      - 2.4.3.3.2 Example: Validate a date in the future
    - 2.4.3.4 DATE
      - 2.4.3.4.1 Important to know:
    - 2.4.3.5 CODESYSTEM
      - 2.4.3.5.1 Reducing the selectable CODESYSTEM elements by filtering
    - 2.4.3.6 ORGANIZATION
      - 2.4.3.6.1 Reducing the Selectable ORGANIZATION Elements by Filtering
      - 2.4.3.6.2 Example
    - 2.4.3.7 ID References
      - 2.4.3.7.1 Performe filtering on context objects
      - 2.4.3.7.2 Reducing the Selectable ID Reference Elements by Filtering
      - 2.4.3.7.3 Filter example
      - 2.4.3.7.4 Filter example
    - 2.4.3.8 TABLE
      - 2.4.3.8.1.1 Sample script: Manipulating table data
      - 2.4.3.8.2 Example: Manipulating table data
      - 2.4.3.8.3 Callback for Table
      - 2.4.3.8.4 The row Object
        2.4.3.8.4.1 Sample script: Table row scripting
      - 2.4.3.8.5 Example: Table row scripting (onrowedit)
      - 2.4.3.8.6 onChange Handler for Table Cells
      - 2.4.3.8.7 Example: onChange handler for a table cell
      - 2.4.3.8.8 rowmodel: Applying a Filter to an Organization Element that is Used as a Table Element
      - 2.4.3.8.9 Example: Apply filter to organization objects in table rows
      - 2.4.3.8.10 Manipulating Row Cells when one Cell Has Been Changed
      - 2.4.3.8.11 Manipulating Multiple Row Cells
      - 2.4.3.8.12 Handling an Empty List as Erroneous (not Null)
      - 2.4.3.8.13 Scripts for BPM Forms
    - 2.4.3.9 Mapping BPM Data Types to DMS Data Types
  - 2.4.4 Reading and Setting Feasibility of Activity Actions
- 2.5 scope.objects
  - 2.5.1 BPM Start Form
  - 2.5.2 BPM Task Form
- 2.6 scope.api
- 2.7 scope.context
3 Using Global Scripts
- 3.1 Creating Global Scripts in yuuvis® RAD designer
  - 3.1.1 Small global script
- 3.2 Using Global Scripts in Form Scripts
  - 3.2.1 Form script using a global script
- 3.3 Sample Global Scripts
  - 3.3.1 Using General Help Functions in Form Scripts
    - 3.3.1.1 Example: Global Form Utilities
  - 3.3.2 Calculation Function Example
    - 3.3.2.1 Example: Simple calculations
  - 3.3.3 Using Global Scripts
    - 3.3.3.1 Example: Form script
4 Tips & Tricks
- 4.1 How to Avoid Rounding Errors
- 4.2 International Values
- 4.3 Value Changes With Action
- 4.4 Debugging Scripts
- 4.5 Chrome
- 4.6 Firefox
- 4.7 Internet Explorer
  - 4.7.1 Example: Messages

Introduction

In yuuvis® RAD client, you can use executable scripts to:

validate data
change data, for example by calculating a value based on other values
change field properties, such as read-only and required
show context-related messages.

Some things to note about script properties:

Client scripts in yuuvis® RAD designer are written in JavaScript (ECMAScript)
Client scripts execute in the user's browser using the browser's native JavaScript runtime
You can define client scripts by object type and form situation, and by process model and activity forms
You can save script functions in global scripts to reuse them or include them in client scripts

Note: When field data changes are made using a script (i.e., without user action) when loading the form, the Save option is not available. In contrast, you can disable fields to protect against user changes.

Script Scope

The relevant object is given to each client script under the name 'scope.' This object provides the API so the scripts can access the object fields and their properties.

Properties of 'scope'

Name	Description

Name	Description
api	Supplies access to the plug-in API, with 'session' (user information), 'dms' (object details, search via DMS-Service), 'http' (connection to any service), 'config', 'util' (helper functions) and 'agent' properties.
data	Supplies all object fields defined in the object or process activity. The fields offer read-only access using the technical name. Available for release 2017-09-27 (3.22.x) or later.
model	Supplies the flattened form model and all object fields defined on the form. The fields can be accessed with the technical name. The form groups cannot be accessed in this way.
situation	Supplies the current form model situation. Scripts can respond to the relevant situation. Possible values are 'CREATE' (create), 'SEARCH' (search) and 'EDIT' (edit index data).
objectId	Supplies the ID of the current DMS object if available (available since version 6.4).

`scope.data`

Even when not defined in the form (object forms as well as process task forms), you can access object field data or process variables by using this part of the scope. Use the technical name of the object type field or process model variable to read its value, as shown in the following example.

Check situation

if (scope.data.status) {			// only fields not NULL are in the data object, so check for existence
	if (scope.data.status == 'active') { ... }
}

`scope.situation`

For object types, you can create a default form to be used for the situations CREATE, EDIT and SEARCH. In each situation, any included scripts are active.

If a general form is used, but different data management is necessary, it is possible to check which situation is given.

For example, how to deactivate a form script to be used in the situation 'SEARCH.'

Check situation

if( scope.situation == 'SEARCH' ) return;      // other situation values are EDIT and CREATE
// ... additional script code

`scope.model`

This section describes how to access all form elements of objects or processes.

Field Properties

The following table describes object field properties that can be accessed with 'scope.model'.

Column "Binding"

RO (ReadOnly): ReadOnly properties can only be read. Changes to the values of RO properties do not affect the interface.
RW (ReadWrite): ReadWrite properties can also be written. Changes to the values of RW properties affect the interface.

Each field has the following properties:

Name	Description	Binding

Name	Description	Binding
name	The normalized name of the fields. Normalized means the simple field name is lower case. The name must not contain special characters. This name is used to map the fields to the 'model.'	RO*
qname	The qualified name. Always <normalized type name>.'name' Warning: The script leads to an error if qnames are not completely written in lower case	RO
label	The display name of the type in the current user locale. Used as a field identifier.	RO
description	The field description is shown below the form field. Beginning with version 10.0 and hotfix 6 of version 9.16 LTS this field is RW	RO RW
type	Describes the data type of the field. The possible values here are documented in the description of field data types. Other field attributes may exist, depending on the data type.	RO
readonly	If the readonly property is set to 'true,' the user cannot change the field value.	RW**
required	Flags a field as mandatory. If this property is set, the user must make an entry.	RW
value	The current value of the field.	RW
multiselect	If this property for fields is set up in the schema, lists of values can be maintained. A JavaScript array is then always expected in 'value.' Not every data type supports the 'multiselect' property.	RO
RO (ReadOnly): ReadOnly properties can only be read. Value changes of RO properties do not affect the interface. *RW (ReadWrite): ReadWrite properties can also be written. Value changes of RW properties affect the interface.

The following example validates dynamic field properties for required fields and write permissions.

Sample script: onChange handler for form validation and user input

Example: onChange handler for form validation and user input

Attention: Beginning with version 10.16 LTS you need to adapt your scripts in forms for the situation SEARCH:
add .value[0] to all statements ending with .value, for example: m.weekdays.value.value[0]=m.weekdays.value.value[0]/8

// Abbreviate with 'm' in the FormModel of the scope.
// You could just use 'scope.model' everywhere instead of 'm'.
var m=scope.model;
// We want to know if the active state changes
// To do so, we register an onchange handler function
m.aktiv.onchange=updateActiveState;
// The logic should also run when there are changes in the area, since we want to
// control the error state of the script here.
m.bereich.onchange=updateActiveState;
// When the weekly hours change, we want to know this for our calculation
m.weekhours.onchange=updateWeekdays;
// Here is the logic implementation for what happens when the active state changes
function updateActiveState() {
  // Track the current active state - as an abbreviation.
  var active = m.active.value;
   
  // Employee initials + status + employee number are required fields,
  // when the employee is active.
  m.emplshort.required      = active;
  m.status.required         = active;
  m.personnelno.required     = active;
   
  // The regulations cannot be changed as long as the employee is active.
  m.unbefristet.readonly        = active;
  m.zielvereinbarung.readonly   = active;
  m.altersvorsorge.readonly     = active;
   
  // Example for a deliberately-set validation error with relevant error message
  // take into account that the error message will be offered for non read-only fields!
  if( active && (!m.area.value || m.area.value=='') ) {
    m.area.error = {msg:'Ein aktiver Mitarbeiter muss einem Bereich zugeordnet sein.'};
  } else {
    // If the validation error does not occur, we may have to reset a previously-set error:
	if (scope.user) {
	    scope.model.area.error = null;
	}
    m.area.error = null;
  }
}
// Here we calculate the weekdays
function updateWeekdays() {
    m.weekdays.value=m.weekdays.value / 8;
}
// Since the active/not active logic should already apply during form initialization,
// we call the function here.
updateActiveState();

Data Types – Field Properties

The following table gives an overview of the possible data types per field. The JavaScript data type lists what is expected as the 'value' of an element.

If the 'multiselect' property is set, then the JavaScript data type is an array of the data type.

Name	Description	JavaScript data type	Multi-selection

Name	Description	JavaScript data type	Multi-selection
STRING	Any text. See also datatype: STRING.	String	Yes
NUMBER	Number and floating point number. See also datatype: NUMBER.	Number	No
BOOLEAN	Simple 'on/off' or 'true/false' value.	Boolean	No
DATETIME	A date or a date with time value. See also datatype: DATETIME.	Date	No
CODESYSTEM	An entry from a catalog. See also datatype: CODESYSTEM.	String Must correspond with the 'data' property in the codesystem.	Yes
TABLE	A table with values. See also datatype: TABLE.	Object Array Properties of each object are defined by the column elements of the table.	No
ORGANIZATION	User or group in the organization tree. See also datatype: ORGANIZATION.	String Corresponds to the technical name of the object in the organization. Currently user or group names. For users, this name corresponds to the user's login name.	Yes

Data Type-Specific Properties

STRING

Name	*DMS description (DMS only) 1**	Binding

Name	*DMS description (DMS only) 1**	Binding
maxlen	The maximum number of characters permitted as a value in this field.	RO*
minlen	The minimum number of characters permitted as a value in this field.	RO
classification	If available, a specific type of text field is described. 'email' to handle this as e-mail input field 'url' to handle this as web address input field 'selector' to handle this as a selection field that can be filled by scripting	RO
RO (ReadOnly): ReadOnly properties can only be read.Changes to values of RO properties do not affect the interface. *RW (ReadWrite): ReadWrite properties can also be written. Changes to values of RW properties affect the interface.

*1: Starting with release 4.3 and in case of BPM, regular expressions can be used for controlling minlen and maxlen, e.g.:

for at least 5 characters:
^.{5,}$

for maximum of 10 characters:
^.{,10}$

for at least 5 and maximum of 10 characters:
^.{5,10}$

for at least 5 letters:

^[a-zA-Z.]{5,}$ etc.

Dynamic lists (Selection)

As with catalog fields, string fields with the api-classification 'selector' are handled by displaying a selection list and selection dialog. You can set the list values using a script.

Note that in yuuvis® RAD designer, the classification is called 'Dynamic list' in English and 'Dynamische Liste' in German.

Important Note

Lists with more than 1,000 elements can lead to delays when opening the selection dialog.

In German only: Webinar on how to use microservices for dynamic lists.

// 1st example: fill a selection list simply
var costcenter = scope.model.costcenter;
costcenter.setList({
	config: {			// configuration with respect to the behavior of the catalog fields 
		allelementsselectable: true,     // use false to only allow to select subentries
		valueField: 'costvalue',         //optional, if not given, the name 'value' is used
		subEntriesField: 'subentries',   //optional, if not given, the name 'entries' is used
        descriptionField: 'descr'        //optional, if not given, the name 'description' is used
	},
	entries: [    // prepare a tree
		{
            costvalue: '4711',
            subentries: [
                {
                    costvalue: '1',
					descr: "Value 1"
                },
                {
                    costvalue: '2',
					descr: "Value 2"
                }
            ]
        },
        {
            costvalue: '4712',
            subentries: [
                {
                    costvalue: '3',
					descr: "Value 3"
                },
				{
					costvalue: '4',
					descr: "Value 4"
				}
            ]
		}
	]
});

// 2nd example: first prepare a flat list variable and a reference to it
var cclist = [];              // this prepares the list 'cclist' with values to be passed to the field 'costcenter' as list 'entries'
for (j = 1; j < 10; j++) {
	for (i = 0; i < 1000; i++) {
		cclist.push({
			value: j*1001000 + i + 1 + ''   // the empty string at the end results in a string format of the value
		});	
	};
};

var costcenter = scope.model.costcenter;
costcenter.setList({
	config: {
		allelementsselectable: true     // optional, default is 'true'; if a hierarchical list is set to 'false', only leaves are selectable
	},
	entries: cclist
});

// 3rd example: lists can be filled by HTTP Request (see also later chapter)
// find in object type 'accounts' where in its field 'costcenter' the value of the variable 'costcenter' is given 
// and generate a list with the value of the fields 'accountno' and 'description
scope.api.dms.getResult({costcenter:costcenter.value},'accounts').then(         // remark: this must be 'then' because 'await' is currently not supported
	function(result) {
		var acnolist = [];
			result.forEach(function(row) {
				if( row.data.accountno ) {
					acnolist.push({
						value: row.data.accountno+' '+row.data.acdescription
					})
				}
			});
			accountno.setList({
				config: {
					allelementsselectable: true
				},
				entries: acnolist
			};
	}),
	function(error) {
		scope.api.util.notifier.error('Failed',error);
	}
);

// 2.b example for tables:

scope.model.etlapositions.onrowedit=function(table,row) {
	row.model.etlacostcenter.setList({
		config: {
			allelementsselectable: true
		},
		entries: [
			{
            	value: '4711'
	        },
    	    {
        	    value: '4712'
			}
		]
	}
}

// 4th example: filling the description depending on the user settings for 'definition language' and different entries for the form situation similar to the standard catalog behavior
var qadynlist = scope.model.myfieldname; 
var myRequest={};							// for search situation take all entries
if ( scope.situation == 'CREATE' ) { 
	 myRequest={create:true};				// for create situation take only those entries where the field 'create' is checked
}
if ( scope.situation == 'EDIT' ) {
	 myRequest={edit:true};					// for edit situation take only those entries where the field 'edit' is checked
}
scope.api.dms.getResult(myRequest,'qadynlist').then(       // remark: this must be 'then' because 'await' is currently not supported
	function(result) {
		var dynlist = [];
		result.forEach(function(row) {
			if( row.data.qavalue ) {
				dynlist.push({
					value: row.data.qavalue,
					description: row.data[scope.api.session.getUser().schemaLocale]    // this feature is available beginning with release 2017-09-13 (3.21.x)
				});
			};
		});
		qadynlist.setList({
			entries: dynlist
		});
	},
	function(error) {
		scope.api.util.notifier.error('Could not values',error);
	}
);

// 5th example: fill dynamic list with favorites data

scope.api.http.get('/service/user/favorites','/rest-ws').then(            // remark: this must be 'then' because 'await' is currently not supported
	function(result) {
	    var favslist=[];
		_.forEach(result.data, function(row) {          // row gets all relevant objects
			favslist.push({
				value: row.title
			});
		});
		scope.model.favoritslist.setList({
			config: {
				allelementsselectable: true
			},
			entries: favslist
		});
	},
	function(error) {
		scope.api.util.notifier.error('Failed to load favorites',error+'');
	}
)

NUMBER

Name	Description (DMS only)	Binding

Name	Description (DMS only)	Binding
scale	Number of decimal places. For integer fields, this is 0.	RO*
precision	Total number of digits without separators.	RO
*RO (ReadOnly): ReadOnly properties can only be read. Changes to values of RO properties do not affect the interface.

The value is not available in the 'SEARCH' situation.

DATETIME

Expects a JavaScript 'Date' as value.

Name	Description (DMS and BPM)	Binding

Name	Description (DMS and BPM)	Binding
withtime	Is 'true' or 'false.' If 'true,' a time in seconds is expected in addition to the date.	RO*
*RO (ReadOnly): ReadOnly properties can only be read. Changes to values of RO properties do not affect the interface.

The value is not available in the 'SEARCH' situation.

Sample Script: Specifying a Date in the Future

When determining a deadline for working on the next process step, you want to make sure the date is not in the past.

Example: Validate a date in the future

var m=scope.model;
// The name of the date field is Deadline
var deadline=m.Deadline;


// Register the onchange handler
deadline.onchange=updateDeadlineState;


// Next is the logic for what we want to happen if the state changes
function updateDeadlineState() {
   
  if( isBeforeToday( deadline.value ) ) {
  	deadline.error = {msg:'Please select a date in the future.'};
  } else {
    // If the validation error does not occur, we may have to delete a previously-set error
    deadline.error = null;
  }
}
function isBeforeToday( pDate ) {
   
  // 
	var date = new Date();
	var today = moment(date).startOf('day');
	return moment(pDate).isBefore(today);
  
}

DATE

Important to know:

// allowed:
scope.model.datumfeld.value = new Date()
scope.model.datumfeld.value = moment().toDate()

// not allowed, sets the date one day into the past after save:
scope.model.datumfeld.value = moment();

The value is not available in the 'SEARCH' situation.

CODESYSTEM

Expects a JavaScript 'String' as value. The string must be the same as given in the 'data' property of the codesystem.

Note: Scripts must set valid catalog values until the client can evaluate them.

Reducing the selectable CODESYSTEM elements by filtering

Entry properties:

Name	Description	Binding

Name	Description	Binding
allowedonnew	If 'true', the entry is visible within the situation of type CREATE.	RO*
allowedonupdate	If 'true', the entry is visible within the situation of type EDIT.	RO
data	Qualified name of the entry.	RO
defaultrepresentation	UI name of the codesystem entry. The UI representation is built using the representation pattern of the codesystem.	RO
id	Entry ID.	RO
label	Localized label of this entry.	RO
order	Index value of the entry within the entry list.	RO
type	Type of entry. Possible values are LEAFENTRY for leaf nodes and INNERENTRY for inner tree nodes.	RO
*RO (ReadOnly): ReadOnly properties can only be read. Changes to value changes of RO properties do not affect the interface.

You can filter CODESYSTEM entries by providing a filter callback function. The function is called once for each entry in the given CODESYSTEM. The callback function is passed to the CODESYSTEM object by calling the 'applyFilter()' function. The entry object is passed to the callback function as an input value. The function returns 'true' if the current entry passed the filter (otherwise 'false').

scope.model.klasse.applyFilter(function(entry){
  return entry.data === 'Employee';
})

To remove the filter:

scope.model.klasse.applyFilter(null)

For CODESYSTEM fields in tables, the filter callback function can be bound in the 'onrowedit' callback function, as shown in the following example.

scope.model.mytablefield.onrowedit = function(table, row){
	row.model.mycodesystemfield.applyFilter(function(entry){
		return entry.data === 'foo';
	}) 
};

Beginning with version 6.16 this new filter is given to disable tree entries:

scope.model.class.applyDisablingFilter(function(entry){
  return entry.defaultrepresentation !== 'Employee';   // entry is disabled when condition is true
});

ORGANIZATION

Expects a Javascript 'String' as value. The string is the technical name of the organization object, and may be user or group names. For users, the technical name is the user login name.

Reducing the Selectable ORGANIZATION Elements by Filtering

To filter autocomplete values, use the setFilter function to pass a filter config object.

The filter config object can have the following attributes:

Name	Description

Name	Description
type	the type of the organization unit ('USER' or 'GROUP') to be displayed
groups	an array of group names
roles	an array of role names
activeonly	whether or not to display only active users/groups

Example

// set filter
scope.model.myOrgaField.setFilter({
	type: 'USER',                            // show only user elements
	groups: ['Employees', 'Accounting'],     // show only members of the listed groups
	roles: ['Trainer', 'Reviewer'],           // show only members of the listed roles
	activeonly: false						// controls whether or not only active users are listed
});

// remove filter
scope.model.myOrgaField.setFilter(null);

In the example above, the filter shows only users that are in the groups 'Employees' or 'Accounting' and are either in the role 'Trainer' or 'Reviewer'. To remove a filter, set it to null.

ID References

In the case of reference fields based on type ID a user is supported by a dialog that offers a search for possible objects to be selected. If only objects of the same context are allowed to be referenced this simple trick will solve this requirement:

Performe filtering on context objects

if(scope.context){
	scope.model.myidreferencefield.contextId = scope.context.id;
}

Reducing the Selectable ID Reference Elements by Filtering

This feature can be used beginning with version 6.14.

To filter autocomplete values, use the setQueryFilters function to pass a filter config object.

The query filters are already documented as "filters" in this article: Search Service API#Request(HTTPbody)

Filter example

scope.model.responsibles.setQueryFilters({
	"personalakte.name": {
		o: 'eq',
		v1: 'Engel'
	}
})

Beginning with version 8.4., the filter for reference fields of abstract object types can be extended by an array of concrete object type names to restrict the filter by these object types:

Filter example

scope.model.referenceddocs.setQueryFilters({
	"basisdocument.status": {
		o: 'eq',
		v1: 'active'
	}
}, ["contract", "statementofearnings"])

TABLE

The following table presents an overview of the possible data types per field. The JavaScript data type states what is expected as the 'value' of an element.

If the 'multiselect' property is set up, then the JavaScript data type is an array of the data type.

Name	Description	Binding

Name	Description	Binding
	No additional properties defined

Expects a JavaScript 'Object Array' as a 'value.' The properties of each object are defined by the column elements of the table. See the following example.

Sample script: Manipulating table data

Example: Manipulating table data

/**
 * Example script: Manipulating table data based on index data change.
 */
// Add change listener to field number
scope.model.number.onchange=function() {
     
    // The current user input on field with the internal name number
    var num = scope.model.number.value;
     
    // Shortcut to access the table
    var table = scope.model.changes;
     
    if(num>0 ) {
        // If number is set (greater than 0) we automatically fill the table
        if( !table.readonly ) {
            // The user may not modify the table
            table.readonly=true;
            // Copy the current values to a property using lodash
            table.old_value=_.map(table.value, _.clone);
        }
    } else {
        // If number is not set (less than 0) we let the user fill the table
        if( table.readonly ) {
            // Copy the old values back to values using lodash
            table.value=_.map(table.old_value, _.clone);
            // The user may modify the table
            table.readonly=false;
            // Cleanup
            delete table.old_value;
        }
    }
    // automatically fills the table if number is greater than 0
    // and add num rows to the table
    if(num>0) {
        // Clean up the table by setting a empty array
		table.value.length=0;   // changes of a single cell must be done in an array variable first, 
								// and then this array has to be pushed back to the table.
        for( i=0; i<num; i++ ) {
            // For each number add a row
            // Each row is an object defined by the internal names of the column elements.
            table.value.push(
                {
                    accepted: i%2,                              // Boolean
                    created: moment().add(i,'day').toDate(),        // Date
                    activedate: moment().add(i,'day').toDate(),     // Another date
                    author: 'Marie Curie '+i,                       // String: Author name with i postfix
                    prio: i+.42,                                    // Decimal
                    company : 'OSVH'                                // Codesystem - the 'data' values must be used.
                }
            )
        } // end for num
    } // end if num>0
}

Callback for Table

Name	Description

Name

Description

onrowedit

This callback is called when the user starts to edit a table row. Like 'onchange,' the first parameter contains the field element (the table itself). The second parameter contains a 'row' object, which describes the row the user wants to edit.

You can access the current value of the table using scope.model.mytable.value.

The `row` Object

The row object is transferred as the second parameter during the 'onrowedit' callback for table fields.

Name	Description	Binding

Name	Description	Binding
index	Row index: '-1' for newly-created row. The first row has the value '0'.	RO*
copyEnabled	Controls whether the "Copy and create as new row" function is enabled. You can only edit this synchronously inside the onrowedit.	RW**
deleteEnabled	Controls whether the "Delete row" feature is enabled. You can only edit this synchronously inside the onrowedit.	RW
saveEnabled	Controls whether the "Save row" feature is enabled. You can only edit this synchronously inside the onrowedit.	RW
persisted	Is 'false' if the edited file was newly created. The property remains 'false' for new rows until the index data is saved. You can use this property to differentiate between a row that has been saved or newly created by the user during the current index data editing.	RO
model	Provides access to the model of the current row. With this model, the script can access and modify the values and element properties of the current row.	RW
RO (ReadOnly): ReadOnly properties can only be read. Value changes of RO properties do not affect the interface. *RW (ReadWrite): ReadWrite properties can also be written. Value changes of RW properties affect the interface.

See how the row object is used in the following example.

Sample script: Table row scripting

Example: Table row scripting (onrowedit)

// Example for row edit
// The 'scope.model.notices' element is a table type with a few columns.
// This example script tries to achieve that only new rows can be edited. New rows are rows that the user has not saved yet.
scope.model.notices.onrowedit=function(table,row) {
    // 'table' is the element, the callback event was triggered.
    // In this case the same as scope.model.notices. 'row' is the row object.
 
    // Show some information as a toast notification - just for demonstration
    scope.api.util.notifier.info("Editing table row","A row at index "+row.index+" is being edited.");
 
    // First we check whether the row is a new, not yet persisted, row, or an existing row
    if(!row.persisted) {
        // This is a row created by the user.
        // He is allowed to change it. So all table columns are set to be editable
        // by setting all row fields' readonly property (the column elements) to false.
        Object.keys(row.model).forEach( function(e) { e.readonly=false });
         
        // Delete/save is enabled by default, but the user is not allowed to copy the existing row as a new one.
        // So we switch off the copy function.
        row.copyEnabled = false;
    } else {
        // This is an already-saved row, so cell values are no longer editable, we have set them all to read only.
        Object.keys(row.model).forEach( function(e) { e.readonly=true });
         
        // Copy/delete/save are all disabled. The user can only 'cancel' the row editing. Nothing else.
        row.copyEnabled = false;
        row.deleteEnabled = false;
        row.saveEnabled = false;
    }
}

onChange Handler for Table Cells

You define table rows in the form model (scope.model). Here you can set properties for each row. When the user edits a row, the system creates a temporary copy of the table elements. This copy can be accessed by a form script using a second parameter in the onchange Handler. Changes to the model are immediately visible in the table editing dialog. Changes to the properties of rowmodel are discarded when row editing has ended.

Example: onChange handler for a table cell

scope.model.mytable.onrowedit = function(table, row){
	// On this element we register a value change handler
	row.model.number.onchange = function(el, rowmodel) {	
		// The rowmodel provides access to the other elements
		// 'number2' is another element of type 'NUMBER' that is contained in the table element
		// For the sake of example this field is set to readonly, if the user inputs a special number in 'elementNumber'

		rowmodel.number2.readonly = ( el.value == 42 );
	}
}

rowmodel: Applying a Filter to an Organization Element that is Used as a Table Element

Example: Apply filter to organization objects in table rows

scope.model.mytable.onrowedit = function(table, row){
	// On this element we register a value change handler.
	row.model.mybool.onchange = function(el, rowmodel) {
		// The rowmodel provides access to the other elements
		// 'myorg' is another element of type 'ORGANIZATION' that is contained in the table element.
		// We apply different filters, depending on the current value of 'myBool'
		if( rowmodel.mybool.value ) {
			rowmodel.myorg.setFilter({
				type: 'USER',              // show only user elements
				groups: ['Employees'],     // show only members of this group
			)};
		} else {
			rowmodel.myorg.setFilter({
				type: 'USER',              // show only user elements
				groups: ['Accounting'],    // show only members of this group
			)};	
		}
	}
}

Manipulating Row Cells when one Cell Has Been Changed

var countries = scope.model.addresslist.onrowedit=function(table,row){
	row.model.country.onchange=function() {
		if(row.model.country.value === 'Germany'){
			row.model.zip.required=true;		// depending on value of country set a zip code as mandatory
		} else {
			row.model.zip.required=false;
		}
	}
}

Manipulating Multiple Row Cells

If we deal with more complex table value manipulation, we need to create a copy of the values. Once the values are written, the table gets populated and changes will get lost. Once all the cell manipulations are done, we can assign the manipulated values to the table values.

// see Manipulating table data
...
let tableCopy = JSON.parse(JSON.stringify(table.value)); //create a copy
for ( i = 0; i < num; i++ ) {
	if (i === 0) {
			tableCopy[i].accepted = !i%2,                               // Boolean
            tableCopy[i].created = moment().add(i+5,'day').toDate(),    // Date
            tableCopy[i].activedate = moment().add(i+5,'day').toDate(), // Another date
			tableCopy[i].author = 'Pierre Curie '+i,                    // String: Author name with i postfix
            tableCopy[i].prio = i+.00,                                  // Decimal
            tableCopy[i].company = 'OSVH'                               // Codesystem - the 'data' values must be used.
	} else {
    	// For each number add a row
	    // Each row is an object defined by the internal names of the column elements.
    	tableCopy.push({
            	accepted: i%2,                              // Boolean
	            created: moment().add(i,'day').toDate(),    // Date
            	activedate: moment().add(i,'day').toDate(), // Another date
        	    author: 'Marie Curie '+i,                   // String: Author name with i postfix
    	        prio: i+.42,                                // Decimal
	            company: 'OSVH'                             // Codesystem - the 'data' values must be used.
    	    });
	}
	// do even more fancy data manipulations
} // end for num
table.value = tableCopy;
...
// see Manipulating table data

Handling an Empty List as Erroneous (not Null)

scope.model.addresslist.onchange=function(){

	if(scope.model.addresslist.value.length > 0){
		scope.model.addresslist.error = null;
    } else if (scope.model.addresslist.value.length == 0) {
		scope.model.addresslist.error = {msg:'At least one address must be given.'};
	}
}

var init = function(){
	if(scope.model.addresslist.value === null || scope.model.addresslist.value.length < 1){
		scope.model.addresslist.error = {msg:'Mindestens eine Adresse muss angegeben werden.'};
	}
}

init()

Scripts for BPM Forms

For scripts that modify or change elements, it does not matter whether the form is a BPM activity form or a DMS index data form. However, the BPM data types must be mapped to DMS data types.

Following is a list of differences between field properties of DMS and BPM forms:

Client-side Form Scripting

Introduction

Script Scope

Properties of 'scope'

scope.data

Check situation

scope.situation

Check situation

scope.model

Field Properties

Sample script: onChange handler for form validation and user input

Example: onChange handler for form validation and user input

Data Types – Field Properties

Data Type-Specific Properties

STRING

Dynamic lists (Selection)

NUMBER

DATETIME

Sample Script: Specifying a Date in the Future

Example: Validate a date in the future

DATE

Important to know:

CODESYSTEM

Reducing the selectable CODESYSTEM elements by filtering

ORGANIZATION

Reducing the Selectable ORGANIZATION Elements by Filtering

Example

ID References

Performe filtering on context objects

Reducing the Selectable ID Reference Elements by Filtering

Filter example

Filter example

TABLE

Sample script: Manipulating table data

Example: Manipulating table data

Callback for Table

The row Object

Sample script: Table row scripting

Example: Table row scripting (onrowedit)

onChange Handler for Table Cells

Example: onChange handler for a table cell

rowmodel: Applying a Filter to an Organization Element that is Used as a Table Element

Example: Apply filter to organization objects in table rows

Manipulating Row Cells when one Cell Has Been Changed

Manipulating Multiple Row Cells

Handling an Empty List as Erroneous (not Null)

Scripts for BPM Forms

`scope.data`

`scope.situation`

`scope.model`

The `row` Object