Summary

When you want an application user to select items from a list on a work object form and have the application do something with those selections (perform an action or save them with the work object, for example), use a list view rule. The list view rule generates the SQL query that obtains the items, provides the HTML that displays the items with check boxes or radio buttons, and defines where to copy the selected data.

This article describes how to use a list view rule to provide a list of options with check boxes in a work object form, using examples from a sample application.
 

Suggested Approach

To accomplish this design task, you link the Applies to class of the list items to the work class with an embedded page list property; create the list view rule with the Report wizard; open and configure the generated list view rule to allow operators to select items; create a section rule that calls the rule with the listView JSP tag; and drop the section into a harness or flow action. If you want the operators to be able to see what they selected when they leave the form, create another flow action or harness to display the selected items.

Task 1: Update the data model of the work class

Configure the data model of the work object so the selected items can be copied to the work page and, if necessary, saved with the work object. First, identify the applies to class of the list items. Then, create page list property for the work class that references the class of the list items. (Note that it must be a page list property because using check boxes means the user can select more than one item from the list.)

What is the Applies to class of your list items?

In the example used in this article, the application is a purchase order system used at an organization named AlphaCorp. The items that can be ordered through the OrderEntrySystem application are instances of a Data- class named Data-OrderEntrySystem. Because an operator using the application can select more than one product, the list item class is connected to the work class through a page list property named ProductsSelected.

Task 2: Create the List View Rule

When you want to use a list view rule in a section, you create it with the Report wizard and then edit the generated rule. If the rule will provide a list of data, start the Report wizard from the Data Reports section of the Monitor Activity slice.

Fill out each of the Report wizard’s form as appropriate for your situation and be sure to clear the options for the Add to Favorites and other buttons in last end form before you click the Finish button. For help with this task, see How to create a report (V5): Creating a List Report.

Task 3: Configure the List View Rule to Provide Selectable Options

The generated list view rule is not configured to present the results as selectable options by default. Complete the steps in this procedure to configure how the list appears in your work object form:

1. Locate and open the rule.
2. On the Display Fields tab, select Embedded and Fixed Header.

3.  On the Contents tab, examine the list in the Get These Fields section. By default it contains the fields that are listed in the Show These Fields section of the Display Fields tab and any properties that Process Commander needs to compute or derive the values for those fields. Are there any additional properties whose values you will want to store with the work object? If so, include them here.

For the OrderEntrySystem example, the Get These Fields section has two additional properties: Price and Image (a field that holds a photo of the product).

4. Before configuring the Selectable tab, select the Pages and Classes tab. Configure two page entries: one for the applies to class of this rule and one for the work class of the flow where you plan to use this list rule. Because you refer to the work class on the Selectable tab, you must define it on the Pages and Classes tab first.

In the Page Name field for the work class, enter primary. The following figure shows the page entry for the example work class, is AlphaCorp-OrderEntrySystem-PurchaseOrder:

Using the page reference primary for the work class ensures that at runtime, this list view rule can find the work object’s primary page, no matter what it is named (pyWorkPage or pyCoverPage or ...) .

5. On the Selectable tab, do the following:

a) Select Enable Selection of Rows.
b) In the Mode field, select Multiple Select.
c) In the Copy To field, select PageList.
d) In the Name field, specify the page list property that you created in Task 1 to connect the list item class to the work class. For the example, it is primary.ProductsSelected.
e) In the Source and Target list, specify where the list rule copy the property values it obtains. That is, in the Source section, specify the properties listed in the Get These Fields section of the Content tab. In the Target section, specify the properties' counterparts in the Page List property of the work class.

Task 4: Create the element that displays the list view rule

A list view rule can be called from a section or HTML rule by using the listView JSP tag. Then a harness or flow action can call the harness. In the OrderEntrySystem example, a flow action calls a section that displays the list, so we start with the section.

1. Create a new section for the work class (User Interface > Section).  Select the HTML tab and use the listView JSP tag from the pega taglib. Here’s the code that invokes the list view rule from the example:

<pega:listView name="ProductList" className="Data-OrderEntrySystem-Product" header="false" />

2. Create a new flow action rule (User Interface > Flow Action). On the Layout tab, drag in a section shape. In the Section Include panel, enter or select the name of the section rule that you created in the previous step:

Task 5: Create the element that displays to the operators the items that they select from the list

You can use a flow action, section, or harness to display the selected items, as appropriate for the design of your application. In the example application, OrderEntrySystem, a flow action uses a repeating group to show the value of the ProductsSelected page list property and prompt the user to enter a value in the Quantity field for each item in the list.

Note: As of V6.1, create the layout on a section rule and reference it on the Flow Action form's HTML tab.

1. Create a new flow action (User Interface > Flow Action).
2. On the Layout tab, drag in a repeating group. In the Repeat panel, set the context for the page list property. For our example, the Page List property is ProductsSelected and its page class is Data-OrderEntrySystem-Products:

3. In the Repeating Group shape on the Layout tab, configure the fields that appear. For the example flow action, the Product, Quantity, Price, and Total fields appear. At runtime, the operator enters a value in the Quantity field and the Total is calculated.

Task 6: Configure the flow to use the new flow actions or sections

In the example application, OrderEntrySystem, the flow action that displays the list, BrowseProductsNewDS, connects the Select Products and Select Quantity assignments. The flow action that shows the products the operator selected and prompts them to enter a quantity, ProductQuantity, connects the Select Quantity and Confirm assignments:

Test the flow by creating a work object. For the OrderEntrySystem flow, the flow action that lists the products looks like this:

The flow action that prompts the operator to specify a quantity for each item selected looks like this: