5PSP Engine

PSP Engine

This chapter describes the Product Selection and Pricing (PSP) engine and explains the how-to aspects of working with PSP. It includes the following topics:

• About the Product Selection and Pricing Engine

• Components of the PSP Engine

• PSP Driver Workflow

• Conditions and Actions for PSP Procedures

• About Temporary Variables

• Row Set Transformation Toolkit Methods

• Configuring PSP Procedures

• Creating a Custom PSP Application

• Calling a PSP Procedure from an External Application

• About Logging of PSP

• About Troubleshooting of PSP

• About Tuning Performance of PSP

About the Product Selection and Pricing Engine

The Product Selection and Pricing (PSP) engine is a generalized procedural logic engine for transforming an input row set into an output row set. PSP is an extension of Siebel Workflow. A PSP procedure is a workflow process that includes a Business Service step employing methods of the Row Set Transformation Toolkit business service.

A PSP procedure transforms a set of input rows into a set of output rows by executing matrix lookups, conditional logic, and external function calls. In this release, the functions of pricing, eligibility (product, attribute, and promotion), and product recommendation use the PSP engine.

For example, Siebel Pricer uses PSP procedures to apply all of the different types of discounts that are available with a particular product. Because these discounts are based on a PSP procedure rather than on C++ code, you can:

• Change the order in which discounts are applied.

• Customize the calculations used by discounts.

• Extend the preconfigured pricing PSP procedure to calculate additional costs or prices and margin.

Advantages of PSP Usage

The following are some of the benefits of using PSP procedures as a basis for Siebel order management tasks:

• Highly configurable procedural logic eliminates or reduces the need for custom script.

• PSP methods and infrastructure are optimized for performance (for example, with set-based processing, caching, and SQL query consolidation).

• The PSP framework can be extended for use with external services and functions.

• Integrators can learn this one framework and use it for pricing, eligibility, and so on.

PSP Concepts

A PSP procedure is the sequence of steps involved in transforming an input row set into an output row set. Examples of steps include a call to a business service, an instance of a transform, a conditional branch, a subprocedure call, or a terminator (an end step). A PSP procedure is any workflow that uses methods from the Row Set Transformation Toolkit business service.

A controller workflow is the invocation mechanism for the PSP engine. A PSP procedure is always called by a controller workflow. A controller workflow retrieves contextual information, invokes a generic PSP procedure, and then processes the results. It insulates the underlying PSP logic (such as a pricing procedure) from the calling context (such as repricing a quote or pricing an XML order passed in through a Web service). For more details on controller workflows, see Controller Workflow.

A row set is a property set that conforms to the structure defined in About Row Sets. It is used to represent the set of data upon which the PSP engine operates (such as data for quote line items).

The Row Set Transformation Toolkit is a business service that exposes a set of methods called transforms. Transform methods are called by steps within a PSP procedure. A transform accepts one or more input row sets, performs a series of operations (such as database queries), and then returns an updated version of the row sets as output. Special step input arguments called actions define the processing performed by a particular step. An action can perform a wide variety of updates to the input row set (such as setting the Net Price field value). Most transforms have a defined set of transform conditions that occur while the transform is executing (for example, the Simple Look-Up transform queries the database and then raises one or more of the following conditions: On First Match, On Match, On Last Match, On No Match). The condition raised depends on the result of the SQL query. Actions are attached to these conditions.

How PSP Procedures Are Built

PSP procedures are created in the same way that standard workflows are created, in the Business Process Designer. The Process Designer is a user interface to help you arrange process objects. You access it from the Workflow Process object in Siebel Tools. For more information about building workflows, see Siebel Business Process Framework: Workflow Guide.

Like a standard workflow, a PSP procedure has a start step and an end step. A PSP procedure differs from a standard workflow in that the steps of a standard workflow perform actions, while the steps of a PSP procedure transform row sets in some way, as shown in the following figure. In the following figure, a set of product information that includes data on product IDs, names, and quantities is transformed into a new set of information that includes an additional product as well as pricing information for each product.

The PSP engine transforms row sets using the methods in the Row Set Transformation Toolkit business service. For more information about these methods, see Row Set Transformation Toolkit Methods.

About Row Sets

A type of property set, a row set is a memory structure used to pass data between business services. A row set is a group of rows where each row contains multiple name-value pairs (paired values). A row within a row set can have multiple child property sets with name-value pairs; the hierarchy goes no deeper than these child property sets.

The following figure provides a graphical example of a row set. In this figure, the second layer of boxes labeled "Row 1," "Row 2," and "Row 3" are the rows within this example row set. Each of these rows 1 through 3 have name-value pairs for data labeled "ID," "Price List ID," "Product ID," "NRC Price," and "MRC Price." Additionally, each of these rows 1 through 3 contains child property sets, called "NRC Price Waterfall Row Set" and "MRC Price Waterfall Row Set." The child property sets contain their own rows with name-value pairs, for a deeper level of pricing data.

For more information about Siebel property sets, see Integration Platform Technologies: Siebel Enterprise Application Integration.

Components of the PSP Engine

The PSP engine is comprised of the pieces shown in the following figure and described in the following topics:

• Controller Workflow

• Variable Maps

• PSP Procedures

• PSP, Siebel Workflow, and Siebel Tools

• Row Set Transformation Toolkit Business Service

• Custom Business Services

Controller Workflow

A controller workflow invokes the PSP engine every time a PSP procedure is called. The controller workflow insulates the PSP procedure from the calling context. The various calling contexts, such as Siebel Configurator, a product picklist, or a Web service, each have separate controller workflows. The PSP Driver Workflow Process is an example of a prebuilt controller workflow. You can configure your own controller workflows to meet your organization’s particular needs.

Note: PSP Driver Workflow Process is the generic controller workflow. For more information, see PSP Driver Workflow.

While the PSP procedure transforms row sets in memory, the controller workflow passes those row sets to the PSP procedure and then determines what to do with the PSP procedure’s output. The typical flow is:

• An end user clicks a button or makes some other choice in the interface.

• This end-user action triggers a signal which executes the controller workflow.

• The controller workflow establishes the inputs for the PSP procedure by finding data and constructing this data into row sets. The controller workflow can use the variable maps mechanism to construct the row sets.

• The controller workflow calls the PSP procedure and passes the inputs to it.

• The PSP procedure transforms the inputs and sends the transformed row set back to the controller workflow.

• The controller workflow determines what to do with these transformed rows. For example, it might display the transformed rows on the screen or write them to the database.

The PSP procedure’s only function is to transform row sets in memory. The controller workflow executes any other actions.

The following figure shows an example of a controller workflow.

This controller workflow and its called PSP procedure operate as follows:

1. Get Shared Context Variables. This first step (after the Start step) obtains the needed data by using the variable maps mechanism (the Context Service business service) to populate a property set containing context variables shared by all rows (such as Channel, Account Type, or User Role).

2. Get Selected Line Items as Row Set. This step instructs the Context Service business service to populate a property set containing the input row set.

3. Price. This Subprocess step calls the Price PSP procedure, passing the context variables and the input row set. The Price PSP procedure transforms the row set and passes the values back to the controller workflow.

4. Update Line Items. This step, which also uses variable maps, updates the line items with the values from the transformed row set. That is, it saves the newly calculated prices.

Variable Maps

Variable maps, using the Context Service business service, help the controller workflow to construct inputs to PSP procedures and process the output of PSP procedures. The Context Service business service optimizes the querying and updating of row set data by reading data directly from the active business component, thereby eliminating unnecessary SQL queries. Context Service provides a row-level delta that determines which line items to update. Batched SQL eliminates unnecessary network round-trips.

The Context Service business service:

• Constructs the input row sets. Context Service converts business component data, XML, or property set data to a common format. It translates from various name spaces to the PSP name space. It defines the subset of fields required by the PSP procedure.

• Writes the output row set back to its source. Context Service converts from the common format back to the business component data, XML, or property set data. It translates from the PSP name space to the target name space.

Note: Most PSP procedures use the Context Service business service, but it is not required for all PSP procedures. For example, a Web service could invoke Siebel Pricer with a property set directly generated from the input XML document by XSLT, without using the Context Service business service.

For more information about variable maps and the Context Service business service, see Variable Maps.

PSP Procedures

A PSP procedure is any workflow that uses methods from the Row Set Transformation Toolkit business service. These methods of the Row Set Transformation Toolkit business service are called PSP transforms. A transform, such as the Simple Look-Up method, processes an input row set. There are a number of transforms that process input row sets in different ways. For example, the Simple Look-Up transform uses a simple search expression to look up each input row in a business component, while the Split transform takes an input row set, evaluates a condition for each of its rows, then splits the input row set into two output row sets.

Note: In addition to invoking Row Set Transformation Toolkit business service methods, a PSP procedure can invoke methods from custom business services.

Each step in a PSP procedure is a parameterized call to a transform method. A PSP procedure can call another PSP procedure as a subprocess, to provide for modularization of logic.

The Siebel Business Process Designer interface is used to create both the PSP procedure and the controller workflow that invokes it. Like any workflow process, a PSP procedure can make use of any standard Siebel Workflow feature.

The following figure shows an example of a PSP procedure used in pricing. Each step is a parameterized call to a method in the Row Set Transformation Toolkit.

Notice that one of the steps splits the input row set into multiple temporary subsets. Later steps perform logic on these subsets. The last step merges these subsets, so they form a single row set again.

PSP, Siebel Workflow, and Siebel Tools

Siebel Workflow—the application you use to define, manage, and enforce your organization’s business processes by creating workflow processes—is also the application you use to create, edit, and execute PSP procedures. Siebel Workflow’s Process Designer resides in Siebel Tools.

Note: Siebel Workflow is also known as Siebel Business Process Designer, which is the configuration interface and the administrative interface for Siebel Workflow.

You configure PSP procedures and their controller workflows from the Workflow Process object, a top-level (highest level) object in the Object Explorer within Siebel Tools. In this way, you use the Process Designer to enter transforms for PSP procedure steps as input arguments.

For more information about Siebel Workflow, see Siebel Business Process Framework: Workflow Guide. For more information about configuring PSP procedures, see Configuring PSP Procedures.

Row Set Transformation Toolkit Business Service

The Row Set Transformation Toolkit is a business service that provides the following methods (also known as transforms) for manipulating and transforming row sets:

• Aggregate Method. Calculate the minimum, maximum, average, sum, or count of sub-groups of the row set.

• Conditional Action Method. Evaluate a Boolean expression for each row and perform actions based on the result.

• Dynamic Look-Up Method. Look up each input row in a business component using a dynamic search expression (example: attribute adjustment).

• Dynamic Subprocedure Method. Send each input row to the specified subprocedure for individual processing. Each row can be associated with a different subprocedure.

• Hierarchical Look-Up Method. Look up the closest, best, or accumulated value in an adjustment table for each row by considering each parent in a hierarchy (example: parent company discount).

• Hierarchical Method. Process a hierarchy of input rows from start to end or end to start (example: customizable product price roll-up).

• Merge Method. Combine two or more row sets into a single row set.

• Query Method. Query a business component and generate a row set.

• Row Set Look-Up Method. Look up each input row in the specified row set (example: check compatibility between a product and the list of products currently owned by the customer).

• Rule Set Look-Up Method. Look up the rules for each input rule set and test the rules against the row set. Perform actions if the rule set passes or fails (example: identify applicable bundles or promotions).

• Simple Look-Up Method. Look up each input row in a business component using a simple search expression (example: list price, exclusive eligibility).

• Split Method. Split an input row set into two output row sets by evaluating a condition for each row.

For each of these methods, you specify a condition and actions, as described in Conditions and Actions for PSP Procedures. All the methods support the same action syntax and capabilities. Each method exposes a unique set of conditions and variables.

For details on each of these methods, see Row Set Transformation Toolkit Methods.

Custom Business Services

In addition to calling Row Set Transformation Toolkit business service methods, PSP procedures can call custom methods that you write using Siebel VB or Siebel eScript. For more information, see Siebel VB Language Reference and Siebel eScript Language Reference.

PSP Driver Workflow

A controller workflow is the invocation mechanism for each PSP procedure. The workflow called PSP Driver Workflow Process is the default controller workflow. When a signal calls the controlling workflow for a process, it passes the names of the PSP procedures to the PSP Driver Workflow.

Note: PSP Driver Workflow is the default controller workflow, but you can configure your own controller workflow to replace the default if you find that modifications are necessary for your organization’s requirements. You configure a controller workflow in the same way that you configure a standard workflow process. You specify the arguments of a controller workflow in the signal definition, so for your custom controller workflow, navigate to the Administration - Order Management screen, then the Signals view in order to change this definition. For information about configuring workflow processes, see Siebel Business Process Framework: Workflow Guide.

Arguments for the default PSP Driver Workflow are shown in the following figure. PSP Driver Workflow is set as the controller workflow for the signal CalculatePriceAll in the Service Name field of the Actions tab.

The PSP Driver Workflow acts as the controller workflow for the pricing and eligibility PSP procedures. It calls the Context Service to construct a property set called Row Set containing the selected rows from the source object (Quote, Order, Agreement, or Customizable Product). It also calls the Context Service to construct a property set called Context that contains header-level information shared by all rows (for example: Account Type, Credit Score). It then invokes the PSP procedure specified in its input arguments. The PSP procedure updates and returns a new version of Row Set. Finally, the controller workflow instructs the Context Service to save any changes in Row Set back to the source object.

The PSP Driver Workflow, shown in the following figure, does the following:

1. Asks the Context Service to generate two property sets (row sets): the shared Context and the Row Set containing individual line items. These are representations of the Line Item and Header business components using variable maps. For more information about variable maps, see Variable Maps.

2. Dispatches to the workflow indicated by the process property PSPWorkflowName. For example, in the event the user selected RepriceAll, this step dispatches to the Pricing Procedure - Default workflow to perform all pricing operations.

3. Synchronizes the updated PSP information back to the input data source (Quote, Order, Agreement, or Customizable Product). The synchronization can be skipped by setting the Sync process property.

The following table provides a list of the steps in the PSP Driver Workflow Process, showing also the business service and method called by each step.

Step Name	Type	Business Service	Method	Description
Get Context Row Set	Business Service	Context Service	GetRowSetData	Generate the Context Property Set which represents the Header Buscomp.
Get Row Set	Business Service	Context Service	GetRowSetData	Generate the Row Set Property Set which represents the Line Item Buscomp.
Set Pricing Date	Business Service	Context Service	GetRowSetData	Set pricing date.
Dispatch Service	Business Service	ISS PSP Dispatch Service	CallPSPWorkflow	Dynamically dispatch to a sub-process.
Need to Sync?	Decision Point	None	None	A user decision point of whether synchronization is needed.
Sync Row Set	Business Service	Context Service	SyncRowSetData	Synchronizes information back to data sources using Context Service.

Conditions and Actions for PSP Procedures

Steps of PSP procedures can call Row Set Transformation Toolkit business service methods. Each Row Set Transformation Toolkit method (transform) performs a parameterized set of actions based on conditions that occur as the method executes.

Conditions and actions for each step are entered as input arguments in Siebel Workflow’s Process Designer in Siebel Tools, as shown in an example in the following figure:

• In the Input Argument field, select the condition name.

• In the Value field, enter the processing to perform if the condition is true.

• You can specify multiple actions for one condition by using a different index number for the condition name. In the following table example, there are multiple actions for the On True 1 condition, with the condition name On True 1_1, On True 1_2, and On True 1_3.

• Some Row Set Transformation Toolkit business service methods can include one or more Boolean conditions to which the other conditions refer. In the following figure example, Condition 1 is a Boolean condition which checks the values in the Effective From and Effective To fields. The conditions On True 1_1, On True 1_2, and On True 1_3 are true if this Boolean condition is true.

• Actions are executed in the sequence specified by the index on the name. For example, the action for On True 1_1 executes before the action for On True 1_2.

PSP-Supported Action Expression Constructs

The following table defines the types of action expressions supported by PSP.

Action	Examples
Set a property of a row to the value of an expression	{Row.Eligibility Status} = LookupValue('ELIGIBILITY_STATUS','No') {Parent.Roll-Up Amount} = ToNumber({Parent.Roll-Up Amount}) + ToNumber({Row.Net Price})
Remove a property from a row	{Row} -= {Row.Temp Roll-Up Price}
Move a row from one row set to another	{Output Row Set} += {Row} {Row Set} += {Output}
Copy a row to another row set	{Output Row Set} += Copy({Row})
Construct a new row and attach it as a child to the specified row set or row	{Row}.{Waterfall} += New(‘Waterfall’, Text = ‘Hello’, Value = 10) {Row Set} += New(‘Row’, Text = {Match.Text})
Delete the current row from a row set	{Row Set} -= {Row} {Output Row Set} -= {Output}

PSP-Specific Functions Used in Action Expressions

Action expressions support the full Siebel Query Language syntax including functions such as LookupValue, IfNull, IIF, and InvokeServiceMethod. For more information about Siebel Query Language, see Siebel Tools Online Help.

In addition to Siebel Query Language syntax functions, action expressions can include the PSP-specific functions shown in the following table.

