Related Topics
Set Form Data Tab
Prior to Process Director v3.53, by far the most common Custom Task used on a Form was the Set Form Data Custom Task, which was configured on the Custom Task Event Mapping tab. For Process Director v3.53 and above, the Set Form Data tab will replace the Custom Task for setting the value of Form Fields. The Set Form Data Custom Task is still available if required, and will still work properly if you have existing projects that use it, but the vast majority of use cases will be satisfied by using the Set Form Data tab. The Set Form Data tab is easier to configure, will reduce the number of Custom Tasks required to configure a Form, and is easier to manage.
In a sample form, the tab will look similar to the one below.
The Set Form Data tab is divided into a number of sections, with each section corresponding to a form event. The order in which the events appear on the tab is not indicative of when, or in what order, the events will fire. When form events fire—and in what order—are determined by where you are in the form's life cycle.
Both the standard form events (i.e., View State Init, Before Validation, etc.) and the event fields have a configuration section. For example, in the sample above, the ExistingVendor (Vendor) field is an event field that, when fired, will extract data from a Business Value. The value of the ExistingVendor (Vendor) field is passed to the Business Value as a parameter, in order to return the specific data for the selected vendor.
- Find the section that corresponds to the event you wish to configure. For this example, we will use the ServiceLevel field from our sample form, above.
- Click the Add Condition button. A new mapping section for the condition will appear in the tab. You may optionally add a condition by clicking on the Click to create condition link, then using the Condition Builder to define the condition. If you don't define a condition, the Set Form Data action will occur every time the event fires.
- Click the Add Form Field button. A new mapping row will appear in the condition section.
- In the Form Field dropdown, select the Form field whose data will be set.
- Repeat steps 3 and 4 as desired.
- Select the new value for the Form control by using the Value Object Picker control.
- Each row can be ordered in the list of mapping rows by clicking one of the arrow icons to move the row up or down. The row can be deleted by clicking the red "X" icon. Similarly, if you have multiple conditions for an event, the conditions can be ordered as well, so the condition evaluations will occur in the order you desire. Items can only be ordered inside their container section.
Working with Arrays and Business Values
When using the Set Form Data tab to assign form field values from a Business Value. Process Director will automatically group all field changes from a single Business Value into a single row.
When setting the value, you can specify the row number if the field value to be set is contained in an array. If you don't specify an array row when setting data, Process Director will handle the Set Form Data action in different ways, depending on the data you are using to modify the array,
When using the Set Form Data tab with Business Value properties, the key thing to remember is that the default behavior when adding Business Value data to an existing array is to append new rows when a Row Number isn't specified. In other words, if the array has two existing rows, then, when the event fires that retrieves Business Value data returns four rows, the array will expand to six rows when the four new rows are appended. If you wish to overwrite the existing array data, then the first thing you must do in the event is to set the array's value to "0", which will clear the array. The new data will then create the appropriate number of rows for the data returned.
It is possible to return data from multiple Business Values in the same event, and Process Director will concatenate the values from multiple Business Values into a single Array change. Process Director will append the number of rows that corresponds to the largest number of results from any Business Value Property in the same Condition Set. With Business Value Properties that return different numbers of results, the Set Form Data will set no data in fields in the appended Array rows that have no corresponding result. In other words, if one Business Value property set returns five rows, and a second returns four rows, then Process Director will append five rows to the array, but the fifth row will have no value from the second Business Value.
When returning data from two different Business Values, you have no way to ensure that the values from each Business Value corresponds with the data from other Business Values. In such a case, you are essentially retrieving two unrelated sets of data. So, if possible, you should retrieve data with multiple columns from a single Business Value.
The behavior with any other type of System Variable is quite different from the Business Value behavior. Instead of appending new rows, the Set Form Data event will apply the new System variable value to each row that is currently in the array, overwriting the existing data on every row with the new value.
More Configuration Tabs
You can view the documentation for each of the other configuration tabs by using the Table of Contents displayed on the upper right corner of the page, or use one of the links below.
Properties: General Form definition properties.
Edit: Opens the editor for the form's visual template, the Online Form Designer.
Form Controls: Enables you to set individual properties for each field on the form.
Custom Task Event Mapping: Enables you to map Custom Tasks to run on specified form events.
Validation Rules: Enables you to add custom validation to the form.
Fill Dropdowns: Enables you to automatically set the options available in a dropdown control.
Other Tabs: Documentation for the Form Data SQL View, History, Meta Data, Versions, and Permissions tabs.
Documentation Feedback and Questions
If you notice some way that this document can be improved, we're happy to hear your suggestions. Similarly, if you can't find an answer you're looking for, ask it via feedback. Simply click on the button below to provide us with your feedback or ask a question. Please remember, though, that not every issue can be addressed through documentation. So, if you have a specific technical issue with Process Director, please open a support ticket.