Sun Java System Content Delivery Server Installation Guide

After you deploy the Content Delivery Server, set up the features that you want to support. Make sure that all the Content Delivery Server components that you need are successfully deployed before continuing (see Chapter 3.)

This section presents the following topics:

• Configure the Content Delivery Server Services
• Configure the SMS Push Message
• Configure Support for MMS
• Configure the Interface Components
• Configure the Content Delivery Server for a Firewall
• Configure Pricing
• Configure Digital Rights Management
• Configure Submission Verifier Workflows
• Configure Customized Marketing Campaigns
• Configure Subscriber Account Management
• Configure Support for Externally Hosted Content
• Configure Support for Customized Reports
• Set up Support for iAppli Applications
• Set up Notifications to Developers
• Set up the Default Option for Subscriber Notifications
• Configure Support for PAR Files
• Control Access by External Systems
• Configure Alias Forwarding

---

4.1 Configure the Content Delivery Server Services

The Content Delivery Server services require information on your configuration and environment to operate properly. You provide this information by setting properties in the property files that each service uses. Set these properties on the host to which the service was deployed.

4.1.1 Configure the Messaging Service

The Messaging Service is used for push messages in the SMS or WAP formats and for email messages in the simple mail transfer protocol (SMTP) format. The Messaging Service is also used for messages in the MMS format.

The procedures for supporting push messages and email are described in the following sections. For information on setting up support for MMS, see Section 4.3, Configure Support for MMS.

See the Sun Java System Content Delivery Server Integration Guide for additional information on configuring your system to support push delivery.

4.1.1.1 Configure the Messaging Service for WAP Push

To configure the Messaging Service for WAP Push support, follow these steps:

1. Open the MsgService.properties file.

This file is in the $CDS_HOME/deployment/deployment-name/conf directory.

2. Set the WAP and PPG properties as needed for your environment, for example:

#WAP and PPG properties

asyncmsg.wap.ppg=

asyncmsg.wap.id=CDS

asyncmsg.wap.ip.bearer=

asyncmsg.wap.priority=high 

asyncmsg.wap.bearer_type=SMS 

asyncmsg.wap.bearer_required=false 

asyncmsg.wap.delivery_method=unconfirmed

asyncmsg.wap.network_type=GSM

asyncmsg.wap.netwok_required=true

4.1.1.2 Configure the Messaging Service for SMS

The Content Delivery Server supports the following SMS push protocols: Short Message Peer-to-Peer (SMPP), SMS HTTP, and CIMD2. Configure the Messaging Service for the protocol that you use.

Set up Support for SMPP

1. Open the MsgService.properties file.

This file is in the $CDS_HOME/deployment/deployment-name/conf directory.

2. Set the SMS properties as needed for your environment.

The following code shows the properties for a sample SMPP Push adapter.

smsc.hostname = 127.0.0.1

smsc.port = 11111

esme.system_id=user1

esme.password = usrpw

esme.system_type =

esme.destination=

smsc.gsm.ton = 2

smsc.gsm.npi = 0

3. Set the push sender properties as needed for your environment.

The following code shows the properties for a sample SMPP Push adapter.

pushsender.send.keep_alive=true

pushsender.keep_alive.milliseconds=30000

4. (Optional) Set the properties used to categorize the outgoing message from the server.

The SMSC can use these properties for billing or for other purposes. If a value is not set for a service type, the value of the default.service_type property is used.

subscriber_detail_url.service_type=

mobile_originated_detail_url.service_type=

gifting_detail_url.service_type=

content_sharing_detail_ur.service_type=

password_reminder.service_type=

campaign_message.service_type=

default.service_type= 

Set up Support for CIMD2

1. Open the MsgService.properties file.

This file is in the $CDS_HOME/deployment/deployment-name/conf directory.

2. Set the SMS properties as needed for your environment.

The following code shows the properties for a sample CIMD2 Push adapter.

smsc.hostname = 127.0.0.1

smsc.port = 11111

esme.system_id=user1

esme.password = usrpw

Set up Support for SMS HTTP

1. Open the MsgService.properties file.

This file is in the $CDS_HOME/deployment/deployment-name/conf directory.

2. Set the SMS properties as needed for your environment.

The following code shows the properties for a sample SMS HTTP Push adapter.

# SMS HTTP properties

cds.sms.http.serverurl=

cds.sms.http.user=

cds.sms.http.password=

cds.sms.http.from=CDS

The following properties specify the names of the HTTP parameters to be passed in the SMS message.

cds.sms.attribname.userid

cds.sms.attribname.password

cds.sms.attribname.from

cds.sms.attribname.msg

cds.sms.attribname.to

For example, if the SMSC uses the HTTP parameter smsfrom to identify where the message is from, set cds.sms.attribname.from to smsfrom. The values must not be null or blank.

4.1.1.3 Configure the Messaging Service for MO Push

To handle MO push messages from subscribers, configure the Messaging Service as described in the following sections. Two SMS push protocols are supported: SMPP and CIMD2. Messages directly from the SMSC in HTTP format are also supported.

Messages must be in the following form:

[shared-keyword] [device-prefix | campaign-prefix] bundle-ID | content-ID | keyword | campaign-coupon

TABLE 4-1 describes the parameters. Instructions for setting these properties are provided after the table.

Set the following properties in the SubscriberPortal.properties file, found in the $CDS_HOME/deployment/deployment-name/conf directory:

• mopush.use.shared_keyword - Shared keyword assigned by the SMSC. The default is blank.
• mopush.destination - Short code or MSISDN to which messages are sent by the subscriber.
• mopush.allow_web_requests - Flag that indicates if instructions for requesting content are shown to unregistered users when using the PC-based Subscriber Portal. The default is true.
• mopush.campaign.prefix - Prefix used to identify a request for a campaign. The default is c.
• mopush.nsm.device_prefix - Prefix used to identify a device that uses the Nokia Smart Messaging (NSM) protocol to download content. The default is n.
• mopush.nsm.user_agent - User agent used with NSM. This property must be set before subscribers are given access to the system. There is no default.
• mopush.ems.device_prefix - Prefix used to identify a device that uses the Enhanced Messaging Service (EMS) protocol to download content. The default is e.
• mopush.ems.user_agent - User agent used with EMS. This property must be set before subscribers are given access to the system. There is no default.
• mopush.wap.device_prefix - Prefix used to identify a device that uses the OTA protocol to download content. The default is w.
• mopush.wap.user_agent - User agent used with WAP. This property must be set before subscribers are given access to the system. There is no default.
• mopush.accept.external.sms - Flag that indicates if messages from any SMSC are accepted. Set to true to accept messages from any SMSC. Set to false to accept messages only from the SMSC specified in the mopush.accept.moblieid property.
• mopush.accept.mobileid - Phone number for the SMSC from which you want to accept messages. This number is used only if the mopush.accept.external.sms property is set to false.

Set the mopush.bundle_content.prefix property in the CDS.properties file, found in the $CDS_HOME/deployment/deployment-name/conf directory. This property defines the prefix used in a bundle ID. The default is b.

Set up Support for SMPP and CIMD2

1. Set the pushlistener.enable property in the MsgService.properties file to true.

This file is in the $CDS_HOME/deployment/deployment-name/conf directory.

2. Save your change.

3. Set the properties in the PushListener.properties file for the connections that you want to support.

By default, a single connection is used to support all types of MO push requests. Set the pushlistener.esme.system_id.all and pushlistener.esme.password.all properties to the values required by your system.

cds_mopush_action=all

pushlistener.esme.system_id.all =

pushlistener.esme.password.all =

pushlistener.cds_mopush_url.all = mo_push.do

You can configure the Messaging Service to support more than one connection to the SMSC. The connection that is used depends on the type of data requested. The following types of data are defined:

• Regular content. Content that is delivered through the standard purchase process.
• Campaign. Campaign information requested by the subscriber.

To support a separate connection for regular content, set the following properties and uncomment the lines by removing the pound sign (#) at the beginning:

pushlistener.esme.system_id.regular_content =

pushlistener.esme.password.regular_content =

To support a separate connection for campaigns, set the following properties and uncomment the lines by removing the pound sign (#) at the beginning:

pushlistener.esme.system_id.campaign =

pushlistener.esme.password.campaign =

4. Set the connection properties in the PushListener.properties file as needed for your environment.

This file is in the $CDS_HOME/deployment/deployment-name/conf directory. These properties are used for all connections. The following code shows sample settings for SMPP.

pushlistener.smsc.hostname = 127.0.0.1

pushlistener.smsc.port = 11111

pushlistener.esme.system_id.all = user1

pushlistener.esme.password.all = usrpw

pushlistener.esme.system_type=

pushlistener.esme.destination=

pushlistener.smsc.gsm.ton = 2

pushlistener.smsc.gsm.npi = 0

pushlistener.send.keep_alive=true

pushlistener.keep_alive.milliseconds=30000

The following code shows sample settings for CIMD2.

pushlistener.smsc.hostname = 127.0.0.1

pushlistener.smsc.port = 11111

pushlistener.esme.system_id.all = user1

pushlistener.esme.password.all = usrpw

Set up Support for HTTP

1. Set the pushlistener.enable property in the MsgService.properties file to false.

This file is in the $CDS_HOME/deployment/deployment-name/conf directory.

2. Save your change.

3. Register the following URL with your SMSC:

http://server:port/mo_push.do

server is the name of the server on which the Subscriber Portal is deployed. port is the port number on which the Subscriber Portal listens for MO push messages. The values specified must be accessible by systems outside the network on which the Content Delivery Server is running.

4.1.1.4 Configure the Messaging Service for Confirmation Messages

To handle User Datagram Protocol (UDP) confirmation messages from a device after a successful one-step download of content, follow these steps:

1. Edit the MsgService.properties file.

This file is in the $CDS_HOME/deployment/deployment-name/conf directory.

2. Set the confirmlistener.enable property to true.

3. Save your change.

4. Edit the ConfirmListener.properties file.

This file is in the $CDS_HOME/deployment/deployment-name/conf directory.

5. Set the udp.confirm_listener.port property to the port number that the device sends confirmation messages to, for example:

udp.confirm_listener.port=2000

This port number is specified by the device manufacturer and wireless carrier. The default is 2003.

See the Sun Java System Content Delivery Server Integration Guide for information on handling MMS confirmation messages.

4.1.1.5 Configure the Mail Service

Campaigns sent as email use the SMTP mail service defined for the Messaging Service. The mail service is initially configured when the Messaging Service is deployed based on properties for the Messaging Service that you set in the deployment configuration file.

To change the mail service used, modify the following properties in the $CDS_HOME/deployment/deployment-name/conf/MsgService.properties file:

• mail.smtp.host. Set this property to the name of the mail server that you want to use. The mail server must be capable of accepting unauthenticated email messages.
• mail.smtp.sender. Set this property to the reply-to address for email messages.

After you change the properties, restart the Messaging Service through the application server.

4.1.1.6 Configure Storage of Response Messages

For messages sent that contain binary content, the Content Delivery Server receives responses from the SMSC or MMSC. To indicate the types of response messages to save in the Content Delivery Server database, set the store.message_response.push_types property in the MsgService.properties file. The default is sms,mms to store responses from both SMS and MMS messages. This file is in the $CDS_HOME/deployment/deployment-name/conf directory.

4.1.2 Configure the Postpaid Service

If you want the Content Delivery Server to support the postpaid billing model, you need to configure the Postpaid Service. To configure the Postpaid Service, follow these steps:

1. Open the PostpaidService.properties file for edit.

This file is in the $CDS_HOME/deployment/deployment-name/conf directory.

2. Set Billing Event properties to specify the billing events that you want to process.

Set the events that you want to process to true. Set the events that you do not want to process to false. To process billing events for free trials, set postpaid.billingevent.process_free_downloads to true.

The following code shows sample settings for the Billing Events.

postpaid.billingevent.type.download_initiated=false

postpaid.billingevent.type.download_install_notified=true

postpaid.billingevent.type.download_error=true

postpaid.billingevent.type.content_purchased=true

postpaid.billingevent.type.content_refunded=true

postpaid.billingevent.type.subscription_purchased=true

postpaid.billingevent.type.subscription_cancelled=true

postpaid.billingevent.type.usage_purchased=true

postpaid.billingevent.type.gift_purchased=true

postpaid.billingevent.type.gift_download_initiated=true

postpaid.billingevent.type.gift_download_confirm=true

postpaid.billingevent.type.gift_download_error=true

postpaid.billingevent.type.gift_expired=true

postpaid.billingevent.type.gift_cancelled=true

postpaid.billingevent.type.gift_subscription_purchased=true

postpaid.billingevent.type.gift_usage_purchased=true

postpaid.billingevent.type.gift_refunded=true

postpaid.billingevent.process_free_downloads=false

3. (Optional) Set the following properties as shown, to prevent the generation of archive files for the billing records,:

postpaid.output.refresh.frequency=

postpaid.output.refresh.size=0

With these settings, billing records are added to a single file that grows until the service is stopped.

To create an archive file whenever a specific number of records are written, set postpaid.output.refresh.size to the number of records. To create an archive file every day, set postpaid.output.refresh.frequency to daily. The following values are valid for the postpaid.output.refresh.frequency property:

• 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.

4. (Optional) Set the following properties to recover past billing records, if desired:

• postpaid.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.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.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.

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.

5. To control the creation of the billing records file, set the postpaid.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.

6. Save your changes to the PostpaidService.properties file.

7. (Optional) Define external identifiers for content, if needed.

If your billing system requires something other than the Content Delivery Server content identifier to identify content, follow these steps:

a. 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.

b. Open the external_content_id_selection.xml file for edit.

This file is in the $CDS_HOME/deployment/deployment-name/conf/resources directory.

c. 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".

d. 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.

e. Save your changes to the external_content_id_selection.xml file.

4.1.3 Configure the Monitoring Service

To integrate the Application Monitoring Agent with your network monitoring system, you need to configure the Monitoring Service. Configure the Monitoring Service to issue only the alarms in which you are interested and disable all other alarms. The statuses and alarms issued by the Monitoring Agent are described in Section 1.1, "Application Monitoring Agent," in the Sun Java System Content Delivery Server System Management Guide.

To configure the Monitoring Service, edit the CDSSnmp.properties file in the $CDS_HOME/deployment/deployment-name/conf directory. The following table describes the properties.

4.1.4 Configure the Event Service

The Event Service generates events based on the properties set in the $CDS_HOME/deployment/deployment-name/conf/EventService.properties file. If the consumer of the event is not running, JMS maintains the events until the consumer of the event is started. Over time, this might result in an out-of-memory error.

The campaign event handler produces events that are consumed by the Notify Service. The billable event handler publishes messages to a topic for the Postpaid Service, which creates a durable topic listener client the first time it runs. If you do not plan to run the Notify Service or the Postpaid Service as part of your Content Delivery Server system, you can avoid the accumulation of messages by configuring the Event Service so the messages are not generated.

When the Notify Service is not running, stop the generation of campaign notifications by commenting out the following statements in the $CDS_HOME/deployment/deployment-name/conf/EventService.properties file. To comment out a property, add a pound sign (#) to the beginning of the line.

#eventservice.handler=Campaign

#eventservice.handler.Campaign.classname=com.sun.content.server.eventservice.server.handler.CampaignEventHandler 

#eventservice.handler.Campaign.events=subscriber_registered|content_purchased|content_refunded|download_install_notified 

When the Postpaid Service is not running, stop the generation of billable events by commenting out the following statements in the $CDS_HOME/deployment/deployment-name/conf/EventService.properties file. To comment out a property, add a pound sign (#) to the beginning of the line.

#eventservice.handler.Billing

#eventservice.handler.Billing.classname=com.sun.content.server.eventservice.server.handler.CDSBillableEventHandler 

#eventservice.handler.billable_event.events=* 

---

4.2 Configure the SMS Push Message

The default SMS push message contains a message from the Content Delivery Server and the URL for the content to be downloaded, for example:

Download: Application Name

http://servername:port/subscriber/main/ddd?subid=101&riid=115

If the length of the message sent causes a problem, you can limit this message to just the message from the Content Delivery Server or just the URL. Edit the template sms_push_msg_templete.xsl found in the $CDS_HOME/deployment/deployment-name/conf directory.

The following code shows a sample template.

1. <?xml version="1.0" ?> 

2. <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"

3. version="1.0">

4. <xsl:output method="text" indent="yes" /> 

5. <xsl:template match="/">

6. <xsl:value-of select="/SMSMessage/MESSAGE" /> 

7. <xsl:value-of select="/CDSSMSMessage/HREF" /> 

8. </xsl:template>

9. </xsl:stylesheet>

To limit the message to just the message from the Content Delivery Server, remove line 7. To limit the message to just the URL, remove line 6.

---

4.3 Configure Support for MMS

To have the Content Delivery Server deliver content by MMS, you must configure the MMS messaging properties in the VSAdminConsole.properties, SubscriberPortal.properties, and MsgService.properties files. The Multimedia Message Service Center (MMSC) processes the MMS message based on the values that you enter for the properties. The MMS messaging properties and their values are described in TABLE 4-3.

1. Edit the VSAdminConsole.properties and the SubscriberPortal.properties files.

These files are in the $CDS_HOME/deployment/deployment-name/conf directory.

2. Set the following MMS messaging properties in each of the two files. The values must match in each file.

The following code shows sample settings for MMS support.

mms_smil.template.filename=mms_smil_template.xsl

mms.message.class=AUTO

mms.message.priority=NORMAL

mms.message.sender.visibility=SHOW

mms.message.read_report_required=true

mms.message.delivery_report_required=true

admin.mms.from.address=address@host.com

3. Set the following additional property in the SubscriberPortal.properties file, for example:

mms.fallback.pushtype=sms

Note that the service that you specify must also be configured for the Content Delivery Server. For more information on configuring SMS or WAP, see Section 4.1.1, Configure the Messaging Service.

4. Edit the MsgService.properties file.

This file is in the $CDS_HOME/deployment/deployment-name/conf directory.

5. Set the full class name for the MMS sender class, for example:

mms.senderclass=com.sun.content.server.server.msgserver.push.TestMMSSenderImpl

---

4.4 Configure the Interface Components

The interface components of the Content Delivery Server are the Developer Portal, Subscriber Portal, Catalog Manager administration console, and the Vending Manager administration console. The Content Delivery Server provides a number of properties that you can set to configure these interfaces to meet your needs. Each interface has its own file that contains the properties for that interface. A common file contains properties that apply to all interfaces.

4.4.1 Set the Common Properties

TABLE 4-4 describes the properties that you can set in the CommonConsole.properties file in the $CDS_HOME/deployment/deployment-name/conf directory. These properties apply to all the Content Delivery Server interfaces.

4.4.2 Set the Developer Portal Properties

TABLE 4-5 describes the properties that you can set in the DeveloperPortal.properties file in the $CDS_HOME/deployment/deployment-name/conf directory. These properties apply only to the Developer Portal.

4.4.3 Set the Subscriber Portal Properties

TABLE 4-6 describes the properties that you can set in the SubscriberPortal.properties file in the $CDS_HOME/deployment/deployment-name/conf directory. These properties apply only to the Subscriber Portal.

4.4.4 Set the Catalog Manager Properties

TABLE 4-7 describes the properties that you can set in the AdminConsole.properties file in the $CDS_HOME/deployment/deployment-name/conf directory. These properties apply only to the Catalog Manager administration console.

4.4.5 Set the Vending Manager Properties

TABLE 4-8 describes the properties that you can set in the VSAdminConsole.properties file in the $CDS_HOME/deployment/deployment-name/conf directory. These properties apply only to the Vending Manager administration console.

---

4.5 Configure the Content Delivery Server for a Firewall

The Content Delivery Server generates URLs to access its components from external entities such as a subscriber's device. If you are running the Content Delivery Server behind a firewall, these URLs must be accessible from outside the firewall. The initial values used are the values set for the prefix.external.uri properties in the deployment configuration file, where prefix is the string used to identify the component. If you did not set these properties before you deployed, set the following properties in the CDS.properties file in the $CDS_HOME/deployment/deployment-name/conf directory.

• default.external.catalogmanager.uri. Set this property to the published external URI of the web server for the Catalog Manager, for example:

default.external.catalogmanager.uri=http://webhost.domain.com:80/admin/

• default.external.developerportal.uri. Set this property to the published external URI of the web server for the Developer Portal, for example:

default.external.developerportal.uri=http://webhost.domain.com:80/developer/

• default.external.fulfillmentmanager.uri. Set this property to the published external URI of the web server for the Fulfillment Manager, for example:

default.external.fulfillmentmanager.uri=http://webhost.domain.com:80/fs/

• default.external.vendingmanager.uri. Set this property to the published external URI of the web server for the Vending Manager, for example:

default.external.vendingmanager.uri=http://webhost.domain.com:80/vsadmin/

• default.external.subscriberportal.uri. Set this property to the published external URI of the web server for the Subscriber Portal, for example:

default.external.subscriberportal.uri=http://webhost.domain.com:80/subscriber/

You must also set the Network ID for the Vending Manager account to the internal IP address of the host running the web server.

Use the Catalog Manager administration console to update the Vending Manager account. See the Sun Java System Content Delivery Server Administration Guide for more information.

---

4.6 Configure Pricing

The pricing of content is managed by the Catalog Manager administrator and the Vending Manager administrator. The default currency is United States dollars. If you want to use a different currency, you must change the settings of the currency properties as described in Section 4.6.1, Set the Currency Symbol.

Pricing models define how subscribers pay for content, for example, by number of uses or uses in a period of time. Pricing models are managed by the Catalog Manager administrator. If you want to add a grace period to content charged on every download, you must define the grace period as described in Section 4.6.2, Set a Grace Period.

4.6.1 Set the Currency Symbol

The currency used in the Content Delivery Server system is defined in the CDS.properties file in the $CDS_HOME/deployment/deployment-name/conf directory. Only one currency is specified per deployment and that currency is used for all components in that deployment.

To specify the currency to use, set the following properties in the CDS.properties file.

Vending Managers that are deployed separately from the Catalog Manager have an additional set of currency properties in the $CDS_HOME/deployment/deployment-name/conf/VSAdminConsole.properties file. These properties identify the currency used by the Catalog Manager. A Vending Manager that is deployed separately from the Catalog Manager can use a different currency. A Vending Manager that is deployed with the Catalog Manager must use the same currency as the Catalog Manager.

Settings for the following properties in the VSAdminConsole.properties file must match the corresponding settings in the CDS.properties file for the Catalog Manager deployment. Otherwise, incorrect catalog prices are shown in the Vending Manager administration console.

4.6.2 Set a Grace Period

A grace period provides subscribers with additional downloads of the same content at no charge. You might want to set a grace period if subscribers are known to have difficulty downloading content on the first try. The grace period can be a set number of downloads, a set number of days during which unlimited downloads are allowed, or a combination of downloads and days. If a combination is used, the grace period ends when one of the two conditions is met. For example, a grace period of five downloads and two days ends when the subscriber downloads the content five times or when two days pass, whichever occurs first.

Grace periods apply only to content associated with the Every Download pricing model. See the Sun Java System Content Delivery Server Administration Guide for information on pricing models.

To set a grace period, set the following properties in the $CDS_HOME/deployment/deployment-name/conf/CDS.properties file:

• pricing.model.recurringDownload.numberOfDays. Set this property to the number of days that unlimited downloads are allowed per purchase. The default is 0.
• pricing.model.recurringDownload.numberOfTimes. Set this property to the number of downloads allowed per purchase.The default is 1.

The default values indicate no grace period and subscribers are charged for every download.

---

4.7 Configure Digital Rights Management

Digital rights management (DRM) protects content against unauthorized use and distribution. This section describes how to set up the Content Delivery Server for the types of DRM that you want to support. If you do not want to use the DRM feature, disable support for all DRM types.

Configure the following attributes of the Content Delivery Server to provide the DRM support required. The properties need to be set only in the Catalog Manager deployment.

• Set the DRM Methods Supported
• Set the Preferred Delivery Type
• Set the Preferred Action for Devices that Do Not Support OMA DRM 1.0
• Set the Event Handler

4.7.1 Set the DRM Methods Supported

In the Content Delivery Server, the DRM method used for an item of content is determined by the content type. The pricing models available for an item of content are determined by the DRM method assigned to the content type.

The Catalog Manager administrator is responsible for assigning DRM methods to content types and for pricing content. Work with the administrator to ensure that you properly configure the system to support the needs of your business. See the Sun Java System Content Delivery Server Administration Guide for more information on DRM.

Before you start using the Content Delivery Server, you must enable the DRM methods that you want to support and disable the methods that you do not want to support. The status of each DRM method is stored in the Catalog Manager database, so this configuration is done only once on the server on which the Catalog Manager is deployed.

The Content Delivery Server supports the following DRM methods:

• None. Content is not protected. Use this option when you do not need to control distribution or enforce usage rights. This option cannot be disabled.
• CDS DRM Agent. Content is protected by one of the Content Delivery Server Digital Rights Management (CDS DRM) agents described in TABLE 4-12. Use this method to protect Java applications without requiring additional DRM software. Only one CDS DRM agent can be used per deployment. See Section 4.7.1.1, Content Delivery Server DRM Agents for information on specifying the agent used.
• CDS OMA DRM 1.0 Forward Lock. Content is protected by the Content Delivery Server implementation of the guidelines defined by OMA DRM 1.0 for preventing content from being forwarded to other devices after purchase. Use this method to prevent unauthorized redistribution of content without requiring additional DRM software.
• OMA DRM 1.0. Content is protected according to the guidelines defined by OMA. See Section 4.7.1.2, OMA DRM 1.0 Methods for additional information. Use this method to prevent unauthorized use and redistribution of content. You must have an application that implements the OMA DRM 1.0 guidelines available to handle the rights management when using this DRM type.

Use the following command to enable and disable DRM methods:

cdsi db import [-conf db-configuration-file] -cs file

db-configuration-file is the name of the database configuration file that contains the information for creating the schemas. If db-configuration-file is not provided, the value specified for the DEFAULT_DB variable in the init_env.sh script is used. The following table describes the valid values for file:

If you enable the CDS DRM Agent method, you must specify the agent to use. See the next section for instructions.

4.7.1.1 Content Delivery Server DRM Agents

CDS DRM agents are provided with the Content Delivery Server for use in protecting Java applications. These agents contain the information needed to enforce the usage rights purchased by a subscriber. No additional DRM software is needed. When content is submitted, the agent that you choose to use is added to the content, which increases the size of the content by the average amount stated in the table. The following table describes the CDS DRM agents.

To specify the CDS DRM agent that you want to use, set the DRMAgent property in the $CDS_HOME/deployment/deployment-name/conf/cdsdrmagent.properties file to one of the following values:

• DisconnectedTime
• DisconnectedUse
• DisconnectedUseTime
• SmallConnectedUseTime
• MediumConnectedUseTime
• StandardConnectedUseTime

The DRMAgent property needs to be set only for the deployment that contains the Catalog Manager.

4.7.1.2 OMA DRM 1.0 Methods

The Content Delivery Server supports the following DRM methods described by the Open Mobile Alliance (OMA) DRM 1.0 specification:

• Forward Lock - This method prevents content from being forwarded to other devices. Usage rights are not enforced with this method.
• Combined Delivery - This method includes a digital rights object with the content. The rights object prevents content from being forwarded to other devices and enforces usage rights.
• Separate Delivery - This method includes a digital rights object that is delivered separately from the content. Separate delivery allows content to be forwarded to other devices, which then access the separate rights object for permission to use the content. Not all devices support separate delivery.

OMA DRM 1.0 can be used for all types of content. Use of this method requires an external DRM server. Separate delivery requires an SMSC or WAP PPG that can handle the rights object.

4.7.2 Set the Preferred Delivery Type

The OMA DRM 1.0 specification provides for the delivery of the digital rights object either with the content (combined delivery) or separate from the content (separate delivery.) Not all devices support separate delivery. If your system supports the OMA DRM 1.0 method, you must choose the preferred delivery method for the rights associated with the content.

In the $CDS_HOME/deployment/deployment-name/conf/omadrm10.properties file, set the oma.drm10.rights property to one of the values described in the following table. This property needs to be set only for the deployment that contains the Catalog Manager.

4.7.3 Set the Preferred Action for Devices that Do Not Support OMA DRM 1.0

Not all devices are compliant with OMA DRM 1.0. Content protected by either combined delivery or separate delivery cannot be delivered to non-compliant devices. For content protected by Forward Lock, you must choose whether or not that content is available to subscribers with non-compliant devices.

In the $CDS_HOME/deployment/deployment-name/conf/omadrm10.properties file, set the oma.drm10.plain property to one of the values described in the following table. This property needs to be set only for the deployment that contains the Catalog Manager.

4.7.4 Set the Event Handler

Event handlers listen for specific events generated by the Event Service and respond to the events as needed. Support for separate delivery requires the use of an event handler. The Content Delivery Server provides an event handler that you can use with SafeNet DRM Mobile or any other DRM server.

To enable the OMA DRM 1.0 event handler, edit the $CDS_HOME/deployment/deployment-name/conf/EventService.properties file and remove the initial pound sign (#) from the following statements:

eventservice.handler=OMARightsDelivery

eventservice.handler.OMARightsDelivery.classname=com.sun.drm.oma.eventservice.OMADRM10RightsDeliveryHandler

eventservice.handler.OMARightsDelivery.events=content_purchased

---

4.8 Configure Submission Verifier Workflows

Submission verifier workflows specify the actions taken by the Content Delivery Server when content is submitted. The workflow that is executed is determined by the criteria that you specify. Content that does not require special processing must be processed by the default workflow.

Workflows are provided with the Content Delivery Server in the $CDS_HOME/deployment/deployment-name/conf/SubmissionVerifierWorkflows.xml file for the following types of content:

• Java applications
• iAppli applications that use the DoJa library
• Copyrighted externally hosted content
• Other content

If you do not want to perform an action provided in a workflow, such as API filtering, comment out the step for that action. If you want to execute a workflow for content other than that specified by the default criteria, change the criteria as described in Section 4.8.5, Specifying Workflow Criteria. To add steps to a workflow or create a new workflow, see the Sun Java System Content Delivery Server Integration Guide.

4.8.1 Workflow for Java Applications

The Content Delivery Server supports Java applications that use the MIDP 1.0 or MIDP 2.0 library. A default workflow is provided for use with most Java applications. A workflow for signing Java applications not protected by a CDS DRM agent is also provided.

4.8.1.1 Default Workflow for Java Applications

The default workflow for Java applications performs API filtering and stores the content. If no DRM method is used to protect the content, the content is stored in its original form. If a CDS DRM agent is used to protect the content, the workflow instruments the MIDlet. For MIDP 2.0 MIDlets, the workflow also adds any needed permissions to the MIDlet-Permissions and MIDlet-Permissions-Opt attributes and signs the MIDlet.

Disable an action by commenting out the associated step. For example, if you do not want to perform API filtering, comment out step 2 of the workflow.

Do not comment out the last step named AddingDerivedEdition. This step stores the version of the content that subscribers download and is required.

To sign applications, a keystore file that contains the private key and trusted certificate for your installation is required. Use the keytool utility provided with the JDK software to create this file. You must specify RSA for the keyalg parameter. See the JDK software documentation for information.

If a CDS DRM agent is used to protect the content, you must set the following properties in the $CDS_HOME/deployment/deployment-name/conf/cdsdrmagent.properties file:

• MIDletSigning.MIDP20.enabled. Set this property to true to sign MIDP 2.0 MIDlets. Set to false if you do not want to sign the MIDlets.
• MIDletSigning.KeyStoreFilePath. Set this property to the fully qualified path name and file name of the keystore file.
• MIDletSigning.KeyStorePassword. Set this property to the password used to access the keystore.
• MIDletSigning.KeyAlias. Set this property to the alias of the private key that you want to use to sign the MIDlet.
• MIDletSigning.KeyPassword. Set this property to the password associated with the private key named by the key alias.

4.8.1.2 Workflow for Signing Java Applications

If you do not use a CDS DRM agent to protect content and have a need to sign MIDP 2.0 MIDlets, an alternate version of the workflow for Java applications is provided. To use this workflow, you must create criteria as described in Section 4.8.5, Specifying Workflow Criteria that identifies the content that you want processed by this wokflow. The criteria for this workflow must precede the criteria for the default workflow for Java applications in the file.

The workflow for signed applications requires a keystore file that contains the private key and trusted certificate for your installation. Use the keytool utility provided with the JDK software to create this file. You must specify RSA for the keyalg parameter. See the JDK software documentation for information.

Edit the Signed Java Application Workflow in the SubmissionVerifierWorkflows.xml file and provide the fully qualified path and file name of the keystore file as the value for the MIDletSigning.KeyStoreFilePath in step 3 of the workflow. You must also provide values for the MIDletSigning.KeyStorePassword, MIDletSigning.KeyAlias, and MIDletSigning.KeyPassword properties. See Section 4.8.1.1, Default Workflow for Java Applications for information on these properties.

4.8.2 Workflow for iAppli Applications

The Content Delivery Server supports iAppli applications that use the DoJa library. The default workflow for iAppli applications performs API filtering and stores the content in its original form.

Disable an action by commenting out the associated step. Do not comment out the last step named AddingDerivedEdition. This step stores the version of the content that subscribers download and is required.

4.8.3 Workflow for Externally Hosted Copyrighted Content

The workflow for externally hosted copyrighted content identifies content that must not be cached by the Content Delivery Server because of copyright restrictions.

Both steps in this workflow are required. The first step named AddingDerivedEdition creates an entry in the catalog for the content. The second step named PreventingCopies ensures that only the metadata is stored for the content, the content itself is not stored.

If you want the Content Delivery Server to accept this type of content, remove the beginning and ending comment statements from the criteria that specifies execution of the workflow named "Copyrighted External Content Workflow."

Any content except for Java applications and iAppli applications can be marked as copyrighted. To specify the content for which this workflow is executed, set the criteria as described in Section 4.8.5, Specifying Workflow Criteria.

4.8.4 Default Workflow

The default workflow is executed for all content that doesn't match the criteria for any other workflow. The default workflow stores the content in its original form.

Do not comment out the step named AddingDerivedEdition. This step stores the version of the content that subscribers download and is required.

4.8.5 Specifying Workflow Criteria

Each workflow must have at least one set of criteria that identifies the content for which the workflow is executed. This criteria is defined with the workflows in the $CDS_HOME/deployment/deployment-name/conf/SubmissionVerifierWorkflows.xml file.

Only one workflow is executed for each item of content. The workflow executed is determined by the first set of criteria that the content matches, so the order of criteria is important. If more than one criterion is specified in a set of criteria, all criterion must be met for the content to be considered a match.

CODE EXAMPLE 4-1 shows sample criteria for the workflow for externally hosted copyrighted content.

<criteria id="3" name="isCopyrighted">

  <desc>

    Sample criteria for copyrighted external content.

    Note: only external content can be copyrighted.

    Note: the only DRM supported for copyrighted content is None.

    Note: criterion names and values are case insensitive.

    Note: for location-type, specify e for external or i for

     internal.

  </desc>

  <workflow-list>

    <workflow id="4">

      <argument-list>

        <argument name="editionnamesuffix value="_Copyrighted"/>

      </argument-list>

    </workflow>

  </workflow-list>

  <criterion name="location-type" value="e"/>

  <criterion name="content-type" value="ringtone"/>

  <criterion name="mime-type" value="audio/mp3"/>

  <criterion name="developer-plan" value="copyrightplan"/>

  <criterion name="developer" value="composer"/>

</criteria>

Edit the criterion for the existing set of criteria or create additional sets of criteria to identify the content that you want to be processed by a workflow. For each new set of criteria:

• Provide a unique value for the criteria id attribute.
• For the workflow id attribute, specify the ID of the workflow that you want to assign. For example, for the copyrighted external content workflow, this value is 4.
• If the specified workflow requires input values, include an argument list within the workflow element and provide the argument names and values.
• Order the sets of criteria within the file with the most restrictive set first. As soon as the content matches a set of criteria, no other criteria are checked. The last set of criteria must specify the default workflow and must not contain any criteria.

Use any combination of the following attributes as the criterion in a set of criteria. The workflow is executed if content matches all items specified.

• location-type. Specify e for externally hosted content, i for locally hosted content.
• content-type. Specify a content type that is supported by the Content Delivery Server.
• mime-type. Specify a MIME type that is supported by the Content Delivery Server.
• developer-plan. Specify the name of a Developer Plan.
• developer. Specify the user name of a developer.
• MicroEdition-Configuration. Specify the MicroEdition Configuration version for the MIDlet, for example, CLDC-1.0.
• MicroEdition-Profile. Specify the MicroEdition Profile version for the MIDlet, for example, MIDP-1.0.
• ConfigurationVer. Specify the Configuration Version for the iAppli application, for example, CLDC-1.0.
• ProfileVer. Specify the Profile Version for the iAppli application, for example, DOJA-1.0.

---

4.9 Configure Customized Marketing Campaigns

The Content Delivery Server provides a feature that enables you to send advertisements to selected subscribers. Messages can be sent using SMS, WAP, MMS, or SMTP.

Campaigns sent as email use the SMTP mail service defined for the Messaging Service. To change the mail service, see Section 4.1.1.5, Configure the Mail Service.

You can include a link to promotional items in the message. The address to which the link points is based on the value specified for the sp.external.uri property in your deployment configuration file.

If the value in the configuration file is not correct, edit the CDS.properties file found in the $CDS_HOME/deployment/deployment_name/conf directory and set the value for the default.external.subscriberportal.uri property to the correct address. If the Content Delivery Server is running behind a firewall, specify an address that subscribers can access from outside the firewall.

---

4.10 Configure Subscriber Account Management

A subscriber account contains information that identifies the subscriber and the device used to access the Content Delivery Server. Subscriber accounts are managed by the Vending Manager administrator through the Vending Manager administration console. Subscribers can also access their own accounts through the Subscriber Portal.

You can configure the options presented to the subscriber and the administrator. For example, you can allow subscribers to only view their accounts, or prevent administrators from deleting accounts. You can also configure which fields subscribers or administrators can edit. For example, you can prevent subscribers from changing their mobile phone numbers, or prevent administrators from changing the subscribers' names.

To specify the options that you want to make available and the fields that can be edited, edit the following files found in the $CDS_HOME/deployment/deployment-name/conf directory:

• subsubmgr.xml. Configure this file to specify the actions that the subscriber can take through the Subscriber Portal.
• vsadminsubmgr.xml. Configure this file to specify the actions that the administrator can take through the Vending Manager administration console.

The options for managing subscriber accounts are add, edit, and delete. These options are represented by the <add>, <edit>, and <delete> tags in the files. To make an option available, set the isEnabled property to true. To hide the option, set the isEnabled property to false. The default is true. For example, to prevent subscribers from creating an account, include the following statement in the subsubmgr.xml file:

<add isEnabled="false"/>

Each field in the subscriber account is represented by a tag in the file under the <edit> tag. To prevent a field from being changed, set the isReadOnly parameter to true. To enable the field to be changed, set the isReadOnly parameter to false. The default is false.

The following code shows the relevant section of a sample subsubmgr.xml file.

<subscriber>

   <subscriber>

      <!-- For adding -->

      <add isEnabled="false"/>

      <!-- For editing -->

      <edit isEnabled="true">

         <password isRequired="true"/>

         <mobile_id isRequired="true" isReadOnly="true"/>

         <first_name isRequired="true"/>

         <middle_name/>

         <last_name isRequired="true"/>

         <salutation/>

         <gender/>

         <street_1/>

         <street_2/>

         <city/>

         <state/>

         <postal_code/>

         <country_code/>

         <email isRequired="true"/>

         <contact_phone/>

      </edit>

   </subscriber>

</subscriber>

The following code shows the relevant section of a sample vsadminsubmgr.xml file.

<vsadmin>

   <subscriber>

      <!-- For adding -->

      <add isEnabled="true"/>

      <!-- For editing -->

      <edit isEnabled="true">

         <password isRequired="true"/>

         <status isRequired="true"/>

         <mobile_id isRequired="true"/>

         <first_name isRequired="true"/>

         <middle_name/>

         <last_name isRequired="true"/>

         <salutation/>

         <gender/>

         <street_1/>

         <street_2/>

         <city/>

         <state/>

         <postal_code/>

         <country_code/>

         <email isRequired="true"/>

         <contact_phone/>

      </edit>

      <!-- For deleting -->

      <delete isEnabled="true"/>

   </subscriber>

</vsadmin>

---

4.11 Configure Support for Externally Hosted Content

If you choose to support content that is hosted externally, you must set the URL that the Event Service can use to access the Developer Portal. If this property is not set correctly, updates to externally hosted content are not fetched.

To set the Developer Portal URL, follow these steps:

1. Edit the CDS.properties file found in the $CDS_HOME/deployment/deployment-name/conf directory.

2. Set the value of the default.internal.developerportal.uri property to the internal address for the Developer Portal.

The default is http://localhost/developer.

---

4.12 Configure Support for Customized Reports

In addition to the reports generated by the Vending Manager, you can configure the Content Delivery Server to store transaction data in a database table that you can use to create your own reports.

To configure support for customized reports, follow these steps:

1. Edit the PostpaidService.properties file found in the $CDS_HOME/deployment/deployment-name/conf directory. Set the postpaid.handler.class property to the name of the report handler, for example:

postpaid.handler.class=com.sun.content.server.postpaid.impl.ReportingHandler

You can have more than one postpaid.handler.class property in the file.

2. Edit the ReportService.properties file found in the $CDS_HOME/deployment/deployment-name/conf directory.

Set the following properties:

• reportdb.username. The user name used to access the reports database. This is prefix_vs_app, where prefix is the value specified for the Prefix element under the Vending element in the database configuration file used to create the database. See Section 3.1.2, Set up the Database for information on this file.
• reportdb.password. The password used to access the reports database. This is the value specified for the Password element under the Vending element in the database configuration file.
• reportdb.server.url. The connection URL for the database. This value is specified as jdbc:oracle:thin:@dbhost.domain.com:1521:sid. Set dbhost.domain.com and sid as needed for your database server.

For information on the data stored for each transaction, see Appendix B.

---

4.13 Set up Support for iAppli Applications

To support iAppli applications, add an entry in the database for the DoJa library and submit the library to the Content Delivery Server.

4.13.1 Add the DoJa Library to the Database

An entry for the DoJa library is added to the Catalog Manager schema by default when the schema is created unless you removed the iappli.sql file from the $CDS_HOME/dist/cds/database/cs directory at the time you created the Catalog Manager schema. If you included iAppli support when you created the Catalog Manager schema, you just need to submit the DoJa library as described in Section 4.13.2, Submit the DoJa Library.

If you did not include iAppli support when you created the Catalog Manager schema, perform the following steps on the host where the Catalog Manager is deployed before submitting the library:

1. Remove all files with the extension .sql from the $CDS_HOME/dist/cds/database/cs directory.

Save these files in another location.

2. Copy the iappli.sql file into the $CDS_HOME/dist/cds/database/cs directory.

3. Run the following command:

cdsi db data [-conf db-configuration-file] -cs

db-configuration-file is the name of the database configuration file that contains the information for creating the schemas. If db-configuration-file is not provided, the value specified for the DEFAULT_DB variable in the init_env.sh script is used. The switch -cs indicates that only the schema for the Catalog Manager is created.

To verify that an entry exists in the database, log in to the Catalog Manager Administration console and display the list of device libraries to see the entry for the DoJa 1.0 library.

4.13.2 Submit the DoJa Library

Submit libraries through the Catalog Manager administration console. See Section 5.1, Starting the Content Delivery Server for information on starting the Catalog Manager.

Make sure an entry for the DoJa library exists in the Catalog Manager database. If not, see the instructions in Section 4.13.1, Add the DoJa Library to the Database for creating the entry. To submit the DoJa library, follow these steps:

1. Start the Catalog Manager administration console from a browser window by typing the following address:

http://hostname:port/admin/main

The Catalog Manager Log In page is displayed.

2. Enter your administrator name and password.

3. Click Log In.

The Catalog Manager main page is displayed.

4. Click Devices in the main menu bar.

The Device Management page is displayed.

5. Click the Libraries tab.

The Device Libraries page is displayed.

6. Click DOJA-1.0.

The Library Definition page is displayed.

7. Click Upload JAR.

The library properties are displayed.

8. For Select JAR File, enter the path of the library file or click Browse to locate the library file.

Do not change the name of the library.

9. Click Next.

The items available for inclusion in the library are displayed.

10. Select Global Package.

11. Click OK.

The library is added to the database and is available for use in Developer Plans to restrict the APIs used by developers.

12. Click OK to close the confirmation page.

---

4.14 Set up Notifications to Developers

Developers submit content to the Content Delivery Server through the Developer Portal. You can set up the Content Delivery Server to send email notifications to developers whenever action is taken on the content that they submitted.

To set up notifications, follow these steps:

1. Make sure that the default.external.developerportal.uri property in the $CDS_HOME/deployment/deployment-name/conf/CDS.properties file points to the location of the Developer Portal.

Use the format http://hostname:port/developer/, where hostname:port is the host name and port number of the host on which the Developer Portal is running.

2. Set the following properties in the $CDS_HOME/deployment/deployment-name/conf/EventService.properties file.

• eventservice.developer.email.enabled - Status of email notifications. Set this property to true to automatically send notifications when action is taken on content. Set to false to disable the sending of notifications. The default is false.
• eventservice.developer.email.from - Address used as the address from which the notification is sent.
• eventservice.developer.email.admin - Address to which developers can respond if they have questions about the notification.
• eventservice.developer.email.template.propertychanged - Fully qualified location of the XSL file that contains the description of the notification sent when any content property is changed.
• eventservice.developer.email.template.submitted - Fully qualified location of the XSL file that contains the description of the notification sent when content has been received or rejected by the Content Delivery Server.
• eventservice.developer.email.template.statuschanged - Fully qualified location of the XSL file that contains the description of the notification sent when the status of content is changed.

3. (Optional) Customize the notifications that are sent.

You can customize notifications by editing the default templates provided with the Content Delivery Server or by creating your own XSL files.

CODE EXAMPLE 4-4 provides the definition of the notification templates that you can follow. If you create your own files, you must update the properties described in the previous step that identify the location of the files.

/*

 * Definition of XML documents that are piped to the

 * XSL transformation sheets.

 *

 * <dn>

 *  <developer>Joe Developer</developer>

 *

 *  <submission> <!-- when content was submitted (even if failed) -->

 *    <succeeded> <!-- may be zero or more -->

 *      <name>Name used to submit</name>

 *      <id>ID used to submit</id>

 *      <url>URL this content is viewable at</url>

 *    </succeeded>

 *    <failed> <!-- may be zero or more -->

 *      <name>Name used to submit</name>

 *      <id>ID used to submit</id>

 *      <errormsg>Error message</errormsg>

 *      <errorlog>Lengthy error info</errorlog>

 *    </failed>

 *  <submission>

 *

 *  <statuschanged>

 *

 *    <!-- The possible status values are:

 *

 *    pending

 *    denied

 *    published

 *    deleted

 *    new

 *

 *    -->

 *

 *    <newstatus>status</newstatus>

 *

 *    <name>Name used to submit</name>

 *    <id>content id</id>

 *    <url>URL where this content is accessible</url>

 *    <message>Message left for developer</message>

 *  </statuschanged>>

 *

 *  <propertychanged>

 *    <name>Name used to submit</name>

 *    <id>content id</id>

 *    <url>URL where this content is accessible</url>

 *    <textproperty> <!-- zero or more of those -->

 *      <name>property name</name>

 *      <oldvalue>old property value</oldvalue>

 *      <newvalue>new property value</newvalue>

 *    </textproperty>

 *

 *    <!-- binary property is special, since it doesn't have a

 *         displayable value, so only name is mentioned.

 *    -->

 *    <binaryproperty>property name</binaryproperty> <!-- zero or

 *           more -->

 *    <priceproperty> <!-- zero or one of this, only for suggested

 *           price -->

 *      <!-- note the pricedata tag. It is used to unify the

 *           structure to make XSLT transformation easier.

 *      -->

 *      <oldvalue><pricedata>

 *        <billing1>

 *          <!-- the following is $13.27, but helps localization

 *               if broken in such a way. There is also a "number"

 *               tag which gives the price in cents (coins)

 *           -->

 *          <price>

 *            <number>1327</number>

 *            <bills>13</bills>

 *            <coins>27</coins>

 *          </price>

 *          <usage_count>usage_count</usage_count>

 *         <usage_period_days>usage_period_days</usage_period_days>

 *          <recurring>recurring</recurring>

 *        </billing1>

 *        <billing2>

 *          <price><bills>13</bills><coins>27</coins></price>

 *          <frequency>frequency</frequency>

 *          <recurring>recurring</recurring>

 *        </billing2>

 *        <billing3>

 *          <price><bills>13</bills><coins>27</coins></price>

 *          <usage_count>usage_count</usage_count>

 *        </billing3>

 *      </pricedata></oldvalue>

 *      <newvalue><!-- the same as for oldvalue --> </newvalue>

 *    </priceproperty>

 *

 *  </propertychanged>

 *

 *  <adminemail>Email address developer can inquire at</adminemail>

 * </dn>

 */

---

4.15 Set up the Default Option for Subscriber Notifications

The Content Delivery Server sends notifications to subscribers about updates or promotions. Subscribers can choose to receive these notifications by setting the option when they set their preferences for their account. You can set the default to either opt-in or opt-out. The initial default is opt-in.

To change the default option, set the user.profile.optin property in the $CDS_HOME/deployment/deployment-name/conf/security.config file. Set this property to true to set the default to opt-in. Set this property to false to set the default to opt-out.

---

4.16 Configure Support for PAR Files

The Content Delivery Server accepts content in either Zip files or Provisioning Archive (PAR) files when submitted to the Content Delivery Server. To support PAR files, you must set properties in the $CDS_HOME/deployment/deployment-name/conf/DeveloperPortal.properties file to map the PAR bundle types to the Content Delivery Server content types.

Add a property for each type of content that you want to support using the following format:

par.bundle-type.type=content-type

type identifies the type of PAR bundle that is submitted. PAR bundle types are defined in the Java Specification Report (JSR) 124, which is available at http://www.jcp.org/aboutJava/communityprocess/final/jsr124/.

content-type identifies the type of content in the PAR bundle and must be one of the content types defined in the Content Delivery Server. For example, the following statement shows the property for submitting image content in an image bundle:

par.bundle-type.image=image

You must restart the Content Delivery Server after you make changes to the properties.

---

4.17 Control Access by External Systems

The Content Delivery Server components are accessed through URLs that are generated from the internal and external URI properties set in the deployment configuration file (see Appendix A.) To prevent unauthorized access, set up the access control file with the rules needed to define what access is allowed. The default access control file allows access by all requestors.

4.17.1 Access Control File

The access_control.config file in the $CDS_HOME/deployment/deployment-name/conf directory is used to determine when access to the Content Delivery Server components is allowed. This file contains the following types of statements:

• Access control lists - One or more patterns of addresses to which the address of the source of the request is matched.

An access control list is identified by the keyword acl and a name that uniquely identifies the list. The list contains one or more address patterns. The format for the statement is acl acl-name {address-patterns}.

acl-name is a string of alphanumeric characters, including underscores, and must not match any keyword used in any statement. address-patterns is one or more host names, IP version 4 (IPv4) address masks, or IP version 6 (IPv6) address masks. For a complete description of this statement in Backus Naur Form (BNF) notation, see Appendix C.

• URI groups - One or more relative paths for Content Delivery Server components to which the target of the request is matched.

A URI group is identified by the keyword uri_group and a name that uniquely identifies the group. The group contains one or more relative paths. The format for the statement is uri_group group-name {paths}.

group-name is a string of alphanumeric characters, including underscores, and must not match any keyword used in any statement. paths is one or more absolute URIs that include the servlet context name and are expressed as regular expressions. For a complete description of this statement in BNF notation, see Appendix C.

• Rules - Statements that define the requests for access that are allowed and the requests that are denied.

A rule is identified by the keyword access and contains the following information:

• Relative path to the Content Delivery Server resources to which access is requested
• Protocol used in the request
• Method used in the request
• IP addresses from which the request is received
• Status of the request, which is either allowed or denied

The format for a rule that references a URI group is
access group group-name protocol protocol method method {control-list}. group-name is the name given one of the URI groups in the file. protocol is the protocol used in the request and is either http, https, or any. method identifies the action requested and is either get, post, put, or any. control-list is a list of statements that indicate which addresses are allowed access and which addresses are denied access.

For a complete description of this statement in BNF notation, see Appendix C. For information on how the rules are interpreted, see the next section.

4.17.2 Access Control Process

When a request for access to a Content Delivery Server component is received, the rules in the access control file are used to determine if the access is allowed.

A rule is matched when the following conditions are met:

• The component to which access is requested matches a path specified for the URI or URI group that the rule references
• The protocol used in the request matches the protocol specified in the rule
• The method used in the request matches the method specified in the rule
• The source of the request matches an address that is referenced in the control list

The rules are processed in the order in which they appear in the file. The request is compared against all the rules in the file unless the keyword final is encountered. The last rule matched determines if access is allowed. In general, you want the more restrictive rules at the end of the file.

The final keyword stops the matching process. This keyword can appear at the beginning of the rule or at the end of any control list in a rule. If the keyword appears at the beginning of the rule, processing stops when the source of the request matches an address in any of the control lists in the rule. If the keyword appears at the end of a control list, the processing stops only when the source of the request matches an address in that control list.

When processing stops, the status of the request is determined by the keyword in the control list that contains the address of the source of the request. If the keyword is allow, access is allowed. If the keyword is deny, access is denied and the error code 404 is returned.

If no rules are matched, access is allowed. To deny access to all requests that do not match any rule, add the following rule at the beginning of your rules:

access uri `/.*' protocol any method any {deny any;}

---

4.18 Configure Alias Forwarding

Alias forwarding is a technique for accepting a URL and redirecting the user to a different location. This feature enables you to provide subscribers with a URL that is easy to remember and redirect the request to the correct location. You can also use this feature to intercept requests and redirect them for special processing.

The mapping of URLs for the Content Delivery Server is defined in the aliasforwarding.xml file. This file is in the $CDS_HOME/deployment/deployment-name/conf directory. To use a different file, set the filter.AliasForwarding.file property in the DefaultWebApp.properties file in the $CDS_HOME/deployment/deployment-name/conf directory.

The alias forwarding file is a filter that uses XML to describe the redirection that takes place when a URL is received. The following table describes the elements in this file.

The following code example shows a sample mapping file.

<AliasForwarding>

    <AliasMap>

        <URLPattern>/dev</URLPattern>

        <TargetContext>/developer</TargetContext>

        <TargetPath>/main</TargetPath>

    </AliasMap>

    <AliasMap>

        <URLPattern>/sub</URLPattern>

        <TargetContext>/subscriber</TargetContext>

        <TargetPath>/desktop_home.do</TargetPath>

    </AliasMap>

</AliasForwarding>

The alias forwarding filter is deployed to the context root /DefaultWebApp, which is set up by the Content Delivery Server as the default application for requests to the Content Delivery Server. Requests that do not contain a URL that matches a known context root are sent to the default application and are processed by the filter. Requests that do contain a URL that matches a known context root are sent directly to the application and are not processed by this filter. For example, based on the mappings in CODE EXAMPLE 4-5, a request to /sub is processed by the filter and rerouted to /subscriber. However, a request to /subscriber is sent directly to the application and is not processed by the filter.

When a request is received by the default application for the Content Delivery Server, the incoming URL is matched against each URLPattern element in the alias forwarding file according to the following rules.

• If the incoming URL does not begin with a slash (/), the slash is assumed.
• If the pattern or the incoming URL does not end with a slash (/) or a file name extension, a slash is assumed.
• If the pattern is /*, the incoming URL is always a match.
• If the pattern is more than three characters, begins with /, and ends with /*, the string between the slashes is matched with the beginning of the incoming URL. For example, the pattern /PATH/* matches the URLs /PATH and /PATH/anything.
• If the pattern begins with /*., the string following the period is matched with the end of the incoming URL. For example, the pattern /*.EXT, matches any URL that ends with .EXT.
• If the pattern begins with *., the string following the period is matched with the end of the incoming URL. For example, the pattern *.EXT matches any URL that ends with .EXT.
• If the pattern begins with / and ends with /, the string between the slashes is matched with the incoming URL. For example, /PATH/ matches the URLs /PATH and /PATH/.
• If the pattern begins with /, the string following the slash is matched with the incoming URL. For example, /PATH matches the URLs /PATH and /PATH/.

The process stops when a match is found. The request is then redirected to the location derived by appending the values for TargetContext and TargetPath that are associated with the URLPattern that matched the incoming request. If no match is found, the request is returned to the application server.

Depending on how you define the mappings, it is possible that when a match is found, the new location is also processed by the filter. Make sure that you do not create a circular mapping that generates only URLs that are processed by the filter and never a URL that is redirected to an actual location.

Sun Java System Content Delivery Server Installation Guide

819-3215-10

Copyright © 2005, Sun Microsystems, Inc. All Rights Reserved.