Bookshelf v8.0: Apply Method

Siebel Order Management Infrastructure Guide > Asset-Based Ordering Methods Reference > Product Manipulation Toolkit Business Service Methods >

Apply Method

This is one of the Product Manipulation Toolkit Business Service Methods.

It applies changes defined by a Sales order line item to a customizable asset. This method uses, as a base, an asset that is cached as a result of a call to set the Product Instance and optionally, a header (asset, quote, or order), passed in during the Set Output Header.

Arguments

OpenOrders

[in] Output result of a call to Business Service Find Orders. (Optional)

For more information, see Remarks.

NOTE: Either OpenOrders or SiebelMessage is acceptable as input but not both.

SiebelMessage

[in] Contains a single complex Open Order or an Open Quote Line Item. (Optional)

NOTE: Either SiebelMessage or OpenOrders is acceptable as input but not both.

SiebelMessage

[out] Output asset image representing a future configurable asset.

Is Apply Result Empty

[out] Y if all the line items are removed from the result, or if the information supplied to create an asset is insufficient information.

NOTE: Either SiebelMessage or Is Apply Result Empty is returned as output but not both.

Returns

An asset PropertySet that represents the original input asset plus the changes defined in the input quote or order line item.

Remarks

Input Arguments

To meet its requirements as a general-purpose tool for processing throughout the Asset-Quote-Order life cycle, the Apply method can accept a variety of arguments as input. All input parameters are optional to a varying degree, and the combination of parameters will be determined by the data present and the desired operation.

Apply handles four possible input parameters:

OpenOrders [input] PropertySet representing a series of Open Orders
OpenOrders can be passed as one of two arguments directly in the Apply method invocation. When a single OpenOrder is to be processed, this argument can be supplied through a standard SiebelMessage PropertySet, obtained through a call to a standard Siebel Adapter. It can be either an Order or a Quote subtype (Quote only on Modify Quote Workflows).

When more than one Open Order is involved in creating the Output Asset, OpenOrders is supplied by a multiple hierarchy OpenOrders type, obtained by invoking the Find Orders Business Service method. Apply checks for the presence of OpenOrders first, and only looks for the single-order SiebelMessage if OpenOrders is not supplied. If both are supplied, only OpenOrders is processed. If neither is supplied and Input Asset is supplied, the Apply method passes the Input Asset PropertySet back as the Output Asset PropertySet.
SiebelMessage [input] PropertySet
This input represents a single Open Order. See the previous description.
Asset [input] PropertySet
This argument is passed through the Set Product Instance method invocation before Apply is invoked. The Input Asset PropertySet is the base Asset upon which all changes from Open Orders are applied. If no Assets related to the Open Orders are being applied, the call to Set Product Instance is skipped.
Header[output] PropertySet
This argument is passed through the method invocations before Apply is invoked. Ordinarily, the Output Header normally is not supplied. However, if it is supplied, it is passed into the Business Service by a separate invocation of Set Output Header immediately before Apply is invoked.

Under most operating conditions, Apply determines the contents of the Output Header from the Input Asset or the Input Orders. However, when the Output Header is supplied, it is passed into the Business Service by a separate invocation of SetOutputHeader immediately before Apply is invoked. The Output Header can be a SiebelMessage PropertySet of type Asset, Order or Quote. It can be either an empty header without subordinate data or a fully formed hierarchy with associated child item data. When child item data is carried with the Output Header, the child item data is removed.

Generally, the Output Header gives the Apply method specific data to create an update Output Header for later synchronization by a Siebel Adapter. Use it only if the Output Header that results from Input Asset or the Input Open Order processing is insufficient for resynchronization.

It is also possible (and occasionally valid) to invoke Apply without passing any arguments at all. If no input is specified at all, Apply returns a value of Y in the Is Apply Result Empty Process Property. This result is also returned when the resulting Asset contains only a header, but no items.

Creating a hybrid asset order

Apply creates a hybrid asset-order to simulate the future configuration of a complex product. Taking an asset representing a complex product as input, Apply overlays all unprocessed items and attributes of that product from all its open orders onto the asset. Because the asset's items and attributes are already provisioned, their action codes will carry the internationalized equivalent of the *(blank) value.

Service Item Unique Keys

The Apply and Delta method operations depend upon the unique keys to each service item. For more information, see the description of Delta Method.

Apply assumes that the asset used as a base on which to apply open orders was set using Set Product Instance. If no asset is supplied, either the first Open Order or the single (SiebelMessage) Open Quote or Order will be used as the basis for creating a new complex asset. If neither asset nor Open Order is supplied, the method returns an Empty result.

Exception Handling

Apply handles all service quote or sales order actions even if they include possible conflicts. For example, if a service quote line item instructs the method to modify a service item that is already disconnected, Apply logic ignores the service quote line item. The exception conditions handled by Apply are listed below.

Apply is executed in two steps:

SetProductInstance (Asset PropSet)
This action initializes internal structures and stores the passed PropertySets that are the result of an earlier invocation of Siebel EAI Adapters. Because a business service is limited to a single hierarchy for each invocation, the PMT business service is invoked twice to pass both PropertySets.

NOTE: The Asset PropertySet is assumed to be a single hierarchy representing a single complex item, keyed by the integration ID for the root of the complex item.
Apply (OpenOrders PropSet)
This action does the following:
- Retrieves the Asset PropertySet from its internal storage (established by calling Set Product Instance) and instantiates the output complex object from it.
- Instantiates a complex object from the OpenOrders PropertySet input parameter.
- Iterates through the OpenOrder PropertySet, applying each item in turn, repeating for each open order in ascending chronological sequence.
- Whenever the hierarchical structure is altered, Apply fixes the output hierarchy to reflect the OpenOrder.
- Returns the output property set.
  NOTE: The OpenOrders PropertySet is assumed to be one of a Null hierarchy, a single hierarchy representing one complex item, or a container of iterations of a complex item, each representing a change over time. The integration ID for the root of the complex item is the key for the item.

The Apply method handles the exception conditions listed in the table that follows.


Exception	Action	Reason
Instruction to add an item that already exists.	Ignores the add instruction. Attributes and the price are not updates.	The instruction is outdated. Therefore, the attributes are unreliable.
Instruction to update an item that no longer exists.	Ignores the update instruction.	The instruction is outdated. It cannot be performed.
Instruction to delete an item that no longer exists.	Ignores the delete instruction.	The action has already occurred.
Instruction to do nothing to an item that does not exist.	No action.	A sequencing problem may have occurred.

Examples

Add, Update, Delete a Complex Order

The following example shows how this method applies add, update, and delete instructions on an order to an existing asset.

Start with a customizable asset, as in the diagram that follows.
Apply a delta order, as in the diagram that follows.

For more information, see Delta Method.
A new customizable asset is created, as in the diagram that follows.

Process a new installation

The following example shows how this method is used to process a new installation.

Start with no asset.
Apply a new installation.
A new customizable asset is created, as in the diagram that follows.

Ignores Instructions to Process Absent Items

The following example shows how this method is used to process a delta quote that includes an update to an absent item.

Start with a customizable asset from an external profile management system, as in the diagram that follows.
Apply a delta quote that was generated a week before, as in the diagram that follows.

NOTE: The calling card referred to in the delta quote was removed from the profile after the quote was created. The [UPDATE] Calling Card branch is ignored.
The Apply method ignores updates to the service item that no longer exists, but successfully executes the remaining changes. This is shown in the diagram that follows.

Ignores Instructions to Add an Already Existing Item

The following example shows how this method is used to process a delta quote that contains an invalid add instruction.

Start with a customizable asset from an external profile management system, as in the diagram that follows.
Apply a delta quote that was generated a week before.
NOTE: The second local line, (650) 213-7575, already exists in the service profile. It was provisioned by an external system user.
Apply ignores add commands where the service item already exists and successfully executes the remaining changes.

Process Instructions to Update the Parent of a Component

The following example shows how this method is used to process a delta quote that updates the parent component.

Start with a customizable asset in the old product format, as in the diagram that follows.
Apply a delta order that updates the parent component of the Call Forwarding feature, as in the diagram that follows.
The Apply method adds the Feature Package product beneath the local line and reattaches the existing Call Forwarding feature to the Feature Package, as in the diagram that follows.