R2132: Questetra Form JavaScript API

 

This API can be used to get a value from an input field or set a value on the Task operating screen (Input form). You can also register an event handler.
As a product characteristic, it takes a certain amount of time to build a DOM tree. It is necessary to consider the timing of event activation.

• 1. Get/Set the value of the input field
  • 1-1. Script Format
  • 1-2. Get/Set Object Value
  • 1-3. Script Examples
• 2. Registering and Deleting Event Handlers
  • 2-1. Form-wide Event
  • 2-2. Data Item Event

1. Get/Set the value of the input field

1-1. Script Format

Get value

qbpms.form.get("FIELD NAME")

• FIELD NAME: "title" or "q_field_name" (the Field name of the Data Item)
• Available when the editing permission setting on the form is "editable" or "display only"

Set value

qbpms.form.set("FIELD NAME", Value in the format according to the Data-type)

• FIELD NAME: "title" or "q_field_name" (the Field name of the Data Item)
• Value in the format according to the Data-type: (refer to "Get/Set Object Value" below)
• Available when the editing permission setting on the form is "editable"
• Merely changes the displaying value on the form, the value on the server will not be updated unless you save or complete the Task

1-2. Get/Set Object Value

Title/String-type

• Get: string
  • If the value is not set, it will be an empty string when editable and null when only display
• Set: string
  • Clears the value when null is set

Numeric-type

• Get: Big object
  • If the value is not set, it will be null
• Set: Big object/string/Number object/numeric
  • If it is a string, the value will be set in the input field as it is
  • If other than string, it sets the string whose value has been converted according to the format of the Data Item definition into the input field
  • Clears the value when null is set

About Big object

• You can generate an object using new Big("string")
• You can get value in string format using toString()
  • Format of string: period as decimal separator, no delimiter (e.g.1234.56)
• See big.js Documentation for the details

Select-type

• Get: Array of objects
  • The object has value (choice ID) and display (display label) as properties.
  • If not selected, the array will be empty
• Set: string or string array
  • String will be the choice ID
  • If an array of multiple elements is passed to a single selection (other than a checkbox), the first value will be set
  • If you set an empty array or null, the value will be cleared (deselected)

Date-type

• Get: Date object
  • The value is interpreted as the time in the time zone of the workflow platform (system)
  • Y/M/D fields that are not entered due to the sub-type setting are complemented with the value "2000-01-01"
  • The time is 00:00:00
  • E.g. A year-month format value "2022-08" will be handled as a Date object that represents "2022-08-01 00:00:00"
  • If the value is not set, it will be null
• Set: Date object/String
  • For a Date object, the input field will be populated with the value converted to the time zone of the workflow platform (system)
  • For a String, the input field will be populated with the value as it is
    • If the format does not match, it will be set to empty
  • Clears the value when null is set

DateTime-type

