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
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
- For a Date object, the input field will be populated with the value converted the following time zone
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
-
size()
-
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
- Get: Array of file object
- File objects have the following attributes
- id: File ID (numeric)
- processDataInstanceId: ID (numeric) representing the Case/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)
- malwareScanStatus: Status of file scan
- SCANNING: Scanning in progress (instances where immediate determination was not possible)
- NO_THREATS_FOUND: No threats found
- THREATS_FOUND: Detected as potentially containing malware
- UNSUPPORTED: File cannot be scanned (e.g., encrypted files)
- TIMEOUT: Instances where scanning could not be completed and determined within the specified time limit
- ACCESS_DENIED, FAILED, UNKNOWN: Instancess that do not normally occur during standard operations
- 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)
- File objects have the following attributes
- Set: (Not available)
- You cannot add files or update file information
Discussion-type/(Guide panel-type)
(Not available)
1-3. Script Examples
Title
Get
let title = qbpms.form.get("title");Set
let strTitle = "CASE 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 choiceSet
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", "yamada@example.com");
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
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
- Supported Data-types
- Title/String-type/Numeric-type/Select-type/Date-type/DateTime-type/User-type/Organization-type/Table-type/File-type
- 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);
}
function user_readyHandler(e) {
qbpms.form.on('change', 'q_string1', user_addedQbpmsEvent);
}
qbpms.form.on('ready', user_readyHandler);