Use cases

Main integration steps

Below is a list of the main steps required to integrate an external SMS system with OpenTV Platform SDP:

Create accounts to represent the subscribers to the platform.
Manage account status and configuration to meet business requirements.
1. Assign profiles to accounts.
2. Limit the number of allowed devices and streams, credit limits, etc.
3. Add/Remove card payment credentials.
4. Cancel / suspend accounts when needed.
5. Control streaming sessions for each account (OTT).
Create Users and link them to Accounts.
Create and manage Devices and link them to Accounts.
1. Hardware root of trusted set-top boxes and smart cards provisioned on SDP via SMS service API.
2. Open devices (for example, using OpenTV Player) can be discovered on the fly.
3. Configure SDP to send device management control commands to the NAGRA CAS system when needed.
Provision rights to the Accounts.
1. Add / remove subscriptions to live packages to Accounts.
2. Add / remove subscriptions to VOD packages to Accounts.
3. Configure SDP to send product activation commands to the NAGRA CAS system when needed.

The following section covers the main use cases referenced above.

Account Management

Summary

Account is the entity that models a subscriber in OpenTV Platform. It holds the the name and address of the subscriber for billing purposes, and is always associated with at least one User.

When a viewer acquires content through SDP, new Billing and AcquiredContentList Entities are created and linked to the viewer's Account to record their purchase.

The status of the account defines what stage in its life cycle the Account is in, and determines what the subscriber can do.

Data model

Account

Name	Type	Description	Always available
`accessPointUID`	Integer	The unique access point identifier within the SDP. Can be used to request the full access point details from the SDP using the Access Point service. An access point provides details on the location the device resides in and how it should connect to the platform.	Yes
`accountNumber`	String (max 20 chars)	The account number. Usually provided by the service provider.	Yes
`accountProfileUID`	Integer	The unique account profile identifier within the SDP. This profile is used to specify the maximum number of allowed devices, device activations, and concurrent OTT streams. Available from SMSDomain-1.3 and above.	No
`address1`	String (max 150 chars)	First line of address.	No
`address2`	String (max 150 chars)	Second line of address.	No
`city`	String	Address city name.	No
`country`	String (max 50 chars)	Address country.	No
`county`	String (max 100 chars)	Address county.	No
`creditLimit`	Double	The maximum spend per globally-specified credit interval, for example, a calendar month. If empty, the account will be able to make unlimited purchases.	No
`creditSpent`	Double	The credit spent so far in the current time period.	No
`creditSpentRS`	String	Not relevant to clients. Used by billing jobs. Available from SMSDomain-1.3 and above.	No
`firstName`	String	Account holder first name.	No
`lastname`	String (max 100 chars)	Account holder last name.	No
`locality`	String (max 100 chars)	Address locality, that is, area name.	No
`maxMPDeviceAllowed`	Integer	The number of open devices associated with the account cannot exceed this value, if set.	No
`maxUserAllowed`	Integer	The number of users associated with the account cannot exceed this value, if set.	No
`npvrProfile`	String (max 32 chars)	The network PVR profile used for this account. Available from SMSDomain-1.3 and above.	No
`password`	String (max 20 chars)	Not typically used.	No
`postcode`	String (max 10 chars)	Postcode or zipcode.	No
`ppvStatus`	Boolean	Boolean to indicate whether the account has access to PPV services. This field was known as `isPPVEnabled` in SMSDomain-1.2 and earlier.	No
`rolloutProfileUID`	Long	The identifier of the rollout profile that should be used for this account. A rollout profile indicates what software versions should be rolled out to an account's open devices. Available from SMSDomain-1.3 and above.	Yes
`status`	String	The account status. One of: `ACTIVE` `CANCELLED` `INACTIVE` `RESTRICTED` `SUSPENDED` Only accounts that are active or restricted will be able to sign on to the system, therefore the status is largely irrelevant to a client UI application. For details see: Account and STB Status.	Yes
`title`	String	Account holder title.	No
`UID`	Integer	Unique account identifier within the SDP. Can be used to query other APIs in the SDP, but not against any other modules or systems.	Yes

Account specification

Allows API clients to uniquely identify an existing Account using one of a range of identifiers. Only one child element may be provided.

Name

Type

Description

Qualifier

accountNumber

String

Unique account identifier.

If provided on creation, SDP verifies that the value is unique.

If not provided, SDP assigns a value to the new Account instance.

WriteOnCreate, optional

uid

Long

Internal numeric identifier assigned by SDP.

RO

Assigned internally

originSpecification

OriginSpecification

The originId and originKey of the account.

WriteOnCreate, optional

Account status

Status values

The status of an account or STB defines what stage the item is in its life cycle and determines what the subscriber can do.

The account or STB status is important for subscriber management use cases. However, since only accounts that are active or restricted will be able to sign on to the system, the status is largely irrelevant to a client UI application.

Status	Meaning
`INACTIVE`	The starting state of the account or STB. Once an account or STB has been moved away from INACTIVE, it cannot be returned to this status. Viewing is not allowed but subscriptions are allowed on the account.
`ACTIVE`	The normal operational state of the account or STB. The account can be provisioned with Set Top Boxes and is permitted to sign on, purchase, and access content.
`RESTRICTED`	A partially operational state. The account may sign on and access subscribed content, but is not permitted to purchase new content or remove existing purchases.
`SUSPENDED`	A non-operational state. The account is not permitted to sign on when in this state. Access to content is temporarily denied. If the account or STB later moves to `ACTIVE` or `RESTRICTED` status, it will regain access to the content it had before it became `SUSPENDED`.
`CANCELLED`	The final state of the account or STB. The account or STB cannot be moved out of this state. It is equivalent to deletion. (The account is not deleted from the database, to ensure that billing records remain valid and unique data such as the account number are not reused.)

Status transitions

These transitions are allowed:

Use Cases

Subscriber Management Systems can fully manage Account Entities in OpenTV Platform.

SMSDomain Service:

Other SDP services:

User Management

Summary

A User represents an end user who is entitled to view digital TV and media services.

Every active User is attached to a single Account. Different Users on the same Account can have different privileges, for example, to access rated content or other services.

Users can have either normal or super-user access privileges. Super-users of an Account might be able to add new Users, manage Ratings, or perform Account administration, if the application supports it. Every Account always has at least one super-user.

A User can have a Rating to denote their morality level for parental control purposes.

Purchases made by users are registered to the Account, although the actual User that performed the purchase will be registered for billing purposes.

Data model

User

Name	Type	Description	Qualifier	Localised	Always available
`account`	AccountSpecification	Identifies the account associated with the user.	RW, mandatory	No	Yes
`dateOfBirth`	Date	The date of birth of the user, in the format `yyyy‑mm‑dd`.	RW, optional	No	No
`defaultUser`	Boolean	Is this the default user for the associated account? Each account must have one default user.	WriteOnCreate, optional	No	No
`hashSalt`	String (max 100 chars)	Salt value used to encrypt the password in the DB. If this field is blank, the password is stored in clear text.	WriteOnCreate, optional	No	No
`loginId`	String (max 100 chars)	Unique ID that the client uses to identify the user at signon. Mandatory when creating OpenTV Player clients. If this field has a value, it must be unique across all users	WriteOnCreate, mandatory	No	Yes
`name`	String (max 20 chars)	Friendly name. Used in addition to `loginID` to identify the user.	RW, mandatory	No	Yes
`originId`	String	Identifier of the system which owns this entity.	WriteOnCreate, optional	No	No
`originKey`	String (max 20 chars)	External user identifier.	WriteOnCreate, optional	No	No
`password`	String (max 100 chars)	Password used to sign on. Mandatory when creating OpenTV Player clients.	RW, optional	No	No
`pin`	String (max 10 chars)	PIN to access restricted content.	RW, mandatory	No	Yes
`purchaseAbility`	String	Keyword indicating if this user is permitted to make purchases. One of: `ALLOWED` `DENIED` Super-users can modify this flag for other users in the account.	RW, optional	No	No
`ratingSpecification`	RatingSpecification	Identifies a rating to assign to the user.	RW, optional	No	No
`type`	String	The type of the user. One of: `SUP` (super-user) `NOR` (normal) At least one user in the account must be `SUP`.	RW	No	No
`uid`	Long	Internal numeric identifier. The SDP internal UID for this entity.	RO, assigned internally	No	Yes

Use Cases

Users can be created as part of an Account creation or can be added to an Account later.

SMSDomain Service

Create User (as part of Account creation)

SDP User Service:

Device Management

Summary

NOCS set-top boxes and smart-cards are provisioned in SDP via SMS Service. When configured to work with a NAGRA CAS system, SDP will take care of propagating the appropriate commands to the CAS, so that it can generate entitlements accordingly.

This enables both generic device management use cases (create, delete, update) as well as CAS-specific use cases (such as pair smart-card with STB, key update/reset, PIN update/reset).

Open devices using OpenTV Player can be discovered automatically the first time they connect to the OpenTV Platform, based on user credentials or other device characteristics. OpenTV Platform will take care of integrating with a DRM system (like NAGRA PRM) to authorize license delivery to open devices.

Data model

Device

This data structure represents a generic device.

Note that a Media Player or Set Top Box is an instance of a Device, and that the Media Player data model and Set Top Box data model extend the Device data model.

Name	Description	Always available
`accountUID`	The unique account identifier within the SDP. This identifier is not known externally to the SDP, so should only be used for SDP API calls. Account number should be used for account identification wherever possible.	Yes
`description`	Description of the device if available.	No
`deviceClassifierUID`	Unique identifier of the device classifier within the SDP. Can be used to retrieve the device classifier from the Device Classifier Service.	No
`deviceEnabled`	`true` if the device is enabled, otherwise `false`. The device will not be able to use the service if this is false, so should be true.	Yes
`deviceType`	The device type. Should be one of: `STB` – Set Top Box `MP` – Media Player	Yes
`drmInstanceName`	The name of the DRM system.	No
`name`	Device name.	No
`physicalAddress`	The current IP address of the device, if available.	No
`profileID`	Can be used to retrieve device profile information from the Profile Service.	No
`UID`	Unique device identifier within the SDP. Can be used to query other APIs in the SDP but not any other modules or systems.	Yes

SetTopBox

This data structure provides the fields that classify a Set Top Box device.

Note that a Set Top Box is an instance of a Device, and that the Set Top Box data model extends the Device data model.

Name	Type	Description	Always available
`banned`	Boolean	If true, then this device is banned from using the system due to improper operation. Other devices in the account might be OK, and the account may otherwise be in perfectly good standing.	Yes
`caSN`	String (max 256 chars)	The Conditional Access Serial Number of the device CA chipset. Can be changed by a firmware change, but this isn't common, so can be used as a device identifier for signon.	No
`drmInstanceName`	String (max 320 chars)	Indicates which DRM the STB uses. Available from SMSDomain-1.3 and above.	No
`drmDeviceID`	String (max 50 chars)	DRM device ID. Available from SMSDomain-1.3 and above.	No
`externalGroupUID`	String	External group identifier.	No
`ipAddress`	String (max 20 chars)	The current IP address of the STB, if known and available.	No
`macAddress`	String (max 20 chars)	The MAC address of the STB.	No
`network`	String (max 256 chars)	A network identifier.	No
`nUID`	String (max 256 chars)	Uniquely identifies the device within a NAGRA STB deployment. Cannot be changed as it is hardwired in the hardware.	No
`port`	Integer	The port used for IP communication with the STB if needed.	No
`provisionId`	String	An optional ID that may be used during provisioning.	No
`provisionPwd`	String (max 10 chars)	An optional password that may be used to authenticate the Set Top Box during provisioning.	No
`serialNumber`	String (max 100 chars)	STB serial number.	No
`smartcardID`	String (max 100 chars)	The smartcard number. If the device is cardbased – it requires a physical smartcard – then this value is hardcoded on the smartcard itself. For a cardless device, this value is generated by the SDP, and paired to the device during provisioning. Can be used to retrieve the full smartcard data from the Smartcard service.	No
`smartcardType`	String (max 11 chars)	The smartcard type. One of: `CARDBASED` `CARDLESS` `UNSPECIFIED`	No
`status`	String	Device status. One of: `ACTIVE` `CANCELLED` `INACTIVE` `RESTRICTED` `SUSPENDED` If the device is cancelled, inactive, or suspended, then an end-user application should not be able to use it to query the API. For details see Account and STB Status.	Yes
`version`	String	The version of the software currently running on the device.	No

MediaPlayer

This data structure provides the fields that classify a Media Player (open) device.

Note that a Media Player is an instance of a Device, and that the Media Player data model extends the Device data model.

Name	Type	Description	Always available
`drmClientId`	String	The DRM client identifier.	No
`mediaPlayerId`	String	The identifer of the open device. Usually created by the DRM system during device initialisation.	Yes

Use Cases

SMSDomain Service

SDP Device Service

Retrieve device

Session Management

Summary

OpenTV Platform provides OTT session management to limit the number of concurrent streams and control the amount of bandwidth consumed by client apps.

Account profiles can include a maximum number of concurrent OTT streams. The client apps will attempt to set up a session for each new play-back session and SDP will enforce this limitation.

In addition, SDP offers an API for the operator to retrieve at any point in time the existing sessions of a given customer account and tear-down an existing session.

OTT Session Service: