Introduction

The Service Provider solution in Feature pack 2 of WebSphere Commerce V7 enables the sale of goods through subscription-based transaction models, focusing primarily on the time-based subscription model. In this subscription model, a one-time purchase of the subscription by the shopper allows for a periodic supply of goods to be received over a certain period. Examples for time-based subscription models include magazine subscriptions, newsletters, subscription for dietary supplements, and so on.

There are other forms of subscription based transaction models such as event-based subscriptions, time and event-based subscriptions, and periodic services offering, each varying in the aspects of the period and frequency of the service being offered and their applicability across industries. This article provides insight into the event-based subscription model and demonstrates features available in the service provider solution.

A subscription is a business model in which the customer gets into an agreement with the vendor by paying a nominal price to receive a periodic supply of goods or services. This model was made popular by magazines and newsletters where customers are charged a subscription fee in return for a periodic supply of the magazine. This is called a time-based subscription and it is the most basic form of subscription best suited for recurring sales of hard goods, such as magazines, newsletters, and so on.

Over time, the fundamental concepts of subscription have been extended to fit in to other industry verticals, such as telecom, media, and entertainment, where business models vary significantly from their traditional hard good selling counterparts. Though each extension is specific to different selling models, the fundamental principle covering them still remains the same.

A subscription-based transaction model has two defining characteristics:

1. Entitlement: An entitlement defines the manner in which the service is to be offered to the customer. In other words, it represents the "contract" between the customer and the vendor when the customer buys or "subscribes" for a service. The entitlement in any subscription-based transaction model essentially covers three aspects:
   1. Time period: The duration up to which the service is to be made available to the customer is defined by the time period of the subscription.
   2. Frequency: The rate at which the service is to be recurred for a customer is defined by the frequency of the subscription.
   3. Number of occurrences: This denotes the total number of times for which the customer is entitled to receive the service from the vendor. In a time-based subscription model, the number of occurrences can be a derived entity inferred from the frequency and time period of the subscription.

   Subscription models are classified primarily based on the entitlement terms.

   • One-time service: A one-time service purchase is a basic form of subscription without any terms and conditions. Following are a few examples of this model:
     • Washing machine + installation/delivery service: The installation service can be a paid service that the customer has to opt for while purchasing the machine.
     • Installation/delivery services: Repair service or any human service.
   • Event-based: An event-based entitlement governs the access to an item (or service) for a defined number of times. The number of times the access is given, either predefined in a catalog or specified by the customer in the order, and in increments predefined in the catalog. In other words, the number of times a subscription can be used is restricted in this form of entitlement while the customer is free to use the subscription anytime within the duration of the subscription (the duration can be infinite). Following are a few examples of this model:
     • Download access for 10 mobile apps
     • Music download of 6 tracks for U.S. $8.00
     • Purchase 2 CPU licenses or 2 user licenses
   • Time-based: A time-based subscription governs the fulfillment of the service over a period of time at a specified frequency. The duration and frequency are predefined in the catalog. In other words, in this form of entitlement, the customer is fulfilled with the item (service) at a defined frequency and over a specific time period.
     Following are a few examples:
     • 3 months access to Britannica online worth U.S. $15.00
     • A year-long subscription for a bi-weekly magazine
2. Payment: The payment defines the terms in which the payment for the service is going to be done. These vary from a one-time payment done at the time of purchase of the subscription, to periodic payments done at a specific frequency over the duration of the subscription.

A subscription business model is largely different from the traditional one-time purchase of goods. In a one-time purchase, the order processing phase deals with the one-time fulfillment of the order. However, in a subscription order, the post order processing starts from the start date specified in the order and spans across the duration of the subscription.

A set of actions or processes are performed on a subscription, which cause the subscription to transit through the various stages in its lifecycle. These processes vary based on the subscription model.

In subscription models, where the frequency of fulfillment is predefined (time-based subscription), the processing action is one of fulfilling the subscription at the frequency defined for the subscription.

