Use Asset Based Ordering

The Commerce/Oracle Configure, Price, Quote integration features asset based ordering (ABO).

Understand asset definition and related properties

This integration supports an asset based ordering (ABO) model. Asset based ordering lets you sell tangible assets or subscription services delivered over a period of time; for example, mobile phone call and data plans, television and broadband packages. When these orders are subsequently fulfilled, the fulfillment system notifies Oracle Configure, Price, Quote via an asset API, and Oracle Configure, Price, Quote then creates an asset in the Oracle Configure, Price, Quote asset repository. To better understand asset based ordering and its related services, it is important that you first understand asset definition and the related properties.

In the Commerce/Oracle Configure, Price, Quote integration, Commerce acts as the first point of contact for registered and account-based shoppers. Commerce lets a shopper review and select their purchases as needed.

In Telco-related purchases, Oracle Configure, Price, Quote acts as the primary Asset system. Commerce makes a call to Oracle Configure, Price, Quote to retrieve the assets for a particular profile or account. Oracle Configure, Price, Quote then manages the retrieval of assets from multiple systems if necessary.

One of the underlying features of any Telco solution is the ability for a self-service channel (in this case, Commerce) to retrieve and display the complete set of assets owned by the shopper and then to allow the shopper to trigger operations on those assets. In order for this to happen, Oracle Commercesupports the following asset-related information properties at the order item level:

• Asset Key - the assetKey property (formerly assetID) is a unique identifier that is assigned to potential assets when adding items to a cart. This value is used throughout the asset life cycle by fulfillment, asset management, and order capture systems. In this case, the term "potential" is used meaning that not every item added to a cart gets completely fulfilled, a provisioning system may fail, etc. For configured items, the assetKey value is assigned as part of the asset configuration process in Oracle Configure, Price, Quote.
• Parent Asset Key - Some configured items in an order may be many levels deep in a BOM structure. In order to ensure that the BOM hierarchy is consistent throughout the asset life cycle, each item in the BOM hierarchy must be able to identify its direct parent. The parentAssetKey property makes this possible. For root items in a BOM hierarchy, the parentAssetKey value is NULL.
• Root Asset Key - Again, some configured items in an order may be many levels deep in a BOM structure. In order to ensure that the BOM hierarchy is consistent throughout the asset life cycle, each item in the BOM hierarchy must be able to identify its root asset. The rootAssetKey property makes this possible. For root items in a BOM hierarchy, the assetKey and the rootAssetKey value is the same.

Understand the mapping of an asset key to an item

In Oracle Commerce, a configurable SKU may be flagged as "non-assetable" which means that when this item is configured and purchased it will not be assigned a customer, billing, or service account and will not become an asset for the shopper. When this item is configured, however, Oracle Configure, Price, Quote returns asset key values for each item in the BOM by default.

Note: The flag name is assetable and the default value is False.

Commerce only maps asset key values to commerce items that are actually "assetable." The rules used in this process are the following:

• If the SKU selected for configuration is based on a product where the property value for assetable = TRUE, map the asset key data.
• If the SKU selected for configuration is based on a product where the property value for assetable = FALSE do not map the asset key data.

Understand the Asset Root

It is also important to point out that when a shopper chooses to configure a SKU in Commerce, the root item of the BOM returned from Oracle Configure, Price, Quote may not always be that same SKU, that is, the root item part number may not map directly to the selected configurable SKU.

Say, for example, a mobile product bundle that is represented by the "Red Bundle" SKU in Commerce is configured several ways. At the initial step of the configuration process, the shopper may be asked to select either the Standard Package, Student Package, or Value Package. Depending on the selection made, the root item of the configuration will be different.

So, based on this example, it is possible that the SKU selected by the shopper to configure the item will be based on a product where _assetable _= TRUE but the root item for the resulting configuration may be based on a product where _assetable _= FALSE.

The rule that decides whether a configured item should be assigned _assetKey _ property is based on whether the SKU that corresponds to the root item of the configuration is "assetable" and not on whether the item that the shopper selected to be configured in Commerce is "assetable".

Understand asset based ordering and related service operations

As already discussed, asset based ordering lets you sell assets or subscription services delivered over a period of time. When these orders are subsequently fulfilled, the fulfillment system notifies Oracle Configure, Price, Quote via an asset API, and Oracle Configure, Price, Quote then creates an asset in the Oracle Configure, Price, Quote asset repository.

Once created, assets can subsequently be reviewed by shoppers in the My Services management area within the shopper account. The shopper can then administer an asset by creating and placing new commerce orders to perform a number of actions on the asset. These include the following:

• Modify
• Renew
• Terminate
• Suspend
• Resume
• Upgrade

A Services-store SSE and the Services-agent SSE can be configured from the administrator’s user interface. To do this, click the Design icon in the Administration user interface. Then click Developer and Server-Side Extensions. Select the name of the SSE. Both SSEs enable integration with 3rd party asset management systems to retrieve and execute operations and services on assets available to the shopper. They also serve as the API for the pre-built integration with Oracle Configure, Price, Quote asset management.

For each of these operations the operation flow is basically the following:

• The shopper views their list of assets.
• The shopper selects an asset.
• The shopper selects the desired operation:
  • For a Modify operation, the system loads the Oracle Configure, Price, Quote hosted iFrame, the shopper makes their modifications, and selects to add to cart. This is the Oracle Configure, Price, Quote hosted iFrame presented to the shopper when they configure a new purchase prior to adding it the cart, reconfigure a new purchase prior to checking out, or modify an existing asset.
  • For an Upgrade operation, all available upgrade options are displayed on the Storefront Asset list and then the specific Asset Details pages. After you have selected a specific Asset, you can select the Upgrade option to view its upgrade details. When you click on an upgrade option, an iFrame is returned and opens up in the context of the available upgrade options. You can then choose your asset upgrade(s) and add them to your cart.
  • For all other operations, the system only makes a call to Oracle Configure, Price, Quote to execute the operation.
• Oracle Configure, Price, Quote asset records are updated.
• Oracle Configure, Price, Quote returns the required JSON representation of the terminated/renewed/suspended/resumed/modified/upgraded asset.
• Commerce transforms the JSON returned to a commerce item and adds it the cart.
  • For the Modify and Upgrade operations, the transformation is executed in the Commerce client layer.
  • For all other operations the transformation occurs in the Services SSE which uses the Asset Action OIC flow.
• The shopper continues shopping.
• When the shopper places the order, the cpq-config-validation-app SSE is triggered through the External Pricing Webhook. This SSE invokes getConfiguration for every flow except when the asset actions are Terminate and Suspend. The response received from OIC gets transformed from the cpq-config-validation-app SSE as the OIC flows, getConfigurations, and getConfigBom return a flat structure of items which is converted to a hierarchical structure. Validation is then done in the cpq-config-validation-app SSE to verify that data is not manipulated on client-side.
• The order items representing Asset Based Ordering operations are submitted downstream and contain all of the information required to ensure that the operation is fulfilled.

The specific Services actions are described in more detail later in this section. These actions are important for maintaining an efficient self-service channel. When a shopper performs any one of these actions on an asset, the Oracle Configure, Price, Quote asset repository is updated accordingly.

Since Commerce serves as the first point of contact for shoppers, it allows shoppers to review and select their purchases. In the case of a Telco commerce solution, the Oracle Configure, Price, Quote asset repository acts as the primary Asset system in which Commerce makes a call to Oracle Configure, Price, Quote to retrieve the assets for a particular profile or account. Oracle Configure, Price, Quote manages the retrieval of assets from multiple systems.

The Commerce Telco solution gives the shopper the ability to retrieve and display the complete set of Assets owned by the shopper/account as well as carry out the mentioned administration operations that can be performed on those assets.

When a shopper opens the My Services management area within their account they are presented with a list of the assets linked to their account. From here they can select an asset and click on the Details button next to the desired asset to see the detailed view of the service.

It is at this point that the shopper can choose between the Modify, Renew, Terminate, Suspend, Resume, and Upgrade actions.

Modify

If the shopper chooses Modify, Commerce loads the current configuration for the service in question and opens a screen that allows the shopper to modify the service as required. The new monthly charge for the service is updated automatically as the shopper makes their selections. The shopper can then add the modified service to their cart.

When the shopper goes through checkout and completes their order, Commerce submits a service modification request to the fulfillment system.

As mentioned, earlier the steps in this operation are typically the following:

• The shopper views their list of assets.
• The shopper selects an asset.
• The shopper selects a Modify operation. For a Modify operation, the system loads an Oracle Configure, Price, Quote hosted iFrame. The shopper makes their asset modifications and selects to add it to cart.
• Oracle Configure, Price, Quote asset records are updated and Oracle Configure, Price, Quote returns the required JSON representation the terminated/renewed/suspended/resumed/modified asset.
• Commercetransforms the required JSON returned to a commerce item and adds it the cart. This transformation is executed in the Commerce client layer.
• The shopper continues shopping and then checks out.

The order items representing ABO operations are submitted downstream and contain all of the information required to ensure that the operation is fulfilled.

Renew

If the shopper chooses Renew, Commerce determines the configuration ID that represents a renewal of the service in its current configuration and then adds a renewal instruction to the shopping cart and opens the Shopping Cart Details page.

When the shopper goes through checkout and completes their order, Commerce submits a service renewal request to the fulfillment system. This is handled and invoked via the Services SSE endpoint /services/{id}/renewService and the SSE invokes the OIC flow.

Terminate a service

If the shopper chooses Terminate, a configuration ID is sent back by Oracle Configure, Price, Quote that represents the termination of the service in question. A termination instruction is added to the shopping cart and the Shopping Cart Details page is then opened

When the shopper goes through checkout and completes their order, Commerce then submits the service termination request to the fulfillment system. This is handled and invoked via the Services SSE endpoint /services/{id}/terminateService which invokes the OIC flow.

Suspend a service

If the shopper chooses Suspend, it allows them to suspend a service. Commerce provides an endpoint that is used to suspend a service. When a shopper selects to suspend a service, they choose the Suspend action and then enter a valid suspend date.

