6.5 Guidelines for Creating Workflows

Data Objects and Variables

The workflow uses a single process object to manage information about the process. A separate activity object is created for each activity in the workflow and form data is maintained for each activity that provides for user interaction.

The data objects associated with each user interface control on a form (text field, drop-down list, and so forth) can be modified immediately prior to the execution of the corresponding activity (Start activity or Approval activity). In addition, this data can be retrieved immediately after execution of the activity. After control has been passed to the next activity, the form control data is no longer available. For this reason, the workflow provides a special object called flowdata that allows you to define your own data items. You can add your own variables to this object to keep track of information that is important to your workflow, including form data that would otherwise be lost.

The following table summarizes the categories of workflow data:

The following table describes the variables for each type of object:

You can reference these objects in ECMAScript expressions. Script expressions in a workflow can at any time refer to data items that are bound upstream in the flow. However, workflow expressions cannot refer to data items that are created downstream (because these data items don’t exist yet) or to data bound on other branches in a flow that supports parallel processing (because these branches could be executing concurrently with the current activity).

Creating New Data Items

You can create a new data item on the flowdata object by specifying a post-activity target expression on the Data Item Mapping tab for the Start or Approval activities. If you specify a name for a new data item in the Target Expression column, this automatically creates the variable. Any activity executed after this activity can then access the data item.

For example, you might want to map the form field called reason to the target expression flowdata.myReason. The variable myReason then becomes a new data item that is available to all activities executed later in the workflow.

Modifying Data Items

You can modify a data item by specifying a pre-activity expression on the Data Item Mapping tab for the Start or Approval activities. For example, to prepend a dollar sign to a price, you might map the following source expression to a target form field called Price:

"$" + flowdata.get('cost')

When the form displays to the user, the Price data appears as follows:

$xx.xx

Another example might be computing the total cost by adding the tax to the base cost. To do this, you could map the following source expression to a target form field called TotalCost:

Number(flowdata.get('cost')) + Number(flowdata.get('tax')) 

Working with Complex Data Item Mappings

All data in the flowdata object is maintained in XML, so you can create data items in a hierarchical fashion as well. For example, suppose you have a workflow form that allows a user to ask for access to two internal systems, one for accounts payable and one for receivables. Suppose the form has (among other fields) two Yes/No fields named Acct_Pay and Acct_Rec. In the post-activity data item mappings, you might create two mappings as follows:

This would create an XML element named SystemAccess with two child elements named AcctPay and AcctRec. One reason to structure data in this way is for clearer organization and management of data in complex workflows containing many forms and data items. To retrieve data from these hierarchies, the following syntax would be used:

flowdata.get('SystemAccess/AcctPay')

For complete details on building ECMAScript expressions, see Section 9.0, Working with ECMA Expressions.

Moving Form Control Data to Flowdata

All form controls you create (except for DNDisplay) are automatically made available for use in pre-activity and post-activity expressions on the Data Item Mapping tab for the activity that uses the form. For example, suppose you want to make a user’s entry data in control ACONTROL on form AFORM in AACTIVITY available for use in a subsequent activity. To do this, you would select AACTIVITY in the workflow, select the Data Item Mapping tab, and click the Post Activity Mapping radio button. Next to the source form field ACONTROL, you would then enter a target expression in the following format:

flowdata.my_ACONTROL

Any subsequent activity in the workflow would then be able to access this data by using pre-activity source expressions such as these:

flowdata.get('my_ACONTROL')

flowdata.getObject('my_ACONTROL')

Moving Flowdata to Form Controls

You can also move flowdata values into form controls. The simplest case is moving a single text value into a form control. In the example above, suppose ACONTROL is a simple text entry field. In this case, to move it into another text entry field in an activity called ZACTIVITY, you would select ZACTIVITY in the workflow, select the Data Item Mapping tab, and click the Pre Activity Mapping radio button. Next to the target form field, you would then enter this source expression:

flowdata.my_ACONTROL

To move more complex form control data (for example, a MultiValue DN control) into another form control, you can use the getObject() expression syntax. For example, assuming ACONTROL is a MultiValue DN control, you could use this source expression:

flowdata.getObject('my_ACONTROL')

To move data into a form control, you need to be aware of type constraints. For example, you should not try to move text-based data into a numeric control, or a Boolean value into a DN control.

About Mapping Activity Operations

In the mapping activity, the source expressions are evaluated before they are assigned to the target expression. If the source expression does not exist prior to the mapping activity, no value is assigned to the target expression.

For example, if flowdata.get(“textfield”) maps to flowdata.copyoftextfield and flowdata.get("copyoftextfield") maps to flowdata.copyoftextfield2, the value of flowdata.copyoftextfield2 is empty at the end of the mapping activity because the value of the flowdata.copyoftextfield is assigned only after the mapping activity.

To assign values to the target expression, you can use either of these options: