PSP Waterfall

This chapter explains the PSP Waterfall mechanism. A PSP procedure can create waterfall output to explain calculations it has made or actions it has taken. The PSP Waterfall business service displays or saves that output. This chapter includes the following topics:

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 the following figure 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.

This image shows an example of a Pricing Waterfall. The fields in the list applet are: Adjustment, Type, Amount, and Price.

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 the following figure 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

The following figure 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. 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.

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

The waterfall output of a PSP procedure is soft-coded in the step actions. Each line item of waterfall output is created by an action that adds a child record to a named child property set of a {Row}. The following is an example PSP action that creates a row of waterfall output:

{Row}.{Net Price Waterfall} += New('Waterfall', [Text] = LookUpMessage('Pricer - 
Dynamic Matrix Adjustment', [Price Book] = {Match.Price Book}), [Adjustment Type] = 
{Match.Adjustment Type}, [Adjustment Amount] = {Match.Adjustment Amount}, [Currency 
Code] = {Row.Currency Code}, [Price] = {Row.Start Price})

In this example, a waterfall record is added to the Net Price Waterfall child property set of the current {Row}.

The fields written to the waterfall record are soft-coded in the action expression (in this case, Text, Adjustment Type, Adjustment Amount, Currency Code, Price). One common configuration is to add additional fields to an existing waterfall. Adding New Fields to an Existing Waterfall describes this configuration.

Another common configuration is to create a new waterfall output for an additional calculated value. For example, a pricing procedure could calculate the Net Price and the Cost of a line item. A waterfall explanation of the calculation of Cost could be exposed as a drill-down link on the Cost field in the UI. You can create many waterfalls for a particular {Row} by defining different child property set names (such as, {Row.Cost Waterfall} += New("Waterfall", …)). See Creating a New Waterfall for detailed instructions.

Further configuration information appears in Saving Waterfall Data.

Adding New Fields to an Existing Waterfall

You can add as many new fields as you like to an existing waterfall using the following procedure as an example. This example adds an Accounting Code field to the existing Net Price waterfall.

To add a new field to an existing waterfall

In Siebel Tools, revise the PSP procedure (for example, revise Pricing Procedure - Calculate Net Price).

Add an extra comma-separated argument to the += New() function in every action that generates waterfall output. For example:

{Row}.{Net Price Waterfall} += New('Waterfall', [Text] = LookUpMessage('Pricer - 
Dynamic Matrix Adjustment', [Price Book] = {Match.Price Book}), [Adjustment Type] 
= {Match.Adjustment Type}, [Adjustment Amount] = {Match.Adjustment Amount}, 
[Currency Code] = {Row.Currency Code}, [Price] = {Row.Start Price}, [Accounting 
Code] = {Match.Accounting Code})

The syntax [Accounting Code] = {Match.Accounting Code} adds the new field.

Add the new field to the waterfall virtual business component (for example, Net Price Waterfall VBC).
Add the new field to the waterfall pop-up applet (for example, Net Price Waterfall Popup List Applet).
(Optional) If the new field needs to be written to the database:
1. Add the new field to the tables used to store this waterfall type (for example, S_QTEIT_WTR_LOG, S_ORDIT_WTR_LOG, S_AGRIT_WTR_LOG).
2. Add the new field to the business components used to persist this waterfall type (for example,Quote Line Item Waterfall, Order Entry Line Item Waterfall, Service Agreement Line Item Waterfall).
3. Navigate to the Administration Application screen, then the Data Maps view. Add the new field to the waterfall data map objects (for example, Quote Waterfall Data Map Object, Order Waterfall Data Map Object, Service Agreement Waterfall Data Map Object).

Creating a New Waterfall

You can add a new waterfall output to any PSP procedure. A PSP procedure can have multiple waterfall outputs.

Note: It is recommended that you copy the configuration of the Net Price Waterfall when creating a new waterfall output.

The following topics contain information about creating new waterfalls:

Populating Child Waterfall Property Sets

When creating a new waterfall output, you first populate a child waterfall property set for each output row of the PSP procedure.

To populate a child waterfall property set for each output row of a PSP procedure

Create new UMS message types to format text for your new waterfall output. See Creating Message Types.
Define PSP actions to create the waterfall output in your PSP procedure.
1. Use the {Row.Waterfall Name} += New() syntax to create a new waterfall record and append it to the desired waterfall property set. The New() function has the following syntax:
```
New('Waterfall',  Name 1 =  Value 1,  Name 2 =  Value 2,.)
```
  Name n and Value n are the waterfall output field names and values; for example:
```
Currency Code = USD
```
2. Use the LookUpMessage function to format text in the appropriate language with variable values substituted through a call to the UMS business service, with the following syntax:
```
LookUpMessage('Message Name',  Name 1 =  Value 1,  Name 2 =  Value 2,.)
```
  Name n and Value n are the payload field names and values that will be used by the UMS business service to construct the message text; for example:
```
Price List = Americas Price List
```

Exposing the Waterfall Output

Next, you expose the waterfall output on the user interface.

To expose the waterfall output as a drilldown on a field in the UI

Create a new virtual business component based on class CSSBCVWaterfall.
1. Create fields for each waterfall output column.
2. Create a field called Name, which is used internally to query the correct data by the waterfall name.
3. Compile the virtual business component.
Create a new pop-up applet based on class CSSSWEFrameListPopupWaterfall using the VBC created in Step 1.
1. Set its search specification to query the field Name with a value of the created waterfall, such as:
```
Name = "Cost Waterfall"
```
2. Define the column layout.
3. Compile the applet.
Create a drilldown link to the new pop-up applet in each list applet that displays the field calculated by the PSP procedure.
1. Add a drilldown object to the applet defining the field on which the drilldown is displayed and the drilldown name. Leave all other fields blank.
  Example:
```
Name = "Waterfall Popup 2"; Field = "Cost"
```
2. Add a user property to the applet indicating which waterfall pop-up applet to display upon each drill-down:
  Example:
```
Name = "Waterfall Popup Applet 2"; Value = "Cost Waterfall Popup List Applet"
```
  Note: Multiple waterfall drilldown links are supported by incrementing the index at the end of the Waterfall Popup Applet N drilldown name.
  
  Applet classes CSSSWEFrameListQuoteItemEC and CSSSWEFrameListWaterfall support waterfall drill-down.
  
  Note: CSSSWEFrameListWaterfall is derived from class CSSSWEFrameListBase directly.
3. Compile the applet.

Saving Waterfall Data

Waterfall data is saved using Data Transfer Utility (DTU). You can configure the application to save waterfall records manually or automatically as described in this topic.

To enable persistence of the new waterfall data in the database

(One option is to do this by using a command.) In the Siebel application, navigate to the Administration - Order Management screen, then the Signals view, and add a new signal to save the waterfall output. Use SaveWaterfall-Order as an example.
1. In Siebel Tools, add a command to invoke the signal when the user selects a menu option. Use SaveWaterfall-Order as an example. Values are described as follows:
  Display Name: [Name to be displayed]
  
  Name: [Name of the command]
  
  Method: [Signal Name]
2. Create a custom table to store the waterfall output (for example, CX_COST_WATERFALL).
3. Create a business component (BC) based on the table with the same field names as in the virtual business component used to display the waterfall.
4. Create a data map object. Use Order Waterfall Data Map Object as an example.
  In the Siebel application, navigate to the Administration - Application screen, then the Data Map Administration view, and create a new data map object.
  
  The source is the VBC and the destination is the BC.
(Another option is to save the waterfall data manually by using an applet menu button or an applet button.) As in Step 1, add a new signal to save the waterfall output.
1. In Siebel Tools, add an applet menu button (call it Save Waterfall).
2. Add an object to Applet Method Menu Item of the waterfall-triggering applet, and then expose it to the applet. Values are as follows:
  Command Name: [The command added to save this waterfall]
  Text: Save Waterfall
  
  Alternatively, you can add an applet button (Save Waterfall) in Siebel Tools by adding a control to the waterfall-triggering applet and then exposing it to the applet. Use the following values:
  Name: Save Waterfall
  Method Invoked: [The signal added to save this waterfall]
  Caption: Save Waterfall

For more information about creating and using signals, see Signals For more information about DTU, see the topic about Data Transfer Utility in Siebel Finance Guide.

PSP Waterfall Business Service Methods

The PSP Waterfall business service provides the methods described in the following table.

Method	Arguments	Description
ShowWaterfallPopup	Name = Popup Applet Name Value = the name of the waterfall popup applet Example: “Quote Line Item Waterfall Popup List Applet”	Display the waterfall pop-up for the current line item.
SyncToDB	See SyncToDB Input Arguments	Generate waterfall records for the current quote, order, or agreement and write them to the database. For more information, see Saving Waterfall Data.

Method

Arguments

Description

ShowWaterfallPopup

Name = Popup Applet Name

Value = the name of the waterfall popup applet

Example: “Quote Line Item Waterfall Popup List Applet”

Display the waterfall pop-up for the current line item.

SyncToDB

See SyncToDB Input Arguments

Generate waterfall records for the current quote, order, or agreement and write them to the database.

For more information, see Saving Waterfall Data.

SyncToDB Input Arguments

The SyncToDB method provides the input arguments described in the following table.

Note: You may prefer to use SyncToDB in a signal, rather than directly in a command, for synchronizing waterfall data to the database. If so, use the guidance provided in Saving Waterfall Data.

Argument	Type	Value
Pricing Output Row Set Type	String	RowSet
Waterfall Data Map Object	String	Quote Waterfall Data Map Object
Waterfall Name Field	String	Name
Waterfall Parent Id Field	String	Item Id
Waterfall Parent Id Variable	String	ID
Waterfall Signal	String	PSPWaterfallAll
Waterfall Synch Process	String	PSP Waterfall Synch to DB Workflow
Waterfall Sequence Number Field	String	Sequence Num