Variable Maps

This chapter explains how variable maps are used by PSP procedures to handle transactional data. It includes the following topics:

About Variable Maps

Siebel order management applications that use the PSP engine—such as for pricing, eligibility, and product recommendation—require a consistent way of loading, querying, and synchronizing transactional data. For example, the Quote Item and Order Entry - Line Items business components represent fundamentally the same concept, but can use different field names to represent the same value. Variable maps meet this requirement.

Variable maps are also used to extend the capabilities of customizable product linked items. A linked item can now refer to a value in a Context property set constructed by the variable maps mechanism. For more information about linked items, see Siebel Product Administration Guide.

Variable maps provide a mechanism for mapping transactional data to a common namespace regardless of the data source. PSP procedures rely on variable maps to map the name of a variable used by a PSP procedure to a field in a Siebel business component or to an attribute used in attribute pricing.

The variable map mechanism employs the Context Service business service, which provides a set of APIs for constructing a property set from the current ordering context and synchronizing changes to that property set back to the source. You can configure the set of data queried and written by a particular transaction.

Note: The variable map APIs work only during an event triggered on a business component derived from CSSBCOrderMgmtBase, CSSBCPecBase, and their subclasses.

You define the particular variable map used by a PSP procedure in the Signals Administration views (navigate to the Administration - Order Management screen, then the Signals view).

Concepts of Variable Maps

A variable is a name-value pair in a property set. A variable map is a definition of how to construct a property set in a given situation and of which changes to save.

Each variable has one or more variable sources that define how to retrieve the variable value in a given mode (such as Quote, Order, or Any). The source type of a variable source can be a business object query, the active business component instance, a business service, a profile attribute, a system preference, or a server parameter. A child variable map is another variable map that is executed for each row retrieved by the current variable map and attached as a child property set. A Business Service source can also construct a child property set for each row. The following figure shows example child variable map output, in relation to the parent variable map output.

Example of Child Variable Map Output. This image shows a Parent variable map output connected to a Child variable map output. The Parent variable map output has RowSet with Row 1, Row 2, and Row 3. Each of these rows contains values for the following: ID, Price List Id, Product Id, NRC Price and MRC Price. A line connects Row 2 in Parent variable map output to Attributes in Child variable map output. Attributes has Row 1 and Row 2 . Row 1 in Parent variable map output is connected by a line to Attributes in Child variable map output. Attributes has Row 1, Row 2, and Row 3.

Variable Map Types

There are three types of variable maps:

Context. Loads a single row containing shared header-level details (such as Channel, Account Type, User Role).
Row Set. Loads any iteration of rows (such as order line items or shipments for an order).
XA. Loads product attributes for a line item.

Working with Variable Maps

You create variable maps using the Administration - Order Management screen, then the Variable Maps views. Here you define the variables that are queried and written in various situations.

To access the Variable Maps views, navigate to the Administration - Order Management screen, then the Variable Maps view, and in the Versions list applet, click the Work Space hyperlink. Variable Maps views include the following:

Variable Maps view. Create new variable maps, update existing variable maps, release a variable map into production.
Child Variable Maps view. Define child variable maps to be executed and attached to the parent. These are returned as a child property set of each row in the parent property set.
Modes view. Define modes for variable maps. Set the mode according to the Mode user property on the business component invoking the signal that causes the variable map to be executed.

To configure mappings from business component field names to the variable map namespace, use the Integration Object object type in Web Tools. For more information, see About Using ISS Integration Objects with the Variable Map Mechanism.

Components of Variable Maps

See the following figure for a graphical representation of the interaction of variable map components. The way the variable map mechanism works follows the following process:

An administrator defines a variable map using the Variable Maps views. This definition is stored in the Siebel database.
A user of a Siebel order management application makes a request (for example, by clicking the Reprice button). The request triggers a signal, which in turn launches a controller workflow.
The controller workflow invokes the Context Service business service’s GetRowSetData method, passing the variable map name for the line item row set, as well as the required CPScope (such as the entire customizable product [CP]) and the required RowScope (such as the currently selected rows).
The Context Service business service retrieves the variable map definition (either from the database or from the cache).
The Context Service business service issues the required queries and business service calls to construct a property set.
For source type Instance, the path specified for the variable is translated into a query against the active business component using one of the ISS mapping integration objects. For more information, see About Using ISS Integration Objects with the Variable Map Mechanism.
The Context Service business service returns the resultant row set property set to the controller workflow.
The controller workflow invokes a PSP procedure to update the row set (for example, to attach prices).
The controller workflow invokes the Context Service business service’s SyncRowSetData method passing the variable map name for the line item row set and the updated row set property set.
The Context Service business service writes any updated field values back to the Siebel database.

The following figure shows how, in the process described in these steps, the various components of the variable maps mechanism interact.

Components of the Variable Map Mechanism. This image is described in surrounding text.

About Using ISS Integration Objects with the Variable Map Mechanism

A schema of a particular entity, an integration object is metadata; it is a generalized representation or model of a particular set of data. A Siebel integration object is an object stored in the Siebel repository that represents a Siebel business object. An ISS integration object is a special type of Siebel integration object used exclusively within Siebel Order Management.

Generally, a Siebel integration object is used by Siebel EAI to transfer data between Siebel objects and external objects. ISS integration objects, on the other hand, are used to create mappings between business components and their Uniform Name mappings. In this way, while ISS integration uses the Siebel EAI structure used by a Siebel integration object—that is, a structure designed for data transfer—its main purpose is different from that of Siebel integration objects.

Using ISS integration objects, you can apply the same uniform names, such as “Line Item”, to different business components (such as Quote Item, Order Item, and so on), because there is no difference between these business components as far as the PSP engine is concerned.

For general information about integration objects and how to build them, see Integration Platform Technologies: Siebel Enterprise Application Integration.

For information about configuring ISS integration objects, see Configuring ISS Integration Objects.

Configuring ISS Integration Objects

Integration object configuration is used to create uniform field names for different physical business components (such as Quote Item, Order Item, and so on). When defining variable maps then, you can specify one source path for all modes.

Note: To avoid errors when trying to retrieve data from business components, it is recommended that you always define the component field names in integration objects, and use the uniform name in the variable source path for necessary modes only.

At run time, the user property of the business component that raised the signal determines which integration object to use. For each business component, there are various user properties (such as the property called Instance Uniform Name EAI Object:Catalog).

To configure ISS integration objects

For the business component that raises the signal, set the value of the user property Instance Uniform Name EAI Object:[BusObj] to the integration object name, for example:
```
Instance Uniform Name EAI Object:Catalog
```
In this example, Catalog refers to the business object that the business component is in at run time.
From the integration object definition, use the value in Integration Object Component Name as the Instance Type.
For example, use Header for the Quote business component in the Catalog business object.

Note: For each business object, each business component within it must have a unique Instance type—for example, no two business components within the Quote business object can be referred to as Header.

Supported Source Types for Variables

A variable can be derived from a number of sources. The same variable can be derived in different ways, depending on the Mode user property of the business component invoking the signal that causes the variable map to be executed.

For example, the Quote Item business component has Mode set to Quote. Using Mode set to Quote, you retrieve the Product ID from the [Product ID] field in the Quote Item business component for the current quote. Using a different setting, Mode set to Configuration, you retrieve the [Product ID] from the [Product ID] value in the Line Items property set of the product instance currently being configured.

The default setting is Mode = Any.

Note: Variable maps work only when invoked by a signal.

You define the driving integration object component for each business component’s mode by navigating to the Administration - Order Management screen, Variable Maps, then the Modes view. The driving integration object component for a mode is the component over which the variable map iterates to generate an output property set.

You set the mode using the user property called Mode. Existing modes are: Asset, Quote, Order, Payment, Product, Agreement, Configuration.

Note: You can configure your own modes. See Creating Variable Maps.

A variable can be derived from the sources listed in the following table.

Source Type	Path	Example
Business Object	[BOName]/[BCName]/[FieldName]	Account/Account/Region
Business Service	[BusSvcName]/[BusSvcMethod]	ABC Assets BS/Get External Assets
Instance	$Current/[IntegrationObjectComponentType]/[IntegrationObjectComponentField]	$Current/Line Items/ Quantity
Profile Attribute	ProfileAttributeName	AnonymousUserZipCode
System	[LoginName], or [LogInId], or [LogInPassword], or Today	Today
Server Parameter	[ServerParameter]	PARAM_PSP_ELIGIBILITY_D ISPL_MODE

Business Object

The Business Object source type, shown in the Variable Sources list applet in the following figure, is used to query business components that are not in the current context.

Note: You can also query for joined business components (such as Account and Address).

For more information, see Querying with the Business Object Source Type.

Business Object Source Type. This image is described in surrounding text.

Business Service

Used with business services (such as Projected Asset Cache), the Business Service source type allows you to invoke a business service to populate one or more variables, and to populate a child property set of the current row. The following figure shows the Business Service source type.

Using the Business Service source type, you can populate multiple variables or child variable maps in a single method invocation. This is possible if the variables are invoking the same business service and method with the same inputs. This consolidated call to the business service can happen regardless of the number of variables (that is, Property Set, another one, or a mix of two) needing to be populated.

Note: Make sure the values for the Sequence field contain appropriate numbers. In the example shown in the figure, Account Id is an input for the business service. This input uses the value of variable Account Id, therefore the Sequence value for Account Id must be smaller than the Sequence value for Credit Score.

For details on how to populate multiple variables or child variable maps in a consolidated call to the business service, see Using the Business Service Source Type to Populate Variables.

Instance

The Instance source type can be used to refer to both of the following:

The current UI context when viewing quotes and orders
The current customizable product instance being configured

Used for Siebel order management business components (such as Order Line Item), the Instance source type, shown in the Business Component User Properties list applet in the following figure, allows you to query active UI business components to retrieve variable values. The business component queried can be a regular, external, or virtual business component.

Used for customizable product instance property sets, the Instance source type retrieves data from the business component initiating the signal that causes the GetRowSetData method to be called. Data can also be retrieved from any parent or child business component.

Mapping Integration Objects

For business components, the Instance source type uses mapping of integration objects to resolve the different business component naming and field naming between Quotes, Orders, Assets, and Agreements. You map integration objects using Web Tools.

For a customizable product with Instance source type, the instances are loaded by Configurator services and the structure of these instances is hierarchical with three types: Header, Line Item, and XA. No other types are supported for a customizable product. The namespace mapping is a simple match between the type specified in the variable source path and the customizable product Instance type.

For more information about using the Instance source type, see Using the Instance Source Type for the Customizable Product Instance Property Sets.

Instance Source Type. This image displays a view with the Business Components list applet and the Business Component User Properties list applet.

The following topics include further information about creating and using variable maps:

Note: For variable map information that is specific to pricing, see Siebel Pricing Administration Guide.

About Using Variable Maps

The following topics provide information about how variable maps are used and defined:

Querying with the Business Object Source Type

You can query a business component for values by using the Business Object source type.

To query a business component to retrieve variable values

In the Variable Sources list applet, set the following fields:

Field	Value
Source Type	“Business Object”
Path	[Business Object]/[Business Component]/[Field Name]
Search Specification	[Business Component Search Spec]
Sort Specification (Optional)	[Business Component Sort Spec]

The Search Specification can include any previously evaluated variable value in {}. Use the Sequence column to provide a correct evaluation sequence.

Using the Business Service Source Type to Populate Variables

The Business Service source type allows you to invoke a business service to populate:

One or more variables as described in Invoking a Business Service to Populate Variables.
A child property set of the current row as described in Invoking a Business Service to Populate a Child Property Set.

Invoking a Business Service to Populate Variables

Use the following procedure to invoke a business service to populate variables.

To invoke a business service to populate variables

In the Variable Sources list applet, set the following fields:

Field	Value
Source Type	“Business Service”
Path	[BusSvcName]/[BusSvcMethod]

In the Variable Source Parameters list applet:
1. Add variable source parameters for each input argument. The variable source parameters can be a literal string or another variable value.
2. Add variable source parameters for each output argument, and specify which variable to populate.

Invoking a Business Service to Populate a Child Property Set

Use the following procedure to invoke a business service to populate a child property set of the current row.

To invoke a business service to populate a child property set of the current row

In the Variable Definitions list applet, set Type (the variable type) to Property Set.

In the Variable Sources list applet, set the following fields:

Field	Value
Source Type	“Business Service”
Path	[BusSvcName]/[BusSvcMethod]

In the Variable Source Parameters list applet:
1. Add variable source parameters for each input argument. The variable source parameters can be a literal string or another variable value.
2. Add variable source parameters for each output argument and specify which variable to populate.

Using a Single Invocation to Populate Multiple Variables or Child Variable Maps

Use the following procedure to populate multiple variables or child variable maps using a single invocation.

To populate multiple variables or child variable maps in a single method invocation

Specify the Source and all the In or Out parameters under a single variable.
It is recommended that other variables have only a definition, no source. This reduces the burden on the Context Service because a separate call to the business service will be issued if there is a second variable having the same business service source.

Note: A best practice is to compare the source and source parameters from different variables to determine whether to consolidate. If the values of all these variables can be obtained through a single call to the business service, combine them and only specify the business service or method as a source under one variable. Otherwise, the same call will be issued multiple times, giving the same result each time.

Using the Instance Source Type for the Customizable Product Instance Property Sets

If you are working with customizable product instance property sets, use the Instance source type. The Instance source type retrieves data from the business component initiating the signal that causes the GetRowSetData method to be called. Data can also be retrieved from any parent or child business component.

To define the data element to be retrieved

In the Variable Sources list applet, set the Path to:
```
$Current/[IntegrationObjectComponentType]/[IntegrationObjectComponentField]
```
Examples:
```
$Current/Header/Price List Id
$Current/Line Item/Quantity
```
Uniform component and field names are defined by integration objects: ISS Quote, ISS Order, ISS Agreement, and ISS Asset.
Each of these integration objects defines the specific business components and fields that provide data for a generic value such as Line Item or Quantity. For example, ISS Quote integration component Line Item maps to the Quote Item business component, whereas ISS Order has the Line Item integration component mapped to Order Entry – Line Items.

Note: To expose a custom business component field in a variable map, you must first add it to the corresponding ISS [XXX] integration object.
The ISS integration objects associated with a particular business component are defined by user properties on the business component, for example: Instance Uniform Name EAI Object: [Business Object].

Note: Make sure that you create a user property for every business object in which the business component can be exposed.

Creating Variable Maps

You create and modify variable maps in the Variable Maps views of the run-time client. Use the following procedure to implement a new variable map.

To implement a new variable map

Navigate to the Administration - Order Management screen, then the Variable Maps view.
In the Variable Maps list applet, create a new record.
Give the variable map a name.
Lock the variable map by checking the Locked Flag field.
This locks the object for your user ID.
In the Versions list applet, click the Work Space hyperlink to drill down on the variable map version.
Click the Modes tab to access the Modes view.
In the Modes list applet, define the variable map modes.
Click the Details tab and create variable definitions and variable maps.
1. In the Variable Definitions list applet, you can define the list of variables in the variable map. These names are independent of the source.
  The In or Out field defines whether the variable map can update the variable.
2. In the Variable Sources list applet, you can define the source of the variable for each mode.
Define child variable maps, as necessary.
Navigate back to the Variable Maps list applet and click the Release New Version button to release the variable map version.
Test the variable map in the run-time client by executing a reprice or another PSP procedure.
Using Application Deployment Manager (ADM), promote the updated signal definition to the production environment.
For information about ADM, see Siebel Application Deployment Manager Guide.

Updating an Existing Variable Map

Use the following procedure to update an existing variable map.

To update an existing variable map

Navigate to the Administration - Order Management screen, then the Variable Maps view.
Select the variable map and lock it by checking the Locked Flag field.
This locks the object for your user ID.
In the Versions list applet, click the Work Space hyperlink to drill down on the variable map version.
Modify the variables as necessary.
Navigate back to the Variable Maps list applet and click the Release New Version button to release the variable map version.
Test the variable map in the run-time client by executing a reprice or another PSP procedure.
Using Application Deployment Manager, promote the updated signal definition to the production environment.
For information about ADM, see Siebel Application Deployment Manager Guide.

Configuring a Custom Mode User Property for a Business Component

Use the following procedure to configure a customer Mode user property for the driving business component.

To configure a custom Mode user property for the driving business component

On the business component that raises the signal, set the Mode user property.
In the Variable Maps, then Modes view, declare the new mode for one or more variable maps.
Define variable sources for the mode.

Behavior of the On Null Property When Defining Variables in a Variable Map

When defining variables in a variable map, note that the On Null property behaves as follows:

If a path is specified for a variable, then that variable appears in the Row Set with whatever value is retrieved. In this instance, the On Null property is an empty string.
If no path is specified for a variable and the On Null property is set to Ignore, then the variable is not included in the Row Set.
If no path is specified for a variable, the On Null Property is set to Default, and a default value is specified, then the variable is included in the Row Set with the default value.

Defining the Variable Map Used by a PSP Procedure

Variable maps are used by the context service to create the property sets that are used by PSP Procedures. You specify the variable maps used by a PSP procedure in the Parameters list applet of the Administration - Order Management screen, then the Signals view.

Note: Certain methods of the Context Service business service include variable map arguments for these definitions. See Variable Map Methods of the Context Service Business Service.

The PSP procedure is independent of the calling context. Most order management signals invoke the PSP Driver Workflow Process (shown in the second figure in this topic), which is a generic controller workflow. The controller workflow uses variable maps to construct inputs for the PSP procedure. Those variable maps are defined in the signal that invokes the controller workflow.

Signal parameters define the scope of line items retrieved using the variable map, and they define the variable maps used to retrieve Context and Row Set data. The following figure shows example signal parameters.

Signal Parameters for Variable Maps. This image shows the Parameters list applet. The parameter CPScope is selected and the values Default Pricing Variable Map — Context and Default Pricing Variable Map — Row Set are selected.

Example of Variable Map Methods in Use

The following figure shows the PSP Driver Workflow Process, which is a generic example of a controller workflow. PSP Driver Workflow Process uses variable maps to retrieve data that is then synchronized back to the database.

PSP Driver Workflow Process. This image is described in surrounding text.

As shown in the previous figure, the PSP Driver Workflow Process steps perform as follows:

Get Context Row Set. Calls the Context Service business service method GetRowSetData to retrieve header-level information using the Context variable map (Variable Map - Context).
Get Row Set. Calls the Context Service business service method GetRowSetData to retrieve row-level information using the Row Set variable map (Variable Map - Row Set) and to scope input arguments.
Dispatch Service. Calls the sub workflow process defined in the calling signal and passes in the input argument.
Set Pricing Date. Sets pricing date based on whether it is for scenario testing:
- Set system time stamp if it is not for scenario testing:
```
{Context.Effective Pricing Date} = TimeStamp() 
```
- Set Active JWS Test DT if it is for scenario testing:
```
{Context.Effective Pricing Date} = GetProfileAttr("Active JWS Test DT") 
```

Sync Row Set. Calls the Context Service business service method SyncRowSetData to write any updates back to the database (for example, updates to prices).

To define the variable map used by a PSP procedure

Navigate to the Administration - Order Management screen, then the Signals view.
In the Signals list applet, select the signal that will invoke the PSP procedure.
In the Versions list applet, click the Work Space hyperlink to access the Actions list.
In the Actions list applet, enter the name of the controller workflow in the Service Name field.

Note: Most PSP signals invoke the generic PSP Driver Workflow Process.
In the Parameters list applet, (scroll down, if necessary), enter parameters for the signal, as follows:
- Using Scope arguments and values, define the scope of line items retrieved by the variable map.
- Using Variable Map parameters, define the variable maps used to retrieve Context and Row Set data.

Migrating Variable Maps Between Environments

You can move variable maps between environments (such as from development to test) by using the Application Deployment Manager (ADM). For information about using ADM, see Siebel Application Deployment Manager Guide.

You can also export a specific version of a variable map using the Export Version applet menu in the Variable Map Version list applet. To import a variable map, navigate to the Administration - Products screen, then the Joint Workspace view. This is a joint workspace for all types of versioned objects (signals, variable maps, products, product attributes, and so on). For more information about import or export, see Siebel Product Administration Guide.

When exported, a variable map and its child variable maps are exported together into an XML file. When imported through the joint workspace, both parent and child variable maps will be imported and listed in the Joint Workspace view.

Note: You must go to each of these variable maps separately to release them.

Variable Map Methods of the Context Service Business Service

The Context Service business service provides the APIs shown in the following table for variable maps.

Method	Arguments	Description
GetRowSetData	[in] CPCollapseAll: String	By default, if the CPScope requires expansion of the customizable product to read all products, after GetRowSetData, this customizable product is expanded on the UI unless this flag is set to be true, in which case the customizable product is collapsed.
	[in] CPScope: String	Component, Master, Whole, Component, and Subcomponents. This argument defines which parts of the current customizable product are queried.
	[out] PropSet: Hierarchy	A row set property set containing the query results.
	[in] RowScope: String	Current, Selected, or All. Defines which rows the Context Service service will read data from.
	[in] VariableMap: String	The variable map defining objects to query.
SyncRowSetData	[in] RowSet: Hierarchy	The updated row set property set.
SyncRowSetData	[in] VariableMap: String	The variable map defining objects to update.