• Get: Date object
  • Depending on the form type, the value will be interpreted as a time in the following time zones
  • Normal Task Operating form (Human Task): time zone based on the operating User's account settings
  • Published web form (Message Start Event (Form)/Receive Task (Form): the time zone of the workflow platform (system)
  • If the value is not set, it will be null
• Set: Date object/String
  • For a Date object, the input field will be populated with the value converted the following time zone
    • Normal Task Operating form (Human Task): time zone based on the operating User's account settings
    • Published web form (Message Start Event (Form)/Receive Task (Form): the time zone of the workflow platform (system)
  • For a String, the input field will be populated with the value as it is
    • If the format does not match, it will be set to empty
  • Clears the value when null is set

User-type

• Get: User object
  • The object has id (numeric), name (string) and email (string) as properties.
  • If the value is not set, it will be null
• Set: string
  • String will be the Email Address
  • The user with the specified email address is set to the value
  • If you set null, the value will be cleared (deselected)

Organization-type

• Get: Organization object
  • The object has ID (numeric), name (string), and email (string) as properties.
  • If the value is not set, it will be null
  • If the retained value is a deleted organization, ID will be null
• Set: string
  • String will be the organization name
  • The organization with the specified name is set to the value
  • If you set null, the value will be cleared (deselected)

Table-types

• Get: List object
  • If the value is not set, it will be "empty (0 rows) List object" when Editable, and null when Display Only
• Set: List object
  • It is not possible to create new List objects, so use the values obtained with qbpms.form.get() and update them as necessary
  • Use the List object obtained from the target Table-type Data Item since List objects that are obtained from other Table-type are not available
  • Automatic calculations within rows and aggregate values for the entire table will be recalculated, and the values of Numeric-type Data Items that refer to table summary values will be also recalculated

About List object

• It is not possible to create new List objects, so use the object obtained with qbpms.form.get()
• You can Get/Set values using the following methods
  • size()
    • Returns the number of rows excluding the summary row
  • getRow(rowIndex)
    • Returns the row object of the specified row index (number starting with 0)
    • Returns null if a row index that does not exist is specified
  • getSummary()
  • Returns the row object of the summary row
  • Returns null if no summary row exists (no table items with summary settings)
  • Values of columns where the aggregation is not set will be null
• updateRow(rowIndex, rowObject)
  • Update the row specified by the rowIndex with the rowObject
  • Updates only the columns contained in the row object
    • Does not update columns not included in row object properties
    • However, columns where calculation is set will be recalculated and updated
  • Specify the property value of the row object with an object or a string that corresponds to the column type of the Table item
    
    • String type: String
    • Numeric type: Big object/Numeric string in the standard format (period as decimal separator, no delimiter)
    • Date type: Date object/String in the format "yyyy-MM-dd"
    • Select type: Choice object (Only Choice ID is referenced)/String of Choice ID
• addRow(rowObject)
  • Adds the specified row object under the last row
• removeRow(rowIndex)
  • Delete the row with the specified row index (number starting with 0)
  • If there is a summary row, the summary value will be updated

About  Row object

• A row object is an object that has values for each column whose property name is the Field Name of the Table item
• Field name setting is required to Get/Update the value since Table items for which Field Name is not set are not included in the object
• The value of the property has the following format depending on the data type of the table item (For the details, see Value Objects for Each Data Type)
  • String type: String
  • Numeric type: Big object
  • Date type: Date object
  • Select type: Choice object

File-type (Ver. 14.2 -)

• Get: Array of file object
  • File objects have the following attributes
    • id: File ID (numeric)
    • processDataInstanceId: ID (numeric) representing the process/data item with which the file is associated
    • name: File name
    • contentType: File Content Type
    • length: File size (byte, numeric)
    • lengthText: A string used to indicate the file size. A unit such as bytes/KB/MB is attached depending on the size.
    • image: Flag indicating whether it is an image or not (boolean value)
    • inline: Flag indicating whether it can be displayed on another screen or not (boolean value)
  • The file object does not contain the file itself
    • File entities cannot be retrieved
  • Files deselected using the Delete button on the form screen are not included in the array
  • If there is no file, it will be an empty array (not null)
• Set: (Not available)
  • You cannot add files or update file information

* [Message Start Event (Form)] cannot obtain information on File-type data items

Discussion-type/(Guide panel-type)

(Not available)

1-3. Script Examples

Title

Get

let title = qbpms.form.get("title");

Set

let strTitle = "PROCESS TITLE";
qbpms.form.set("title", strTitle);

String-type

Get

let string = qbpms.form.get("q_string");

Set

qbpms.form.set("q_string1", "STRING");
qbpms.form.set("q_string2", "ORANGE\nAPPLE\nPEACH\nGRAPE");  //multiple lines

Numeric-type

Get

let strNum = "null";
let obj = qbpms.form.get("q_numeric");
if (obj !== null) {
  strNum = obj.toString();
}

Set

qbpms.form.set("q_numeric1", "1001.101");
qbpms.form.set("q_numeric2", new Number("1002.102"));
qbpms.form.set("q_numeric3", new Big("1003.103"));
qbpms.form.set("q_numeric4", 1004.104);

Select-type

Get

let array1 = qbpms.form.get("q_radioButton");
let display1 = array1[0].display; //display label

let array2 = qbpms.form.get("q_checkBox");
let value2 = array2[1].value; //Choice ID of the second choice

Set

qbpms.form.set("q_radioButton", "true");
qbpms.form.set("q_selectBox", ["true", "false"]); // "true", the first one, will be set
qbpms.form.set("q_checkBox", ["true", "false"]);

Date-type

Get

let date = qbpms.form.get("q_YMD");
let dateStr = date.toDateString();

Set

qbpms.form.set("q_YMD", new Date());
qbpms.form.set("q_YM", "2022-08");

DateTime-Type

Get

let datetime = qbpms.form.get("q_datetime");

Set

qbpms.form.set("q_datetime1", new Date(datetime.getTime() + (60 * 60 * 1000))); //after 60 minutes
qbpms.form.set("q_datetime2", "2022-08-08 11:11");

User-type

Get

let userName = qbpms.form.get("q_user").name;

Set

qbpms.form.set("q_user", "[e-mail]");

Organization-type

Get

let orgId = qbpms.form.get("q_org").id;

Set

qbpms.form.set("q_org", "Sales");

 

Table-type

Get

let table = qbpms.form.get('q_table1');
let table_size = table.size();
let row1 = table.getRow(1); //Row object with row number "1"
let selected = row1.select.display; //value of Select type table item (display label)

Set

let rowObject = {
  "str":"Row update 1",
  "num1":"1111.11",
  "num2":new Big("2222"),
  "select":{"value":"a"},
  "date":"2022-08-08"
};
let table = qbpms.form.get('q_table1');
table.updateRow(1, rowObject);
qbpms.form.set('q_table1', table);

File-type (Ver. 14.2 -)

Get

let files = qbpms.form.get("q_file");
let fileName = files[0].name; //Name of the first file

(Not available for "Set")

Discussion-type/(Guide panel-type)

(Not available)

2. Registering and Deleting Event Handlers

* To avoid conflicts with what is used in Questetra, define your own function's name/element ID to start with "user_".

2-1. Form-wide Event

2-1-1. Script format

Registering event handler

qbpms.form.on(EVENT-TYPE, EVENT-HANDLER)

Deleting event handler

qbpms.form.off(EVENT-TYPE, EVENT-HANDLER)

• Event-type: "ready"
• Event handler: Is a function, which has one parameter that is an event object

2-1-2. Event-type

ready

• Fires when the form is displayed and the form API is available
• If registered after displaying the form, the event handler will be executed immediately
• Event object is fixed

2-1-3. Script example

"Hello world!" Is displayed in the message dialog when the Operating Form screen is displayed

function user_readyHandler(e) {
  window.alert("Hello world!");
}

qbpms.form.on('ready', user_readyHandler);

2-2. Data Item Event

2-2-1. Script Format

Registering event handler

qbpms.form.on(EVENT-TYPE, FIELD NAME, EVENT-HANDLER)

Deleting event handler

qbpms.form.off(EVENT-TYPE, FIELD NAME, EVENT-HANDLER)

• Event-type: "change"
• Field Name: "title" or "q_field_name" (Field Name of the Data Item)
• Event-handler: Is a function, which has one parameter that is an event object

2-2-2. Event-type

change

• Fires when the value of an editable Data Item input field changes
• Fires when the value is set by qbpms.form.set, in addition to manually changing the value
• The change event is not fired for File-type data items in the [Message Start Event (form)]
• Supported Data-types
  • Title/String-type/Numeric-type/Select-type/Date-type/DateTime-type/User-type/Organization-type/Table-type/File-type*
    • Marked with * are available on and after Ver. 14.2
• Event object properties
  • type: "change"
  • varName: Field Name
  • value: A value to be set (Same as those got by qbpms.form.get())

2-2-3. Script example

Display a message dialog when the value of the target Data Item changes

function user_addedQbpmsEvent(e) {
  window.alert("VALUE CHANED：" + e.value);
}

qbpms.form.on('change', 'q_string1', user_addedQbpmsEvent);

---

Notes

Reference: Automatically Populate Multiple Data Fields with Selected Employee Information-When Realized with Questetra Professional Edition