Siebel Order Management Infrastructure Guide > PSP Waterfall >

About Waterfalls

A waterfall is an applet or a pop-up window that provides line-item explanation about field values— displaying any combination of values such as text, numbers, or dates—such as the figures that were used to arrive at a particular value in a field. As one example of a waterfall, the pricing waterfall shown in Figure 34 shows the details of the calculation used to arrive at the net price. This example shows a base price used for an item ordered, minus the discount given to arrive at the net price.

Figure 34. Example of a Pricing Waterfall

As another example, you might implement a waterfall on a product's eligibility status, to show the end user all the reasons a product cannot be purchased (rather than just one reason).

All text displayed to the end user in waterfalls is translatable. the Unified Messaging Service (UMS) business service dynamically translates and substitutes waterfall text . The UMS business service processes all translations through the LookUpMessage API in PSP action script:

{Row}.{Net Price Waterfall} += New('Waterfall', [Text] = LookUpMessage({Row.Temp List Price Message}, [Price List] = {Match.Price List}), [Currency Code] = {Row.Currency Code}, [Price] = {Row.List Price})

For more information about UMS, see Unified Messaging.

A PSP Procedure Generates Waterfall Output Each Time It Executes

Waterfall output is generated on demand when the user clicks a waterfall-enabled field, but the PSP procedure generates the waterfall output every time it executes. The waterfall's output may be ignored much of the time, but when the user drills into a waterfall-enabled field, the procedure reruns to generate and then display the waterfall output for that record and field.

For example, the values for the pricing waterfall in Figure 34 are generated when the user clicks the Net Price field in a Quote or Order line item. The waterfall pop-up window appears displaying these values. The user clicks OK to hide the pop-up window. But even if the user does not click the Net Price field to view the pricing waterfall, the same waterfall output is generated (but not saved or displayed without configuration) when the PSP procedure executes.

A Controller Workflow Invokes the PSP Waterfall Business Service

Figure 35 shows how the PSP Waterfall mechanism generates and saves waterfall output. For a PSP procedure that generates waterfall output, such as the Pricing PSP procedure shown in the diagram, a controller workflow invokes the PSP waterfall business service.

The PSP engine supports the creation of a waterfall with an unlimited number of sequenced child rows to explain each name-value pair in the row. It is the child rows' type that defines the waterfall to which they belong. For example, "Net Price Waterfall" is the type for each of the child rows that compose the Net Price waterfall in the example above. Multiple waterfalls can be created for one row, up to one for each name-value pair.

Each waterfall has a configurable set of name-value pairs. For example, a pricing waterfall uses different fields than an eligibility waterfall.

Figure 35. How PSP Works with Waterfall Output

Waterfalls and Performance

Waterfall output is generated every time a PSP procedure executes. For example, when the user clicks a Net Price to display its waterfall, that record is repriced and fresh waterfall output is generated for display. This process keeps the waterfall output and net price in sync. This process requires minimal overhead, because it is done in memory.

If a line item is read-only (for example, because it has already been submitted as an order), then it is not possible to reprice the item. In this case, the waterfall virtual business component looks for saved waterfall output for that line item and the waterfall displays that saved waterfall output instead.

NOTE:  The ReadOnlyOrderStatus user property is overwritten by the Business Component read-only field user property (if the value for the business component user property is active). For example, if ReadOnlyOrderStatus for a BC User Property is set to Billed, Submitted, Completed, and read-only status for Submitted is Active, then the record is read-only for the status value Submitted (not for Billed and Completed).

Waterfall output is only saved to the database upon user request. Writing waterfall records to a database can be costly. The waterfall records are written in the background to minimize end-user latency. For more information, see Saving Waterfall Data.

Configuration of Waterfalls

When configuring waterfalls, refer to the information provided in the following topics:

• About Configuring Waterfall Output
• PSP Waterfall Business Service Methods