Image Removed

Introduction

We need a design confluence page for this KN BSS Integration.

1. Data flow diagrams for each of use cases.
2. Get it reviewed by leads
3. Get these flows accepted by customer and third-parties involved

Once these are done, development team can start working on the Epic

Ticket:

Jira Legacy

server	24i
serverId	de9265ec-7df1-3171-8c6c-74fc0056a720
key	BPLAT-7116

Overview of BSS integration

Phase 1: No integration, users are provisioned through CMS

Phase 2: NetAdmin will provision users through an API as part of the vending process

Resources

KN ITV Channel configurations v1.5.xlsx

Table of Contents

Big picture

Use case diagrams

Create new user (phase 2 only)

Non-technical flow diagram

This page details all of the BSS integration points to manage STB and users.

This document is comprised of two sections:

An overview of the user stories - User Stories - business integration
A more detailed exploration of each call that the customer needs to make - Details of calls

Solution overview

There are two steps for Customer:

Create a user account
Link the STB to the user account

Details of exactly how to do this are given below on this page.

The STB will be able to identify itself to Amino API, which links it to a user. Details of how this works are available at (BSS) Passwordless STB login

Summary of data integration

This table summarizes the data we need

Item number	Data	Provided by	How it is provided
1	User account to be created	Customer	POST https://domain.tld/api/management/user
2	Serial number of the STB that was sold	Customer	POST https://domain.tld/api/management/stb/link_user
3	User identity of the person the STB was sold to	Customer	POST https://domain.tld/api/management/stb/link_user
4	STB serial number when logging in	Amino	Embedded in a signed JWT token

Note: Items 2 and 3 are supplied in the SAME call to link_user, there is not a duplicate call made

Table of Contents

User Stories - business integration

New User buys new STB

	Action	API call required	Offline business process required
1	User go to Customer store and buy a new STB		Capture user details and the STB serial number
2	Customer system then provision new user	Create user account
3	Customer system then link the STB to that user	Link user account to STB
4	User go home and turn on the new STB
5	STB uses the key included in the firmware to sign a JWT that includes the STB serial number as a "sub" claim
6	Amino API uses the JWT and the linkage from step 3 to determine which user to log in

Existing User buys new STB

	Action	API call required	Offline business process required
1	User go to Customer store and buy a new STB		Capture user details and the STB serial number
2	Customer then link the STB to the existing user account	Link user account to STB
3	Optionally, Customer unlinks the old STB	Remove STB Ownership from an User
4	User go home and turn on the new STB
5	STB uses the key included in the firmware to sign a JWT that includes the STB serial number as a "sub" claim
6	Amino API uses the JWT and the linkage from step 2 to determine which user to log in

Existing user sell his/her STB

	Action	API call required
1	User A sells his/her STB to user B
2	User A call Customer to unlink the STB from his/her account	Remove STB Ownership from an User	Capture user details and the STB serial number
3	User B call Customer to link the STB to his/her account	Link user account to STB
4	Customer captures information and:		Capture user details and the STB serial number
4a	Unlink the STB from user account A	Remove STB Ownership from an User
4b	Link the STB to user account B	Link user account to STB
5	User B turns STB on after being told the linking is complete
6	STB uses the key included in the firmware to sign a JWT that includes the STB serial number as a "sub" claim
7	Amino API uses the JWT and the linkage from step 3 to determine which user to log in

Manage user entitlements

	Action	API call required
1	Entitle a user to a package	Entitle user to "A" package
2	Remove entitlement from user to package	Remove user entitlement to "A" package

Details of calls

Link user account to STB

Flow diagram (non-technical)

Image Added

Code Block

theme	Midnight
collapse	true

title Create newLink user account noteto leftSTB
of
Aminonote factoryright of Customer
At manufacture time end noteCustomer Aminocaptures factory->Move API: List of STB serial numbersuser account
    and keysthe noteSTB right of NetAdmin:
  At sale timeserial number
end note
NetAdminCustomer->Move API: User identity and their STB serial number

Which endpoint NetAdmin should use

NetAdmin will POST to https://boox.fi

POST https://domain.tld/api/management/stb/link_user
Move API->Customer: 200 OK

Technical details

Customer will POST to https://domain.tld/api/management/stb/link_user

Request

Method	URL	Authorization
POST	https://domain.tld/api/management/stb/link_user

Parameter

IP

LocationMandatoryDescriptionservice_tokenQuery

Token generated for a service. This param will be skipped if Service-Token HTTP Header exists

Parameters

Please note that M is for Mandatory and O is for Optional.

Parameters	M/O	Description	Values
service	O	Service to which the user belongs.	String of service username. Shared separately.
serial_no

Query

M

Serial Number of STB. If device does not exists with provided serial no then it will be added.	Alpha numeric string. e.g. 615507895162
email

Query

M

Email

address

address of user who is provisioned for using the STB	Valid email address. e.g. john.doe@example.com
public_keys

Query

M	This may be configured to be optional in your deployment, please check with your account manager
chipset_id

Query

O	STB device chipset number/ID.	chipset_id is a random list of characters (max 32 characters).
mac

Query

How the user will sign in

See /wiki/spaces/BPLAT/pages/38550375 to see the process of letting the user sign in.

Entitle user to "A" OTT package

TBC: What Move API must be called by KN? Do we need to provision a new endpoint like the one at Channel License

Image Removed

Code Block

theme	Midnight
collapse	true

title Entitle user to "A" OTT package

KN BSS->Move API: GET /api/user/<email>/product/<product_id>/buy/option/<option_id>
Move API->Irdeto: SOAP entitlement call
Irdeto->Move API: 200 OK
Move API->KN BSS: 200 OK

Entitle user to "Start" DVB package

O

Ethernet interface MAC address.

mac is a random list of characters (max 18 characters).

Response

HTTP Code Response

200

{

	"id": "123",
	"serial_no": "CUS-STB0001",
	"user": {
		"id": "10001",
		"email": "stb_user@cusstb.com"
	}
}

400

{
  "error" {
    "code": 9,
    "text": "Access to this resource is locked to IP addresses"
  }
}

401 none

Error Codes

Error Code	Description
1414	Email does not exist
1426	Parameter is required
1427	Invalid length of chipset_id
1428	Invalid length of mac
1433	STB exists and linked
1434	Record already exists for value
1435	STB is already assigned
1436	Invalid email address format

How the user will sign in

See (BSS) Passwordless STB login

Remove STB Ownership from an User

Technical details

Customer will POST to https://domain.tld/api/management/stb/unlink_user

Request

Method	URL	Authorization
POST	https://domain.tld/api/management/stb/unlink_user	IP

Parameters

Please note that M is for Mandatory and O is for Optional.

Parameters	M/O	Description	Values
service_token	O	Token generated for a service. This param will be skipped if Service-Token HTTP Header exists.
serial_no	M	Serial Number of STB.	Alpha numeric string. e.g. 615507895162
email	M	Email address of user who is provisioned for using the STB	Valid email address. e.g. john.doe@example.com

Error Codes

Error Code	Description
1414	Email does not exist
1426	Parameter is required
1432	STB serial_number does not exist
1418	Invalid STB link, Service (Using service_token)

Version	Old Version 11	New Version Current
Changes made by	Andy Beak (Unlicensed)	Tung Hoang
Saved on	Sept 18, 2018	May 08, 2019

Versions Compared

Key

Introduction

Overview of BSS integration

Resources

Big picture

Use case diagrams

Create new user (phase 2 only)

Non-technical flow diagram

Solution overview

Summary of data integration

User Stories - business integration

New User buys new STB

Existing User buys new STB

Existing user sell his/her STB

Manage user entitlements

Details of calls

Link user account to STB

Flow diagram (non-technical)

Which endpoint NetAdmin should use

Technical details

Request

Parameters

How the user will sign in

Entitle user to "A" OTT package

Response

Error Codes

How the user will sign in

Remove STB Ownership from an User

Technical details

Request

Parameters

Error Codes

Content Comparison

Versions Compared

Key

Introduction

Overview of BSS integration

Resources

Big picture

Use case diagrams

Create new user (phase 2 only)

Non-technical flow diagram

Solution overview

Summary of data integration

User Stories - business integration

New User buys new STB

Existing User buys new STB

Existing user sell his/her STB

Manage user entitlements

Details of calls

Link user account to STB

Flow diagram (non-technical)

Which endpoint NetAdmin should use

Technical details

Request

Parameters

How the user will sign in

Entitle user to "A" OTT package

Response

Error Codes

How the user will sign in

Remove STB Ownership from an User

Technical details

Request

Parameters

Error Codes