In models where the frequency of fulfillment is not defined (such as event-based or time-event-based subscriptions), the processing of the subscription is triggered not by the system, but by the customer's actions towards the subscription. The service provider solution in Feature Pack 2 (FEP2) provides the necessary framework to manage the post order processing required for the subscriptions in the system.

The article describes the overall architecture of the subscription component and provides insights on modeling other forms of subscriptions. A case study will illustrate a modeling of a sample event-based scenario, highlighting the details of various customizations required to achieve it.

Back to top

Overview of subscriptions in WebSphere Commerce

Subscriptions in WebSphere Commerce are modeled as catalog entries having specific attributes of fulfillment frequency, payment frequency, and duration associated to them. This enables WebSphere Commerce to have a single order check out flow for both subscriptions and regular catalog entries. While creating a catalog entry in WebSphere Commerce, you can choose the catalog entry to be a subscription. Since the FEP2 solution focused mainly on time-based subscriptions, creation of subscription catalog entries through the Commerce Management Center (CMC) is only for time-based subscriptions.

When an order containing subscription items is detected, the order system invokes the subscription manager, which is the component in WebSphere Commerce that manages the life cycle of subscriptions in the system by performing multiple actions on it during its duration. These actions are broadly classified into the following two groups:

• System triggered: The actions are performed by the subscription manager itself without the interference of the user.
• User triggered: The actions are performed based on the user's actions fulfilling the subscription at regular intervals, updating with subsequent fulfillment cycles, transitioning it from states such as "active" to "expire", and so on.

To facilitate the user to perform actions on the subscription, the subscription manager exposes a set of Web services that are invoked by the store front. The system triggered actions are monitored and executed by a scheduler mechanism inside the subscription manager component.

The subscription actions supported and the corresponding functionality provided for each action vary based on the subscription transaction model. For example, in a time-based subscription model, a system triggered action performs the task of fulfilling the subscription while also scheduling the next fulfillment action in the process. However, this scheduled action has no role in an event-based subscription transaction model where the fulfillment or usage of the subscription is driven by the user.

Similarly, a user triggered action for usage in an event-based subscription has no role to play in a time-based subscription model. Thus, when modeling a new subscription type in the system, it is important to identify the new subscription actions to be supported along with the modifications to the behavior of common actions across subscription models.

Time-based subscription in WebSphere Commerce

As outlined earlier, in time-based subscriptions, the fulfillment of the subscription occurs in accordance to a fixed schedule, starting from a specified start date and spanning over a specific duration, both of which are chosen by the customer. The schedule is fixed by the vendor based on the periodicity of the product.

When a customer purchases a time-based subscription, its lifecycle is outlined as follows:

1. The subscription is marked "inactive" until the payment for it has been authorized.
2. Once the subscription is "active", a series of fulfillment actions are performed based on the schedule for the subscription.
3. At any point during the duration of the subscription, the customer is provided with the option to cancel the subscription. Once cancelled, further fulfillments towards the subscription are discontinued and any refund to be made towards the subscription is performed.
4. Once the stated number of fulfillments is completed, the subscription is marked "expired".
5. The customer has an option to "renew" a subscription either before or after the actual expiry.

As you can see, the actions of fulfillment are system triggered in the case of time-based subscription, and is thus handled by the subscription scheduler. The user actions, such as "cancel" and "renew", affect the lifecycle of a subscription.

Figure 3 charts out the lifecycle of a time-based subscription.

Back to top

Supporting other forms of subscriptions in WebSphere Commerce

You can extend the subscription manager in WebSphere Commerce to manage various subscription models, such as event-based or time-based. These subscription models vary from the time-based subscription model in the following two ways:

• The parameters, such as fulfillment frequency, time period and number of occurrences, which control the entitlement of a subscription. For example, in time-based subscriptions, the fulfillment schedule is defined by the subscription itself. However, in models such as event-based or time event-based subscriptions, the concept of fulfillment is replaced with usage, and hence the parameter has no affect on these subscription models.
• The actions that control the course of the subscription during its duration. For example, a system triggered action for fulfillment has no meaning in subscriptions where user actions trigger the usage of the subscription.

These two factors thus play a vital role in deciding what customizations are needed. Over the next two sections, the article broadly outlines the various factors that need to be considered for each of the subscription models.

Back to top

Modeling an event-based subscription model

Unlike the time-based subscription model, an event-based subscription model has no pre-defined fulfillment schedule. The fulfillment in this model occurs at the request of the user. In other words, the fulfillment depends on the usage of the subscription that is triggered by user actions. The number of times a subscription can be used is predefined by the vendor along with the duration over which the subscription is valid. The duration can be infinite. Since the fulfillment schedule is not pre-defined, the scheduled fulfillment action of the time-based subscription plays no role in an event-based subscription. However, the event-based subscription requires new user services to validate and trigger its usage.

When a customer purchases an event-based subscription, its lifecycle is outlined as follows:

1. The subscription is marked "inactive" until the payment for it has been authorized.
2. Once the subscription is "active", the customer is free to use the subscription during its duration (the duration can be infinite).
3. The usage of the subscription is triggered by a user action on the store. For example, in a ring tone subscription scenario, the usage of the subscription is recorded when the user chooses to download a ringtone from the store.
4. The subscription can be cancelled anytime within its duration. The cancellation may allow for any refund to be made based on the remaining usage.
5. Once the stated number of usages is completed, the subscription is marked "expired".
6. The customer has an option to "renew" a subscription either before or after the actual expiry.

   Figure 4 charts out the lifecycle of an event-based subscription.

   
   
   Figure 4. Lifecycle of an event-based subscription model
   
   
   

Case study: Scenario of an event-based subscription

You can extend the subscription manager in WebSphere Commerce to accommodate other subscription models. The article uses a sample scenario to demonstrate the extensions of the subscription manager to accommodate an event-based subscription.

The sample scenario models an event-based subscription that allows users to download a pre-defined number of ring tones from the store for a one-time payment made during the purchase of the subscription.

The following sections describe the use cases of the sample scenario.

Use Case 1: Customer purchases the event-based subscription from the store

The subscription attributes for a time-based subscription are different from those of an event-based subscription. An event-based subscription only relies on the attribute that the number of occurrences (or usages) allowed for the subscription. The duration is entirely optional while the fulfillment frequency is impertinent.

Though the overall order flow remains the same for both subscription types, intricate differences do exist primarily in terms of the attributes that are displayed on the store front for the subscription item, the attributes that are sent to the subscription manager for the subscription item, and the subsequent processing of the subscription item in the subscription manager.

Use Case 2: Customer browses through the ring tones

Store navigation for a customer broadly remains the same with the exception that the ring tones are modeled differently from the regular catalog entries. The ring tone catalog entries contain a new descriptive attribute called "softSKU" to distinguish them from regular catalog entries. This attribute is used on the store to optionally display the "Download" button instead of the traditional "Add to Cart" for these catalog entries.

Use Case 3: Customer chooses to download the ring tone

When a customer chooses to download the ring tone, the customer is requested to provide the subscription ID through which the download is being made. The subscription ID provided is then used to make the service request to the subscription manager to check the validity of the subscription and record the event of download. Based on the service response, the user is allowed to download the ring tone.

The following sections outline the implementation details of the use cases mentioned above.

Back to top

Implementation steps for the case study

You can deploy the code assets provided with the article. Once extracted to the local file system, the folder structure for the code assets is similar to the one shown in Figure 5.

The code asset contains the following folders:

1. Bootstrap: This folder contains the table definition SQLs to create the new tables, the command registry entries for the extended or newly created commands, and the access control policy for the new actions added.
2. CSV files: This folder contains the CSV files to create the new catalog entries and attribute relationships for the catalog entries.
3. Stores: Files under this folder are to be deployed in the store's Web application of WebSphere Commerce. The files here contain the changes required at the store front. The folder structure exactly mimics the folder structure under stores. The store assets are based on the Madisons store. For custom stores, you need to merge these files accordingly.
4. WC: Files under this folder are to be deployed in the EAR of WebSphere Commerce. The files under this represent the configurations for the subscription component.
5. WebSphereCommerceServerExtensionsLogic: This folder contains the entire source associated with the use case.

The following sections outline the steps for deployment while explaining the reason behind each of the steps.

Back to top

Creating the mobile ring tones catalog

In this step, the catalog entries which model the mobile ringtones and mobile ring tone subscriptions are loaded using the Catalog Upload option in CMC. Once loaded successfully, the ring tone subscriptions are available on the store front for purchase.

• Upload the CatalogEntries.csv file: This uploads the new catalog entries that represent the Ringtone Subscription catalog entry and a Downloadable Ringtone catalog entry.
• Upload the AttributeDictionaryAttributeAndAllowedValues.csv file: This uploads two new attributes:
  1. numOfFulfillments: This defining attribute is used on the ring tone subscription catalog entries to predefine the number of ring tones downloadable against a subscription.
  2. softSKU: This defining attribute is used to distinguish an intangible SKU from a physical SKU.
• Upload the CatalogEntryAttributeDictionaryAttributeRelationship.csv file: This associates the catalog entries and the attributes uploaded above.

The catalog entries created in the above steps require a mandatory step of inventory allocation to prevent back ordering. Refer to the Creating ad hoc inventory receipts topic in the Information Center for the performing inventory allocation for the ringtone subscription SKUs (in our case, the SKU is SUB_RINGTONE_02-01) using the adhoc inventory receipts.

Note: The downloadable ringtone requires no inventory allocation. Most often, a Digital Rights Management (DRM) system handles the licensing and sale of these items.

Back to top

Order component changes

When an order containing subscription items is received, the order component transfers the subscription items to the subscription manager for persistence.

The order component uses two task commands:

• CheckOrderAttributesCmdImpl, which checks and extracts the subscription attributes from a subscription item.

• ServiceProviderProcessSubscriptionCmdImpl, which builds the subscription request to invoke the subscription manager.

By default, it extracts the attributes pertaining to a time-based subscription item and invokes the subscription manager. Thus, it has to be customized to look for attributes specific to an event-based subscription.

The CMDREG entries for these two task commands are provided in the SQL file in the boot strap folder. The command registry entries are created at the store level. You can change this to support the functionality across the site.

The extended task commands are found under the com.mycompany.commerce.order.commands package in the WebSphereCommerceServerExtensionsLogic folder. The ExtCheckOrderAttributesCmdImpl additionally looks for the numOfFulfillments attribute in the subscription item. The ExtServiceProviderProcessSubscriptionCmdImplcommand is customized to additionally make use of the numOfFulfillments attribute to build the subscription request.

Refer to the provided code assets for the implementation of these classes.

Back to top

Subscription manager changes for OrderFlow

In this step, the creation process in the subscription manager is customized to handle an event-based subscription. An event-based subscription differs from a time-based subscription, primarily in two aspects:

• The lack of system triggered fulfillment cycles
• The lack of a predefined fulfillment frequency

The command responsible for handling the creation of subscriptions is:

com.ibm.commerce.subscription.facade.server.commands.
 ProcessSubscriptionCreateActionCmdImpl

This class is extended to bypass the validations for the fulfillment schedule, which is defunct in the case of event-based subscriptions.

The command registry entry for registering the extended class is provided in the boot strap SQL file:

com.mycompany.commerce.subscription.facade.server.commands.
 ExtProcessSubscriptionCreateActionCmdImpl

The following creates the first fulfillment schedule job for a subscription:

com.ibm.commerce.subscription.facade.server.dataaccess.bom.mediator.
 ChangeSubscriptionMediator

Therefore, the above class is customized to bypass this step.

The extended mediator is registered in the wc-business-object-mediator.xml file:

com.mycompany.commerce.subscription.facade.server.dataaccess.bom.mediator.
 ExtChangeSubscriptionMediator

This configuration is provided in the WC/xml/config/com.ibm.commerce.subscription-ext folder. This configuration is to be copied under the same path in the WC.ear file.

The default validator implementation needs to be overridden to handle the validations required for event-based subscriptions. The extended validator is registered in the wc-component.xml. This configuration is provided in the WC/xml/config/com.ibm.commerce.subscription-ext folder. This configuration is to be copied under the same path in the WC.ear file.

Note: Copying all subscription configuration files at this step causes the server to fail and must be copied at the end.

Back to top

Subscription manager changes for entitlement checks

The lack of a system-driven periodic fulfillment cycle in an event-based subscription implies that the usage of the subscription depends on the user's actions. These actions require a valid subscription ID, in which case the subscription manager is notified through a service call to record the usage of the subscription.

In our case study, the download action performed by the user notifies the subscription manager. The user provides a subscription ID for the download. The new service called "checkUsage" is exposed on the subscription manager, which can perform various actions, such as checking the validity of the subscription, checking the usage entitlement for the user and the ring tone being downloaded, logging this usage of the subscription, and so on.

For the purpose of the article, this service only records the usage. To record the usage, a new table is added to the subscription manager called XSUBSCREVNTLOG. The DDL to create the new tables is provided in the bootstrap folder in the asset.

The physical SDOs pertaining to the new table is provided in WebSphereCommerceServerExtensionsLogic. Its corresponding configurations are part of the WC/xml/config/com.ibm.commerce.subscription-ext folder.

The following new process action command is added:

 ExtProcessSubscriptionCheckUsageCmdImpl

This class creates an entry in the XSUBSCREVNTLOG to record the usage. It can be enhanced according to the business requirements for the subscription model.

The following extends ChangeSubscriptionBasePartMediator to save the XSUBSCREVNTLOG table entry:

com.mycompany.commerce.subscription.facade.server.dataaccess.bom.mediator.
 ExtChangeSubscriptionBasePartMediator

To facilitate the store front for invoking the "checkUsage" service, a utility method is added to the subscription client facade. The following class extends the SubscriptionFacadeClient to add a new method called checkUsage:

com.mycompany.commerce.subscription.facade.client.
ExtSubscriptionFacadeClient

Back to top

Store front changes

As outlined in the flow, the changes in the store component include providing an option to download SKUs (SKU with softSKU attribute set to true) against a subscription. The download action invokes a service, which performs an entitlement check to decide whether the SKU can be downloaded against the specified subscription. The changes are implemented as follows:

• Create a JavaScript file named EventBasedDownload.js, which declares a new service to redeem the downloadable SKU (for example, a ringtone) against a subscription. The new service, RedeemEventService, takes the catalog entry Identifier and Subscription Identifier as input.

  Path:

  <WCDE_INT70>\workspace\Stores\WebContent\Madisons\javascript\ EventBasedDownload.js

  
  
• Create a Struts entry for the new RedeemEventService. This service invokes the checkUsage function in ExtSubscriptionFacadeClient.

  Path:

  < WCDE_INT70>\workspace\Stores\WebContent\WEB-INF\ struts-config-subscription-services-ext.xml

  
  
• In the product details page, add a new "Download" button for the downloadable SKU:

  Path:

  <WCDE_INT70>\workspace\Stores\WebContent\Madisons\Snippets\Catalog\ CatalogEntryDisplay\CachedItemDisplay.jsp

  
  
  • Include EventBasedDownload.js at the beginning of the file:

    <script type="text/javascript" src="<c:out value="${jsAssetsDir}javascript/ EventBasedDownload.js"/>"></script>

    
    
  • Set the common parameters:

    dojo.addOnLoad(function() { EventBasedDownload.setCommonParameters('<c:out value='${WCParam.langId}'/>', '<c:out value='${WCParam.storeId}'/>','<c:out value='${WCParam.catalogId}'/>'); });

    
    
  • Declare a new variable isSoftSKU and initialize it to false:

    <c:set var="isSoftSKU" value="false"/>

    
    
  • Locate the following code snippet:

    <c:forEach var='definingAttrValue2' items='${itemWithAttr.catalogEntryAttributes.attributes}'>

    
    

    In the above mentioned <c:forEach> loop, add one more condition to check the value of the softSKU attribute.

    <c:if test="${definingAttrValue2.attributeIdentifier.externalIdentifier. identifier == 'softSKU'}"> <c:if test="${definingAttrValue2.value.value == '1'}"> <c:set var="isSoftSKU" value="true"/> </c:if> </c:if>

    
    

  • Locate the following <c:when> condition and update it to check for the isSoftSKU variable. This hides the "Add To Cart" button.

    <c:when test="${!isSubscription || (isSubscription && !isSoftSKU && fulfillmentFrequency != '' && paymentFrequency != '' && timePeriod != '') || alwaysShowAddToCart}" >

    
    
  • Update the corresponding <c:otherwise> shown in the listing below. This displays the "Download" button.

    <c:otherwise> <c:choose> <c:when test="${isSoftSKU}"> <label>Enter the subscription Identifier:</label> <input type="text" size="10" id="downloadSubId" value=""/> <div> <span class="primary_button" > <span class="button_container"> <span class="button_bg"> <span class="button_top"> <span class="button_bottom"> <a class="ajaxAddToCart" href="javascript:setCurrentId('download'); EventBasedDownload.redeemEvent (document.getElementById('downloadSubId').value, '<c:out value='${item.itemID}'/>')" id="download">Download</a><br /> </span> </span> </span></span></span></div></c:when> <c:otherwise> <p><fmt:message key="SKU_NOT_BUYABLE" bundle="${storeText}" /> </c:otherwise> </c:choose> </c:otherwise>

    
    

This article demonstrated the download capability by just creating a single SKU. If the product has multiple SKUs, then make the above changes in CachedProductOnlyDisplay.jsp.

The code assets provided in this article contains the required store front changes. You need to merge these changes into the custom store implementations based on the requirements.

Back to top

Conclusion

In this article, you learned about the various subscription models and its characteristics that define them. You also learned about the subscription capabilities provided in WebSphere Commerce and how to extend them to model other types of subscription, including a case study of a sample event-based subscription.

Acknowledgments

The authors would like to thank George Jacob from the IBM India Lab for his help in reviewing this article.

Back to top

Download

Information about download methods

Resources

Learn

• WebSphere Commerce V7 Information Center: Subscriptions
  
  
• WebSphere Commerce V7 Information Center
  
  
• developerWorks WebSphere Commerce zone
  
  

Discuss

• WebSphere Commerce discussion forum
  
  

About the authors

Pavan Kini is a Software Developer with IBM India Software Lab, Bangalore. He has 3 years of experience with WebSphere Commerce development. He has worked with Web 2.0 store models, service providers, and SEO solutions.

Siddharth C. Ravikanthrao is a Staff Software Engineer with IBM India Software Labs, Bangalore. He has 4 years of experience with WebSphere Commerce development. He has worked with the WebSphere Commerce Sales Center, Gift Center, Service provider, and SEO solutions.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Overview of subscriptions in WebSphere Commerce
• Supporting other forms of subscriptions in WebSphere Commerce
• Modeling an event-based subscription model
• Implementation steps for the case study
• Creating the mobile ring tones catalog
• Order component changes
• Subscription manager changes for OrderFlow
• Subscription manager changes for entitlement checks
• Store front changes
• Conclusion
• Download
• Resources
• About the authors
• Comments

Dig deeper into WebSphere on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers