SmartTUBE 5. OSS and BSS API description - SmartLabs · After that billing is performed in the OSS/BSS until a subscriber or the OSS/BSS cancels the subscription. When the term of

Document released on 10.04.2017

©2017 SmartLabs

SmartTUBE 5. OSS and BSS API description

105318, Russia, Moscow, Shcherbakovskaya str., b. 3. page 2 out of 31 Ph.: (495)645-44-56 http://www.smartlabs.tv CONFIDENTIAL

©2017 SmartLabs, LLC.

This guide contains the Application Programming Interface (API) description intended

for integration of SmartTUBE (Multiscreen Media Service Delivery Platform) with

operator’s Operation and Business Support Systems (OSS/BSS).

SmartLabs LLC is able to change and improve any product described in this guide, to

change the use conditions and description, and also to edit the guide itself without

preliminary notice. Please, follow the changes on our web site.

SmartTUBE, SmartLabs logo are trademarks of SmartLabs, LLC.

Confidential. No part of this document can be reissued, republished or distributed

without the permission of SmartLabs.


Contents 1 Terms and abbreviations .......................................................................................... 4

2 Intended audience .................................................................................................... 6

3 Introduction .............................................................................................................. 7

4 SmartTUBE object model ......................................................................................... 9

5 Method invocation .................................................................................................. 11

6 Return Value Processing ........................................................................................ 12

6.1 SmartTUBE errors ............................................................................................ 13

7 Service account states ........................................................................................... 15

8 Methods Description .............................................................................................. 16

8.1 SmartTUBE methods ....................................................................................... 16

8.1.1 Adding a service account and a connection .............................................. 16

8.1.2 Creating a service account from a template .............................................. 17

8.1.3 Editing a service account ........................................................................... 18

8.1.4 Deleting a service account ......................................................................... 19

8.1.5 Adding a device ......................................................................................... 19

8.1.6 Editing a connection to a device ................................................................ 20

8.1.7 Deleting a connection to a device .............................................................. 21

8.1.8 Changing the pricing plan .......................................................................... 21

8.1.9 Adding or refusing from a service .............................................................. 22

8.1.10 Getting information about a service account .......................................... 23

8.1.11 Getting the list of services ...................................................................... 24

8.1.12 Sending a message ................................................................................ 25

8.1.13 Removing purchased content and services ............................................ 25

8.1.14 Getting reports on service accounts ....................................................... 26

8.2 OSS/BSS methods ........................................................................................... 28

8.2.1 Purchasing content .................................................................................... 29

8.2.2 Adding or refusing from a service .............................................................. 29


1 Terms and abbreviations API

Application Programming Interface

SmartTUBE 5

The platform for delivering services and managing subscriber accounts, content and

other resources of the IPTV/OTT system

AdminUI

Web application for managing SmartTUBE 5

OSS/BSS

Operation Support System/Business Support System – a system or several systems of

the operator to manage subscriber accounts, products and services, and to monitor

service consumption. Usually the system involves Automated Billing, Order

Management, and more features

IPTV

Internet Protocol Television – provision of multimedia services in IP networks of a

certain operator

OTT

Over-the-Top – provision of multimedia services over the Internet

STB

Set-top box

Operator

IPTV/OTT service provider


Subscriber

A person, who concludes a contract with the service provider in order to get access to

certain services

Pricing plan

Terms and cost of service delivery during the specified period of time. You can set only

one pricing plan for a service account

Service

The bundle of uniform content items or functionality (e.g. TSTV) included in a pricing

plan


2 Intended audience This document is intended for qualified technical service personnel, engineers and

software developers of the Customer, including third-party specialists, responsible for

SmartTUBE integration with the Operator’s OSS/BSS.


3 Introduction Integration of an operator’s OSS/BSS and the SmartTUBE is normally performed on a

per project basis and depends on the operator’s business processes and service and

pricing management mechanisms. However, there are some basic principles that are

applicable to the majority of such projects.

Prices and billing cycles are set in OSS/BSS

As a rule, when integration of OSS/BSS and SmartTUBE is configured, the operator’s

OSS/BSS renders invoices, charges for purchases and defines billing cycles. The

SmartTUBE is not a billing system, it does not perform any billing system duties such as

accounting, billing or charging. Any prices, fees, or billing cycles specified in a pricing

plan in the SmartTUBE are for informational purposes only, to be displayed in a

subscriber’s user interface at service subscription or at content purchasing. When a

user subscribes to a service (buys content), the SmartTUBE sends the service ID to the

OSS. The OSS uses this ID to identify the service and its price to charge for

subscription.

When integration with OSS/BSS is not configured, the SmartTUBE can withdraw money

for purchases that are paid for with a card. In such a case, prices and billing cycles are

set in the SmartTUBE.

SmartTUBE does not use subscribers' personal data. Such data is stored in

OSS/BSS

It is assumed that the operator’s OSS/BSS stores information about subscribers, their

accounts, pricing plans and services available to subscribers within their pricing plan.

The SmartTUBE maintains its own database that contains similar information, but the

SmartTUBE does not have access to subscribers' personal data; it uses only abstract

IDs that are associated with subscribers' accounts in the OSS/BSS. A service account

in the SmartTUBE is associated with the information about the subscriber’s pricing plan

and interactive TV services available within this pricing plan.

Data in the SmartTUBE and OSS/BSS databases is synchronized

Integration of SmartTUBE and OSS/BSS requires that the information used for

providing services is consistent in both databases. Such data – information on a

subscriber's status, pricing plan and subscribed services list – is synchronized by

means of the API methods described in this document. Other data, such as parameters

of the pricing plan and services description, is specified manually in the AdminUI

management interface.

In order to cross-refer the data stored in the SmartTUBE and OSS/BSS databases,

most objects in the SmartTUBE have an external identifier (ExternalID) that contains the

ID of the corresponding object in the operator's OSS/BSS.

API methods to facilitate integration


Two groups of methods must be implemented to facilitate integration of the OSS/BSS

and the SmartTUBE on the interaction initiator:

1. SmartTUBE-side methods (interaction is initiated by a subscriber), 2. OSS/BSS-side methods (interaction is initiated by the OSS/BSS). Important. OSS/BSS-side methods described in this document are prototypes of the

features that can be implemented in the OSS/BSS to solve certain business tasks.

Methods implemented on the side of the SmartTUBE ensure interaction when the

OSS/BSS initiates changes. These methods allow you to do the following tasks:

Subscriber management (adding/removing subscribers, changing account states, and more)

Pricing plan subscription management.

For example, if on the side of the OSS/BSS a new account is added, the OSS/BSS

must call the SmartTUBE-side method to inform the SmartTUBE that the corresponding

service account must be created in the SmartTUBE.

Methods implemented on the side of the OSS/BSS facilitate interaction when a

subscriber initiates changes, for example when a subscriber is purchasing content or

subscribing to services available within their pricing plan.

When a subscriber is the initiator, the workflow is as follows:

1. The client application sends the request to the SmartTUBE. Important. The client application never addresses the OSS/BSS directly; all requests are sent through the SmartTUBE.

2. The SmartTUBE server calls the OSS/BSS-side method. 3. The call returns a reply to the SmartTUBE server. The SmartTUBE takes information

from this reply and sends it to the client application.

http://docs.int.smlabs.net/pages/viewpage.action?pageId=6389923


4 SmartTUBE object model Service Account. The ServiceAccount entity uniquely identifies each subscriber in the

SmartTUBE and contains information on connected devices, subscriber's regional

settings, and a reference to a pricing plan (the ProductOffer entity). Typically, a service

account corresponds to a subscriber’s account in the OSS/BSS.

Note. Test service accounts are used in the SmartTUBE 5 for testing. When operating

under test service account, the SmartTUBE 5 does not address the OSS/BSS

(OSS/BSS methods are not called; it is considered that they are executed successfully).

Subscriber's device. This device provides subscribers with access to services. The

SmartTUBE can work with different types of devices, such as:

STB – a set-top box,

WEB – a web portal,

IPHONE – iPhone,

IPAD – iPad,

OTTSTB – an OTT set-top box,

ANDROID – an Android device,

Smart TV LG,

Smart TV Samsung.

The type of the connection is determined using the external ID (deviceType) – the

EXTERNALID parameter.

Note. By default devices are registered automatically when accounts are created from

templates. Device activation using a code and a number is needed if this feature is

disabled. The use of this feature depends on the business model of providing services

by an operator.

The login and password are used to authorize web connections.

The client application profile belongs to a certain service account: it is the same for all

connections.

Pricing plan and services. A service account can be associated with only one pricing

plan (the ProductOffer entity) at any given moment. A pricing plan is a fixed list of

services. On the server, the services can be filtered by the device type specified in the

deviceType parameter. The device can get only the services and prices that are


available to all devices or this particular device type within the pricing plan. One or

several devices of the specified type that are bound to the same service account are

subscribed to the same service by the SmartTUBE server. You can customize the

service attributes in a pricing plan. For example, for the service to be enabled by

default, set its status to 'Active'. You may also configure the restriction so that a

subscriber cannot disable the service.

The cost and usage conditions of each service are set in a price list. Each content type

in the SmartTUBE model has its own price list type determined by the discriminator. The

following types of price lists are possible:

One-time purchase – a fee for the service paid once. The SmartTUBE allows you to specify additional parameters (rules) for such services to configure differentiated pricing, for example, a rule to charge for the duration of the service (a day, month, year, forever, etc.).

Subscription – a fee paid at a certain period of time (the OSS/BSS charges for subscriptions). The SmartTUBE allows specifying duration for subscription-based services.

Important. The SmartTUBE sends a subscription command to the OSS/BSS once.

After that billing is performed in the OSS/BSS until a subscriber or the OSS/BSS

cancels the subscription. When the term of rendering a "one-time" service expires, the

service is disabled in the SmartTUBE automatically.

Service consumption history

The service consumption history (content purchases, subscriptions/unsubscriptions, etc)

is stored in the SERVICE_USAGE table.

The history of pricing plan changes is stored in the

SERVICE_ACCOUNT_PO_HISTORY table.

The history of changes of the service account state (ACTIVE, NOT ACTIVE, BLOCKED,

CLOSED, DELETED) is stored in the SERVICE_ACCOUNT_HISTORY table.


5 Method invocation API methods are called using HTTP(-S) GET or POST requests. The type of the

protocol (HTTP or HTTPS) depends on the server settings.

On the side of the SmartTUBE

The syntax of an API method call using GET is as follows:

http[s]://<server address>:<server port>/<prefix>/integrationapi/<method

name>? <parameter 1>=<value 1>&<parameter 2>=<value 2> ...

The <prefix> value depends on the SmartTUBE server deployment settings, its version

and installed components. For example, it can be sdpapidb.

Exception: The report method for creating reports has its own syntax. See section

Getting reports on service accounts.

On the side of OSS/BSS

The syntax of an API method call using GET is as follows:

http[s]://<server address>:<server port>/<method name>? <parameter 1>=<value

1>&<parameter 2>=<value 2> …

Sending parameters in a request

There are 3 ways to define parameters within a request:

In a GET request string;

In a POST request body as application/x-www-form-urlencoded parameters;

In an HTTP header using the smartlabs_ prefix, for example,

smartlabs_parameter1.

For example, an HTTP GET request to call method1 with parameters param1=value1 and

param2=value2 will look like this:

http://111.111.0.1:8080/prefix/method1?param1=value1&param2=value2

http://111.111.0.1:8080/prefix/method1?param1=value1&param2=value2


6 Return Value Processing When a method is executed successfully, the OSS or the SmartTUBE returns data in

JSON format.

If a method is executed successfully, the OSS or the SmartTUBE returns code="0" and

for some methods also fields in the following format:

{

"code":0,

"field 1":"field 1 value",

"field 2":"field 2 value",

"field 3 - list":[

{

"field 3.1":"field 3.1 value for the list item 1",

"field 3.2":"field 3.2 value for the list item 1"

}

{

"field 3.1":"field 3.1 value for the list item 2",

"field 3.2":"field 3.2 value for the list item 2"

}

]

}

