You do not need to change your billing implementation to use Content Delivery Server. You can configure Content Delivery Server to work with your current billing system through the use of billing adapters.
A billing adapter for postpaid or asynchronous billing converts the information provided by Content Delivery Server to the format needed by your billing system. Content Delivery Server posts billing events to a JMS queue. You can receive these billing events using a JMS client. The JMS client uses the billing adapter to format the information for your billing system.
A billing adapter for prepaid or synchronous billing is called by Content Delivery Server as the purchase is being processed. The adapter can dynamically change the price of content, if desired, validate the purchase in real time, or manage billing through an external system such as premium SMS.
You can create your own postpaid billing adapter using the Event Service API if the adapter provided does not meet your needs. You can create your own prepaid billing adapter using the Billing API. See the Sun Java System Content Delivery Server Customization Guide for information on these APIs.
This chapter includes the following topics:
2.1 Billing Adapters Provided
For postpaid billing, Content Delivery Server provides the Postpaid Service. This service includes a JMS client that processes the billing events in the event queue and generates a file that contains the information that your billing system can use to charge subscribers. The file format can be XML, comma-separated values (CSV), or name-value pairs. See Section 2.2, Working with the Postpaid Service.
No prepaid billing adapters are provided.
2.2 Working with the Postpaid Service
The Postpaid Service supports billing systems that charge subscribers after content has been purchased. You can use the Postpaid Service instead of a customized billing adapter if your billing system supports postpaid billing and processes records in one of the following formats:
2.2.1 Configure the Postpaid Service
To have Content Delivery Server support the postpaid billing model, configure the Postpaid Service. The handler used is the PostpaidDefaultHandler. To configure the Postpaid Service, follow these steps:
1. Open the $CDS_HOME/deployment/deployment-name/conf/PostpaidService.properties file for edit.
Set the following properties:
- postpaid.handler.PostpaidDefaultHandler.events. Specify the billing events that you want the handler to process. See the comments in the file for a list of valid events.
- postpaid.handler.PostpaidDefaultHandler.billingevent.process_free_downloads. Set to true to process events for free content. Set to false if you do not want to process events for free content.
- postpaid.handler.PostpaidDefaultHandler.billingevent.process_prepay_events. Set to true to process events for prepaid content. Set to false if you do not want to process events for prepaid content.
- postpaid.handler.PostpaidDefaultHandler.output.header. To add a header to the top of the output file, see the comments in the file for information on setting this property.
2. (Optional) Set up archive files for the billing records as desired:
- To prevent the generation of archive files and instead add billing records to a single file that grows until the service is stopped, set the following properties as shown:
postpaid.handler.PostpaidDefaultHandler.output.refresh.frequency=
postpaid.handler.PostpaidDefaultHandler.output.refresh.size=0
|
- To create an archive file whenever a specific number of records are written, set postpaid.handler.PostpaidDefaultHandler.output.refresh.size to the number of records.
- To create an archive file on a recurring basis, set the postpaid.handler.PostpaidDefaultHandler.output.refresh.frequency property to one of the following values:
- daily. A new file is generated every day at the time the Postpaid Service started. For example, if the service started at 02:07:00, a new file is generated each day at 02:07:00.
- weekly. A new file is generated on the same day of each week at the time that the Postpaid Service started. For example, if the service started on a Thursday at 22:30:57, a new file is generated every Thursday at 22:30:57.
- monthly. A new file is generated on the same date each month at the time that the Postpaid Service started. For example, if the service started on March 14 at 21:23:34, a new file is generated on the 14th of each month at 21:23:34.
- yearly. A new file is generated on the same date each year at the time the Postpaid Service started. For example, if the service started on January 6 at 04:10:05, a new file is generated every January 6th at 04:10:05.
| Note - Stopping and restarting the Postpaid Service, restarts the period for which files are written. For example, if the frequency is set to weekly and the Postpaid Service is initially started on a Monday and then restarted on Thursday, the next file is written on the next Thursday, not on the next Monday.
|
3. (Optional) Set the following properties to recover past billing records:
- postpaid.handler.PostpaidDefaultHandler.recovery.enabled. Set this property to true to enable the recovery of past billing records. Set to false if you do not want past billing records recovered.
- postpaid.handler.PostpaidDefaultHandler.recovery.starting.point. Set this property to the timestamp for the beginning of the period for which you want to recover records. The value must be specified in the format mm-dd-yyyy hh:mm:ss, for example, 01-01-2004 00:00:01.
- postpaid.handler.PostpaidDefaultHandler.recovery.stopping.point. Set this property to the timestamp for the end of the period for which you want to recover records. The value must be specified in the format mm-dd-yyyy hh:mm:ss, for example, 01-01-2004 23:59:59.
- postpaid.handler.PostpaidDefaultHandler.recovery.file.suffix. Set this property to the string appended to the recovery file that is created. The default is .recover.
If recovery is enabled, the next time the Postpaid Service is started, billing records for the period specified are written to the $CDS_HOME/deployment/deployment-name/conf/Postpaid.recover file. When the recovery process completes, the file is renamed to Postpaid.recover.timestamp.
4. To control the creation of the billing records file, set the postpaid.handler.PostpaidDefaultHandler.output.refresh.empty_file property.
The billing records file is generated at the following times:
- The end of each period
- When the Postpaid Service is restarted
- When events are recovered
Set the property to true to generate a file whether or not billing records exist. Set the property to false to generate a file only if billing records exist.
The default if the property is missing is true. If the property is set to something other than true or false, false is assumed.
5. To define the records that you want generated, set the postpaid.handler.PostpaidDefaultHandler.output.template.file property to the fully qualified name of the file that defines the records.
Use one of the following values:
- deployment/deployment-name/conf/resources/default_record.xsl. Use this file with PostpaidDefaultHandler to generate name-value records.
- deployment/deployment-name/conf/resources/xml_record.xsl. Use this file with PostpaidDefaultHandler to generate XML records.
- deployment/deployment-name/conf/resources/csv_record.xsl. Use this file with PostpaidCSVHandler to generate CSV records.
6. Save your changes to the PostpaidService.properties file.
2.2.2 Billing Event Parameters
The following table shows the information provided for each billing event:
TABLE 2-1 Billing Event Parameters
|
Parameters
|
Description
|
|
billing-ticket
|
Billing ticket for this transaction.
|
|
campaign_coupon
|
Coupon code for a campaign.
|
|
campaign_id
|
String that identifies the campaign.
|
|
catalog-res-id
|
String that identifies the content edition.
|
|
content_binary_mimetype
|
MIME type of the content.
|
|
content_class_id
|
String that identifies the content item.
|
|
content_description
|
Long description of the content.
|
|
content_drm_type_id
|
String that identifies the DRM method used to protect the content.
|
|
content_short_description
|
Short description of the content.
|
|
content-id
|
String that identifies the content that was purchased. This value is the same as catalog-res-id.
|
|
content_name
|
Name of the content.
|
|
current-status
|
Current status of this transaction.
|
|
date
|
Date on which the transaction occurred.
|
|
destination-address
|
Address to which content is sent, for example, the MSISDN of the subscriber who requested content.
|
|
developer-content-id
|
Unique identifier used by the developer to identify the content.
|
|
developer-id
|
String that identifies the developer of the content.
|
|
developer_name
|
Name of the developer who submitted the content.
|
|
download-confirm
|
Flag that indicates whether a confirmation is required after a successful download.
|
|
download-count
|
Number of times the content can be downloaded for the price paid.
|
|
download-current-count
|
Number of times the subscriber has downloaded this content, including this time.
|
|
download-expiration
|
Flag that indicates whether the download period has expired.
|
|
download-period
|
Time period during which the content can be downloaded without additional charge to the subscriber.
|
|
download-price
|
Price of the content purchased.
|
|
download-purchase
|
Flag that indicates this is a purchase request.
|
|
download-recurring
|
Flag that indicates whether the subscriber is charged for each download.
|
|
event-log
|
Name of the event log.
|
|
event-msg
|
Message issued with the event.
|
|
event-source-type-id
|
Number that identifies the source of the event.
|
|
event-type
|
Numeric representation of the event that occurred.
|
|
event-type-id
|
String that identifies the type of event that occurred.
|
|
external_content_id
|
String that identifies the content to the billing system.
|
|
external_group_id
|
String that identifies the group to which the content belongs.
|
|
external-request-text
|
Text of the request from the subscriber, for example, the MO push request content.
|
|
gift_message
|
Message included with the gift.
|
|
gifted_current_downloads
|
Number of times the recipient downloaded this gift, including this time.
|
|
gifted_current_subscriptions
|
Number of subscription periods used by the recipient, including this period.
|
|
gift_download_date
|
Date that the gift was first downloaded by the recipient.
|
|
gift_expiration_date
|
Date by which the gift must be claimed by the recipient.
|
|
gift_purchase_date
|
Date the gift was purchased by the giver.
|
|
gifted_downloads
|
Number of downloads included in the gift.
|
|
gifted_subscriptions
|
Number of subscription periods included in the gift.
|
|
is_on_device
|
Flag that indicates whether the content is already on the device.
|
|
is-prepay
|
Flag that indicates whether the subscriber prepaid for the content.
|
|
limited-time-end
|
End date until which the content can be used.
|
|
limited-time-price
|
Price to use the content for a specified time period.
|
|
limited-time-start
|
Start date from which the content can be used.
|
|
locale
|
Subscriber’s locale.
|
|
msisdn
|
MSISDN for the subscriber device.
|
|
pricingoption_key
|
String that identifies the pricing option.
|
|
pricingoption_name
|
Name of the pricing option.
|
|
push-msgtext
|
Message sent to the subscriber’s device or email.
|
|
recipient_locale_code
|
Locale of the intended recipient of the content.
|
|
recipient_login_id
|
Login ID of the intended recipient of the content.
|
|
recipient_mobile_id
|
Mobile ID of the intended recipient of the content.
|
|
recipient_unique_device_id
|
Unique device ID of the intended recipient.
|
|
server-id
|
String that identifies the Vending Manager.
|
|
session-id
|
String that identifies the subscriber’s session.
|
|
source-address
|
Address of the external entity from which the message was received, for example the MSISDN of the SMSC.
|
|
subscription-expiration
|
Date that the subscription period ends.
|
|
subscription-frequency
|
How often the subscription price is charged.
|
|
subscription-recurring
|
Flag that indicates whether to automatically charge the subscriber for the next period when the current subscription period ends.
|
|
subscription-price
|
Price of the subscription period.
|
|
timestamp
|
Time at which the transaction occurred.
|
|
unique-device-id
|
String that uniquely identifies the device used.
|
|
usage-count
|
Number of uses allowed for the price specified for usage-price.
|
|
usage-price
|
Price charged for the number of uses specified for usage-count.
|
|
user-id
|
String that identifies the user who initiated the transaction.
|
|
username
|
Login name for the subscriber.
|
|
vending-res-id
|
String by which the Vending Manager identifies the content.
|
2.3 Configuring External Content and Group IDs
If your billing system requires something other than Content Delivery Server content identifier to identify content, follow these steps to configure external content and group IDS for your system:
1. In the CDS.properties file, set the common.external_content_id.enable property to true.
This file is in the $CDS_HOME/deployment/deployment-name/conf directory. When this property is true, the administrator is prompted when stocking content to provide the content ID and group ID known to the billing system.
2. Open the external_content_id_selection.xml file for edit.
This file is in the $CDS_HOME/deployment/deployment-name/conf/resources directory.
3. Add an entry element for each known content ID under the content_id element, for example:
<content_id>
<entry default=”true”>ID-1A</entry>
<entry>ID-1B</entry>
<entry>ID-1C</entry>
</content_id>
|
This list is provided to the administrator when external content IDs are assigned to content. For content that is auto-stocked, the external content ID is set to the value of the entry element that contains the attribute default=”true”.
4. Add an entry element for each known group ID under the group_id element, for example:
<group_id>
<entry>Games</entry>
<entry>Pictures</entry>
</group_id>
|
This list is provided to the administrator when group IDs are assigned to content.
5. Save your changes to the external_content_id_selection.xml file.
| Sun Java System Content Delivery Server Integration and Configuration Guide
|
820-1944-10
|
   
|
Copyright © 2008, Sun Microsystems, Inc. All Rights Reserved.