Function	Description
ToNumber({Row.Qty})	Convert the specified property value to a number. All values are stored as a string in a property set.
ToDate({Row.Effective Start Date})	Convert the specified property value to a date. All values are stored as a string in a property set.
ToCurrency({Row.Net Price}, {Row.Currency Code})	Convert the specified property to a currency. All values are stored as a string in a property set.
AdjustPrice({Row.Net Price}, {Row.Currency Code}, {Match.Adjustment Type}, {Match.Adjustment Amount}, {Match.Currency Code}, {Match.Exchange Date})	Apply the specified pricing adjustment. This function automatically converts the currency of monetary adjustments to match the currency of the line item.
LookUpMessage('Pricer Waterfall - Selected Contract Adjustment', [Account] = {Row.Temp Contract Account})	Retrieve substituted, translated text from the UMS business service. Payload variables are specified as name-value pairs after the message type. For more information about the Unified Messaging framework, see Unified Messaging For details on using the UMS business service in a PSP procedure, see Using Unified Messaging with the PSP Engine.
GetXA({Row}, ‘Color’)	Get an attribute value for a row. The GetXA method has two different signatures: GetXA({Row},<Attribute Name>) GetXA({Row}, "Name", <Attribute Name>, "LICValue") For more information about the second signature, see Using the Four-Parameter GetXA Signature.
Sum({Row Set}, ‘Extended Net Price’)	Sum the value of a field for all children of a property set.
Avg({Row}.{Shipments}, ‘Cost’)	Calculate the average value of a field for all children of a property set.
Min({Row Set}, ‘Score’)	Get the minimum value of a field for all children of a property set.
Max({Row Set}, ‘Score’)	Get the maximum value of a field for all children of a property set.
Count({Children})	Count the children of a property set.
Round({Row.Price}, {Context.Precision})	Round a number to the specified decimal places.

Using the Four-Parameter GetXA Signature

Use the four-parameter GetXA signature if the attribute that you want to obtain is of type integer, otherwise errors can result in calculations especially where numerous digits are involved.

To use the four-parameter GetXA signature in a workflow, you must add an additional step to retrieve LICValues for the attributes as described in the following procedure.

To use the four-parameter GetXA signature in a workflow

1. Add an additional step to retrieve LICValues for the attributes as follows:

   1. In the workflow editor, create a new "Business Service" before executing the GetXA step.

   2. Set the Business Service Name to "Pricing Manager" and Method to "PopulateAttrLICValue"

   3. Set the following input parameter:

      Input Argument	Type	Property Name
      Row Set	Process Property	Row Set

   4. Set the following output parameter:

      Property Name	Type	Output Argument
      Row Set	Output Argument	Row Set

2. Use the following four-parameter GetXA signature:

   GetXA({Row}, "Name", <Attribute Name>, "LICValue")
   

   for example, as follows:

   {Row.Temp Attr} = ToNumber(GetXA({Row},"Name","Attribute Name","LICValue"))
   

LookUpMessage API

The Unified Messaging framework’s UMS business service processes all translations using the LookUpMessage API in a PSP action script. For example, for a pricing waterfall, it might use the following 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 details on using the UMS business service in a PSP procedure, see Using Unified Messaging with the PSP Engine.

Row Set Variables Used in Action Expressions

Action expressions operate on the row set variables shown in the following table.

Variable	Description
{Row Set}	The input row set for the step (specified as an input argument).
{Context}	The input property set of variables shared by all rows (specified as an input argument). {Context} acts as a set of default values for every {Row}. If {Row.Value} is not specified, then PSP automatically returns {Context.Value}. This also works for {Parent.Value} in the Hierarchical transform. If no value is found in {Row} or {Context}, then an error is raised.
{Output Row Set}	The optional output row set for the step. Most steps allow rows to be updated and written to both {Row Set} and {Output Row Set}.
{Row}	The {Row Set} row currently being processed by the transform.
{Output}	The last row added to the {Output Row Set} property set.
{Parent}	The parent row of {Row}. (Hierarchical transform only.)
{Children}	A row set containing the child rows of {Row}. (Hierarchical transform only.)
{Match}	A property set containing name-value pairs from a joined record in a business component or other row set. (Look-Up transforms only.)
{Property Set.Name}	The value of property “Name” in the property set. (Examples: {Row.Net Price} or {Match.Discount %})
{Property Set}.{Type}	The child row set of “Property Set” of type “Type”. (Example: {Row}.{Net Price Waterfall})

Conditions and Action Variables Vary by Transform

All Row Set Transformation Toolkit business service methods (transforms) support the same action syntax and capabilities. However, each method exposes a unique set of conditions and variables. For example:

• The Simple Look-Up transform joins each input row to a business component. It exposes On First Match, On Match, On Last Match, and On No Match conditions.

  Actions can reference:

  • Any field in the input row (for example, {Row.Product Id}), or

  • The joined business component (for example, {Match. List Price}).

  • The Hierarchical transform sorts the input row set into a series of tree structures and then navigates each tree from start to end or end to start. It exposes On Leaf Row, On Row, On Parent Row, and On Top Row conditions. Actions can reference:

    • The current row (example: {Row.Roll-Up Price})

    • Its immediate parent row (example: {Parent.Price})

    • Its child rows (example: {Children.Qty}).

For more information about the conditions and actions for each method, see Row Set Transformation Toolkit Methods.

About Temporary Variables

You can create temporary variables simply by using a name that is not defined in the Variable Maps.

A temporary variable persists for the life of the property set unless you explicitly delete it using a {Row} -= {Row.Temp Variable} action. In general, there is no need to delete temporary variables, because they create little overhead in having a few temp variables.

It is recommended that you use a naming convention for temporary variables, such as beginning each one with Temp (for example, Temp Roll Up Price), to make sure that they do not conflict with the names of other variables.

Note: Variable names are case sensitive. For example, if you try to refer to the {Row.Net Price} variable and you mistakenly use {Row.NEt Price}, the application will not recognize the variable.

Row Set Transformation Toolkit Methods

PSP procedures use the methods in the Row Set Transformation Toolkit to manipulate and transform row sets. The Row Set Transformation Toolkit includes the following methods:

• Aggregate Method

• Conditional Action Method

• Dynamic Look-Up Method

• Dynamic Subprocedure Method

• Hierarchical Look-Up Method

• Hierarchical Method

• Merge Method

• Query Method

• Row Set Look-Up Method

• Rule Set Look-Up Method

• Simple Look-Up Method

• Split Method

Aggregate Method

The Aggregate method calculates the sum, average, minimum, maximum, or count of subgroups of the input row set.

Arguments

Input Argument	Description
Context	Optional. Property set of variables shared across all rows.
Row Set	The set of rows to process.
Output Row Set	Output Row Set is always created and contains the aggregation results. Each row contains the Group By fields plus the Aggregate Fields (example: Price List ID, Product ID, Qty). For the Count aggregate type, the output row contains the Group By fields plus a field called Count.
Process Condition	A Boolean condition that is evaluated to determine whether to process each row.
Aggregate Type	Sum, Avg, Min, Max, or Count.
Aggregate Field	The field to aggregate (example: Qty). Required for all types except Count. Multiple fields can be aggregated by specifying a comma-separated list of field names.
Group By	Optional. A comma-separated list of row field names. Defines the groups of aggregates. (Example: Price List ID, Product ID).

Example

The following figure shows an example of arguments for a PSP procedure step named Sum Product Quantity, which calls the Aggregate method.

Conditional Action Method

The Conditional Action method evaluates one or more Boolean expression for each row in the row set and performs actions on the row based on whether the conditions are true.

Arguments

Input Argument	Description
Context	Optional. Property set of variables shared across all rows.
Row Set	The set of rows to process.
Output Row Set	Optional. The property set used for output.
Process Condition	A Boolean condition that is evaluated to determine whether to process each row.
Condition [1..10]	Optional. Boolean expressions that must be satisfied to initiate corresponding actions. Executed like an If…Else If…Else If…Else statement.
On True [1..10]_[1..10]	Actions to perform if the corresponding condition is true.
On Default [1..10]	Actions to perform if none of the conditions is true.

Example

The following figure shows an example of arguments for a PSP procedure step named Keep Price, which calls the Conditional Action method.

Dynamic Look-Up Method

The Dynamic Look-Up method looks up each input row in a dynamic matrix using a dynamic search expression. For example, it could be used for attribute adjustments.

Arguments

Input Argument	Description
Context	Optional. Property set of variables shared across all rows.
Row Set	The set of rows to process.
Output Row Set	Optional. The property set used for output.
Process Condition	A Boolean condition that is evaluated to determine whether to process each row.
Dynamic Matrix Name	The name of the dynamic matrix to query.
Cache Enabled	Optional. Whether to cache query results. Y or N. The default is N.
On First Match [1..20]	Actions to perform on the first query result for each input row.
On Match [1..20]	Actions to perform on every query result for each input row.
On Last Match [1..20]	Actions to perform on the last query result for each input row.
On No Match [1..20]	Actions to perform if there are no query results for an input row.

Example

The following figure shows an example of arguments for a PSP procedure step named Matrix Adjustment, which uses the Dynamic Look-Up method.

Dynamic Subprocedure Method

The Dynamic Subprocedure method sends each input row to the specified subprocedure for individual processing. Each row can be associated with a different subprocedure.

Note: Rows are grouped together into an input row set and passed to each subprocedure in a single invocation.

Arguments

Input Argument	Description
Context	Optional. Property set of variables shared across all rows.
Row Set	The set of rows to process.
Subprocedure Expression	Defines the procedure to execute for the row.
[Input Arguments]	Any other input arguments to be passed to the subprocedures.

Example

The following figure shows an example of arguments for a PSP procedure step named Execute Line Specific Pricing.

Hierarchical Look-Up Method

The Hierarchical Look-Up method looks up the closest, best, or accumulated value in an adjustment table for each row by considering each parent in a hierarchy. For example, it could be used to give discounts to companies based on their parent-company discounts.

Arguments

Input Argument	Description
Context	Optional. Property set of variables shared across all rows.
Row Set	The set of rows to process.
Output Row Set	Optional. The property set used for output.
Process Condition	A Boolean condition that is evaluated to determine whether to process each row.
Hierarchy Business Object	The business object to query to retrieve the hierarchy (example: Account).
Hierarchy Business Component	The business component to query to retrieve the hierarchy (example: Account).
Row ID Field	The hierarchical ID field in the input row (example: “Account Id”.
HBC ID Field	The ID field of the hierarchy business component (example: “Id”).
HBC Parent Field	The parent ID field in the hierarchy business component (example: “Parent Account Id”).
HBC Visibility Mode	Optional. The visibility mode of the hierarchy business component query.
HBC Search Specification	Optional. An additional search specification that is applied to the hierarchy query.
Business Object	The business object to query for matching records (example: Agreement).
Business Component	The business component to query for matching records (example: Agreement Item).
Search Specification	A search expression comprised of business component fields, literals, and variable values from {Context} and {Row}. For example: [Product Id] = {Row.Product Id} AND [Effective From] <= Today() AND ([Effective To] IS NULL OR [Effective To] >= Today())
In Memory Search Specification	Optional. Additional terms that are ANDed with the Search Specification. The In Memory Search Specification is executed in memory. This can be used only if Cache Enabled is Y.
Cache Search Specification	Optional. Additional terms that define the key values for the Level 1 cache; for example: [Price List Id] = {Row.Price List Id}) For more information, see About PSP Cache Performance Statistics.
Sort Specification	Optional. A comma-separated list of business component fields used to sort the query result.
Cache Enabled	Optional. Specifies whether to cache query results. Y or N. The default is N.
BC ID Field	The hierarchy object ID field on the query business component (example: Account Id).
On First Match [1..20]	Actions to perform on the first query result for each input row.
On Match [1..20]	Actions to perform on every query result for each input row.
On Last Match [1..20]	Actions to perform on the last query result for each input row.
On No Match [1..20]	Actions to perform if there are no query results for an input row.

Implementing Aggregate Functions

The arguments for the Hierarchical Look-Up method are used with the aggregate functions shown in the following table. See the following table for further description.

Aggregate Function	Approach
Closest	On First Match condition, set the output row value to a match record value.
Minimum	On Match condition, set the output row value to the value of an expression: {Row.Value} = IIF({Match.Value} < {Row.Value}, {Match.Value}, {Row.Value})
Maximum	On Match condition, set the output row value to the value of an expression: {Row.Value} = IIF({Match.Value} > {Row.Value}, {Match.Value}, {Row.Value})
Accumulated	On Match condition, set the output row value to the value of an expression: {Row.Value} = {Row.Value} + {Match.Value} Note: This can be adjusted to support compounding adjustments.

Example

The following figure shows an example of arguments for a PSP procedure step named Hierarchical Contract Adjustment, which uses the Hierarchical Look-Up method.

Hierarchical Method

The Hierarchical method processes a hierarchy of input rows from start to end or end to start. For example, it could be used for a customizable product price roll-up.

Arguments

Input Argument	Description
Context	Optional. Property set of variables shared across all rows.
Row Set	The set of rows to process.
Output Row Set	Optional. The property set used for output.
Process Condition	A Boolean condition that is evaluated to determine whether to process each row.
Row Id Field	The ID field in {Row} (example: “Id”).
Parent Field	The name of the parent ID field that defines the hierarchy in the input row set.
Direction	Up or Down. Indicates the direction of traversal of the tree.
On Top Row [1..20]	Actions to perform on the first row in each tree.
On Row [1..20]	Actions to perform on every row.
On Parent Row [1..20]	Actions to perform on every row that has children beneath it in a tree.
On Leaf Row [1..20]	Actions to perform on rows that have no children.

Example

The following figure shows an example of arguments for a PSP procedure step named Customizable Product Roll-Up, which uses the Hierarchical method.

Merge Method

The Merge method combines two or more row sets into a single row set.

Arguments

Input Argument	Description
Row Set	The target row set into which all other row sets will be merged.
Row Set [1..20]	The row sets to merge.

Example

The following figure shows an example of arguments for a PSP procedure step named Merge Ineligible, which uses the Merge method.

Query Method

The Query method queries a business component and generates a row set.

Arguments

Input Argument	Description
Context	Optional. Property set of variables shared across all rows.
Output Row Set	The property set used for output.
Business Object	The business object to query.
Business Component	The business component to query.
Search Specification	A search expression comprised of business component fields, literals, and variable values from {Context}. For example: [Account Id] = {Context.Account Id}
In Memory Search Specification	Optional. Additional terms that are ANDed with the Search Specification. The In Memory Search Specification is executed in memory. This can be used only if Cache Enabled is Y.
Cache Search Specification	Optional. Additional terms that define the key values for the Level 1 cache; for example: [Price List Id] = {Row.Price List Id}) For more information, see Logging of Performance.
Process Condition	A Boolean condition that is evaluated to determine whether to process the query.
Sort Specification	Optional. A comma-separated list of business component fields used to sort the query result.
Cache Enabled	Optional. Specifies whether to cache query results. Y or N. the default is N.
On First Match [1..20]	Actions to perform on the first query result.
On Match [1..20]	Actions to perform on every query result.
On Last Match [1..20]	Actions to perform on the last query result.
On No Match [1..20]	Actions to perform if there are no query results.

Example

The following figure shows an example of arguments for a PSP procedure step named Get Account Address, which uses the Query method.

Row Set Look-Up Method

The Row Set Look-Up method looks up each input row in another row set using a specified search expression. For example, it could be used to check for compatibility.

Arguments

Input Argument	Description
Context	Optional. Property set of variables shared across all rows.
Row Set	The set of rows to process.
Output Row Set	Optional. The property set used for output.
Process Condition	A Boolean condition that is evaluated to determine whether to process each row.
Match Row Set	The row set that will be matched with the input row set.
Search Specification	A search expression comprised of literals and variable values from {Context}, {Row}, and {Match}. For example: {Row.Product Id} = {Match.Product Id}
On First Match [1..20]	Actions to perform on the first match for each input row.
On Match [1..20]	Actions to perform on every match for each input row.
On Last Match [1..20]	Actions to perform on the last match for each input row.
On No Match [1..20]	Actions to perform if there are no matches for an input row.

Example

The following figure shows an example of arguments for a PSP procedure step named Flag Incompatible Rows, which uses the Row Set Look-Up method.

Rule Set Look-Up Method

The Rule Set Look-Up method looks up the rules for each input rule set and tests the rules against the row set. Then it performs actions if the rule set passes or fails. For example, it could be used for identifying applicable bundles or promotions.

Arguments

Input Argument	Description
Context	Optional. Property set of variables shared across all rows.
Row Set	The set of rows to process.
Output Row Set	Optional. The property set used for output.
Process Condition	A Boolean condition that is evaluated to determine whether to process each row.
Business Object	The business object to query to retrieve the rules.
Business Component	The business component to query to retrieve the rules.
Search Specification	A search expression comprised of business component fields, literals, and variable values from {Context} and {Row}. For example: [Required Flag] = 'Y'
In Memory Search Specification	Optional. Additional terms that are ANDed with the Search Specification. The In Memory Search Specification is executed in memory. This can be used only if Cache Enabled is Y.
Cache Search Specification	Optional. Additional terms that define the key values for the Level 1 cache; for example: [Price List Id] = {Row.Price List Id}) For more information, see Logging of Performance.
Sort Specification	Optional. A comma-separated list of business component fields used to sort the query result.
Cache Enabled	Optional. Specifies whether to cache query results. Y or N. The default is N.
Rule Set Field	The field in the business component that groups the rules into a rule set (example: Promotion Id, Bundle Id).
Row Join Field	The field in the {Row} that is joined to a matching rule (example: Product Id). This transform tests all rows that join to see if the rule expression is satisfied.
Rule Join Field	The field in the rule business component that is joined to a matching {Row} (example: Product Id).
Rule Expression	Optional. A Boolean expression that defines whether a rule is satisfied by a row; for example: "{Match.Min Qty} = 0) OR {Match.Min Qty} <= {Row.Qty}")
Pass Only If All Rules Match	Y or N. This indicates whether to execute the On Pass … conditions only if all rules in a rule set pass, or whether to execute those conditions for any rule that is satisfied.
Row Set Sort Specification	Optional. A comma-separated list of {Row} field names that determine the sequence in which rows in {Row Set} are processed as they are compared with the rules. This transform is used to make sure that the highest value item is given away in a buy-one-get-one-free scenario. This transform is required for backward compatibility.
Rule Sets	A property set containing a list of rule sets to test. Each child property set can contain the following fields: [Rule Set Sequence Id] (optional) [Sequence] (optional) A value for the "Rule Set Field" (example: [Bundle Id]) [Next Sequence on Fail] (optional) For example, the list of promotions that requires integrity checking or the list of bundles associated with the current price list. If the [Next Sequence on Pass] field is populated, then the Rule Sets transform skips to that value of [Sequence] if the current rule set passes. If the [Next Sequence on Fail] field is populated, then the transform skips to that value of [Sequence] if the current rule set fails. Note: There may be multiple sequences of rule sets in the Rule Sets property set. Individual rule-set sequences are identified by the optional [Rule Set Sequence Id] field. Attributes of the rule set being evaluated are exposed to action syntax as {Rule Set.Value}.
On Pass First Match	Occurs for the first row in the row set that matches a rule in a rule set for which the evaluation criteria are satisfied. For 'On Pass … [Rule]' conditions, {Row} and {Match} variables are available to actions.
On Pass Match	Occurs for every row in the row set that matches a rule in a rule set for which the evaluation criteria are satisfied. For 'On Pass … [Rule]' conditions, {Row} and {Match} variables are available to actions.
On Pass Last Match	Occurs for the last row in the row set that matches a rule in a rule set for which the evaluation criteria are satisfied. For 'On Pass … [Rule]' conditions, {Row} and {Match} variables are available to actions.
On Fail First Rule	Occurs for the first rule not satisfied in a failed rule set. Note: For On Fail … [Rule] conditions, only the {Match} variable is available to actions.
On Fail Rule	Occurs for each rule that was not satisfied in a failed rule set.
On Fail Last Rule	Occurs for the last rule that was not satisfied in a failed rule set.

Example

The following figure shows an example of arguments for a PSP procedure step named Identify Applicable Bundles, which uses the Rule Set Look-Up method.

Simple Look-Up Method

The Simple Look-Up method looks up each input row in a business component using a simple search expression. For example, it could be used to look up list price or exclusive eligibility.

Arguments

Input Argument	Description
Context	Optional. Property set of variables shared across all rows.
Row Set	The set of rows to process.
Output Row Set	Optional. The property set used for output.
Process Condition	A Boolean condition that is evaluated to determine whether to process each row.
Business Object	The business object to query.
Business Component	The business component to query.
Search Specification	A search expression comprised of business component fields, literals, and variable values from {Context} and {Row}. For example: [Price List Id] = {Row.Price List Id} AND [Product Id] = {Row.Product Id}
In Memory Search Specification	Optional. Additional terms that are ANDed with the Search Specification. The In Memory Search Specification is executed in memory. This can be used only if Cache Enabled is Y.
Cache Search Specification	Optional. Additional terms that define the key values for the Level 1 cache; for example: [Price List Id] = {Row.Price List Id}) For more information, see About PSP Cache Performance Statistics.
Sort Specification	Optional. A comma-separated list of business component fields used to sort the query result.
Cache Enabled	Optional. Specifies whether to cache query results. Y or N. The default is N.
On First Match [1..20]	Actions to perform on the first query result for each input row.
On Match [1..20]	Actions to perform on every query result for each input row.
On Last Match [1..20]	Actions to perform on the last query result for each input row.
On No Match [1..20]	Actions to perform if there are no query results for an input row.

Example

The following figure shows an example of arguments for a PSP procedure step named In Price List, which uses the Simple Look-Up method.

Split Method

The Split method splits an input row set into two output row sets by evaluating a condition for each row.

Arguments

Input Argument	Description
Context	Optional. Property set of variables shared across all rows.
Row Set	The set of rows to process.
Condition	A Boolean expression that references {Context} and {Row} field values.
On True Row Set	The row set to which rows are moved if Condition evaluates to True.

Example

The following figure shows an example of arguments for a PSP procedure step named Inclusive Eligibility, which uses the Split method.

Configuring PSP Procedures

You configure, test, and release a PSP procedure as you would any workflow process. For information about creating workflow processes, see Siebel Business Process Framework: Workflow Guide.

Note: Workflow processes which rely on the UI context and on variable maps and signals can only be tested in the workspace but cannot be simulated.

Use the following sequence of steps:

1. Create or edit a PSP procedure in the Siebel Tools development environment.

2. From within Siebel Tools, start the Siebel Client in debug mode.

3. In the Siebel Client, test the behavior of the PSP procedure.

4. Activate the PSP procedure in production.

The following topics contain more information about configuring PSP procedures:

• Creating PSP Procedures

• Best Practices for Configuring PSP Procedures

• Configuring Eligibility, Compatibility, and Pricing

Creating PSP Procedures

PSP procedures are created in the same way that standard workflow processes are created. For information about creating workflow processes, see Siebel Business Process Framework: Workflow Guide.

To create a PSP procedure

1. In Siebel Tools, create a workflow process.

2. To one or more of the workflow’s steps, add Row Set Transformation Toolkit methods as input arguments.

Caution: PSP requires that each input property set for a PSP procedure step must also be defined as an output property set, even though the input property set is technically not output. This is required by a workflow performance optimization that makes sure input and output property sets are not copied when the transform method is invoked.

Best Practices for Configuring PSP Procedures

To reduce the work of maintenance and to tune performance, follow these guidelines for designing PSP procedures:

• Use the standard PSP procedures as your starting point. Trim and tune each PSP procedure to match your business requirements. PSP procedure execution is critical to the end-user response time of your Siebel application. Always review the standard, shipped PSP procedures and trim them as necessary, for example:

  • Eliminate steps that are not required in your implementation.

  • Eliminate variables from the default variable maps that are not required to support your business logic.

    Note: These tuning guidelines can have a major impact on performance and scalability. For help with tuning, create a service request (SR) on My Oracle Support. Alternatively, you can phone Global Customer Support directly to create an SR or get a status update on your SR. Support phone numbers are listed on My Oracle Support.

• Add useful subprocedures. In every case for which the same set of steps is invoked from multiple places, consider creating a subprocedure for those steps. Then call the subprocedure rather than repeating the set of steps.

• Remove unnecessary subprocedures. Avoid or remove subprocedures that are not required by your organization’s particular needs. This is recommended because subprocedure calls involve copying the row set, which adds to performance overhead.

• Keep the logic generic. Do not implement account-specific or product-specific logic in a PSP procedure. Because this logic changes frequently, it is best for it to be maintained by marketing administrators.

Configuring Eligibility, Compatibility, and Pricing

Different information is required to configure eligibility, compatibility, and pricing in the following scenarios:

• In an asset-based ordering (ABO) environment. For more information, see Eligibility, Compatibility, and Pricing Using the Configurator in an ABO Environment.

• In a non-ABO environment. For more information, see Eligibility, Compatibility, and Pricing Using the Configurator in a Non-ABO Environment.

• When using the line item UI, as opposed to the Configurator UI

  • The line item UI refers to the Line Items applet in Siebel application. Access the Line Items applet by navigating to (for example) the Sales Order screen, List, then the Line Items view.

  • This Line Items applet contains a Customize button, which allows you to start the Configurator if the product in the order line item can be configured. The Configurator creates a new view (the Configurator UI) to display the line item in a different way, and allow you to reconfigure the line item.

    For more information, see Eligibility, Compatibility, and Pricing Using the Line Item UI.

This topic describes the configuration that is necessary in Business Components, Integration Objects, and Business Service Properties to set up eligibility, compatibility, and pricing for these different scenarios.

For information about how to configure additional fields for use in eligibility, compatibility, and pricing, see Configuring an Additional Field For Use in Eligibility, Compatibility, and Pricing.

Eligibility, Compatibility, and Pricing Using the Configurator in an ABO Environment

This topic describes how to enable ABO for a Siebel Developer Web Client and a Siebel Application Object Manager.

Enabling Asset Based Ordering for a Siebel Developer Web Client

Use the following procedure to enable ABO for a Siebel Developer Web client.

To enable Asset Based Ordering for a Siebel Developer Web Client

• Set the AssetBasedOrderingEnabled parameter in your configuration file (siebel.cfg) to True.

  Then when you click the Customize button in the quote items applet or order line items applet in your Siebel Business Application:

  • No signal is raised.

  • The SIS OM Edit Delta Quote Line Item workflow is invoked

  • The following integration objects are used to build the Configurator instance property set:

    SIS OM Quote

    SIS OM Order

    SIS OM Asset

Enabling Asset Based Ordering for a Siebel Application Object Manager

Use the following procedure to enable ABO for a Siebel Application Object Manager.

To enable Asset Based Ordering for a Siebel Application Object Manager

1. Set the AssetBasedOrderingEnabled parameter in your Siebel Business Application by navigating to the Administration - Server Configuration screen, Enterprises, Component Definitions, and then the Parameters view.

2. Query for the object manager component where you want to enable ABO.

3. Query for the parameter Order Management - Enable Asset Based Ordering, and set the Current Value to True.

4. Save this record.

   Then when you click the Customize button in the quote items applet or order line items applet in your Siebel Business Application:

   • No signal is raised.

   • The SIS OM Edit Delta Quote Line Item workflow is invoked

   • The following integration objects are used to build the Configurator instance property set:

     SIS OM Quote

     SIS OM Order

     SIS OM Asset

Eligibility, Compatibility, and Pricing Using the Configurator in a Non-ABO Environment

This topic describes how to disable ABO for a Siebel Developer Web Client and a Siebel Application Object Manager.

Disabling Asset Based Ordering for a Siebel Developer Web Client

Use the following procedure to disable ABO for a Siebel Developer Web client.

To disable Asset Based Ordering for a Siebel Developer Web Client

• Set the AssetBasedOrderingEnabled parameter in your configuration file (siebel.cfg) to False.

  Then when you click the Customize button in the quote items applet or order line items applet in your Siebel Business Application:

  • The Customize signal is raised.

  • The Configurator Load workflow is invoked

  • The following integration objects are used to build the Configurator instance property set:

    7.7 Quote Integration Object

    7.7 Order Entry Integration Object

Disabling Asset Based Ordering for a Siebel Application Object Manager

Use the following procedure to disable ABO for a Siebel Application Object Manager.

To disable Asset Based Ordering for a Siebel Application Object Manager

1. Set the AssetBasedOrderingEnabled parameter in your Siebel Business Application by navigating to the Administration - Server Configuration screen, Enterprises, Component Definitions, and then Parameters view.

2. Query for the object manager component where you want to disable ABO.

3. Query for the parameter Order Management - Enable Asset Based Ordering, and set the Current Value to False.

4. Save this record.

   Then when you click the Customize button in the quote items applet or order line items applet in your Siebel Business Application:

   • The Customize signal is raised.

   • The Configurator Load workflow is invoked

   • The following integration objects are used to build the Configurator instance property set:

     7.7 Quote Integration Object

     7.7 Order Entry Integration Object

Eligibility, Compatibility, and Pricing Using the Line Item UI

When the user clicks on the Reprice (Pricing) button or Verify (Eligibility) button in the quote items applet or order line items applet in the Siebel Business Application, the following integration object is used to for Eligibility, Compatibility, and Pricing evaluation:

• ISS Quote

Configuring an Additional Field For Use in Eligibility, Compatibility, and Pricing

When RaiseSignal is called from a business component (for example, Reprice All from quote), the instance is a BusComp pointer and data is pulled from the business component that is currently in memory (that is, the business component that the applet within the view is based on). When the instance is a BusComp pointer, the integration object is determined by the 'Instance Uniform Name EAI Object*' user properties on that business component.

• Example: Reprice All from the "Quote Item List Applet (Pricing)" on the "Quote Item Detail View (Pricing)" view:

  Integration Object (ABO Mode) - ISS Quote

  Integration Object (Non ABO Mode) - ISS Quote

  When RaiseSignal is called from the Configurator, the instance is a CxObj pointer and data is pulled from the Configurator instance property set. When the instance is a CxObj pointer, the integration object is determined by the final property set that is passed into Configurator.

• Example: Eligibility Check within configurator when launched from Quote UI:

  Integration Object (ABO Mode) - SIS OM Asset

  Integration Object (Non-ABO Mode) - 7.7 Quote Integration Object

The following procedure describes the objects that must be modified in order to involve an additional field in the eligibility, compatibility, and pricing processes. Using this procedure ensures consistent behavior between quotes and orders in the line item UI and in the Configurator UI, in both ABO mode and in non-ABO mode.

To include additional fields in eligibility, compatibility and pricing

1. Add the field to the following business components:

   MACD Quote Item

   MACD Order Entry - Line Items

   Product Eligibility BusComp

2. Add the field to the following integration objects:

   • Quote UI:

     ISS Quote

   • Order UI:

     ISS Order

   • Configurator UI (ABO Mode):

     SIS OM Quote

     SIS OM Order

     SIS OM Asset

   • Configurator UI (non-ABO Mode):

     7.7 Quote Integration Object

     7.7 Order Entry Integration Object

3. Copy the value of the additional field used in the pricing process by creating the corresponding business service user properties for the SIS OM PMT Service.

4. Add the field to the following variable maps:

   • Quote UI and Order UI:

     Default Eligibility Variable Map - Context, and Product Eligibility Variable Map - Context

     Default Pricing Variable Map - Context

   • Configurator UI (ABO Mode):

     Cfg Eligibility Variable Map - Context

     Default Pricing Variable Map - Context

   • Configurator UI (non-ABO Mode):

     Cfg Eligibility Variable Map - Context

     Default Pricing Variable Map - Context

5. Update the following workflow processes as necessary:

   .Product Eligibility & Compatibility - Default

   .Pricing Procedure - Default

Creating a Custom PSP Application

PSP is a general-purpose mechanism that can be used anywhere in the Siebel application. For example, you can create a custom PSP procedure to determine the allowed shipping methods for a line item on an order, or you can create a custom PSP procedure to determine the disclosures that must be read to a customer before the purchase of a product.

Your custom PSP application must include the following:

• Matrix tables, business components, and the administrative UI to capture the rules.

• Signals to invoke the controller workflow. See Signals.

• A controller workflow that establishes the input context and row set and processes the PSP output.

• A PSP procedure that transforms the input row set.

• If necessary, scripted business service methods that extend the set of Row Set Transformation Toolkit business service methods. See Creating a Custom Transform.

Creating a Custom Transform

PSP procedures can invoke any custom business service method that you create using Siebel VB or Siebel eScript. Custom business service methods for PSP follow these guidelines:

• The row set and context are passed as inputs to the custom business service method.

• Wherever possible, parameterize new methods to make them flexible and applicable to multiple situations.

• The method uses standard property set APIs to read and write from the row set.

• The row set must be returned as an explicit output argument of the business service method.

For more information, see Siebel VB Language Reference or Siebel eScript Language Reference.

Calling a PSP Procedure from an External Application

You can invoke a PSP procedure from an external application by using a Web service ASI or a business service API.

To call a PSP procedure from an external application

1. Create a Web Service ASI or expose a business service API.

2. Use the Web Service ASI or business service API to invoke a controller workflow.

3. Use the controller workflow to do the following:

   1. Convert the XML input document to a row set using the XSLT or the Siebel Data Mapper.

   2. Construct a Context property set (if required) from the XML input document using XSLT or the Siebel Data Mapper.

   3. Invoke the standard PSP procedure.

   4. Construct an XML response from the output row set.

About Logging of PSP

PSP transforms support logging for troubleshooting and performance tuning. Logging is implemented using the standard Siebel logging mechanisms. See Siebel System Monitoring and Diagnostics Guide.

With one exception, all PSP logging events have the primary purpose of supporting troubleshooting. The PSP logging event called PSP Cache supports performance tuning.

Troubleshooting PSP

There are several server parameters used for PSP logging. For details on using PSP logging events for troubleshooting, see About Troubleshooting of PSP.

Tuning Performance of PSP

For details on using the PSP Cache event and other logging events for performance tuning, see About Tuning Performance of PSP and Logging of Performance.

About Troubleshooting of PSP

To manage PSP logging-related server parameters, navigate to the Administration - Server Configuration screen, Servers, and then the Events view, and query on “PSP*”.

The server parameters for PSP logging are listed in the following table. PSP Cache Event is used for performance tuning, while all the other server parameters described in this topic are used for troubleshooting.

Event Type	Alias
PSP Cache Event	PSPCache
PSP Data Event	PSPData
PSP Parser Event	PSPParser
PSP Transform Event	PSPTransform
PSP Pricer Service Event Note: The PSP Pricer Service Event logging parameter is used only in implementations that include Siebel Pricer.	PSPPricerSvc

Like all other Siebel-standard log events, the default log level is 1, and the log level can be set from 1 to 5. The higher the log level is set, the more messages are logged. Log level settings generate the types of data listed in the following table.

The data logged by the PSP logging-related server parameters is explained in the topics that follow.

Level	Type of Data Logged
1	Error messages
2	Warnings
3	Information
4	Detailed information
5	Debugging information

PSP Cache Event

Log levels and data logged for PSP Cache Event are listed in the following table. PSP Cache Event is used for logging for PSP Cache, and for tuning performance of PSP transforms.

For more information about this event, see Logging of Performance. For information about other events used to log performance of PSP, see Logging of Performance.

Level	Data Logged
3	PSP Cache miss or hit
	Keys: first-level key, second-level key

PSP Data Event

Log levels and data logged for PSP Data Event are listed in the following table. PSP Data Event is used for logging of PSP transform input arguments.

Level	Data Logged
4	Input arguments (excluding the hierarchy arguments) of each transform are logged as Name:Value pairs.
5	The whole input property set of each transform is logged as an XML string.

PSP Parser Event

Log levels and data logged for PSP Parser Event are listed in the following table. PSP Parser Event is used for logging of PSP Parser.

Level	Data Logged
5	Debugging information for PSP parser.

PSP Transform Event

Log levels and data logged for PSP Transform Event are listed in the following table. PSP Transform Event is used for logging of PSP transforms.

Level	Data Logged
3	Business service name
	Number of rows processed.
	Number of rows deleted.
4	Transform progress information.
5	Debugging information for PSP transforms.

PSP Pricer Service Event

Log levels and data logged for PSP Pricer Service Event are listed in the following table. PSP Pricer Service Event is used for logging of Pricer service APIs.

Level	Data Logged
5	Debugging information for PSP Pricer business service.

About Tuning Performance of PSP

Consider the following when tuning the performance of your preconfigured and custom PSP procedures:

Preconfigured PSP Procedures

Tune the preconfigured PSP procedures by:

• Removing steps that your implementation does not require

• Eliminating unused values from the variable maps

General Design Guidelines

Follow these general design guidelines to further improve the performance of PSP:

• Optimize eligibility PSP procedures by:

  • Executing low-cost tests first

  • Performing high-cost tests (such as Web Service calls) only in post-pick processing

• Build performance hints into the procedure definition. Use the Process Condition input argument in each step to identify the subset of rows in the row set that require processing (example: "{Row.Promotion Id} IS NOT NULL"). This can eliminate unnecessary SQL and in-memory operations.

• When multiple steps operate on the same subset of rows, split the row set, perform the operations on the subset of rows, and then merge the two split row sets afterwards.

• Avoid unnecessary subprocedures. Subprocedure calls involve copying the row set, which it is best to avoid where possible.

• Optimize external Web Service calls by:

  • Designing the Web Service interface to be set-based

  • Making sure that a single invocation will process all rows in the row set

• Use PSP Cache for caching of database query results. For more information about how to tune PSP performance with caching, see Logging of Performance.

SQL Queries

Use the following guidelines to improve the SQL query performance of PSP:

• Minimize the number of SQL queries executed. Consolidate multiple Simple Look-Up steps into one step if the steps use data from the same reference data business component with the same search specification.

• Tune SQL queries by:

  • Querying through thin business components to minimize Siebel Object Manager overhead and reduce query complexity.

  • Making sure that all search specifications have index coverage.

Logging of Performance

PSP provides extensive logging of performance-related data. Analyze the PSP log to determine which steps are consuming the most processing time and where the caching can be further optimized.

PSP logging that takes place in the server environment is more effective than PSP logging that takes place locally, because in the server environment there is only one environment variable controlling the log level for all the events.

You can use the events listed in the following table to log the performance of PSP.

Event Type	Alias	Description
Object Manager Business Service Operation and SetErrorMsg Log	ObjMgrBusServiceLog	Logs the performance of business service methods which include the PSP transform methods.
Workflow Performance	WfPerf	Logs the performance at the workflow level or step level.
PSP Cache Event For more information, see Logging of Performance.	PSPCache	Logs the performance of PSP Cache.

When debugging the pricer, the price waterfall output provides valuable clues as to which transforms and actions were executed. For more details on logging, see About Logging of PSP.

About PSP Cache

Siebel PSP Cache is a mechanism designed to improve performance of PSP transforms. PSP Look-Up transforms use caching to reduce the number of SQL statements executed by the database. The cache stores the results of PSP Look-Up transform queries. The cache key is the business object, the business component, the search specification, and the sort specification.

The PSP Cache of query results is shared across all user sessions on an Object Manager. A particular query is issued only once for each Object Manager and then shared by all users. This sharing maximizes the probability of a cache hit and improves performance and scalability for all users on the server.

Transforms Involving Database Queries

Of all the PSP methods (transforms) provided by the Row Set Transformation Toolkit business service, those that involve database queries are the following:

• Simple Look-Up

• Query

• Hierarchical Look-Up

• Rule Set Look-Up

• Dynamic Look-Up

There are two ways that PSP Cache is implemented: one is special for the Dynamic Look-Up transform, and the other is for the rest of the transforms:

• PSP Dynamic Look-Up Transform Cache. This cache is used when the Dynamic Look-Up transform performs a query. For more information, see About Using the PSP Dynamic Look-Up Transform Cache.

• PSP Generic Cache. This cache is used when all transforms other than the Dynamic Look-Up transform perform a query. For more information, see Using the PSP Generic Cache.

The following topics contain more information about PSP Cache:

• Enabling PSP Cache

• Setting Cache Size

• Using the PSP Generic Cache

• Optimizing PSP Cache

• Defining a Cache Refresh Key

• Configuring a Clear Cache Button

• About Using the PSP Dynamic Look-Up Transform Cache

• About PSP Cache Performance Statistics

Enabling PSP Cache

You turn the PSP Cache on or off using an input argument, at the PSP procedure step level (that is, one input argument for each step that involves caching). By default, caching is disabled.

To enable caching, add an input argument to the step involving a Look-Up transform or Query transform, as follows:

Cache Enabled = Y

Note: If Cache Enabled is not defined for a PSP procedure step, the default value is N and caching is not enabled.

Setting Cache Size

To control cache size, use the following server parameters:

• PSP Level 1 Cache Max Item Count. The server parameter with this display name is PSPCacheMaxItemCntLevel1. This is the maximum number of business component or cache refresh key combinations; for example:

  Price List Item/Price List Id = ’12-12345’)
  

  The default value is 10000.

• PSP Level 2 Cache Max Item Count. The server parameter with this display name is PSPCacheMaxItemCntLevel2. This is the maximum number of distinct queries cached for each PSP Level 1 Item. The default value is 10000.

When either Level 1 or Level 2 cache reaches capacity, the least recently used query results are dropped to make space for new cache entries.

It is not possible to directly control the amount of memory consumed by the PSP cache by setting a total size for PSP cache, as the architecture does not count the memory of each cache item.

Note: You must restart the Siebel server for any parameter changes to take effect.

For information about setting server parameters, see Siebel System Administration Guide.

Using the PSP Generic Cache

The PSP Generic Cache is the cache used for all transforms that involve database queries except the Dynamic Look-Up transform. The Simple Look-Up, Query, Hierarchical Look-Up, and Rule Set Look-Up transforms use PSP Generic Cache.

Topics that relate only to PSP Generic Cache and not to PSP Dynamic Look-Up Transform Cache are the following:

• Optimizing PSP Cache

• Defining a Cache Refresh Key

• Configuring a Clear Cache Button

Optimizing PSP Cache

To maximize the cache hit rate (and hence, performance and scalability), partition the transform search specification into a high selectivity clause that is executed by the database and used as part of the PSP cache key (the Search Specification input argument) and a low selectivity clause that is executed by the PSP transform itself to further filter the query results (the In Memory Search Specification input argument). When you use the In Memory Search Specification input argument in combination with a Search Specification input argument, your search specification is, effectively, “[Search Specification] AND [In Memory Search Specification]”. The two search specification input arguments are divided by purpose as follows:

• Search Specification. Use this input argument to define highly selective search criteria executed by the database.

• In Memory Search Specification. Use this input argument to define low selectivity search criteria executed by the Siebel Server.

  Note: The Dynamic Look-Up transform does not support the In Memory Search Specification input argument. This transform dynamically generates its own search specification.

The order of search implementation is as follows: first the Search Specification input argument is applied to the database query. Next, the returned result set is further filtered in memory by applying the In Memory Search Specification input argument.

Example values for Search Specification and In Memory Search Specification are shown in the following table for the Pricer Simple Volume Discount step.

Input Argument	Value
Search Specification	[Volume Discount Id] = {Row.Volume Discount Id} AND [Volume Discount Method] = LookupValue('VOL_DISCNT_METHOD', 'SIMPLE')
In Memory Search Specification	[Minimum Quantity] <= {Row.Extended Quantity Requested} AND ([Maximum Quantity] >= {Row.Extended Quantity Requested} OR [Maximum Quantity] IS NULL) AND [Volume Discount Start Date] <= Timestamp() AND ([Volume Discount End Date] >= Timestamp() OR [Volume Discount End Date] IS NULL)

The example shown in the previous table results in one query for each volume discount that retrieves all result rows. All subsequent queries against that volume discount are served from the cache regardless of the values for [Extend Quantity Requested] or Timestamp().

Note: In Memory Search Specification execution does not use sophisticated database features such as indexes. Make sure the result set searched in memory is not too large. For example, loading an entire price list in one query is not likely to improve performance; search a subset of the price list.

For information about PSP Cache performance, see About PSP Cache Performance Statistics.

Defining a Cache Refresh Key

One complication caused by the PSP engine's extensive use of caching is that changes to reference data (such as price list line items) that are currently in cache are not reflected immediately after an updated version of the reference data is released. The PSP Cache persists until a Siebel Server is restarted. To enable administrative updates against a running system, every administration view that maintains data cached by PSP has a Clear Cache button that causes all PSP caches on all object managers in the Siebel Enterprise to purge a subset of the cached data for that particular business component. That subset of data is defined by the cache refresh key for the business component.

When implementing PSP Cache through the PSP Generic Cache, you can control the granularity of the cache refresh by defining a cache refresh key for a business component. If no cache refresh key is defined, the business component is refreshed as a whole. To improve performance, you can use a cache refresh key to clear only a selected part of the cache.

A business component can have only one cache refresh key. Some business components have a cache refresh key that comes preconfigured. For example, the Price List Item business component has a cache refresh key of Price List Id. This means that when the user clicks the Clear Cache button in the Price List list applet, only the selected price lists are cleared from the cache.

You define a cache refresh key by adding user properties to the Row Set Transformation Toolkit business service. For each cache refresh key, one pair of user properties is required, as shown in the following table.

Name	Value
Cache Key: Price List Item	Price List ID
Cache Key: [BC Name]	[Key Field 1], [Key Field 2]

Note: You must update a workspace with the changes and then deliver it for the changes to take effect.

Search Specification and Cache Refresh Key

If a cache refresh key is defined for a business component, then every query against that business component must provide the cache key field values in its Search Specification or in the Cache Search Specification input argument.

Note: Failure to specify the cache refresh key values will result in an error.

Use the Cache Search Specification input argument to avoid unnecessary clauses in the Search Specification executed by the database. The transform will look first at the Cache Search Specification, and then at the Search Specification to identify cache key values.

The syntax and structure of the Cache Search Specification input argument are shown in the following example:

[Price List Id] = {Context.Price List Id} AND [Price List Item Id] = {Row.Price List 
Item Id}

Row Set Transformation Toolkit Methods for PSP Cache Refresh

The Row Set Transformation Toolkit methods listed in the following table, with their corresponding input arguments and output arguments support refreshing of the PSP cache:

Method		Description
Get Cache Key		Checks the cache key definitions for the specified business component and constructs a property set containing the cache key values for each selected row in the active business component. This enables multiselect when clearing cache entries (such as price lists).
	In: Business Component Name
	Out: Row Set
Refresh Cache		Clears the entire PSP cache.
Refresh BC		Clears all PSP cache entries for the specified business component. Note: Refresh BC does not clear the cache if the business component has a cache key defined.
	In: Business Component Name
Refresh BC On Cache Key		Clears all PSP cache entries for the specified business component and cache key values. The input Row Set is typically the output of the Get Cache Key method.
	In: Business Component Name
	In: Row Set

When the user clicks the Clear Cache button for business components without a cache key, the Refresh BC method is called directly by a run-time event. For business components with a cache key (for example, Price List Item has one preconfigured), the methods Get Cache Key and Refresh BC On Cache Key are invoked by a workflow that is triggered by a run-time event.

Configuring a Clear Cache Button

The PSP cache persists until the Siebel Server is restarted, but you can force a refresh of cached data across all servers in the enterprise. In the Administration - Pricing views, Clear Cache buttons exist for this purpose, to allow administrative updates against a running system. All objects cached by PSP must support a Clear Cache button that forces this refresh of cached data.

Requirements for configuring Clear Cache buttons vary as follows:

• If the business component does not have a cache refresh key defined, a run-time event must be defined to refresh the cache. See Clear Cache Button for BusComps without a Cache Refresh Key.

• If the business component does have a cache refresh key defined, a workflow and a run-time event must be defined to refresh the cache. See Clear Cache Button for BusComps with a Cache Refresh Key.

Note: Although there is a Clear Cache button in the Administration - Pricing screen, then the Attribute Adjustments view, the run-time event for this button is fixed. This is the Clear Cache button associated with the PSP Dynamic Look-Up Transform Cache. Do not try to configure this Clear Cache button as you would the Clear Cache button used by the PSP Generic Cache.

Clear Cache Button for BusComps without a Cache Refresh Key

In this case, you must define a run-time event to refresh the cache.

To configure a new Clear Cache button for a business component without a cache refresh key defined

1. Create a control in the desired applet where the method invoked is EventMethodCacheRefresh.

2. Navigate to the Administration - Runtime Events screen, then the Action Sets view, and create a new record in the Action Sets list applet.

3. Give the record a name, such as “Cache Refresh BC - Applet Name”.

4. Create a new record in the middle list applet, with the following values:

   • Name is PSP Refresh

   • Action Type is BusService

5. In the More Info form applet (at the end), enter the following values:

   • Business Service Name is Row Set Transformation Toolkit

   • Business Service Method is Refresh BC

   • Business Service Context is a list of business component names with commas as the separator, and with each business component name included in quotation marks

     Example:

     Business Service Context ="ProcessName", "PSP Refresh Cache On Cache Key - 
     Price List"
     

6. Navigate to the Administration - Runtime Events screen, then the Events view, and create a new record with the following values:

   • Object Type is Applet

   • Object Name is the name of the applet referred to in Step 1

   • Event is InvokeMethod

   • Subevent is EventMethodCacheRefresh

   • Action Set Name is the name of the action set created in Step 2

Clear Cache Button for BusComps with a Cache Refresh Key

In this case, you must define a workflow and a run-time event to refresh the cache.

To configure a new Clear Cache button for a business component with a cache refresh key defined

1. Create a control in the desired applet where the Method Invoked is EventMethodCacheRefresh, add the control to the desired applet web template.

2. Define the cache keys by adding user properties to the Row Set Transformation Toolkit business service, according to the format shown in the following table, for example:

   Property	Value
   Name	Cache Key: Price List Item
   Value	Price List Id

3. Create a workflow that does the following:

   1. Calls the Get Cache Key method to determine the selected cache key values.

   2. Invokes the Refresh BC On Cache Key method for each business component that shares the same cache key. The following figure shows an example of a Clear Cache workflow.

      

4. Navigate to the Administration - Runtime Events screen, then the Action Sets view, and create a new record in the Action Sets list applet with a name such as “Cache Refresh BC - Applet Name”.

5. Create a new record in the middle list applet, with the following values:

   Property	Value
   Name	PSP Refresh
   Action Type	BusService

6. In the More Info form applet (at the end), enter the following values:

   Property	Value
   Business Service Name	Workflow Process Manager
   Business Service Method	RunProcess
   Business Service Context	Process Name

   For example:

   Business Service Context = PSP Refresh Cache On Cache Key - Price List
   

7. Navigate to the Administration - Runtime Events screen, then the Events view, and create a new record with the following values:

   Property	Value
   Object Type	Applet
   Object Name	The name of the applet referred to in Step 1
   Event	InvokeMethod
   Subevent	EventMethodCacheRefresh
   Action Set Name	The name of the action set created in Step 4

About Using the PSP Dynamic Look-Up Transform Cache

The Dynamic Look-Up transform has its own cache, called the PSP Dynamic Look-Up Transform Cache. You enable this for a particular step by setting Cache Enabled to Y, the same as for the generic PSP cache. No other cache-specific input arguments are supported for the Dynamic Look-Up Transform.

The Dynamic Look-Up transform supports a preconfigured Clear Cache button; do not modify this preconfigured Clear Cache button.

Note: This is the Clear Cache button in the Administration - Pricing screen, then the Attribute Adjustments view. The run-time event for this button is fixed. Do not try to configure this Clear Cache button as you would the Clear Cache button used by the PSP Generic Cache.

About PSP Cache Performance Statistics

To view statistics on PSP Cache performance, navigate to the Administration - Server Management screen, Tasks, and then the Statistics view, and query on “PSP*”. The Siebel application provides the following statistics:

• PSP Cache Hit Total. An integer that indicates how many times the cached query results are used.

• PSP Cache Miss Total. An integer that indicates how many times a query cannot be found in PSP Cache for which a database query has been conducted.

Note: The higher the value of PSP Cache Hit Total /(PSP Cache Hit Total + PSP Cache Miss Total), the better performance exhibited by PSP Cache.