Example:

The accountInfo method can return the following data:

{

"code":0,

"message":"Ok",

"name":"sa_name",

"state":"ACTIVE",

"createdAt":"06/02/2013 15:33:22",

"productOffer":"PRODUCT1",

"terminalList":[

{

"uuid":"3333333!E3:33:33:33:03:33",

"deviceType":"STB"

}

{

"uuid":"1111111!E1:11:11:00:01:11",

"deviceType":"STB"

}

]

}

If an error occurred during method execution, the OSS or the SmartTUBE returns the

code that is not 0 and the corresponding error message.


On the side of the SmartTUBE

code="1" indicates a general error at method execution.

If an error occurs, information about the error is returned:

{

"code":error code,

"message":"text"

}

For example {"code":106,"message":"Account not found"}.

Several error codes can be returned. For example, when an SmartTUBE method is

invoked with only one parameter specified out of three required, the server returns an

error message about each of the parameters that are not specified.

In case of a fatal error an HTTP error code is returned, for example 500.

Other errors that may occur on the side of the SmartTUBE are described in SmartTUBE

errors.

On the side of the OSS/BSS

If an error occured, its description returns in the following format:

{

"code":code,

"logMessage":"full error description to display in the log",

"userMessage":"error message to display on a device",

}

6.1 SmartTUBE errors

The list of possible errors on the side of the SmartTUBE:

Code Text

1 Internal error

50101 Account state not found

50102 Product offer not found

50103 Account already exist

50104 Service provider not found

50105 Template not found


50106 Account not found

50107 Device type not found

50108 Terminal not found

50109 Service spec not found


7 Service account states There is an external ID for each of the states of a service account in SmartTUBE.

Service account state Description External ID

Active The application works normally. The user has access to service in accordance with the pricing plan set for the service account

ACTIVE

Not active A new service account, no active connections.

The application is loaded; thereafter the service account state changes to ACTIVE

NOT ACTIVE

Blocked (for example, when there are no money on the account)

The application is started without access to services. Under this service account, the user cannot watch TV or purchase movies

BLOCKED

Closed (the agreement is terminated)*

The application will not start CLOSED

Deleted (the agreement is terminated)*

The application will not start DELETED

* – from the point of view of SmartTUBE, the states CLOSED and DELETED are the

same. If a service account is in one of these states, services and content are not

delivered and subscriptions are not available.


8 Methods Description This section contains the detailed description of all integration API methods.

8.1 SmartTUBE methods

List of methods implemented on the side of the SmartTUBE:

Method Purpose

createAccount Adding a service account and a connection

createAccountByTemplate Creating a service account from a template

updateAccount Editing a service account

deleteAccount Deleting a service account

addTerminal Adding a device

updateTerminal Editing a connection

deleteTerminal Deleting a connection to a device

changeProductOffer Changing the pricing plan

subscribeService Adding a service

accountInfo Getting information about a service account

accountServiceList Getting the list of services

sendAccountMessage Sending a message

resetAccount Removing purchased content and services

report Getting reports on service accounts

8.1.1 Adding a service account and a connection

Purpose

The method creates a service account and adds a connection on this account if needed.

Method name

createAccount

Call parameters


Parameter Type Mandatory? Description

accountNumber String yes The service account number

productOffer String yes An external ID of the pricing plan. You can create the pricing plan in SmartTUBE web interface; its external ID is set in the web interface as well (see the document SmartTUBE 5. Administration guide)

name String yes Name of the service account

accountState String yes An external identifier of the service account state

login String no Login for the device activation

password String no Password for the device activation

uid String no Unique ID of the connection

deviceType String no Device type (see SmartTUBE object model)

location String no Is taken into account only if the uid parameter is passed.

The external identifier of a region for the connection.

The value of this parameter is used at SmartTUBE server for filtering TV-channels, which can be streamed on the subscriber's device

Return value

code="0" is returned in case of success.

8.1.2 Creating a service account from a template

Purpose

The method creates a service account from a template and adds a connection on this

account if needed.

Method name

createAccountByTemplate

Call parameters




template String yes Template name (same as in the SmartTUBE web interface)

name String yes Name of the service account

accountState String yes An external identifier of the service account state



uid String no Unique ID of the connection

location String no Is taken into account only if the uid parameter is passed.

The external identifier of a region for the connection.


Return value


8.1.3 Editing a service account

Purpose

The method applies changes to a service account.

Method name

updateAccount

Call parameters




name String no Name of the service account

accountState String no An external identifier of the service account state



stateMessage String no Reason for changing the account state

profilePin String no PIN. If you specify the PIN, it will be applied to all the profiles on the service account

Return value


8.1.4 Deleting a service account

Purpose

The method deletes a service account and all the information about it.

Method name

deleteAccount

Call parameters



Return value


8.1.5 Adding a device

Purpose

The method creates a connection to a device on a service account.

Method name

addTerminal

Call parameters




uid String yes Unique ID of the device

deviceType String yes Device type (see SmartTUBE object model)



terminalName String no Name of the connection

location String no The external identifier of a region for the connection.


Return value


8.1.6 Editing a connection to a device

Purpose

The method applies changes to the parameters of device connection.

Method name

updateTerminal

Call parameters



newUid String no New unique ID of the device

deviceType String no Device type (see SmartTUBE object model)




terminalName String no Name of the connection

location String no The external identifier of a region for the connection.


Return value


8.1.7 Deleting a connection to a device

Purpose

The method deletes a connection to a device.

Method name

deleteTerminal

Call parameters


uid String no Unique ID of the device

Return value


8.1.8 Changing the pricing plan

Purpose

The method changes the pricing plan of the account.

Method name

changeProductOffer

Call parameters




productOffer String yes An external ID of the pricing plan. You can create the pricing plan in SmartTUBE web interface; its external ID is set in the web interface as well (see the document SmartTUBE 5. Administration guide)

Return value


8.1.9 Adding or refusing from a service

Purpose

The method adds or removes a service for the service account.

Method name

subscribeService

Call parameters



serviceEId String yes An external ID of the service (see the document SmartTUBE 5. Administration guide)

state String yes Action:

1 – add a service

0 – refuse from a service

startDate MM/dd/yyyy HH:mm:ss

no Date of the service delivery start

stopDate MM/dd/yyyy HH:mm:ss

no Date of the service delivery end

isProcessExclusive Number no An attribute indicating that mutually exclusive services must be taken into account (see the document SmartTUBE 5. Administration guide):


1 – taken into account,

0 – not taken into account

isProcessBundle Number no An attribute indicating that dependent services must be taken into account (see the document SmartTUBE 5. Administration guide):

1 – taken into account,

0 – not taken into account

Return value


8.1.10Getting information about a service account

Purpose

The method returns data on a service account.

Method name

accountInfo

Call parameters



Return value

If executed successfully, the method returns the following data:

Field Description

createdAt Date of service account creation

name Name of the service account


productOffer An external ID of the pricing plan. You can create the pricing plan in SmartTUBE web interface; its external ID is set in the web interface as well (see the document SmartTUBE 5. Administration guide)

state An external identifier of the service account state

terminalList List of devices connected to the service account.

Each device is defined by the following parameters:

deviceType – device type (see SmartTUBE object model)

terminalName – name of the connection

uuid – unique ID of the device

8.1.11Getting the list of services

Purpose

The method returns the list of services provided to the service account.

Method name

accountServiceList

Call parameters



Return value

If executed successfully, the method returns the following data for each of the services:

Field Description

canBeSubscribed Attribute showing whether the service is available for subscription

deviceType Device type (see SmartTUBE object model)

startDate Date of service delivery start

endDate Date of service delivery end

externalid External identifier of the service


isActive Attribute indicating whether the service is active (true/false)

name Name of the service

type Service discriminator, for example CHANNELPACKAGE

8.1.12Sending a message

Purpose

The method sends a text message.

Method name

sendAccountMessage

Call parameters



message String yes The message text

Return value


8.1.13Removing purchased content and services

Purpose

This method removes purchased services and/or content from the service account.

Method name

resetAccount

Call parameters



resetService Number no Possible values:

1 (default) – remove all services from the service account. As a result, only services included in the pricing plan will be available to the


user of this service account.

0 — do not remove services from this service account

resetPurchase Number no Possible values:

1 – remove all content from the service account. Content will become unavailable to this service account.

0 (default) – do not delete content

Return value


8.1.14Getting reports on service accounts

To get different information on service accounts (states, connections, purchases, etc)

you may use the report method. The syntax of this method is as follows:

http[s]://<server address>:<server

port>/report?run_report_id=<value>&<parameter 2>=<value 2> ...

Common parameters


run_report_id String yes The identifier of the report. It determines the contents of the report

accountNumber String no The service account number

States and a pricing plan

Value of the run_report_id – OSS_ACCOUNT_TARIF.

Return value


Field Description

accountnumber The service account number

state An external identifier of the service account state (see Service


account states)

product An external ID of the pricing plan. You can create the pricing plan in SmartTUBE web interface; its external ID is set in the web interface as well (see the document SmartTUBE 5. Administration guide)

Connections

Value of the run_report_id – OSS_TERMINAL.

Return value


Field Description


uid Unique ID of the device

lastauthdate Date of the last authorization in the "DD/MM/YYYY hh:mm:ss" format

devicetype Device type (see SmartTUBE object model)

Purchasing content

Value of the run_report_id – OSS_PURCHASE.

For this run_report_id you may also specify the following parameters:


date_start MM/dd/yyyy HH:mm:ss

no Start date of the report data range

date_end MM/dd/yyyy HH:mm:ss

no End date of the report data range

Return value


Field Description


usagedate Date of the purchase in the "DD/MM/YYYY hh:mm:ss" format


stopdate Expiration date of the purchase validity in the "DD/MM/YYYY hh:mm:ss" format. NULL, if there are no restrictions

contentid ID of the purchased content

price Price for the purchased content

Adding a service

Value of the run_report_id – OSS_SUBSCRIPTION.

For this run_report_id you may also specify the following parameters:


date_start MM/dd/yyyy HH:mm:ss

no Start date of the report data range

date_end MM/dd/yyyy HH:mm:ss

no End date of the report data range

Return value


Field Description


usagedate Date of the service subscription in the "DD/MM/YYYY hh:mm:ss" format

stopdate Expiration date of the service validity in the "DD/MM/YYYY hh:mm:ss" format. NULL, if there are no restrictions

service An external ID of the service (see the document SmartTUBE 5. Administration guide)

price Price for adding the service

8.2 OSS/BSS methods

List of methods implemented on the side of the OSS/BSS:

Method Purpose

purchase Purchasing content


subscribe_request Adding a service

8.2.1 Purchasing content

Purpose

The method purchases content.

Method name

purchase

Call parameters





contentType String yes Type of the content:

METACONTENTBUNDLE – season,

METAEPISODE – episode,

METAMOVIE – movie,

METASERIES – series

contentId Number yes ID of the purchased content

contentName String no Name of the content in the language that has the highest priority in Admin UI

price Number yes Price for the purchased content


no Expiration date of purchase validity

Return value


8.2.2 Adding or refusing from a service

Purpose


The method sends data on the service that is being added or removed. Based on the

reply the decision is made on the SmartTUBE side whether to add a service or not.

Method name

subscribe_request

Call parameters





serviceEId Number yes An external ID of the service (see the document SmartTUBE 5. Administration guide)

serviceName String no Name of the service in the language that has the highest priority in Admin UI

state String yes Action:

1 – add the service

0 – refuse from the service

price Number yes Price for adding the service


no Expiration date of the service validity

Return value


Field Description

immediately An attribute indicating the necessity to add or remove a service on the side of the SmartTUBE:

true – the service is added or removed at once,

false – the service will not be added or removed until the

request subscribeService is received (see Adding a service). This value is recommended if, for example, generating a reply


to this method call takes more than 5 seconds

Example: { "code":0, "immediately":true }

Documents

SmartTUBE 5. OSS and BSS API description - SmartLabs · After that billing is performed in the OSS/BSS until a subscriber or the OSS/BSS cancels the subscription. When the term of