This article describes the scripting functionality which can be used for data manipulation and validation in forms for objects and process tasks.
...
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 |
---|---|
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). |
...
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'.
Info | ||
---|---|---|
| ||
|
Each field has the following properties:
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 | A field description. Can be used in tooltips for example. | RO |
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.
...
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
...
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.
| 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.:
...
Code Block | ||||
---|---|---|---|---|
| ||||
// 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+''); } ) |
...
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. |
Warning |
---|
The value is not available in the 'SEARCH' situation. |
DATETIME
Anchor | ||||
---|---|---|---|---|
|
Expects a JavaScript 'Date' as value.
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. |
Warning |
---|
The value is not available in the 'SEARCH' situation. |
...
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').
...
Code Block | ||||
---|---|---|---|---|
| ||||
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:
Code Block | ||
---|---|---|
| ||
scope.model.class.applyDisablingFilter(function(entry){ return entry.defaultrepresentation !== 'Employee'; // entry is disabled when condition is true }); |
...
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.
...
Code Block | ||||
---|---|---|---|---|
| ||||
// 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)
Code Block | ||||
---|---|---|---|---|
| ||||
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() |
...
qname
The qualified nameqname
is not supported.required
The propertyrequired
is not supported, but can be used by scripts.name
The name of the element is the technical name of the data field bound by the parameter.label
The label stems from the localized name of the data field bound by the parameter.
Mapping BPM Data Types to DMS Data Types
BPM data type | DMS data type | Description |
---|---|---|
String + ID | STRING | |
Boolean | BOOLEAN | |
Date + LocalDate | DATETIME | LocalDate is withtime false . LocalDate therefore stands for a day without time. |
Decimal + Long | NUMBER | scale is not currently supported. |
CodeSystem | CODESYSTEM | |
All list types | TABLE |
Reading and Setting Feasibility of Activity Actions
...
'1' is a code which is set in yuuvis® RAD designer for each individual activity action.
...
Name | Type | Description |
---|---|---|
id | String | The ID of the context object. |
title | String | The title of the context object. |
typeName | String | The name of the type of the context object. |
Using Global Scripts
Form scripts are defined by type and situation. The scripts are independent of each other and cannot share functionality. If you need to use generally applicable functions or the project-specific logic of multiple form scripts, you can add global scripts and include them in local scripts.
Creating Global Scripts in yuuvis® RAD designer
...