NBI Technical Description¶
NBI provides functionality to extract subscriber billing related information from VOSS-4-UC whenever a subscriber change occurs, and to send this information (in a payload) to a northbound billing system.
NBI includes a call back service, which is utilized by the northbound system to provide status updates for each billing message sent. Billing-related changes include changes made to both subscribers directly or to their associated devices and services.
NBI monitors for changes by connecting to one of the VOSS-4-UC nodes and observes transactions within the VOSS-4-UC Transaction Log. Connectivity details are discussed below and are defined in the NBI configuration file.
Access to NBI for administration functions is through the NBI Admin GUI (Web Portal).
Major Functions and Features¶
This section describes NBI in terms of its major functions and features:
- Voss NBI Module
- NBI Administration Portal (GUI)
- Access Control to NBI GUI
- Real-time Billing Payload
- Billing Reconciliation Support (SDE Report)
- Extract Function (EXTRACTOR PROCESS)
- Transmit Function (NOTIFIER PROCESS)
- Call Back Function (CALLBACK PROCESS)
- Tracking Table
- Connectivity
- Provisioning Control (Site Transition flag)
- Configuration
- Diagnostics
- Provisioning Control (User State) and managing Go-Live Dates
- Managing Site and Subscriber Information
VOSS NBI Module¶
NBI is a single server appliance that runs on the Ubuntu operating system:
- Small footprint - limited disruption to existing service (this is an add-on)
- Server separation - reducing load on the live VOSS-4-UC application
NBI consists of the billing payload and three functions to Extract changes, Transmit payloads northbound and, to receive status updates back (Call Back).
A single NBI (only) is connected to a VOSS-4-UC cluster.
NBI Administration Portal (GUI)¶
The NBI Web-based Administration Portal (GUI) provides the ability to:
- View details on all sent messages - information is extracted from the Tracking Table (including message status)
- Control default Subscriber States (new Subscriber detected)
- Set Subscriber State (Pending, Live), and manage Go-Live dates
- Manage Subscribers individually, or through Bulk Load
- Manage overall Site Transition status (on/off)
Additionally, flexible filters provide the ability to easily search and locate in the different views. It is also possible to export (XLS, JSON, CSV) and import data.
Access Control to the NBI GUI¶
Secure credentials are required to access the NBI Admin GUI. The same administrator login details are used for the main VOSS-4-UC application.
Real-time Billing Payload¶
Whenever a subscriber is changed, a billing information payload is generated in near real-time and is sent northbound. This billing information payload, which may be customized according to the requirements of the receiving system, contains information about:
- The Subscriber
- The action taken (Add/Change/Delete)
- The set of associated devices and services that have been provisioned or changed
Billing Reconciliation (SDE Report)¶
NBI may be configured to generate a billing friendly report export, which may be used by the northbound system to run a lower frequency reconciliation process. This JSON format report has a configurable schedule, and can be made available to all customers or to a selection of customers. The content is configurable based on the requirements of the northbound system, and the output is deposited to a local NBI media directory.
Extract Function (Extractor Process)¶
NBI detects changes to the live service by polling for new entries in the VOSS-4-UC Transaction Log. Once a change is detected (known as a Trigger Event), NBI uses the standard VOSS-4-UC APIs to extract subscriber and service information and builds a standard, JSON format billing payload. Payloads are stored in the Tracking Table, and are marked as READY for sending by the Transmit Function.
Note
The full list of Trigger Events that cause NBI to create a payload are documented in the appendix.
To maintain the chronology of events, NBI processes top level transactions sequentially from the VOSS-4-UC database. The system includes mechanisms to prevent processing being blocked by large bulk load and data sync jobs that may be running on the transaction log.
If NBI is taken offline or loses the connection with VOSS-4-UC, it retains a record of the last transaction processed and catches up once it is brought back online.
NBI typically connects to Secondary Database Nodes so that undue load is not placed on the main Primary Database Node in the VOSS-4-UC cluster (although this is configurable).
NBI automatically connects to the Primary Database Node for write operations and replication-lag-sensitive read operations.
In a typical installation, to provide redundancy and load distribution, a list of Secondary Database Nodes is configured in addition to the Primary Database Node.
The VOSS-4-UC Transaction Log is polled to detect changes to the live system. To reduce load on the node, the polling period defaults to 5 minutes. A regular, scheduled job (‘nbi_sync’), keeps the NBI synchronized with VOSS-4-UC (specifically, for Customer, Site and Subscriber information). This job may run overnight, and provides a key mechanism to get new Subscribers loaded into NBI.
Transmit Function (Notifier Process)¶
The Transmit Function regularly searches for payload messages in the Ready state, and then sends these northbound (via HTTP, or secure HTTPS), over a RESTful API service to a well-known destination URL.
Payload transmission may be buffered or re-sent in case of underlying network issues or if the northbound system is busy. Once the northbound system receives the messages, they are marked as UserInProgress. If network failures persists, messages are marked as SendFailed.
Note
The Transit Function automatically retries sending a payload message several times, in case of intermittent issues on the underlying network.
Call Back Function (Callback Process)¶
NBI supports a Call Back function and tracking mechanism, which the northbound system can utilize to communicate various status updates or error reports back to NBI, against each billing payload message sent.
The Call Back Function marks messages with these statuses:
- UserProcessed - completed successfully
- UserFailed - in this case, the northbound system indicates an associated Error Status
Tracking Table¶
NBI tracks all billing events and messages in its Tracking Table, which contains records representing billable events and their associated payloads (including status information and error details, if any).
Note
The contents of the Tracking Table and associated fields are documented in the appendix.
The Tracking Table is held on the VOSS-4-UC node(s), and so benefits from the redundancy (multiple nodes) and backup mechanisms found on these nodes. The NBI appliances itself holds no data billing payloads and their history.
Connectivity¶
NBI connects to VOSS-4-UC using a combination of the VOSS-4-UC API and direct access to the mongo database (where all NBI data is kept – there is none on the NBI appliance itself).
- Access to the VOSS-4-UC API is made using a service account (configured on VOSS-4-UC and at the Provider Level in the hierarchy), and through the VOSS-4-UC Web Proxy Node.
- Access to the mongodb is made through direct access to the VOSS-4-UC Unified Nodes, with Secondary Nodes being preferred (with the ability to move to another node if the selected node is not available).
NBI connects to the northbound system (for sending payloads) over HTTP or HTTPS. All connectivity details are defined in the NBI configuration file.
Provisioning Control (Site Transition Flag)¶
Sites may be set into a Transition state from the NBI GUI, whereby sending of billing payloads for that particular site is fully disabled, regardless of whether the Subscriber is in a Live state.
This feature is provided as a fail-safe, at a site level, and may be deployed when transitioning an existing customer onto the VOSS-4-UC service or during the initial provisioning of new customers.
Configuration¶
A configuration file on the NBI appliance manages the configuration of NBI operational parameters. This file is initially configured on NBI installation, and may be updated from the command line (see later commands).
Diagnostics¶
- Message reporting screens to track billing payloads and status
- Integration and alarming with NOC systems (SNMP)
- Log files are maintained and can be accessed from the command line interface (for each of the main functions, and are date/time stamped)
- Commands to check on status and general health of the server appliance
Provisioning Control (User State) and managing Go-Live Dates¶
Subscribers (as seen by NBI) are assigned one of the following states:
- Test
- Pending
- Live
In a Test or Pending state, any changes made against the subscriber do not initiate a billing payload, and no entry is made into the Tracking Table.
Billing payloads are only sent for subscribers that are in Live stage.
The use cases are as follows:
- During initial provisioning for a customer, when subscribers being on-boarded, the billing flow may be disabled. Subscribers are automatically discovered as they are built into VOSS-4-UC, and are placed in a Pending state (no payloads sent)
- Once a Go-Live billing date is agreed with the customer, sites and associated users may be promoted into a Live state. All subsequent changes will then automatically flow into billing (payloads sent). This promotion may be made manually or pre-set through configuring a go-live date (schedule) against each subscriber.
The default subscriber state (the initial subscriber state) is configured at a site level and may be set to any of Test, Pending or Live:
| Test | Subscribers with a Test State are for NBI testing purposes only; payloads are never sent northbound. Once a Subscriber is placed in a Test State, this state can never be changed. |
| Pending | A Subscriber in a Pending State is staged during the initial onboarding of a customer, and can then be promoted into a Live State (either manually or on a Go-Live schedule). |
| Live | Subscribers in a Live State are processed and billing payloads are sent automatically to the northbound system. |
Managing Site and Subscriber Information¶
- Use the Sites menu to manage sites (associated default subscriber state, transition flag).
- Use the Subscribers menu to manage subscribers (associated activation state, go-live date, send new payload). Subscribers can be freely moved between Pending and Live states (and back again).
Run Time Configuration Parameters¶
The parameters described in this section can be configured on the NBI and are contained within the NBI configuration file.
Note
Most of these parameters may be updated from the utility found on the command line interface. Where this is not possible, contact VOSS Support for assistance (these parameters require command line root access).
| Parameter | Configuration File Extract (bdeconf.json) |
| Poll Interval | "pollInterval": 5000 "sets poll interval in milliseconds
to check for new transactions in the VOSS-4-UC Transaction
Log. Default is 5 minutes
|
| Batch Size | "batchSize": 100 "number of records to process in a
single batch when doing bulk processing
|
| Location of VOSS-4-UC application and access credentials | "vossApiRootURL": "http://<login>:<IP>/api",
"Administration credentials for NBI to login into the
VOSS-4-UC application. This should be created as a
service account with no password expiry and at
Provider Level (e.g. nbiadmin)"
"vossDbDSN": "mongodb://<login>@<IP1>:27020, <IP2>:27020,
<IP3>:27020, <IP4>:27020/VOSS?
authSource=admin&ssl=true&replicaSet=DEVICEAPI&readPreference=secondaryPreferred"
"Access details for the VOSS-4-UC database – note each
unified node is specified for redundancy with the secondary
being preferred"
|
| Parameter | Configuration File Extract (bdeconf.json) |
| Call Back function | "callback": {
"address": "0.0.0.0",
"port": 5009,
"username": "voss",
"password": "callbackpass",
"url": http://<IP>:5009/callback }
|
| Sandbox | "sandbox": {
"address": "127.0.0.1",
"port": 5006 }
|
| Location of the northbound service (URL) and access credentials | "notifier": {
"url": "https://<IP>:<PORT>",
"useCerts": true,
"indicates if certs are deployed (or not)"
"key": "/opt/billing-data-extract/certs/<name>.key",
"ca": "/opt/billing-data-extract/certs/ca.crt",
"cert": "/opt/billing-data-extract/certs/<name>.crt" }
|
Hardware and Network Specification (Single Node Server Appliance)¶
| Resource | Specification |
| CPU | 2 vCPU @ 2GHz with no reservation |
| Memory | 4GB |
| Disk | 80GB |
| Network | 1 Gbit/s minimum |
| Source (Function) | Destination | Destination Port |
| NBI (Extract Function) | VOSS-4-UC | HTTPS TCP 443/8433 |
| NBI (Extract Function) | VOSS-4-UC | TCP 27020 |
| NBI (Extract Function) | VOSS-4-UC | SSH TCP 22 |
| NBI (Transmit Function) | Northbound CRM | HTTPS TCP 443/8443 |
| Northbound CRM | NBI (Call Back Function) | TCP 5009 |
| Command Line Management | NBI | SSH/SFTP TCP 22 |
| NBI (Services) | DNS | TCP/UDP 53 |
| NBI (Services) | NTP | UDP 123 |
| NBI (Services) | SNMP Server / NOC | SNMP TCP/UDP 161, 162 |
| SNMP Server / NOC | NBI (Services) | SNMP TCP/UDP 161, 162 |
| Network Bandwidth Requirement | |
|---|---|
| Flow - NBI to / from VOSS-4-UC | 350 KB/s bandwidth |
| Flow - NBI to / from northbound system | 150 KB/s bandwidth |
Command Interface¶
Maintenance is carried out from a platform user login application command line, either via SSH or from the VM console command line. The password is configured during installation and can be changed using system password. On initial login, the system displays a banner indicating the general system health.
Appliance Commands
The table describes the appliance commands:
| network - network management | keys - ssh/sftp credentials |
| notify - notifications control | log - manage system logs |
| diag - system diagnostic tools | schedule - scheduling commands |
| snmp - snmp configuration | system - system administration |
| drives - manage disk drives | security - security update tools |
| app - manage applications | user - manage users |
Logs are provided for the three main NBI functions:
- Extractor
- Notifier
- CallBack processes
NBI-specific Commands (billing-data-extract)
The table describes the NBI-specific commands (billing-data-extract):
| config | View and Edit billing-data-extract configuration file |
| run_sde | Method for running SDE to produce reconciliation files. This command can be put on schedule to execute nightly. |
| syncnbi | Ensure that NBI is in sync with VOSS-4-UC database |
| syncnbi-dryrun | Dry run to report on sync status between NBI and VOSS-4-UC database |
| test_connection | Test remote VOSS-4-UC database and VOSS-4-UC API connection |
| message-tracking | Manage and prune message tracking database |
Security Considerations (Certificates)¶
The upstream connection and passage of billing payloads may be secured, where required, to use HTTPS over the northbound connection. In this case, a suitably signed certificate should be produced and then installed onto the NBI – into a folder location and then this recorded into the NBI configuration file.
Note
These certificates need to be copied to, set up, and configured correctly on the northbound system.
Installation Requirements¶
The virtual machine is deployed using the OVA template, which is supplied by VOSS.
Installation of the NBI follows this sequence:
- Configure VOSS-4-UC for NBI:
- Open firewall ports for access to mongodb (NBI data collections) on Unified Nodes.
- Configure NBI service account (limited access profile, password without expiry, at Provider Level).
- Install NBI appliance OVA and set network configuration parameters.
- Install billing-data-extract application on NBI appliance.
- Install certificates (as required).
- Configure and connect billing-data-extract application to VOSS-4-UC and northbound system.
- Location of Unified Nodes (IPs) and Web Proxy
- URL for northbound system
- Service access account for VOSS-4-UC
- mongodb access credentials
- Certificates
- Provision and restart NBI appliance for operation.
Note
