SMS and CRM basics

Concepts

Subscriber Management Systems (SMS) are the subset of Business Support Systems (BSS) responsible for creating new accounts, administering account details and billing information, and provisioning and managing devices (set-top boxes, smartcards and open devices).

OpenTV Platform back-end must have up-to-date information about accounts and devices in several situations:

• When using a Conditional Access (CAS) system: when a subscriber purchases a product, it needs to identify the product and the subscriber's devices to the CAS, so that the CAS can provide the correct entitlements.
• When using a Digital Rights Management (DRM) system: when a subscriber wants to view content, the system needs to check whether the subscriber is entitled to access that content, and if he is, obtain a license from the DRM which the client can use to decrypt the content.
• In systems where subscribers can purchase content directly from their device, the back-end applies purchase restrictions, and handles creation of the billing records that identify the product and the subscriber's account towards an external billing system.

If the operator uses an external subscriber management system to manage accounts and devices, an interface must be provided that sends this information to the back-end.

Subscriber management tasks are typically split into two parts:

• Account management
  Includes management of accounts and users, including their subscriptions to content.
   
• Device management
  Concerned with client devices such as set-top boxes, smartcards and open devices.

In OpenTV Platform, billing is treated as a separate BSS activity, therefore is outside the scope of this guide.

In addition, OpenTV Platform provides OTT session management to control the amount of bandwidth consumed by client apps by limiting the number of concurrent streams.

Overall architecture

OpenTV Platform offers two integration points to SMS/CRM systems:

• Definition of products and their relation with content.
• Creation of accounts, users and devices, provision subscriptions.

CMS interfaces

Products can be defined in CMS using XML files or the CMS UI. File ingest format is defined in CMS VOD and BTV import specifications available from CMS deliveries.

SDP interfaces

Provisioning operations on SDP are accessible via a set of SOAP-based Web Services interfaces. APIs are grouped per business domain into 'Services'.

Services in SDP are organised into a structure in which Services build on other Services to help them perform their business functions:

• At the lowest level are the Services responsible for managing Entities in the database, or for exposing interfaces to external systems.
  These Services never use any other Services, so they are called primitive Services.
  For example: AccountService, DeviceService.

• At the next level are the aggregate Services: these never interface with the database or an external system, and instead use the primitive Services to do this work for them.
  Aggregate Services can also call other aggregate Services to implement any complex business operation.
  For example: AccountAggregateService, DeviceAggregateService

• The SMS Service (Contract First Web Services API)
  This is the entry point API for subscriber management in SDP.
  This service uses other aggregate and primitive services and also takes care of sending commands to the CAS system when needed.

The following diagram shows a sample of the SDP hierarchy of services. SMS systems always use SMS Service unless explicitly indicated otherwise (in particular for data retrieval operations).

Prerequisites

Before an SMS can be integrated with OpenTV Platform, the operator must make some decisions about how the system is going to be used:

• Define names for CAS instances

  SDP can be used to provision devices and to send entitlement requests for products to configured CAS instances.
  Each product defined on CMS must contain the CAS instance name.

• Define names for DRM systems

  Each content item can be protected by one DRM system whose name is included as part of the content definition in CMS.
  SDP can be configured to perform license delivery authorisation based on the account's access rights for that content.

• Device features

  Content and products can be made available only for certain devices that are suitable for them.
  A set of features can be configured in SDP to classify devices according to their capabilities.
  Similarly, content in CMS can be assigned a set of features so that system filtering can be applied.

API basics

This section provides an overview of how the SMSDomain Web Service API is designed, specifically the base URL and the requests and responses of each call.

Base URL

All URLs referenced in this guide use the following base URL:

http://<server>/api/smsservice_1.2

The WSDL file for this API is exposed at the following URL:

http://<server>/api/smsservice_1.2?wsdl

Resources required by the WSDL, such as schemas, are exposed at the following URL:

http://<server>/api/smsservice_1.2?wsdl&resource=<resourceName>

Requests

The body of the SMSDomain API request contains a single request element that specifies the operation to perform. 

The request element has the same name as the operation.

This element contains the information required in the request, including the request parameters as child elements. All types used by this API are defined in the associated XML schemas described in the API documentation.

The following example shows a sample request for a "CreateAccount" operation:

<soapenv:Header/>
<soapenv:Body>
   <sms:CreateAccount>
      <model>
         <accountNumber>130</accountNumber>
         <status>ACTIVE</status>
         <accessPointSpecification>
               <uid>1</uid>
         </accessPointSpecification>
         <creditLimit>1000.0</creditLimit>
      </model>
   </sms:CreateAccount>
</soapenv:Body>

Request parameters

The following conventions are used for input and output parameters:

• Strings are passed literally, UTF-8 encoded.
• Numeric parameters (Integer, Long, Double) are specified as decimal numbers.
• Boolean types are specified as true or false.
• Date types are in ISO format: <yyyy>-<MM>-<dd>T<hh>:<mm>:<ss> with an optional time zone at the end: <+/-><hh>:<mm> 
  For example: 2012-06-21T16:01:00+01:00

Responses

Successful responses

When an SMSDomain request completes successfully, the response is supplied in a single response element.

Update and delete responses contain an empty body. Create responses include the object created, as defined in the respective XSD schema.

The following example shows a sample successful response for a "CreateAccount" operation: 

<soapenv:Header/>
 <soapenv:Body>
    <acc:Account>
       <account>
          <uid>55</uid>
          <accountNumber>130</accountNumber>
          <status>ACTIVE</status>
          <accessPointSpecification>
             <uid>1</uid>
          </accessPointSpecification>
          <creditLimit>1000.0</creditLimit>
          <modificationDate>2012-05-22T09:30:10+01</modificationDate>
       </account>
    </acc:Account>
 </soapenv:Body>

Error responses

If any request fails, the response returned by the SDP includes a "ServiceException" container with the following fields:

The following example shows a sample error response for a "CreateAccount" operation:

<soapenv:Header/>
<soapenv:Body>
   <sms:ServiceException>
      <account>
         <code>55</code>
         <chainedCode>missing mandatory accountNumber parameter</chainedCode>
   </sms:ServiceException>
</soapenv:Body>