Defining Workflows
Including Custom Features in a Workflow
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

This chapter describes how to include custom features in a workflow. It includes the following topics:

Extending the Standard Task Form
Each task has an associated task form that displays (at a minimum) a standard set of items, as follows:
To add additional buttons (which are visible only when the task is assigned), provide a comma-separated list of button names in the %Actions property of the task request.
To add additional editable values (which are visible only when the task is assigned), set one of the following properties in the task request object:
If you use %FormFields or %FormTemplate, you can specify default values to be shown in the fields. To do so, specify the %FormValues property of the task request object. This property is an array of strings, subscripted by field name. Use the array interface to add values to the property.
When the Workflow Engine processes a task, it makes a copy of all the form-related properties from the task request into the task response, including the array collection %FormValues. As fields in the form acquire new values, the Workflow Engine keeps updating the values in the %FormValues collection of the task response object.
Forms always display the current values in the %FormValues collection. This allows dynamic operation of forms within a specific task: by modifying the values of the form-related properties, the task response callback methods can influence how form processing takes place. The %FormValues collection of the task response object is available to the original caller when the final task response is sent back to it.
Using a Custom Task Form
It is possible to display a custom form to a user for a workflow task. The steps are as follows:
  1. Create an HTML template file that defines the contents of the customized form. This is implemented as a Caché Server Pages (CSP) page so that it can contain dynamic content, if desired.
  2. Set the %FormTemplate property of the task request object to the name of this CSP page. For example, the <call> statement sending the task request to the workflow operation would contain:
    <assign property='callrequest.%FormTemplate'
            value='"MyForm.csp"'
            action='set' />
  3. Set the %FormFields property of the task request object to a comma-delimited list of field names. This is the list of fields that will be defined for the form. For example:
    <assign property='callrequest.%FormFields'
            value='"Details,CustomerName"'
            action='set' />
  4. If you wish to provide initial values for the form fields, set the corresponding element (that is,. the array key is the name of the field) of the %FormValues collection property of the task request object to the desired value. For example:
    <assign property='callrequest.%FormValues'
            value='request.CustomerName'
            action='set'
            key='"CustomerName"' />
As described in previous sections, whenever a workflow user reviews a task that he or she currently owns, the system displays a the associated task form. By default, this form is automatically generated using the fields defined by the values in the %FormFields property of the task request object. The calling business process provides these values. However, there is a way to use a custom-designed template instead of this generated form.
A workflow form template defines a block of HTML that is injected into the standard task form. This HTML block can include any number of form fields; these fields will be automatically submitted and processed by the Workflow Engine whenever a user performs an action on the workflow task. The HTML contained in a template file is not a complete HTML document; it is simply the HTML needed to display the custom portion of the form. Specifically, the resulting HTML generated by the task form looks like this:
<html>
  <body>
    <form>
      —TEMPLATE CONTENTS INJECTED HERE—
    </form>
  </body>
</html>
The following template defines an HTML table that displays two HTML input controls: a text box and a select (combobox). The names of the controls correspond to the fields defined by the %FormFields property. This example also uses a server-side expression to get the initial value for the Details property. The %task variable is always pre-set to the current task response object:
<!— workflow template —>
<table>
  <tr>
    <td>Details:</td>
    <td>
      <input type="text"
             name="Details"
             value="#(%task.%FormValues.GetAt("Details"))#">
    </td>
  </tr>
  <tr>
    <td>Company:</td>
    <td>
      <select name="CustomerName">
        <option value="ABC Corp">ABC Corp</option>
        <option value="XYZ Corp">XYZ Corp</option>
      </select>
    </td>
  </tr>
</table>
In addition to HTML, the workflow template file can contain the following, optional, Javascript callback functions:
To add these callbacks to a workflow template file, simply place the function definition within a <script> tag in the template file; for example:
<script language="JavaScript">
        function onLoad(form)
        {
                // form is the workflow form object
                return true;
        }

        function onAction(form,action)
        {
                // form is the workflow form object
                // action is a string containing the user's action
                // returning false will cancel this action
                return true;
        }
        </script>
Customizing the Task Distribution Strategy
The task distribution strategy is specified in the task response class. To implement a custom task distribution strategy, do the following:
Creating a Custom Task Response Class
When you create a subclass of EnsLib.Workflow.TaskResponse, you override its OnNewTask() callback method (and possibly other methods). The following is a list of the callback methods that you can override:
EnsLib.Workflow.TaskResponse callback methods control the distribution of tasks by calling a number of API methods defined in the Workflow Engine (EnsLib.Workflow.Engine).
The following is a list of the class methods in EnsLib.Workflow.Engine that you can use when you override the callbacks listed previously.
  1. AssignTask() — Assign a task to a specific user.
  2. CompleteTask() — Mark a task as Completed and return the response to the caller.
  3. FindLeastBusyUser() — Return the name of the “least busy” user. This is the user with the fewest assigned tasks in the system.
  4. SendTask() — Send a task to a specific user.
  5. SendTaskToAll() — Send a task to all users in the current role.
  6. SendTaskToTitle() — Send a task to one or more users with the given title in the current role.
  7. SendTaskToTop() — Send a task to the top n users in the current role, according to their respective ranking in the role.
  8. UnassignTask() — Remove task assignment.
For details on these methods, see the InterSystems Class Reference.
Invoking the Custom Task Response Class
A task request message has class parameter (RESPONSECLASSNAME) that specifies which response class to use. You can override this by setting the %TaskHandler property of the request class.
This means that you have two ways to cause the task request to use the desired task response: