Tasks
Task forms are similar to Requests where the HTML contains an input section and an output section driven by scripts. Task forms differ from Requests as follows:
- •Task form input is rendered as read-only (WSHT Input) and the form response area contains editable HTML controls (WSHT Output).
- •Task forms interact with the WSHT API (instead of directly invoking processes like the Request forms). In Requests, submitting a form consists of POSTing JSON to the appropriate endpoint. In Tasks, 'Saving' a form is equivalent to calling the WSHT API setOutput() operation.
- •Task forms are driven by a Process Central task manager JavaScript framework. This framework handles common work such as task operations (claim, save) and managing peripheral data associated with a task such as comments and attachments.
The JavaScript object that models a task form is:
// Function that encapsulates the task form script.
var AeTaskForm$ID = function() {
// the task name
var mTaskName = "ApproveLoan";
// task id
var mTaskId = null;
// task instance (AeTask instance)
var mTask = null;
/**
* Called by the manager to initialize the task form.
*/
this.avcform_initialize = function(aTaskId, aTaskFormContext) {
mTaskId = aTaskId;
mTaskFormContext = aTaskFormContext;
// (equivalent to Request's documentReady() fn )
//
// Initialize your code here. You can populate
// some UI fields, but not the task UI fields.
// (see avcform_onTaskReady())
//
// Set up form validation if needed
}
/**
* Called when the task instance has been loaded from the server.
*/
this.avcform_onTaskReady = function(aTask) {
// Called one time when the task instance (AeTask object)
// is first loaded (via WSHT API). Use this to initialize mTask
// and display input and outdata from the task.
mTask = aTask;
this.showData(); // display task data
}
/**
* Called when the task instance has been updated from the server.
*/
this.avcform_onTaskUpdated = function(aTask) {
// called each time the task has changed. For example, task
// was claimed (state went from READY state to IN_PROGRESS).
mTask = aTask;
}
/**
* Called when loading task instance from the server failed.
*/
this.avcform_onTaskLoadError = function(aMessage) {
// return false to allow AVC system to handle error.
// or return true to indicate that your code handled it.
return false;
}
/**
* Called to enable/disable form input fields
* @param aEnable Indicates if the form should be enabled or disabled
*/
this.avcform_enable = function(aEnable) {
// return false to allow AVC system to handle enable/disabling of form fields
// you can enable/disable your custom controls here.
// normally a form is enabled when its editable (Claimed)
return false;
}
/**
* Called to validate the task form data before the task is saved
*/
this.avcform_validate = function() {
// Called when the form needs to be validated before saving it (WSHT setOutput operation).
// The form is not saved (setOutput not called) if this method returns false.
// return true for relaxed validation on saving a form that isn't 100% complete
return true;
}
/**
* Called to validate the task form data before the task is completed
*/
this.avcform_validateForCompletion = function() {
// Validation function called before completing a task.
// Return true if the form is valid or false to prevent WSHT complete() operation.
return true;
}
/**
* Called when the task needs to be saved.
*/
this.avcform_save = function(aCompleteTask) {
// This function is called when the user presses the "Save" button.
// Code save the form (WSHT setOuput) goes here. (normally generated for you).
}
/**
* Binds data to the UI controls.
*/
this.showData = function() {
// this method is called when the task is loaded. e.g. via avcform_onTaskReady() above.
if(mTask != null) {
// show task data in UI
}
}
}
Note that at the end of the script, you will see a function similar to:
$(document).ready(function() {
ACTIVEVOS_TASKFORM_CONTEXT.init(_TASK_INSTANCE_ID_, new AeTaskForm$ID() );
});
The ACTIVEVOS_TASKFORM_CONTEXT is a JavaScript object that is made available at runtime by the framework. The _TASK_INSTANCE_ID_ is replaced at runtime with the string value of the task instance ID. For example:
// runtime
$(document).ready(function() {
ACTIVEVOS_TASKFORM_CONTEXT.init("urn:b4p:123", new AeTaskForm_123() );
});
The ACTIVEVOS_TASKFORM_CONTEXT.init(...) function basically 'registers' the task form instance with the framework. The framework will then call back appropriate functions on the task form instance; for example, avcform_initialize(), avcform_onTaskReady() and avcform_onTaskUpdated(). Specifically, the task form JavaScript object interacts with the Central (framework) in the following way:
- 1. The avcform_initialize(aTaskId, aTaskFormContext) function is called when the form in loaded. Central will then get the task data using the Human Task API.
- 2. Once the task data is available, Central will call the avcform_onTaskReady(aTask) function on the form object passing in the task instance.
The form UI is updated at this time to reflect the task's input and output values.
- 3. Process Central's framework handles user interaction on the tasks operation toolbar (such as Claim, Save). When the task state has changes due to a user interaction (for example, a user claimed a task), the framework invokes the WSHT API and later calls the avcform_onTaskUpdated(aTask) function.
The avcform_enable(bool) function is also called to enable (when a task is claimed) or disable the form UI.
- 4. When the Save button is pressed, the framework invokes the task form object's avcform_validate() function to validate the UI data, followed by invoking the avcform_save() function. The code in avcform_save() saves the form by invoking the WSHT setOutput() operation.