16
Billing

Each section of this document presents a different topic. These sections include:

Section 16.1, "Overview"

Section 16.2, "Using the Billing Integration Framework"

Section 16.3, "BillingLoader Utility"

Section 16.4, "Billing Collector and Service Detail Record"

Section 16.5, "Billing Driver"

Section 16.6, "Billing Integration Scenario"

16.1 Overview

OracleAS Wireless Billing Integration Framework provides an extensible and flexible framework to model billable services, capture billable actions, and integrate with any billing engine.

Figure 16-1 Billing Framework Architecture

Text description of the illustration drm13.gif

16.1.1 Concepts

Billable Action--Customer actions which should be tracked, authorized and reported to the billing system. Typical examples are premium service access, mobile content download, alert subscription and message delivery.

Billing Context--A marker interface whose implementation object provides all the data related to a given billable action. OracleAS Wireless has the following objects predefined as Billing Context:

• For Multi-Channel service access: oracle.panama.rt.ServiceContext

• For J2ME application download: oracle.panama.model.UserDownloadStatus

• For mobile alert subscription: oracle.panama.mobilealert.ServiceAlertSubscription

• For messaging:
  • Sending: oracle.panama.messaging.transport.impl.SendingBillingContext

  • Receiving: oracle.panama.messaging.transport.impl.ReceivingBilling
Context

Service Detail Record (SDR)--A generic object that captures all the billing-specific attributes from the billing context for a given billable action. The attributes are of two types: mandatory and extended. Mandatory attributes are user information, service information and component information. Extended attributes contain the component-specific information.

Billing Collector--An extensible object that processes the BillingContext and generates the corresponding service detail record.

Billing Driver--A Java interface defined by OracleAS Wireless; it interacts with an external billing system to handle a given billable action. A billable action is usually handled in two steps:

• Before the action starts, the driver's preService API is called by the billing framework. For example: In a typical scenario in which usage authorization is based on user balance and credit, resource reservation, rating and fraud detection, the driver can instruct the billing framework to veto the user billable action request.

• After the action completes, the driver's postService API will be called by the billing framework which completes the billing transaction.

16.2 Using the Billing Integration Framework

16.2.1 Billable Actions and Billing System Interaction

16.2.1.1 Default Billable Actions

OracleAS Wireless defines the following billable actions:

• Multi-Channel service request--the model service is defined with the cost attribute set to a non-zero value:
  • calling driver's preService API right after service authorization and before service invocation. If the result code of the API call indicates failure, the request is rejected.

  • calling driver's postService API after the service request has been served and before any listener notification.

• J2ME application download:
  • calling driver's preService API right before the download request is generated by the provisioning server. If the result code of the API call indicates failure, the request is rejected.

  • calling driver's postService API after provisioning server has received notification from the installed device indicating successful installation and before any listener notification.

• Alert Subscription:
  • calling driver's preService API right before user subscribes to a mobile alert service. If the result code of the API call indicates failure, the request is rejected.

  • calling driver's postService API after the alert subscription has been created.

• Messaging:
  • Sending
    • calling driver's preService API before the message delivery request is accepted by the messaging framework. If the result code of the API call indicates failure, the request is rejected.

    • calling driver's postService API after the message delivery request is accepted by the messaging framework.

  • Receiving
    • calling driver's preService API before the message is routed to targeted registered application. If the result code of the API call indicates failure, the message is discard.

    • calling driver's postService API after the message has been routed to targeted registered application.

16.2.1.2 Custom Billable Actions

OracleAS Wireless billing integration framework allows users to introduce custom billable actions to meet their business needs. Following are the steps to introduce a new billable action:

• Identify the place where the new billable action should take place, for example, a runtime hook or a JSP.

• Define an object which provides access to all the data related to this new billable action. This object can be any Java class as long as it implements the marker interface BillingContext. You may also use the predefined BillingContext objects mentioned above if appropriate.

• Customize the Billing Collector object to handle your new BillingContext object by either extending the BillingCollectorImpl or defining your own implementation of the Billing Collector. Billing Collector's implementation is presented in greater detail in the next section.

  The Billing Collector class can be extended (subclassed) from the out-of-the-box collector implementation or created new. Once it is created, the implementation class is set in: EM > Wireless Server: Site Administration > Billing Framework > Billing Collector Class name.

Use the following code segment to trigger a new billable action for a preService call:

// Suppose your BillingContext Object is foo 
BillingController controller =  BillingController.getInstance(); 
if (controller.isBillingEnabled() ) 
 { 
       try { 
             BillingResult result = controller.preService(foo); 
            if ( result != null ){ 
               ServiceDetailRecord sdr = result.getServiceDetailRecord(); 
               if (result.getResultCode() != BillingResult.FAILED) { //Succeed 
                 // Add your logic here 
               } 
              else { // Failed 
                    // Add your logic here to handle preService failure 
                    //BillingException e = new BillingException(failure message); 
                    // e.setResult(result);
                    // throw e;

              } 
          } 
      } catch (BillingException be) { 
               //Handle Billing Execption here 
         } 

Use the following code segment to trigger a new billable action for postService call:

// Suppose your BillingContext Object is foo 
BillingController controller =  BillingController.getInstance(); 
if (controller.isBillingEnabled() ) 
 { 
       try { 
             BillingResult result = controller.postService(foo); 
            if ( result != null ){ 
               ServiceDetailRecord sdr = result.getServiceDetailRecord(); 
               if (result.getResultCode() != BillingResult.FAILED) { //Succeed 
                 // Add your logic here 
               } 
              else { // Failed 
                    // Add your logic here to handle postService failure 
              } 
          } 
      } catch (BillingException be) { 
               //Handle Billing Execption here
         } 

16.3 BillingLoader Utility

The BillingLoader Utility is a batch utility to download, purge and upload billing transaction records. For more information on BillingLoader Utility, see OracleAS Wireless Administrator's Guide.

16.4 Billing Collector and Service Detail Record

A billable operation for every component is split into 2 parts: a pre-event and post-event. An SDR is generated for both the pre- and post- events. The billing data collector class is used to create one SDR for each pre- or post- service call.

When the pre-service SDR is passed to the billing system, the billing system is expected to set a unique Billing Reference ID and return the SDR as part of the billing result.

The returned pre-service billing reference ID is extracted by OracleAS Wireless. It is set in the post service SDR of the same billable operation so that the external billing system can maintain state between the pre- and post- event of any single billable operation based on the billing reference ID.

Only the post service billing event SDR is logged to the database, unless the driver starts-up a transaction by setting the transaction ID attribute in the SDR which it returns after the pre-service. If the transaction ID is set, then the pre-service SDRs are also logged. You can identify the pre and post service SDRs based on the LOG_TYPE column which will be either PRE_SERVICE or POST_SERVICE.

The SDR ID is an internal ID used as a primary key in our tables. You can look up a particular SDR based on the SDR ID.

There is normally only one SDR ID for every post-service event, unless the driver starts up a transaction (in which case the pre-service SDR is logged).

16.4.1 Default Billing Collector Implementation

The BillingCollector implementation object is responsible for processing the BillingContext for a given billable action. It generates an appropriate Service Detail Record for the billing driver to process. OracleAS Wireless includes a default BillingCollector implementation named BillingCollectorImpl which handles the following BillingContext objects:

• For multi-channel service access: oracle.panama.rt.ServiceContext
  • Extended Attribute Name:
    • SERVICE_URL--the URL of the service invoked

    • SERVICE_TYPE--the type of the service, that is, Folder or Link (FOLD, LINK)

    • DEVICE_NAME--the device name

    • INVOKER--the Invoker for this runtime service. The list of values include HTTP, ASYNC, ALERT, PROVISIONING, AGENT. This attribute can be used by the driver to trace the root-invoker of this service. The Invoker attribute and the list of values are defined in the BillingDataCollector Interface.

    • ASK_IN_MSGID--this is set if the service is the INVOKER attribute value is ASYNC. The value denotes the Incoming message ID for the Async application. It can use used to relate the message request with the Async action.

• For J2ME application download: oracle.panama.model.UserDownloadStatusAPPLICATION_NAME
  • Extended Attribute Name:
    • CONTENT_NAME--the Application name

    • CONTENT_VERSION--the Content version

    • USER_DEVICE_NAME (if available)--the user device name

    • MIME_TYPE--the mime type downloaded

    • CURRENT_NUMBER_OF_DOWNLOADS--the number of previous downloads before the current download

    • CONTENT_SIZE--the size of the content

• For mobile alert subscription: oracle.panama.mobilealert.ServiceAlertSubscription
  • Extended Attribute Name:
    • OPERATION_TYPE--indicates if it is an Alert Message SDR or Alert Subscription SDR. The value for mobile alert is ALERT_SUBSCRIPTION

    • SERVICE_URL--URL for the invoked service. Alert Engine invokes a service to generate content, and this attribute is the URL for the service.

    • ALERT_DELIVERY_ADDR--the end-user address to which alerts will be delivered. A comma-separated list of possible addresses.

• For messaging:
  • Sending: oracle.panama.messaging.transport.impl.SendingBillingContext

  • Extended Attribute Name:
    • TYPE--indicates if the action a sending or receiving action. It is set to S for sending.

    • FROM--the from address (can be null).

    • TO--the destination address.

    • DELIVERY_TYPE--the delivery channel type.

    • SERVICE_NAME (Optional)--the client name (such as Push Server, Async Agent).

    • DRIVER_NAME--the driver name (for the sending case only).

    • REPLY_TO--the reply to address.

  • Receiving: oracle.panama.messaging.transport.impl.ReceivingBillingContext

  • Extended Attribute Name:

  • Extended Attribute Name:
    • TYPE--indicates if the action a sending or receiving action. It is set to R for receiving.

    • FROM--the from address (can be null).

    • TO--the destination address.

    • DELIVERY_TYPE--the delivery channel type.

    • SERVICE_NAME (Optional)--the client name (such as Push Server, Async Agent).

    • DRIVER_NAME--the driver name (for the sending case only).

    • REPLY_TO--the reply to address.

16.4.2 Service Detail Record ID Versus Billing Reference ID

Service Detail Record ID is defined by the Billing Collector. The default format is [Component Name: Random Key]. The Billing Reference ID is obtained from the billing system. In the pre-bill case, it is usually defined as the authorization ID.

16.4.3 Extend Default Billing Collector

OracleAS Wireless billing integration framework enables users to extend the default billing collector implementation for various reasons:

• To capture more data than the default implementation for a default BillingContext:

  public class MyBillingCollector extends 
  oracle.wireless.billing.BillingDataCollectorImpl 
  { 
     ... 
      public ServiceDetailRecord createServiceDetailRecord(BillingContext context) 
     { 
         ServiceDetailRecord sdr = null; 
          if (context instanceof oracle.panama.rt.ServiceContext ){ 
              sdr = super.createServiceDetailRecord(context); 
             if ( sdr != null){ 
               // Add your additional data capture logic here 
              // For example: 
             // oracle.panama.rt.ServiceContext serviceContext = 
  (oracle.panama.rt.ServiceContext)context; 
             // sdr.setExtendedData("SERVICE_PATHURL", 
  context.getService().getURLPathParameter()); 
           } 
         } 
         else{ 
            sdr = super.createServiceDetailRecord(context); 
        } 
        return sdr; 
     } 
    ... 
  }
  

• To capture data from a custom BillingContext:

  public class MyBillingCollector extends 
  oracle.wireless.billing.BillingDataCollectorImpl 
  { 
     ... 
      public ServiceDetailRecord createServiceDetailRecord(BillingContext context) 
     { 
         ServiceDetailRecord sdr = null; 
          if (context instanceof MyBillingContext ){ 
               // MyBillingContext mycontext = (MyBillingContext)context; 
              // get the user name from your context 
              // Java.sql.Timestamp accessTime = null; 
              // BillingManager manager = BillingManager.getInstance(); 
              //sdr = manager.createServiceDetailRecord(<User Name>, <Your service 
  Name>, accessTime, <your billing component name>); 
             // sdr.setExtendedData("MY_DATA", <Get data from your context 
  object>); 
             ... 
           } 
         } 
         else{ 
            sdr = super.createServiceDetailRecord(context); 
        } 
        return sdr; 
     } 
    ... 
  } 
    
  

To ignore a billable action base on the context data. Simply return a null object from the createServiceDetailRecord call based on your business logic.

Specify your extended Billing Collector using Oracle Enterprise Manager:

EM > Wireless Server: Site Administration > Billing Framework > Billing Collector Class name

16.4.4 Maintaining Transaction Context on Multi-part Requests

A typical wireless request spans multiple entities (a multi-part request). For example, an Async request may originate at the Messaging Server, forwarded to the Async Listener, which invokes a Runtime service and then returns the result back to the user through the Messaging Server. The Billing Rules may demand a billing at each stage of the transaction, but the pricing may vary depending on the context of the request. To support such a scenario, it is necessary to maintain the history of the request's path (available resources to the Billing Driver [or Data Collector]), where the Billing Rules are enforced.

16.4.4.1 Creating and Assigning Billing Transactions

The Billing Driver (or Data Collector) can assign a given Service Detail Record to be part of a transaction. For example, the pre-service call implementation of the Billing Driver can contain the following lines to add the SDR to a newly created transaction.

           BillingTransaction Trans = 
BillingTransactionManager.getInstance().createTransaction();
          Trans.getId(); // if its XYZ say       
           sdr.setTransaction(Trans);

This creates a new transaction and adds the Service Detail Record to it. The subsequent service detail records can be added to the same transaction by retaining the transaction ID. Here is the pseudo-code for subsequent Service Detail Records:

            BillingTransaction Trans = 
BillingTransactionManager.getInstance().lookupTransaction (XYZ);
          Trans.getId(); // if its XYZ say       
          Trans.addSdr(sdr); // OR sdr.setTransaction(Trans);

The past Service Detail Records for this transaction can be looked-up using the BillingTransaction public APIs (see BillingTransaction's getServiceDetailRecords()).

16.4.4.2 Logging Rules for Service Detail Records

A Service Detail Record, which is part of a transaction, is implicitly logged to the database as soon as the call BillingResult is returned from the BillingDriver implementation. The BillingController inspects the Service Detail Record and does this automatically.

The SDR's part of this transaction is available for lookup (see BillingTransaction's getServiceDetailRecords()). If the SDR is not part of a transaction, then its logging is deferred to the logging framework, to be accomplished in the background.

16.4.4.3 Maintaining Transaction State in a Single-Thread Multi-part Request

If all subsequent requests of a multi-part request are done in the context of the same Java Thread, the transaction information can be stored in the Thread as a Thread Local object and referenced later for a subsequent request. The Default implementation of the BillingDataCollector (oracle.wirless.billing.BillingDataCollectorImpl) provides just that. The transaction APIs for setting and getting are available through the BillingController object.

  /**
   * Returns the current billing transaction
   * @return BillingTransaction the current billing transaction
   */
public BillingTransaction getCurrentTransaction();

/** Sets the transaction for the current transaction
 * @param transaction the current transaction
 */
public void setCurrentTransaction(BillingTransaction transaction);

16.5 Billing Driver

To integrate OracleAS Wireless billing integration with an external billing system, the system integrator must provide a Java implementation class which implements the BillingDriver interface. To set your driver:

EM > Wireless Server: Site Administration > Billing Framework > Billing Driver Provider (Driver Class Name)

The desired behavior of the Billing Driver implementation is as follows:

• init--this API must contain logic to connect to an external billing system.

• preService--this API must contain logic to handle one or all of the following billing operations:
  • Authorization

  • Rating

  • Resource Reservation

  • Fraud Detection

  • Others

• postService--this API must contain logic to complete a billing transaction.

• cancelService--this API must contain logic to cancel a billing transaction.

• destroy--this API must contain logic to disconnect from a billing system.

  Note: In this release, integration with only one billing system at a time is supported. However, the driver implementor can use a proxy which interfaces with different billing systems as needed.

16.6 Billing Integration Scenario

16.6.1 Handling Prebilling

Here is an implementation example of handling prebilling:

• Define the billable actions using either default or custom actions.

• Use the driver's preService call to do billing authorization and/or resource reservation, return an authorization ID generated by the billing system.

• Use the driver's postService call to complete the billing transaction by passing the authorization obtained from the preService call.

16.6.2 Handling Postbilling

Here is an implementation example of handling postbilling:

• Define the billable actions using either default or custom actions.

• Use the driver's preService call to do billing authorization and/or rating/fraud detection.

• Use the driver's postService call to submit billing-related data to the billing system.