By clicking on the Suspend button, Commerce determines the configuration ID that represents the suspension of the service in question, adds a suspension instruction to the shopping cart, and opens the Shopping Cart Details page. When the shopper goes through checkout and completes their order, Commerce submits a service suspension request to the fulfillment system. Also, when the Suspend action is chosen from the store user interface, the transaction date is set to current date (i.e., the date that the shopper suspended the service. This suspension may be indefinite or for set for a specific period of time by entering a date. A specific shopper use case example might be letting a shopper suspend a data plan for 30 days.

The Services SSEs support the Suspend operation which returns either a Configured Item or an Error. Services is part of the Oracle Integrated Cloud flow.

The Services API has an endpoint called Suspend Service. The endpoint can be triggered when a shopper selects to suspend a service, enters a valid suspend date and time, and selects to proceed. Inputs include the following:

• Asset Key
• Action - Suspend
• Transaction Date - The valid suspend date and time information that the shopper entered. The Suspend date is not equal to or later than the asset end date.

The API returns either a Configured Item or an Error.

Resume a Service

If the shopper chooses Resume, it allows them to resume a service that was previously suspended. Commerce provides an endpoint that is used to resume a service. When a shopper selects to resume a service, they choose the Resume action and then enter a valid resume date and time to resume the service.

By clicking on the Resume button, Commerce determines the configuration ID that represents the service in question that is to be resumed, adds a resume instruction to the shopping cart, and opens the Shopping Cart Details page. When the shopper goes through checkout and completes their order, Commerce submits a resume service request to the fulfillment system. Also, when the Resume action is chosen from the store user interface, the transaction date is set to current date (i.e., the date that the shopper resumed the service).

The Services SSEs also support this Resume operation which returns either a Configured Item or an Error. Services is part of the Oracle Integrated Cloud flow.

The Services API has an endpoint called Resume Service. The endpoint can be triggered when a shopper selects to resume a service, enters a valid resume date and time and selects to proceed. Inputs include the following:

• AssetKey
• Action: Resume
• Transaction Date: The valid Resume date and time that the shopper entered. The Resume date is not equal to or later than the asset end date.

The API returns either a Configured Item or an Error.

Note: An action code of Renew, Terminate, Suspend, and Resume is assigned to an item when that respective operation has been applied to that item.

Upgrade an Asset

With Asset Based Ordering, you have the ability to upgrade an existing asset. If a shopper chooses the Upgrade operation, they can upgrade an asset to one of the upgrades available for the product. Any Root asset may have one or more upgrade options available at any time. Commerce SSE endpoints getServices and getServices/{id} return the upgrade options for each of the asset if the query param "expand=occ_upgradeOptions" is passed. Once the shopper selects the Upgrade action and clicks the Upgrade button, this action invokes the upgradeService SSE endpoint which gets the upgrade name as input and returns the query string that is to be used as punchin URL to launch the Oracle Configure, Price, Quote iFrame. From the user interface point of view, a shopper selects to upgrade an asset, choose the Upgrade action in the Asset Details view and then select the asset upgrade that they desire.

Oracle Configure, Price, Quote maintains a custom upgrade options table for Commerce to query in order to know which upgrades are available for a given asset. The key parameter controlling the operation is the SKU of one or more items that are part of a current asset bundle. The response received after initiating this operation includes all of the eligible SKUs that an asset can be upgraded to.

Commerce has an Upgrade endpoint to fetch all available upgrade options. The input for this endpoint is currentModel and currentOffer. The following presents the details on the information needed to retrieve the upgrade options table from Oracle Configure, Price, Quote:

• Oracle Configure, Price, Quote Table Name: INT_UPGRADE_OPTIONS
• Input (via URL parameter): occ_Upgrade_options query parameter which is a list of currentSku plus currentModel for the assets. Type: String. This query parameter is passed from Commerce to the SSE endpoint (described further in this section). After a getAssets call, you then pick the currentModel and currentOffer from each asset and invoke the Oracle Configure, Price, Quote upgrade options table.
• Output: upgradeName, upgradeProductId(OCC)

The following presents the details on the basic schema of the upgrade options table maintained by Oracle Configure, Price, Quote that contains the specified upgrade information:

Table 2-2 Oracle Configure, Price, Quote Upgrade Table

Column Name	Data Type and Description
currentSku	String. This value defines the current offer. This needs to be stored as an attribute of an asset record. This value is sent from Commerce while retrieving the upgrade options.
currentModel	String. The model name for which the upgrade offer is valid.
upgradeName	String. This value is passed to he Oracle Configure, Price, Quote iFrame while upgrading and is used by Oracle Configure, Price, Quote to default and render the upgrade options. This is not be used by Commerce for any purpose.
upgradeProductId	String. This is used by Commerce to identify the product corresponding to upgrade option. The product display name, description, images, etc. can be used to show upgrade details to the shopper.

Note: A combination of currentSku and currentModel is used as the parameter to find the matching upgrade options

The Oracle Configure, Price, Quote upgrade table is queried by Commerce to help identify the upgrades that are available for a given asset. These upgrade options are then presented to the shopper. An example of what the upgrade information would contain includes the following:

Table 2-3 Example of upgrade options returned to Commerce

currentSku	currentModel	upgradeName	upgradeProductID
4ForUDeal	nPlay	4ForUDeal	prod102

It is recommended that the currentSku column is indexed. The following presents additional details on each returned upgrade option:

• currentOffer - Maps to a configurable attribute on the root config model in Oracle Configure, Price, Quote. This needs to be stored as an attribute mapping onto the root asset as well. This value is sent from Commerce while retrieving the upgrade options.
• currentModel - Maps to the variable name of the root config model in Oracle Configure, Price, Quote which the upgrade offer applies to.
• upgradeName - Maps to the _config_upgrade_name that is passed from Commerceto Oracle Configure, Price, Quote, which drives recommendation rules on the upgrade. This is not used by Commerce for any other purpose.
• upgradeProductId - Maps to the Product Id of the upgrade offer in Commerce. This is used to show upgrade details (product display name, description, images, etc) to the shopper.

As mentioned, Commerce provides an Upgrade endpoint that is used in the operation to upgrade the asset. This endpoint is part of the Services SSE which works to complete multiple service operations (already mentioned in the above sections) via the Services API. For this operation, the Services API has an endpoint called Upgrade. The following information provides more detail on what is required by the API to upgrade an asset using this endpoint:

• SSE name: Services
• Endpoint name: Upgrade
• Endpoint trigger: The endpoint is triggered when the user clicks Upgrade against an upgrade option
• Inputs:
  • Logged in User Token
  • AssetID
  • upgradeName (returned from Oracle Configure, Price, Quote)
• Returns: Upgrade URL Query String. This is the string of data that is appended to the base Modify URL to ensure that the upgrade iFrame is correctly pre-populated based on the product that the shopper is upgrading from and the product that they are upgrading to.

The activity that occurs at the store user interface level during the Upgrade operation is the following:

• Select the Asset List view. This lets you view information about all of your assets/services. This view will also show the upgrade options (if available) for the asset. You cannot trigger an Upgrade operation from this view as the actual upgrade URL is not yet determined until the asset details are retrieved.
• Select the asset you wish to view and click the Details button so that you can view the asset details and as well as possible upgrade details.
• When you click the Details button of any asset, the asset details page is displayed which shows all of the details associated with that asset along with available asset action options.
• The asset details page also has a section showing the upgrade options available for that asset. When you display the asset details page, the product details of that SKU/Product are displayed. The Upgrade button is displayed next to any upgrade available for that asset.
• Click the Upgrade button in the Asset view of the asset that you want upgraded. Your upgrade option details are then displayed in the Asset Details view. You can also get the same results by clicking the link for the available upgrade from the Service list.
• Click Upgrade. When the Upgrade operation is initiated, the following occurs:
  • If there are upgrades available for the asset, the SSE endpoint returns an Upgrade URL Query String and creates the upgrade punch-in URL to load the iFrame containing the information about the available upgrades.
  • When you select to upgrade you are finally presented with a pre-configured modification to your asset bundle.
  • If the SSE endpoint returns an error, this means there are no upgrades available for this asset and an appropriate error message is displayed.
• Add the upgrade to your cart and submit the order to complete the upgrading process.

Finally, each of the Asset Based Ordering services operations described earlier may be carried out by a shopper or by an agent acting on the shopper’s behalf.

Additional information related to using the Upgrade feature with Commerce

The following additional details should be kept in mind when using the Upgrade feature:

• In Commerce you can start a configuration upgrade from a configurable SKU (for example, "4ForU Deal") which in turn maps to a model "nPlay" in Oracle Configure, Price, Quote.
• Configuration metadata is set with key "offer" and value "4ForU Deal" for the above SKU and is passed to Oracle Configure, Price, Quote
• After the configuration upgrade is completed, the BOM returned from the Oracle Configure, Price, Quote for that configuration may have a different rootSKU (i.e., "nPlay") and that is what is added to cart. "4ForUDeal" may be a child of "nPlay".
• In Commerce, there is another SKU for "nPlay" that is configurable and maps to the same model "nPlay" in Oracle Configure, Price, Quote.
• After the order is submitted, an asset with "nPlay" is created which has an asset attribute of Offer. Offer then has a value of 4ForUDeal.

Also, via the CommerceAdmin, you can create products with an upgradeProductId as the productId value, and mark them as 'notForIndividualSale.' This lets you do the following:

• Have a unique name for each upgrade that can be displayed in the store
• Have a unique description to describe what the upgrade is
• Support locale specific translations
• Have the ability to upload images related to the upgradeOption.

Handle further upgrades to an asset that has already been upgraded

In some use cases, you may have a situation where you have an asset with currentOffer=sku1234 that is being upgraded to Upgrade 101. When you then visit the Asset Details page again you are presented with the same upgrade option of Upgrade101. This can occur because the upgrade does not modify the currentOffer and it is still sku1234 and its corresponding upgrade options are being fetched during the getAssets/getAsset flow.

The following details show how you can solve this type of situation:

Table 2-4 Example of how to handle further upgrades to an asset

currentOffer	currentModel	upgradeName	upgradeProductID
4ForUDeal	nPlay	4ForUDealPlus	4ForUDealPlus

• Let's say a shopper starts an upgrade configuration from the SKU "4ForUDeal" by passing the configuration metadata offer=4ForUDeal.
• After upgrading the configuration, the BOM sent from Oracle Configure, Price, Quote may have a different root SKU id such as "nPlay." "4ForUDeal" may be a child of it. It will also contain an attribute "offer" with value "4ForUDeal"
• An asset with "nPlay" as the currentModel gets created and the getAssets/getAsset flows return the asset details along with asset attribute offer=4ForUDeal.
• The offer attribute is sent as the currentOffer to the Oracle Configure, Price, Quote while retrieving the upgrade option 4ForUDealPlus.
• Once the upgrade has been performed by passing the upgrade name 4ForUDealPlus to Oracle Configure, Price, Quote in the queryString, the BOM returned from Oracle Configure, Price, Quote will have the attribute "offer" with value "4ForUDealPlus".
• After submitting the order and updating the asset, the asset attribute "offer" value now gets updated to "4ForUDealPlus".
• In subsequent getAssets and getAsset calls the asset attribute offer value will be returned as "4ForUDealPlus", so that there are no matching records for that currentOffer in upgrade options table in Oracle Configure, Price, Quote.

Understand the Disable Reconfiguration feature

Regarding these operations, the Oracle Commerce and Oracle Configure, Price, Quote integration also has the ability to prevent shoppers from attempting to reconfigure items in their cart that have been added by any of the following operations:

• Renew
• Terminate
• Suspend
• Resume

To assist in disabling reconfiguration on already configured items added by any of these actions, an action code of Renew, Terminate, Suspend, and Resume is assigned to an item when that respective operation has been applied to that item.

This code is assigned to make sure that shoppers are prevented from attempting to reconfigure an asset. The purpose of the code is to make sure the reconfigure session(s) fails, either at reconfiguration or order validation time.

Differentiate between new order items and ABO order items

To identify items in an order that are the result of an operation on an existing asset (Terminate, Renew, Suspend, Resume, Modify, Upgrade), Commerce has checked to see if there was an assetId value. If there was, Commerce assumed that the item is the result of an ABO and not a net new purchase. This approach worked on the assumption that an asset identifier would only be assigned when the asset record was created in Oracle Configure, Price, Quote.

Asset identifier values are now assigned at the time when a shopper adds an item to the cart. To ensure that Commerce can always reliably differentiate between new order items and ABO order items when an ABO item is added to the cart, a lineType property for each item in the configuration hierarchy is set to ASSET.

The rule used to differentiate between new order items and ABO order items is the following: If assetKey value is present and _lineType = NULL then the item is a new purchase and not an operation on an existing asset.

Retrieve assets for an order with an asset key

For the cancel in-flight feature, Commerceneeds a mechanism for retrieving all of the assets derived from a particular order. Commerce used to retrieve the assets for a particular order based on assetID (stored on the asset record in Oracle Configure, Price, Quote). Commerce now uses the assetKey value.

For any given order Commerce queries the Oracle Configure, Price, Quote assets API to retrieve the assets for the order based on the collection of assetKey values. This query is limited to the assetKey values for the root items in the order only

Understand restricting the quantity of assetable items

A shopper used to be able to increase the item quantity for a configured item in the cart in the same way as any other purchase. This action does not work where an asset key value has been assigned.

Asset keys are assigned to net new purchases as part of the configuration process. Oracle Configure, Price, Quote assigns an assetKey for the root and all child items in the configuration. If an item has been assigned an asset key then this asset key is used to identity a single instance of this asset throughout the fulfillment, provisioning and asset management processes. As a result, the quantity of an item cannot be greater than one.