Entities are the objects that store data in the database to represent different elements of a business service. All the data held in the system is either attached to a single Entity or represented as a relationship between Entities. Everything you can do with the system is performed by creating and manipulating Entities of different types, or by managing their relationships.
The relevant entities from the SMS/CRM perspective are listed below:
Rights management: AcquiredContentList, PolicyGroup.
The following diagram shows the main Entities used in the SMS domain along with their connections.
Account
An Account is a basic Entity which represents a physical subscriber who is the registered billable person. Metadata that describes the Account is held here, including some Account business operating limits. It has fields which store data such as the account number, and the contact name and billing address of the account holder. The account number is mandatory, so it must always be present. The address information is optional.
Several people can use the same Account. These people are Users of the Account. An Account is always associated with at least one User.
An Account also has a relationship with one or more Set Top Boxes. When creating a new Account, a subscriber management system also creates new Users and Set Top Boxes to associate with it, or uses Users and Set Top Boxes which have been previously created.
An Account should be assigned an AccessPoint to represent the infrastructure it uses to access media services.
Account data structure
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
36 reads
Account Status
The status of an Account defines what stage the Account is in its life cycle and determines what the subscriber can do.
Account status details
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:
19 reads
User
A User represents an end user who is entitled to view digital TV and media services. It has fields that store (amongst other things) a full name and an age rating for parental control purposes.
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.
A Device is an abstract entity that models the device running the client application used by subscribers to access the platform. Devices are classified into different types according to their capabilities to enable different business models (content types, commercial offer, device provisioning limits).
Devices can be Enabled or Disabled. Access to the platform from disabled devices will not be allowed.
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
15 reads
SetTopBox
A SetTopBox models a type of device used in cable or IP networks, typically in combination with a CAS head-end and embedding hardware-based security.
A SetTopBox adds specific device information like CASN, NUID used to identify it within the CAS system. It must be pre-provisioned before the device attempts to connect to the platform.
In a card-based CAS deployment, set-top boxes are linked to SmartCard objects.
SetTopBox data structure
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
30 reads
MediaPlayer
A MediaPlayer models open devices like desktop computers, handheld devices, connected TVs or pure OTT set-top boxes.
Such devices are not under control of the operator, therefore they must be created on-the-fly when they connect to the platform, authenticated typically through user credentials.
MediaPlayer devices can be associated to a DRM system for content protection.
MediaPlayer data structure
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
16 reads
SmartCard
In a card-based CAS environment, the SmartCard corresponds to a physical card that handles cryptographic authentication for an Account. It can also be used to represent virtual smart cards in cardless CAS systems.
Smartcard data structure
Name
Type
Description
Always available
casInstanceId
String (max 20 chars)
Identifies the CAS system that this smartcard belongs to.
Yes
modificationDate
dateTime
Date and time the smartcard was last modified.
No
originId
Integer
An identifier for the system which owns this smartcard.
Identifiers up to 9999 are reserved for identifying systems pre-integrated with SDP. Operators can define their own meanings for values of 10000 and above.
No
originKey
String (max 20 chars)
The key or identifier that the system that owns this smartcard uses to identify it.
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.
Yes
status
String
The status of the smartcard, one of:
AVAILABLE – this smartcard is not allocated to an STB, so is available to be assigned. This status is only applicable in card-based systems.
UNAVAILABLE – this smartcard is in use by an STB.
CANCELLED – this smartcard has been cancelled and cannot be re-used.
Yes
stbUid
Long
Unique ID of the STB.
Available from SMSDomain-1.3 and above.
No
statusCode
String
This returns the status of the smartcard.
Allowed values are:
AVAILABLE(A)
UNAVAILABLE(U)
CANCELLED(C)
Available from SMSDomain-1.3 and above.
No
11 reads
JavaScript errors detected
Please note, these errors can depend on your browser setup.
If this problem persists, please contact our support.
