ONMSi- Fiber Analytics

Full REST API for fiber optic JSON data access

SQL API for direct querying and dashboarding
Fiber Analytics standalone install
User Manual
ONMSi- Fiber Analytics
Full REST API for fiber optic JSON data
access SQL API for direct querying
and dashboarding
Fiber Analytics standalone install
User Manual

Viavi Solutions
1-844-GO-VIAVI
www.viavisolutions.com
Notice

Every effort was made to ensure that the information in this document was accurate at
the time of printing. However, information is subject to change without notice, and VIAVI
reserves the right to provide an addendum to this document with information not avail-
able at the time that this document was created.

Copyright

© Copyright 2023 VIAVI, LLC. All rights reserved. VIAVI, Enabling Broadband and
Optical Innovation, and its logo are trademarks of VIAVI, LLC. All other trademarks and
registered trademarks are the property of their respective owners. No part of this guide
may be reproduced or transmitted electronically or otherwise without written permission
of the publisher.

Trademarks

VIAVI and ONMSi are trademarks or registered trademarks of VIAVI in the United
States and/or other countries.

Ubuntu is a registered trademark of Canonical in the United Stated and/or other coun-
tries.

Red Hat ® Enterprise Linux ® is a registered trademark of Red Hat Inc. in the United
Stated and/or other countries.

Microsoft Internet Explorer and Microsoft Edge are either trademarks or registered
trademarks of Microsoft Corporation in the United States and/or other countries.

Firefox is a registered trademark of Mozilla Fundation in the United States and/or other
countries.

Google Chrome is a registered trademark of Google Incorporation in the United Stated

and/or other countries.

Java is either trademark or registered trademark of Oracle Corporation in the United

States and/or other countries.

Specifications, terms, and conditions are subject to change without notice. All trade-
marks and registered trademarks are the property of their respective companies.

Ordering information

This guide is a product of VIAVI's Technical Information Development Department.

WEEE Directive Compliance

VIAVI has established processes in compliance with the Waste Electrical and Electronic
Equipment (WEEE) Directive, 2002/96/EC.

User Manual 70ONMSI80 Rev. 000 v

 This product should not be disposed of as unsorted municipal waste and should be
collected separately and disposed of according to your national regulations. In the
European Union, all equipment purchased from VIAVI after 2005-08-13 can be returned
for disposal at the end of its useful life. VIAVI will ensure that all waste equipment
returned is reused, recycled, or disposed of in an environmentally friendly manner, and
in compliance with all applicable national and international waste legislation.

It is the responsibility of the equipment owner to return the equipment to VIAVI for
appropriate disposal. If the equipment was imported by a reseller whose name or logo
is marked on the equipment, then the owner should return the equipment directly to the
reseller.

Instructions for returning waste equipment to VIAVI can be found in the Environmental
section of VIAVI’s web site at www.viavisolutions.com. If you have questions
concerning disposal of your equipment, contact VIAVI’s WEEE Program Management
team.

vi User Manual 70ONMSI80 Rev. 000

Table of Contents

About This Guide ix

Purpose and scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .x
Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .x
Technical assistance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .x
Recycling Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .x
Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .x

Chapter 1 Adding a Monitoring Test to Fiber Analytics 1

Pre-requisite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Adding a Monitoring Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Chapter 2 Configuring the ONMSi additional attributes renaming 3

Principle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4
Mapping definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4
Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4

Chapter 3 REST API Quick Start 5

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
Pre-requisite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
POST/api/authenticate/jwt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Basic request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8
API measurements end points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
GET /fa/api/measurements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Basic request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Advanced request: Horizontal filtering (rows) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
API measurements resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
API alarms end points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
GET /fa/api/alarms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Basic request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26
Advanced request: Horizontal filtering (rows) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
API alarms resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28

User Manual 70ONMSI80 Rev. 000 vii

Table of Contents

API homes end points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

GET /fa/api/homes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Basic request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Advanced request: Horizontal filtering (rows). . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
API Home resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
API test_points end points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
GET /fa/api/test_points. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Basic request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Advanced request: Horizontal filtering (rows). . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
API test_points resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
Advanced request - Full documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Paginated requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Full documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Chapter 4 SQL API Quick Start 45

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Pre-requisite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Connection parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Set up the fiberanalytics user password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Additional information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Database connection example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
DBeaver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Connection settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Grafana. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Setting up the datasource. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Data model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
The alarm view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
The build_test view. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
The Home view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
The measurement view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
The monitoring_test view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
The test_point view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Querying JSONb data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Standard dashboards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
1. Alarm Duration & compliance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Filters and parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Alarm Geolocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Filters and parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Quality of optical network in terms of global linear attenuation . . . . . . . . . 56
Filters and parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57
Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57
Quality of fiber network in terms of optical event . . . . . . . . . . . . . . . . . . . . . . 58
Filters and parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

viii User Manual 70ONMSI80 Rev. 000

About This Guide

Topics discussed in this chapter are as follows:

• “Purpose and scope” on page x
• “Assumptions” on page x
• “Technical assistance” on page x
• “Recycling Information” on page x
• “Conventions” on page x

User Manual 70ONMSI80 Rev. 000 ix

About This Guide
Purpose and scope

Purpose and scope

The purpose of this guide is to help you successfully install and use the ONMSi features
and capabilities. Additionally, this guide provides a complete description of VIAVI’s
terms and conditions of the licensing agreement.

Assumptions
This guide is intended for experienced users and admnistrators who want to implement
ONMSi effectively and efficiently. It is recommended to attend the ONMSi training to
learn how to install, configure, use, and troubleshoot the ONMSi.

Technical assistance
If you require technical assistance, call 1-844-GO-VIAVI. For the latest TAC informa-
tion, go to http://www.viavisolutions.com/en/services-and-support/support/technical-
assistance.

Recycling Information
VIAVI recommends that customers dispose of their instruments and peripherals in an
environnmentally sound manner. Potential methods include reuse of parts or whole
products and recycling of products components, and/or materials.

Waste Electrical and electronic Equipment (WEEE) Directive

In the European Union, this label indicates that this product should not be disposed of
with household waste. Il should be deposited at an appropriate facility to enable
recovery and recycling.

Conventions
This guide uses naming conventions and symbols, as described in the following tables.

Table 1 Typographical conventions

Description Example
User interface actions appear in this On the Status bar, click Start
typeface.
Buttons or switches that you press on Press the ON switch.
a unit appear in this TYPEFACE.

x User Manual 70ONMSI80 Rev. 000

 About This Guide
Conventions

Table 1 Typographical conventions (Continued)

Description Example
Code and output messages appear in All results okay
this typeface.
Text you must type exactly as shown Type: a:\set.exe in the dialog box.
appears in this typeface.
Variables appear in this typeface. Type the new hostname.
Book references appear in this type- Refer to Newton’s Telecom Dictionary
face.
A vertical bar | means “or”: only one platform [a|b|e]
option can appear in a single com-
mand.
Square brackets [ ] indicate an login [platform name]
optional argument.
Slanted brackets < > group required <password>
arguments.

Table 2 Keyboard and menu conventions

Description Example
A plus sign + indicates simultaneous key- Press Ctrl+s
strokes.
A comma indicates consecutive key strokes. Press Alt+f,s
A slanted bracket indicates choosing a sub- On the menu bar, click
menu from menu. Start > Program Files.

Table 3 Symbol conventions

NOTEThis symbol represents a general hazard.

WARNING
This symbol represents a risk of electrical shock.

NOTE
This symbol represents a Note indicating related information or tip.

User Manual 70ONMSI80 Rev. 000 xi

About This Guide
Conventions

This symbol, located on the equipment or its packaging, indicates

that the equipment must not be disposed of in a land-fill site or as
municipal waste, and should be disposed of according to your
national regulations.

Table 4 Safety definitions

WARNING
Indicates a potentially hazardous situation which, if not avoided,
could result in death or serious injury.

CAUTION
Indicates a potentially hazardous situation which, if not avoided, may
result in minor or moderate injury.

xii User Manual 70ONMSI80 Rev. 000

 1

Chapter 1 Adding a Monitoring Test to Fiber Analytics

This chapter provides a general description of the ONMSi requirements for installation
of the equipment.

Topics discussed in this chapter include the following:

• “Pre-requisite” on page 2
• “Adding a Monitoring Test” on page 2

User Manual 70ONMSI80 Rev. 000 1

Chapter 1 Adding a Monitoring Test to Fiber Analytics
Pre-requisite

Pre-requisite
Fiber Analytics is an extension to ONMSi (Optical Network Monitoring System)
providing fiber related data access through:
1 Full REST API
2 An SQL API

Installing and running Fiber Analytics supposes that an ONMSi is already installed.
• ONMSi version 5.00 or higher
• OTU 8000E or 5000
– Software version 21.63 or higher

Adding a Monitoring Test

The collection of measurement data by Fiber Analytics is performed by declaring peri-
odically scheduled monitoring test with dedicated options.

From monitoring test configuration dashboard:

In the scheduling window, parameter allows to store measurement into Fiber Analytics.

Note that the reference of the monitoring test should not be in smart acquisition mode.

Figure 1 Scheduling configuration

2 User Manual 70ONMSI80 Rev. 000

 2

Configuring the ONMSi additional attributes

Chapter 2

renaming

Topics discussed in this chapter are as follows:

• “Principle” on page 4
• “Mapping definition” on page 4
• “Procedure” on page 4

User Manual 70ONMSI80 Rev. 000 3

Chapter 2 Configuring the ONMSi additional attributes renaming
Principle

Principle
Optionally, the Fiber Analytics application allows you to perform a renaming of some
additional attributes attached to ONMSi resources when exported from the ONMSi to
FA.

Additional attributes available for renaming are those of links, otu, domains and alarms.

Mapping definition
The renaming needs to be declared into a configuration file of Fiber Analytics. The YAML
configuration file is located in:

• Directory: <rfts_apps>/conf/fiberanalytics/model
• File: application-core-dbt.yaml

By editing that file, you can define the mapping between ONMSi additional attribute name and
the Fiber Analytics additional attribute name:

# Rename additional attributes

additionalAttributeMapping:
link:
'onmsiAdditionalAttribute': 'faAdditionalAttribute'
'onmsiAdditionalAttribute2': 'faAdditionalAttribute2'
'Section ID': 'Cable ID'
otu:
'onmsiAdditionalAttribute': 'faAdditionalAttribute'
domain:
'onmsiAdditionalAttribute': 'faAdditionalAttribute'
alarm:
'onmsiAdditionalAttribute': 'faAdditionalAttribute'

Procedure
• Login as support user on the ONMSi host
• Edit the 'application-core-dbt.yaml' and add a mapping (in the above example,
Section ID in ONMSi will be renamed in Cable ID in FA)
• restart Fiber Analytics model application
– $ rfts_ctrl restart -c fa-model

4 User Manual 70ONMSI80 Rev. 000

 3

Chapter 3 REST API Quick Start

Topics discussed in this chapter are as follows:

• “Introduction” on page 6
• “Authentication” on page 6
• “API measurements end points” on page 9
• “API measurements resources” on page 13
• “API alarms end points” on page 25
• “API alarms resources” on page 28
• “API homes end points” on page 33
• “API Home resources” on page 36
• “API test_points end points” on page 39
• “API test_points resources” on page 41
• “Advanced request - Full documentation” on page 42

User Manual 70ONMSI80 Rev. 000 5

Chapter 3 REST API Quick Start
Introduction

Introduction
The Fiber Analytics REST API consists of requests and responses to collect fiber data
produced by ONMSi (Optical Network Monitoring System), OTUs (Optical Test Unit)
model 8kv2 and/or 5k.

Those calls are proceeded by a fiber analytics web server. In the following documenta-
tion, we assume the web server base URL to access REST API is noted <fa-server>.

The REST API is usable after an authentication request on the ONMSi server. In the
following documentation, we assume the web server base URL to access ONMSi
authentication API is noted <onmsi-server>.

Notes:
• In case FA is in colocation with the ONMSi product, <fa-server> equals <onmsi-
server>
• The recommended configuration is to have separate servers.

Base URL Example

<onmsi-server> = http://topaz-onmsi-demo/
<fa-server> = http://topaz-fa-demo/

Data available from the REST API are the following:

• measurements
• alarms
• homes
• test_points

Accessing these data is discussed after the authenticating part.

Authentication

Pre-requisite
• Fiber Analytics installed on a server <fa-server>;
• ONMSi installed on a server <onmsi-server>;
• A valid Fiber Analytics API licence;
• An ONMSi user having the API profile.

Overview
The ONMSi server is in charge of authenticating the Fiber Analytics user.

6 User Manual 70ONMSI80 Rev. 000

 Chapter 3 REST API Quick Start
Authentication

The successful authentication response is an access token (JWT token) to be used in

further calls to the FA REST APIs.

Figure 2 Authentication

NOTE
Starting with Fiber Analytics 2.00, the authentication URL /api/private/fa/authenticate
is not anymore supported. Please, use /api/authenticate/jwt instead.

POST/api/authenticate/jwt
The POST <onmsi-server>/api/authenticate/jwt operation is used to authenticate and provide
a valid JWT token:

Summary
• Header:
– 'Content-Type': application/json
– 'Authorization': Basic with <user>and <password>
• Body:
– JSON object providing the requested role
– Role for Fiber Analytics should be set to 'faapi'

User Manual 70ONMSI80 Rev. 000 7

Chapter 3 REST API Quick Start
Authentication

Body

{
"role": "faapi"
}

• Response message:
– JSON object providing the access token to be used by future API calls

Body

{
"accessToken": "eyJhbGciOiJSUzUxMiJ9.eyJzdWIiOiJmaWJlcmFuY-
Wx5dGljcyIsInJvbG......"
}
• Returned code:
– 200 OK
– 400 Bad Request: The role payload is missing
– 401 Unauthorized: Erroneous user/password or user not declared as API user in
ONMSi

Basic request
CURL request example

CURL request

curl -i -X POST \
-H "Content-Type:application/json" \
-H "Authorization:Basic ZmliZXJhbmFseXRpY3M6cGFzc3dvcmQ=" \
-d \
'{
"role": "faapi"
}' \
'http://topaz-onmsi-demo/api/authenticate/jwt'

In that previous example, the user 'faApiUser' with password 'faApiUser ' is
coded in the basic authorization field.

HTTP details

8 User Manual 70ONMSI80 Rev. 000

 Chapter 3 REST API Quick Start
API measurements end points

Request example

POST /api/authenticate/jwt HTTP/1.1

Authorization: Basic ZmliZXJhbmFseXRpY3M6cGFzc3dvcmQ=
Content-Length: 21
Content-Type: application/json
Host: topaz-onmsi-demo
{ "role": "faapi" }

Response example

HTTP/1.1 200 OK
Server: nginx
Date: Thu, 01 Apr 2021 12:42:05 GMT
Content-Type: application/json
Content-Length: 798
Connection: keep-alive
{"accessToken":"eyJhbGciOiJSUzUx-
MiJ9.eyJzdWIiOiJmaWJlcmFuYWx5dGljcyIsInJvbGUiOiJmYWFwaSIsImV4c
CI6MTYxNzM2NzMyNX0.bt1SJnAeYywsfUAYJ--
HnavV0MQLZ518dTxJUvN4hwAI7H8OFHygD58XbFRGT4bfq9Y8MKSNo8u4wtADy
4BPjOtcNbaJZf-JiiP8YBttXGKID1hNfx5PuIMSNAqaohKXb-
ty9Z31oKE3_Nae1-n0vMLVkvnjpP6QUx5XuXxGg0mVCG564wB4-lImeB3Du-
bwZV0QfCtg4HoA6hPL9C5BzYdiCDgeZRAkclcTEL0zdGWkQ_RRr3m8q8OoYRRJ
_M2fk4_HrwqwyT8fHGS_cOZlcVuyOxmI7HtgZq-
RqqGiOwoD4cbcwRDVkmAteO5ijDsTmAR88RKuFzJCZrC6rZ7ujwdTu2R3oKKAo
eH_AW80hv7BrvalpyjWyFhtcMXsBraG-
ZAqx3mPTxpRfVl8Lhy3XRhAH4Xms3A9Zf4Ul2UqY_JrP4Rm2XDnlvx8viq9RMs
fPyAE4zDJeD6Pm0QTRTVMvgf6Vhja_uB0oSHoI8mDjjcVaS7sa6Ya4elUkevRx
pw44g8axBnIKcm9i_QxD6BERAJeZ8Nx9uFTnQlK5Q74059jZ6I1YL6cAPMtTyu
AllcbBela1p5hlZ_mIbSw9m2wggAsWJ_v3CIxOq7msF4ZHzMpvWxQw_SXx3r2I
OvlANZj0fyvyrS5UYo-6obe_BvaLh2FZA-wbIiNzSqAg0htV5L8"}

To simplify the reading of the document, the above accessToken is noted <yourToken>

API measurements end points

Document the GETs operations on <fa-server>/fa/api/measurements.

CAUTION
The GET requests are limited to return a MAXIMUM of 500 items. Client iterative fil-
tering (by rows) or paginated requests are necessary to fetch a large set of measure-
ments

User Manual 70ONMSI80 Rev. 000 9

Chapter 3 REST API Quick Start
API measurements end points

GET /fa/api/measurements
The GET /fa/api/measurements operation is used to get full contents of measurements.
• Header:
– Authorization: Bearer <with JWT token provided by authentication>
• Response message:
– JSON Array of measurements
• Returned codes:
– 200 OK
– 400 Bad Request: When requested role does not exist.
– 401 Unauthorized: JWT token is missing, badly signed or expired. A detailed
message is provided.

Basic request
CURL request example

CURL request

curl -i -X GET \
-H "Authorization:Bearer eyJhbGciOiJSUzUx-
MiJ9.eyJzdWIiOiJmaWJlcmFuYWx5dGljcyIsInJvbGUiOiJmYWFwaSIsImV4c
CI6MTYxNzM2NzMyNX0.bt1SJnAeYywsfUAYJ--
HnavV0MQLZ518dTxJUvN4hwAI7H8OFHygD58XbFRGT4bfq9Y8MKSNo8u4wtADy
4BPjOtcNbaJZf-JiiP8YBttXGKID1hNfx5PuIMSNAqaohKXb-
ty9Z31oKE3_Nae1-n0vMLVkvnjpP6QUx5XuXxGg0mVCG564wB4-lImeB3Du-
bwZV0QfCtg4HoA6hPL9C5BzYdiCDgeZRAkclcTEL0zdGWkQ_RRr3m8q8OoYRRJ
_M2fk4_HrwqwyT8fHGS_cOZlcVuyOxmI7HtgZq-
RqqGiOwoD4cbcwRDVkmAteO5ijDsTmAR88RKuFzJCZrC6rZ7ujwdTu2R3oKKAo
eH_AW80hv7BrvalpyjWyFhtcMXsBraG-
ZAqx3mPTxpRfVl8Lhy3XRhAH4Xms3A9Zf4Ul2UqY_JrP4Rm2XDnlvx8viq9RMs
fPyAE4zDJeD6Pm0QTRTVMvgf6Vhja_uB0oSHoI8mDjjcVaS7sa6Ya4elUkevRx
pw44g8axBnIKcm9i_QxD6BERAJeZ8Nx9uFTnQlK5Q74059jZ6I1YL6cAPMtTyu
AllcbBela1p5hlZ_mIbSw9m2wggAsWJ_v3CIxOq7msF4ZHzMpvWxQw_SXx3r2I
OvlANZj0fyvyrS5UYo-6obe_BvaLh2FZA-wbIiNzSqAg0htV5L8 " \
'http://topaz-fa-demo/fa/api/measurements'

HTTP details

10 User Manual 70ONMSI80 Rev. 000

 Chapter 3 REST API Quick Start
API measurements end points

Request example

GET /fa/api/measurements HTTP/1.1

Authorization:Bearer eyJhbGciOiJSUzUx-
MiJ9.eyJzdWIiOiJmaWJlcmFuYWx5dGljcyIsInJvbGUiOiJmYWFwaSIsImV4c
CI6MTYxNzM2NzMyNX0.bt1SJnAeYywsfUAYJ--
HnavV0MQLZ518dTxJUvN4hwAI7H8OFHygD58XbFRGT4bfq9Y8MKSNo8u4wtADy
4BPjOtcNbaJZf-JiiP8YBttXGKID1hNfx5PuIMSNAqaohKXb-
ty9Z31oKE3_Nae1-n0vMLVkvnjpP6QUx5XuXxGg0mVCG564wB4-lImeB3Du-
bwZV0QfCtg4HoA6hPL9C5BzYdiCDgeZRAkclcTEL0zdGWkQ_RRr3m8q8OoYRRJ
_M2fk4_HrwqwyT8fHGS_cOZlcVuyOxmI7HtgZq-
RqqGiOwoD4cbcwRDVkmAteO5ijDsTmAR88RKuFzJCZrC6rZ7ujwdTu2R3oKKAo
eH_AW80hv7BrvalpyjWyFhtcMXsBraG-
ZAqx3mPTxpRfVl8Lhy3XRhAH4Xms3A9Zf4Ul2UqY_JrP4Rm2XDnlvx8viq9RMs
fPyAE4zDJeD6Pm0QTRTVMvgf6Vhja_uB0oSHoI8mDjjcVaS7sa6Ya4elUkevRx
pw44g8axBnIKcm9i_QxD6BERAJeZ8Nx9uFTnQlK5Q74059jZ6I1YL6cAPMtTyu
AllcbBela1p5hlZ_mIbSw9m2wggAsWJ_v3CIxOq7msF4ZHzMpvWxQw_SXx3r2I
OvlANZj0fyvyrS5UYo-6obe_BvaLh2FZA-wbIiNzSqAg0htV5L8

Host: topaz-fa-demo

Response example
HTTP/1.1 200 OK
Server: nginx
Date: Thu, 01 Apr 2021 15:51:03 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Content-Encoding: gzip
Content-Range: 0-499/*
Content-Location: /measurements
[{"measurement":{"cdm": {"tests": [{"type": "OTDR", "label":
"OTDR", "results": {"data": {"otdrResults": {"distanceUnits":
"m", "measuredResults": [{"events": [{"id": 1, "idSlm": 1,
"lossdB": 1.709, "distance": 0, "distanceM": 0, "eventType":
"First Connector", "reflSaturated": false, "reflectancedB": -
32.81, "sectionLength": 0, "sectionLossdB": 0, "sectionLengthM":
0, "eventTestStatus": "fail", "lossAlarmFailed": true,
"reflAlarmFailed": true, "cumulativeLossdB": 0, "slopeAlarm-
Failed": false, "reflPeakDistanceM": 3.19}, {"id": 2, "idSlm":2,
"lossdB": 0, "slopedB": 0.219, "distance": 10628.49, "distanceM":
10628.49, "eventType" : : "Reflection", "slopedBkm": 0.2189999,
"reflSaturated": false, "reflectancedB": -56.42, "section-
Length": 10628.5, "sectionLossdB": 2.3329999, "sectionLengthM":
10628.5, "eventTestStatus": "pass", "lossAlarmFailed": false,
"reflAlarmFailed": false, "cumulativeLossdB": 2.333, "slope-
AlarmFailed": false,"reflPeakDistanceM": 10631.68}, {"id": 3,

User Manual 70ONMSI80 Rev. 000 11

Chapter 3 REST API Quick Start
API measurements end points

"idSlm": 3, "distance": 10633.6, "distanceM": 10633.6, "event-

Type": "Fiber End", "reflSaturated": false, "reflectancedB": -
57.01, "sectionLength": 5.1, "sectionLossdB": 0, "section-
LengthM": 5.1, "eventTestStatus": "none", "lossAlarmFailed":
false, "reflAlarmFailed": false, "cumulativeLossdB": 2.333,
"slopeAlarmFailed": false, "reflPeakDistanceM": 10634.87}],
"linkOrldB": 32.87, "linkLossdB": 2.333, "acqDateTime": "2022-
05-09T14:11:24+02:00", "fiberLength": 10633.6, "fiberLengthM":
10633.5996, "wavelengthNm": 1650, "numberOfEvents": 3, "averag-
eSlopedBkm": 0.2189999, "wavelengthTestStatus": "fail", "maxCon-
nectorMeasureddB": 1.709, "maxReflectanceMeasureddB": -32.81}],
"resultsFilename": "acq_otu10548_0_1652105501_2.msor.json"}},
"status": "fail", "comment": "", "testTime": "2022-05-
09T14:11:24+02:00"}, "configuration": {"otdrSettings":
{"fiber": {"number": 0, "cableId": "Cable_ID", "fiberId": "otu-
8000e-10548 OS(001)", "direction": "Loc A > Loc B", "locationA":
"Loc A", "locationB": "Loc B", "fiberLabel": ""}, "setup":
[{"pulse": "30ns", "range": "40km", "refrIndex": 1.4685, "reso-
lution": "64cm", "scatterCoef": -81, "wavelengthNm": 1650,
"bendOnSplicedB": 0, "averagingTimeSec": 10, "bendOnConnec-
tordB": 0}], "configFile": "", "launchCable": {"endCableUsed":
"No", "startCableUsed": "No", "includeLinkEndConnector": false,
"includeLinkStartConnector": false}, "otdrTopology": "Expert-
SM", "alarmThresholds": {"type": "fail", "orldB": 27, "splice-
LossdB": 0.2, "thresholdSet": "Default", "reflectancedB": -35,
"connectorLossdB": 0.5, "slopeThresholds": [{"slopedBkm": 1,
"wavelengthNm": 1650}]}}}, "schemaVersion": "1.2.0"}, {"type":
"ONMSI", "results": {"data": {"measurement": {"buildTest":
{"orldB": 32.87, "orlAlarm": false, "createdBy": "admin",
"endLeveldB": 0.58, "linkLossdB": 2.33, "eventsAlarm": true,
"beginLeveldB": -1.67, "endDistanceM": 10633.6, "fiberLengthM":
10615.1, "linearAttdBkm": 0.22, "linkLossAlarm": false,
"beginDistanceM": 18.5, "linearAttAlarm": false, "fiberEndDe-
tected": true, "resultOverridden": {"date": "2022-05-
12T21:28:42.372+02:00", "byUser": "admin"}, "splitterDetected":
false}}}, "status": "pass", "testTime": "2022-05-
09T14:11:24+02:00"}, "configuration": {"measurement": {"otu":
{"uid": "hapy_cbbrm_6113", "name": "otu-8000e-10548", "port": 1,
"portName": "OS(001)"}, "link": {"uid": "hapy_cbbrm_6699",
"name": "otu-8000e-10548 OS(001)"}, "buildTest": {"uid": "hapy-
_cbbrm_1140", "name": "Build_Auto", "description": "Configura-
tion with automatic acquisition parameters without smart
acquisition, and default thresholds"}, "domainList": [{"uid":
"hapy_cbbrm_22707", "name": "Domain Jan"}, {"uid": "hapy_cb-
brm_2593", "name": "PON"}], "domainTree": [[{"uid": "hapy_cb-
brm_22707", "name": "Domain Jan"}], [{"uid": "hapy_cbbrm_2593",
"name": "PON"}]], "centralOffice": {"uid": "hapy_cbbrm_3301",
"name": "CO CO2", "additionalAttributes": {"External key":
"CO_CO2"}}}}, "schemaVersion": "1.0.0"}], "checkSum":
"_NOT_EVALUATED_", "assetInfo": {"model": "OTU 8000E",
"uniqueId": "OTU 8000E_10548", "assetType": "T-BERD/MTS 8000",
"hwVersion": "", "swOptions": [], "swVersion": "21.40",

12 User Manual 70ONMSI80 Rev. 000

 Chapter 3 REST API Quick Start
API measurements resources

"modulesInfo": [{"model": "81165C-HR-APC", "uniqueId": "81165C-

HR-APC_00093", "assetType": "T-BERD/MTS module", "swVersion":
""}], "manufacturer": "VIAVI Solutions", "calibrationDate":
"2017-11-23"}, "cdmVersion": "2.1"}, "internalKey": 377, "sche-
maVersion": "1.0.0"}}, ...

Advanced request: Horizontal filtering (rows)

• Get measurement by acquisition date

Request for measurements with acquisition date more recent than 2023, january first

GET /fa/api/measurements?acquisitionDate=gte.2023-01-01T00:00:00

API measurements resources

Measurements returned by the GET REST API request is a JSON array

GET Response structure

[
...
{
"acquisitionDate ": "2023-01-24T18:15:34+00:00",
"measurement": {
"schemaVersion": "1.0.0",
"internalKey": 400,
"cdm": {
// HERE TAKE PLACE THE CDM v2.1 with OTDR and
ONMSi tests
},

}
},
{
"acquisitionDate ": "2023-01-24T15:48:46+00:0",
"measurement": {
"schemaVersion": "1.0.0",
"internalKey": 401,
"cdm": {
// HERE TAKE PLACE THE CDM v2.1 with OTDR and
ONMSi tests
},

}
},
...
]

User Manual 70ONMSI80 Rev. 000 13

Chapter 3 REST API Quick Start
API measurements resources

The detailed grammar, described by JSON schema, is available in separate files.

• fa-api-cdm-onmsi.schema.json
• fa-api-cdm-otdr-onmsi.schema.json
• fa-api-cdm-otdr.schema.json
• fa-api-measurement.schema.json
• fa-api-context.schema.json

Herebelow are examples of complete measurements including OTDR and ONMSI test
type.

Individual monitoring measurement example

{
"schemaVersion": "1.0.0",
"internalKey": 400,
"cdm": {
"cdmVersion": "2.1",
"workflow": {
"type": "",
"techInfo": {
"techId": ""
},
"attributes": {
"jobComments": ""
},
"workflowId": null,
"workOrderId": "",
"customerInfo": {
"company": ""
},
"workOrderLabel": ""
},
"assetInfo": {
"model": "OTU 5000",
"uniqueId": "OTU 5000_EBAJ00441",
"assetType": "Unknown",
"hwVersion": "",
"swOptions": [],
"swVersion": "17.16",
"modulesInfo": [
{

14 User Manual 70ONMSI80 Rev. 000

 Chapter 3 REST API Quick Start
API measurements resources

"model": "EOTDR2-NF-B1-CO",
"uniqueId": "EOTDR2-NF-B1-CO_00441",
"assetType": "T-BERD/MTS module",
"swVersion": "",
"calibrationDate": "2018-10-05"
}
],
"manufacturer": "VIAVI Solutions",
"calibrationDate": "2012-06-13"
},
"tests": [
{
"type": "OTDR",
"label": "OTDR",
"schemaVersion": "1.1.0",
"workflowId": null,
"configuration": {
"otdrSettings": {
"fiber": {
"number": 1,
"cableId": "Cable",
"fiberId": "Fiber",
"direction": "Loc A > Loc B",
"locationA": "Loc A",
"locationB": "Loc B",
"fiberLabel": ""
},
"setup": [
{
"pulse": "1us",
"range": "160km",
"refrIndex": 1.4692,
"resolution": "40m",
"scatterCoef": -81,
"wavelengthNm": 1625,
"bendOnSplicedB": 0,
"averagingTimeSec": 20,
"bendOnConnectordB": 0
}

User Manual 70ONMSI80 Rev. 000 15

Chapter 3 REST API Quick Start
API measurements resources

],
"configFile": "",
"launchCable": {
"endDistance": null,
"endCableUsed": "No",
"startDistance": null,
"startCableUsed": "No",
"includeLinkEndConnector": false,
"includeLinkStartConnector": false
},
"otdrTopology": "Expert-SM",
"schemaVersion": 1,
"alarmThresholds": {
"type": "none"
}
}
},
"results": {
"data": {
"otdrResults": {
"distanceUnits": "m",
"schemaVersion": 1,
"measuredResults": [
{
"events": [
{
"id": 1,
"idSlm": -1,
"lossdB": 1.133,
"slopedB": null,
"distance": 0,
"eventType": "First Connector",
"reflSaturated": false,
"reflectancedB": -114.22,
"sectionLength": 0,
"eventTestStatus": "none",
"lossAlarmFailed": false,
"reflAlarmFailed": false,
"cumulativeLossdB": 0,

16 User Manual 70ONMSI80 Rev. 000

 Chapter 3 REST API Quick Start
API measurements resources

"slopeAlarmFailed": false
},
{
"id": 2,
"idSlm": -1,
"lossdB": -0.059,
"slopedB": 0.203,
"distance": 4081.03,
"eventType": "Splice",
"reflSaturated": false,
"reflectancedB": null,
"sectionLength": 4081.03,
"eventTestStatus": "none",
"lossAlarmFailed": false,
"reflAlarmFailed": false,
"cumulativeLossdB": 0.83,
"slopeAlarmFailed": false
},
{
"id": 3,
"idSlm": -1,
"lossdB": 0.178,
"slopedB": 0.204,
"distance": 8162.06,
"eventType": "Splice",
"reflSaturated": false,
"reflectancedB": null,
"sectionLength": 4081.03,
"eventTestStatus": "none",
"lossAlarmFailed": false,
"reflAlarmFailed": false,
"cumulativeLossdB": 1.607,
"slopeAlarmFailed": false
},
{
"id": 4,
"idSlm": -1,
"lossdB": 0.071,
"slopedB": 0.202,

User Manual 70ONMSI80 Rev. 000 17

Chapter 3 REST API Quick Start
API measurements resources

"distance": 28240.73,
"eventType": "Splice",
"reflSaturated": false,
"reflectancedB": null,
"sectionLength": 20078.67,
"eventTestStatus": "none",
"lossAlarmFailed": false,
"reflAlarmFailed": false,
"cumulativeLossdB": 5.832,
"slopeAlarmFailed": false
},
{
"id": 5,
"idSlm": -1,
"lossdB": null,
"slopedB": 0.206,
"distance": 29750.71,
"eventType": "Fiber End",
"reflSaturated": false,
"reflectancedB": -56.33,
"sectionLength": 1509.98,
"eventTestStatus": "none",
"lossAlarmFailed": false,
"reflAlarmFailed": false,
"cumulativeLossdB": 6.215,
"slopeAlarmFailed": false
}
],
"linkOrldB": 31.24,
"linkLossdB": 6.215,
"acqDateTime": "2019-12-03T14:30:23",
"fiberLength": 29750.71,
"wavelengthNm": 1625,
"averageLossdB": 0.209,
"numberOfEvents": 5,
"maxSpliceMeasureddB": 0.176,
"wavelengthTestStatus": "none",
"maxConnectorMeasureddB": null,
"maxReflectanceMeasureddB": null

18 User Manual 70ONMSI80 Rev. 000

 Chapter 3 REST API Quick Start
API measurements resources

}
],
"resultsFilename": "generated-1575383424-EBAJ00441-
10264257-10264264-1.csor.json"
}
},
"status": "none",
"comment": "",
"testTime": "2019-12-03T14:30:23"
}
},
{
"type": "ONMSI",
"schemaVersion": "1.0.0",
"configuration": {
"monitoring": {
"otu": {
"uid": "lug_ubljz_8182929",
"name": "Malegi",
"port": 13
},
"link": {
"uid": "lug_ubljz_10264257",
"name": "MME/MVG/001-SSI/JLG/001#27",
"additionalAttributes": {
"Cable ID": "MME/MVG/001-SSI/JLG/001",
"FDMS port number": 27
}
},
"test": {
"uid": "lug_ubljz_10264264",
"scheduled": true
},
"domainList": [
{
"uid": "lug_ubljz_984208",
"name": "South"
},
{

User Manual 70ONMSI80 Rev. 000 19

Chapter 3 REST API Quick Start
API measurements resources

"uid": "lug_ubljz_1141677",
"name": "KK"
},
{
"uid": "lug_ubljz_5161920",
"name": "Shimoga"
}
],
"domainTree": [
[
{
"uid": "lug_ubljz_984208",
"name": "South"
},
{
"uid": "lug_ubljz_1141677",
"name": "KK"
},
{
"uid": "lug_ubljz_5161920",
"name": "Shimoga"
}
]
],
"pointToPoint": {
"majorThresholddB": 3,
"minorThresholddB": 1,
"lastMarkerDistanceM": 29670.71,
"firstMarkerDistanceM": 244.86
}
}
},
"results": {
"data": {
"monitoring": {
"pointToPoint": {
"lastMarkerLeveldB": -7.34,
"firstMarkerLeveldB": -1.18,
"lastMarkerNoiseMargindB": 20.04

20 User Manual 70ONMSI80 Rev. 000

 Chapter 3 REST API Quick Start
API measurements resources

}
}
},
"status": "none",
"testTime": "2019-12-03T14:30:23"
}
}
],
"checkSum": "224189122c5b3f113471e38025c468c8"
}
}

Individual build test measurement example

{
"cdm": {
"tests": [
{
"type": "OTDR",
"label": "OTDR",
"results": {
"data": {
"otdrResults": {
"distanceUnits": "m",
"measuredResults": [
{
"acqDateTime": "2022-05-09T19:44:00+02:00",
"fiberLength": 0,
"fiberLengthM": 0,
"wavelengthNm": 1625,
"numberOfEvents": 0,
"wavelengthTestStatus": "none"
}
],
"resultsFilename": "acq_otuE-
BAJ00101_1_1652125464_2.msor.json"
}
},
"status": "none",

User Manual 70ONMSI80 Rev. 000 21

Chapter 3 REST API Quick Start
API measurements resources

"comment": "",
"testTime": "2022-05-09T19:44:00+02:00"
},
"configuration": {
"otdrSettings": {
"fiber": {
"number": 0,
"cableId": "Cable_ID",
"fiberId": "5000-101_port2",
"direction": "Loc A > Loc B",
"locationA": "Loc A",
"locationB": "Loc B",
"fiberLabel": ""
},
"setup": [
{
"pulse": "10ns",
"range": "450m",
"refrIndex": 1.4685,
"resolution": "16cm",
"scatterCoef": -81,
"wavelengthNm": 1625,
"bendOnSplicedB": 0,
"averagingTimeSec": 20,
"bendOnConnectordB": 0
}
],
"configFile": "",
"launchCable": {
"endCableUsed": "No",
"startCableUsed": "No",
"includeLinkEndConnector": false,
"includeLinkStartConnector": false
},
"otdrTopology": "Expert-SM",
"alarmThresholds": {
"type": "fail",
"orldB": 27,
"spliceLossdB": 0.2,

22 User Manual 70ONMSI80 Rev. 000

 Chapter 3 REST API Quick Start
API measurements resources

"thresholdSet": "User",
"reflectancedB": -35,
"fiberLengthMin": 0.02,
"connectorLossdB": 0.7,
"slopeThresholds": [
{
"slopedBkm": 1,
"wavelengthNm": 1625
}
]
}
}
},
"schemaVersion": "1.2.0"
},
{
"type": "ONMSI",
"results": {
"data": {
"measurement": {
"buildTest": {
"createdBy": "admin",
"eventsAlarm": false,
"beginLeveldB": -27.91,
"beginDistanceM": 10.69,
"fiberEndDetected": false,
"splitterDetected": false
}
}
},
"status": "fail",
"testTime": "2022-05-09T19:44:00+02:00"
},
"configuration": {
"measurement": {
"otu": {
"uid": "hapy_cbbrm_20771",
"name": "otu-5000-00101",
"port": 2,

User Manual 70ONMSI80 Rev. 000 23

Chapter 3 REST API Quick Start
API measurements resources

"portName": "OS(2)"
},
"link": {
"uid": "hapy_cbbrm_21045",
"name": "5000-101_port2"
},
"buildTest": {
"uid": "hapy_cbbrm_21058",
"name": "Build_Auto_New"
},
"domainList": [
{
"uid": "hapy_cbbrm_229",
"name": "Default"
}
],
"domainTree": [
[
{
"uid": "hapy_cbbrm_229",
"name": "Default"
}
]
],
"centralOffice": {
"uid": "hapy_cbbrm_21035",
"name": "CO SD Build",
"additionalAttributes": {
"External key": "CO SD Build"
}
}
}
},
"schemaVersion": "1.0.0"
}
],
"checkSum": "_NOT_EVALUATED_",
"assetInfo": {
"model": "OTU 5000",

24 User Manual 70ONMSI80 Rev. 000

 Chapter 3 REST API Quick Start
API alarms end points

"uniqueId": "OTU 5000_EBAJ00101",

"assetType": "Unknown",
"hwVersion": "",
"swOptions": [],
"swVersion": "21.99",
"modulesInfo": [
{
"model": "EOTDR2-L-A1-COTU",
"uniqueId": "EOTDR2-L-A1-COTU_101",
"assetType": "T-BERD/MTS module",
"swVersion": ""
}
],
"manufacturer": "VIAVI Solutions",
"calibrationDate": "2022-04-12"
},
"cdmVersion": "2.1"
},
"internalKey": 380,
"schemaVersion": "1.0.0"
}

API alarms end points

Document the GETs operations on <fa-server>/fa/api/alarms.

CAUTION
The GET requests are limited to return a MAXIMUM of 500 items. Client iterative fil-
tering (by rows) or paginated requests are necessary to fetch a large set of alarms.

GET /fa/api/alarms
The GET /fa/api/alarms operation is used to get full contents of alarms.
• Header:
– Authorization: Bearer <with JWT token provided by authentication>
• Response message:
– JSON Array of alarms

User Manual 70ONMSI80 Rev. 000 25

Chapter 3 REST API Quick Start
API alarms end points

• Returned codes:
– 200 OK
– 400 Bad Request: When requested role does not exist.
– 401 Unauthorized: JWT token is missing, badly signed or expired. A detailed
message is provided.

Basic request
CURL request example

CURL request

curl -i -X GET \
-H "Authorization:Bearer <yourToken>" \
'http://topaz-fa-demo/fa/api/alarms'
HTTP details

Request example

GET /fa/api/alarms HTTP/1.1

Authorization: Bearer Authorization:Bearer <yourToken>

Host: topaz-fa-demo

26 User Manual 70ONMSI80 Rev. 000

 Chapter 3 REST API Quick Start
API alarms end points

Response example

HTTP/1.1 200 OK
Server: nginx
Date: Wed, 09 Jun 2021 14:18:22 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Content-Encoding: gzip
Content-Range: 0-499/*
Content-Location: /alarms
[{"alarmUid":"hapy_cbbrm_121","updatedDate":"2022-05-
18T17:54:13.358+02:00","alarm":{"type": "EQUIPMENT_ALARM", "events":
[{"uid": "hapy_cbbrm_44148", "time": "2022-05-18T17:37:07+02:00",
"type": "NEW", "ackStatus": "UNACKNOWLEDGED", "clearStatus":
"UNCLEARED", "perceivedSeverity": "MAJOR"}, {"uid":
"hapy_cbbrm_44229", "time": "2022-05-18T17:54:13.212+02:00", "type":
"CLR", "ackStatus": "UNACKNOWLEDGED", "clearStatus": "CLEARED",
"userIdentifier": "admin", "systemIdentifier": "ONMSi",
"perceivedSeverity": "MAJOR"}], "origin": {"uid": "hapy_cbbrm_43587",
"type": "OTU"}, "context": {"otu": {"uid": "hapy_cbbrm_43587",
"name": "otuv2-system-test1", "device": "OTU 8000E", "ipAddress":
"otuv2-system-test1", "serialNumber": "0013", "softwareVersion":
"21.26", "parentDomainUids": ["hapy_cbbrm_229"]}, "domainList":
[{"uid": "hapy_cbbrm_229", "name": "Default"}], "domainTree":
[[{"uid": "hapy_cbbrm_229", "name": "Default"}]], "centralOffice":
{"uid": "hapy_cbbrm_44156", "name": "CO CO_Test_21_26",
"additionalAttributes": {"External key": "CO_CO_Test_21_26"}}},
"systemDn": "ONMSi", "ackStatus": "UNACKNOWLEDGED", "raisedTime":
"2022-05-18T17:37:07+02:00", "changedTime": "2022-05-
18T17:54:13.212+02:00", "clearStatus": "CLEARED", "probableCause":
"other", "schemaVersion": "1.0.0", "specificProblem":
"AUTOTEST_TEST_SYNCHRONIZATION", "latestClearedTime": "2022-05-
18T17:54:13.212+02:00", "perceivedSeverity": "MAJOR",
"maxPerceivedSeverity": "MAJOR"}},...

Advanced request: Horizontal filtering (rows)

• Get alarm by uid:

Request for an alarm with an uid equals to hapy_cbbrm_11

GET /fa/api/alarms?alarmUid=eq.hapy_cbbrm_11

Note: Alarm uids are unique identifiers obtained by a concatenation of

1 ONMSi unique instance name (ex: hapy_cbbrm)
2 ONMSi alarm object id (11)

• Get multiple alarms with condition on updated date:

User Manual 70ONMSI80 Rev. 000 27

Chapter 3 REST API Quick Start
API alarms resources

CAUTION
ONMSi monitoring system is continuously updating the state of alarms according to
the state of the customer network. The API data reflects the LATEST state of alarms.

Request for alarms with range of updated date

GET /fa/api/alarms?updatedDate=gte.2020-08-01T00:00:00&updated-
Date=lt.2020-08-
02T00:00:00

API alarms resources

Alarms returned by the GET REST API request is a JSON array.

Response example

[
...
{
"alarmUid": "hapy_cbbrm_11",
"updatedDate": "2022-05-05T19:12:09.077+02:00",
"alarm": {
// HERE TAKE PLACE THE ALARM
}
},
{
"alarmUid": "hapy_cbbrm_13",
"updatedDate": "2022-05-05T19:15:29.165+02:00",
"alarm": {
// HERE TAKE PLACE THE ALARM
}
},
...
]

The detailed grammar, described by JSON schema, is available in separate files.

• "fa-api-alarm-event.schema.json
• "fa-api-alarm.schema.json
• "fa-api-fault.schema.json
• "fa-api-context.schema.json

Herebelow is an example of a complete alarm.

28 User Manual 70ONMSI80 Rev. 000

 Chapter 3 REST API Quick Start
API alarms resources

Individual build test measurement example

{
"type": "QUALITY_OF_SERVICE_ALARM",
"fault": {
"uid": "hapy_cbbrm_20721",
"faultType": "POINT_TO_POINT",
"geoLocation": {
"latitude": 41.91678837,
"longitude": 12.45494997
},
"pointToPoint": {
"attenuation": {
"distanceM": 6738.00,
"attenuationdB": -15.00
},
"localization": {
"uid": "hapy_cbbrm_20722",
"inLaunchCable": false,
"onOutOfSyncTest": false,
"lmOptEventAssocInvalid": true,
"opticalDistFromOriginM": 6738.00,
"cableLengthFromNetworkM": 0.00,
"lmOptEventAssocDisabled": false,
"originatingLinkChunkUid": "hapy_cbbrm_20610",
"distSecondLandmarkAfterM": 3859.72,
"optDistSecLandmarkAfterM": 4183.19,
"distSecondLandmarkBeforeM": 37.23,
"optDistSecLandmarkBeforeM": 61.71,
"secondaryLandmarkAfterName": "Parco Tor di Quinto",
"secondaryLandmarkBeforeName": "Piazzale Clodio"
},
"deviationLinkLossdB": 3.40,
"lastMarkerDistanceM": 10766.44,
"firstMarkerDistanceM": 36.45,
"pointToPointFaultType": "ATTENUATION",
"deviationFirstMarkerdB": 0.12
}

User Manual 70ONMSI80 Rev. 000 29

Chapter 3 REST API Quick Start
API alarms resources

},
"events": [
{
"uid": "hapy_cbbrm_20723",
"time": "2022-05-09T17:35:44+02:00",
"type": "NEW",
"ackStatus": "UNACKNOWLEDGED",
"clearStatus": "UNCLEARED",
"additionalText": "FIBER_CUT",
"perceivedSeverity": "MAJOR"
},
{
"uid": "hapy_cbbrm_20757",
"time": "2022-05-09T17:41:09.844+02:00",
"type": "CMT",
"ackStatus": "UNACKNOWLEDGED",
"clearStatus": "UNCLEARED",
"additionalText": "J'y vais.",
"userIdentifier": "fer53986",
"perceivedSeverity": "MAJOR"
},
{
"uid": "hapy_cbbrm_45991",
"time": "2022-05-19T13:08:57.685+02:00",
"type": "CLR",
"ackStatus": "UNACKNOWLEDGED",
"clearStatus": "CLEARED",
"userIdentifier": "admin",
"systemIdentifier": "ONMSi",
"perceivedSeverity": "CRITICAL"
}
],
"origin": {
"uid": "hapy_cbbrm_19689",
"type": "LINK"
},
"context": {
"otu": {
"uid": "hapy_cbbrm_7497",
"name": "vOTU-BF-333",
"port": 1
},
"link": {

30 User Manual 70ONMSI80 Rev. 000

 Chapter 3 REST API Quick Start
API alarms resources

"uid": "hapy_cbbrm_19689",
"name": "vOTU-BF-333 OS(1)"
},
"test": {
"uid": "hapy_cbbrm_19696",
"name": "test1"
},
"domainList": [
{
"uid": "hapy_cbbrm_17151",
"name": "P2P-BFL"
},
{
"uid": "hapy_cbbrm_6777",
"name": "BFL"
}
],
"domainTree": [
[
{
"uid": "hapy_cbbrm_6777",
"name": "BFL"
},
{
"uid": "hapy_cbbrm_17151",
"name": "P2P-BFL"
}
]
],
"centralOffice": {
"uid": "hapy_cbbrm_20517",
"name": "Colosseo",
"additionalAttributes": {
"External key": "FNM_10006"
}
}
},
"details": "FIBER_CUT",
"systemDn": "OTU ID=7497, SN=EBAF33333",
"ackStatus": "ACKNOWLEDGED",
"raisedTime": "2022-05-09T17:35:44+02:00",
"changedTime": "2022-05-19T13:15:24.926+02:00",
"clearStatus": "UNCLEARED",

User Manual 70ONMSI80 Rev. 000 31

Chapter 3 REST API Quick Start
API alarms resources

"probableCause": "thresholdCrossed",
"schemaVersion": "1.0.0",
"specificProblem": "ATTENUATION",
"latestClearedTime": "2022-05-19T13:08:57.685+02:00",
"perceivedSeverity": "CRITICAL",
"latestUnclearedTime": "2022-05-19T13:15:22.266+02:00",
"maxPerceivedSeverity": "CRITICAL"
}
"domainList": [
{
"uid": "hell_sfl6o_3842",
"name": "North"
},
{
"uid": "hell_sfl6o_731521",
"name": "RAJ"
},
{
"uid": "hell_sfl6o_799983",
"name": "Jaipur"
}
],
"domainTree": [
[
{
"uid": "hell_sfl6o_3842",
"name": "North"
},
{
"uid": "hell_sfl6o_731521",
"name": "RAJ"
},
{
"uid": "hell_sfl6o_799983",
"name": "Jaipur"
}
]
]
},
"details": "ATTENUATION",
"systemDn": "OTU ID=799985, SN=0",

32 User Manual 70ONMSI80 Rev. 000

 Chapter 3 REST API Quick Start
API homes end points

"ackStatus": "UNACKNOWLEDGED",
"raisedTime": "2020-01-01T00:17:34+00:00",
"changedTime": "2020-01-01T00:19:01+00:00",
"clearStatus": "CLEARED",
"probableCause": "thresholdCrossed",
"schemaVersion": "1.0.0",
"specificProblem": "ATTENUATION",
"latestClearedTime": "2020-01-01T00:19:01+00:00",
"perceivedSeverity": "MAJOR",
"maxPerceivedSeverity": "MAJOR"
}

API homes end points

Document the GETs operations on <fa-server>/fa/api/homes.

CAUTION
The GET requests are limited to return a MAXIMUM of 500 items. Client iterative fil-
tering (by rows) or paginated requests are necessary to fetch large set of homes.

GET /fa/api/homes
The GET /fa/api/homes operation is used to get full contents of homes.
• Header:
– Authorization: Bearer <with JWT token provided by authentication>
• Response message:
– JSON Array of homes
• Returned codes:
– 200 OK
– 400 Bad Request: When requested role does not exist.
– 401 Unauthorized: JWT token is missing, badly signed or expired. A detailed
message is provided.

Basic request
CURL request example

User Manual 70ONMSI80 Rev. 000 33

Chapter 3 REST API Quick Start
API homes end points

CURL request

curl -i -X GET \
-H "Authorization:Bearer <yourToken>" \
'http://topaz-fa-demo/fa/api/homes'
HTTP details

Request example

GET /fa/api/homes HTTP/1.1

Authorization:Bearer <yourToken>

Host: topaz-fa-demo

34 User Manual 70ONMSI80 Rev. 000

 Chapter 3 REST API Quick Start
API homes end points

Response example

HTTP/1.1 200 OK
Server: nginx
Date: Wed, 09 Jun 2021 14:18:22 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Content-Encoding: gzip
Content-Range: 0-499/*
Content-Location: /homes
[{"homeUid":"hapy_cbbrm_3311","updatedDate":"2022-05-
16T17:13:29.477+02:00","home":{"vip": false, "name": "Home CO2-
01/01", "context": {"otu": {"uid": "hapy_cbbrm_6113", "name":
"otu-8000e-10548", "port": 2}, "link": {"uid": "hapy_cb-
brm_3303", "name": "CO2-01", "additionalAttributes": {"External
key": "CO2-01"}}, "test": {"uid": "hapy_cbbrm_3310", "name":
"CO2-01"}, "domainList": [{"uid": "hapy_cbbrm_22707", "name":
"Domain Jan"}, {"uid": "hapy_cbbrm_2593", "name": "PON"}],
"domainTree": [[{"uid": "hapy_cbbrm_22707", "name": "Domain
Jan"}], [{"uid": "hapy_cbbrm_2593", "name": "PON"}]], "central-
Office": {"uid": "hapy_cbbrm_3301", "name": "CO CO2", "addition-
alAttributes": {"External key": "CO_CO2"}}}, "updatedBy":
"supportONMSi", "identifier": "923785695535047", "schemaVer-
sion": "1.0.0", "peakMeasurementResult": {"uid": "hapy_cb-
brm_39515", "status": "OK", "reflector": {"name": "FBG-0dB",
"description": "1650nm FBG reflector (APC)", "reflectancedB": -
0.25}, "measuredBy": "admin", "insertionLossdB": 29.81,
"measurementDate": "2022-05-16T17:13:09", "distanceFrom-
OriginM": 10624.96, "levelFromReferencePointdB": 8.10, "uncon-
firmedInsertionLossdB": 29.81},
"referencePeakMeasurementResult": {"uid": "hapy_cbbrm_6748",
"status": "NEW", "measuredBy": "supportONMSi", "associationBy":
"supportONMSi", "associationDate": "2022-05-
05T17:36:25.234+02:00", "measurementDate": "2022-05-
05T17:35:45", "distanceFromOriginM": 10624.84, "levelFromRefer-
encePointdB": 7.64}}},...

Advanced request: Horizontal filtering (rows)

• Get home by uid:

Request for a home having an uid equals to hapy_cbbrm_44172

GET /fa/api/homes?homeUid=eq.hapy_cbbrm_44172

Note: Home uids are unique identifiers obtained by a concatenation of

1 ONMSi unique instance name (ex: hapy_cbbrm)

User Manual 70ONMSI80 Rev. 000 35

Chapter 3 REST API Quick Start
API Home resources

2 ONMSi home object id (44172)

• Get multiple homes with condition on updated date:

CAUTION
ONMSi monitoring system is continuously updating state of homes according to the
state of the customer network. The API data reflects the LATEST state of homes.

Request for homes with range of updated date

GET /fa/api/homes?updatedDate=gte.2022-05-01T00:00:00&updated-
Date=lte.2022-06-01T00:00:00

API Home resources

Homes returned by the GET REST API request is a JSON array.

GET Response structure

[
...
{
"homeUid": "hapy_cbbrm_3311",
"updatedDate": "2022-05-16T17:13:29.477+02:00",
"home": {
// HERE TAKE PLACE THE HOME
}
},
{
"homeUid": "hapy_cbbrm_3312",
"updatedDate": "2022-05-16T17:13:29.508+02:00",
"home": {
// HERE TAKE PLACE THE HOME
}
},
...
]

36 User Manual 70ONMSI80 Rev. 000

 Chapter 3 REST API Quick Start
API Home resources

The detailed grammar, described by JSON schema, is available in separate files.

• fa-api-home.schema.json
• fa-api-peak-measurement-result.schema.json
• fa-api-context.schema.json

Herebelow is an example of a complete home

Individual home example

{
"vip": false,
"name": "Home CO2-01/01",
"context": {
"otu": {
"uid": "hapy_cbbrm_6113",
"name": "otu-8000e-10548",
"port": 2
},
"link": {
"uid": "hapy_cbbrm_3303",
"name": "CO2-01",
"additionalAttributes": {
"External key": "CO2-01"
}
},
"test": {
"uid": "hapy_cbbrm_3310",
"name": "CO2-01"
},
"domainList": [
{
"uid": "hapy_cbbrm_22707",
"name": "Domain Jan"
},
{
"uid": "hapy_cbbrm_2593",
"name": "PON"
}
],
"domainTree": [
[
{
"uid": "hapy_cbbrm_22707",
"name": "Domain Jan"
}
],

User Manual 70ONMSI80 Rev. 000 37

Chapter 3 REST API Quick Start
API Home resources

[
{
"uid": "hapy_cbbrm_2593",
"name": "PON"
}
]
],
"centralOffice": {
"uid": "hapy_cbbrm_3301",
"name": "CO CO2",
"additionalAttributes": {
"External key": "CO_CO2"
}
}
},
"updatedBy": "supportONMSi",
"identifier": "923785695535047",
"schemaVersion": "1.0.0",
"peakMeasurementResult": {
"uid": "hapy_cbbrm_39515",
"status": "OK",
"reflector": {
"name": "FBG-0dB",
"description": "1650nm FBG reflector (APC)",
"reflectancedB": -0.25
},
"measuredBy": "admin",
"insertionLossdB": 29.81,
"measurementDate": "2022-05-16T17:13:09",
"distanceFromOriginM": 10624.96,
"levelFromReferencePointdB": 8.10,
"unconfirmedInsertionLossdB": 29.81
},
"referencePeakMeasurementResult": {
"uid": "hapy_cbbrm_6748",
"status": "NEW",
"measuredBy": "supportONMSi",
"associationBy": "supportONMSi",
"associationDate": "2022-05-05T17:36:25.234+02:00",
"measurementDate": "2022-05-05T17:35:45",
"distanceFromOriginM": 10624.84,
"levelFromReferencePointdB": 7.64
}
}

38 User Manual 70ONMSI80 Rev. 000

 Chapter 3 REST API Quick Start
API test_points end points

API test_points end points

Document the GETs operations on <fa-server>/fa/api/test_points.

CAUTION
The GET requests are limited to return a MAXIMUM of 500 items. Client iterative fil-
tering (by rows) or paginated requests are necessary to fetch a large set of test
points.

GET /fa/api/test_points
The GET /fa/api/test_points operation is used to get full contents of test points.
• Header:
– Authorization: Bearer <with JWT token provided by authentication>

• Response message:
– JSON Array of test points

• Returned codes:
– 200 OK
– 400 Bad Request: When requested role does not exist.
– 401 Unauthorized: JWT token is missing, badly signed or expired. A detailed
message is provided.

Basic request
CURL request example

CURL request

curl -i -X GET \
-H "Authorization:Bearer <yourToken>" \
'http://topaz-fa-demo/fa/api/test_points'
HTTP details

User Manual 70ONMSI80 Rev. 000 39

Chapter 3 REST API Quick Start
API test_points end points

Request example

GET /fa/api/test_points HTTP/1.1

Authorization:Bearer <yourToken>

Host: topaz-fa-demo

Response example

HTTP/1.1 200 OK
Server: nginx
Date: Wed, 09 Jun 2021 14:18:22 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Content-Encoding: gzip
Content-Range: 0-499/*
Content-Location: /test_points
[{"test_point_uid":"hapy_cbbrm_26188","updatedDate":"2022-05-
12T14:19:57.416+02:00","testPoint":{"name": "TP SD_COs_1-01/1",
"context": {"link": {"uid": "hapy_cbbrm_26180", "name":
"SD_COs_1-01", "additionalAttributes": {"External key":
"SD_COs_1-01"}}, "test": {"uid": "hapy_cbbrm_26187", "name":
"SD_COs_1-01"}, "centralOffice": {"uid": "hapy_cbbrm_26178",
"name": "CO SD_COs_1", "additionalAttributes": {"External key":
"CO_SD_COs_1"}}}, "updatedBy": "supportONMSi", "schemaVersion":
"1.0.0"}},...

Advanced request: Horizontal filtering (rows)

• Get a test point by uid:

Request for a test point having a test point uid equals to hapy_cbbrm_26188

GET /fa/api/test_points?testPointUid=eq.hapy_cbbrm_26188

Note: Test point uids are unique identifiers obtained by a concatenation of

1 ONMSi unique instance name (ex: hapy_cbbrm)
2 ONMSi test point object id (26188)

• Get multiple test points with condition on updated date:

40 User Manual 70ONMSI80 Rev. 000

 Chapter 3 REST API Quick Start
API test_points resources

CAUTION
ONMSi monitoring system is continuously updating state of test points according to
the state of the customer network. The API data reflects the LATEST state of test
points.

Request for test points with range of updated date

GET /fa/api/test_points?updatedDate=gte.2022-05-
01T00:00:00&updatedDate=lte.2022-06-01T00:00:00

API test_points resources

Test point returned by the GET REST API request is a JSON array.

GET Response structure

[
…
{
"testPointUid": "hapy_cbbrm_26188",
"updatedDate": "2022-05-05 17:27:11.554 +0200",
"testPoint": {
// HERE TAKE PLACE THE TEST POINT
}
},
{
"testPointUid": "hapy_cbbrm_26189",
"updatedDate": "2022-05-05 17:27:11.715 +0200",
"testPoint": {
// HERE TAKE PLACE THE TEST POINT
}
},
...
]
The detailed grammar, described by JSON schema, is available in separate files.
• fa-api-testpoint.schema.json
• fa-api-peak-measurement-result.schema.json
• fa-api-context.schema.json

Herebelow is an example of a complete test point

User Manual 70ONMSI80 Rev. 000 41

Chapter 3 REST API Quick Start
Advanced request - Full documentation

Individual test point example

{
"name": "TP CO_SD-01/1/04",
"context": {
"link": {
"uid": "hapy_cbbrm_2599",
"name": "CO_SD-01",
"additionalAttributes": {
"External key": "CO_SD-01"
}
},
"test": {
"uid": "hapy_cbbrm_2606",
"name": "CO_SD-01"
},
"centralOffice": {
"uid": "hapy_cbbrm_2597",
"name": "CO CO_SD",
"additionalAttributes": {
"External key": "CO_CO_SD"
}
},
"upstreamTestPoint": {
"uid": "hapy_cbbrm_2617",
"name": "TP CO_SD-01/1"
}
},
"updatedBy": "supportONMSi",
"schemaVersion": "1.0.0"
}

Advanced request - Full documentation

Paginated requests
Two ways are offered to control the limits and pagination:
• Either by HTTP range headers, used to describe the size of results and the size of
request.
• Or by 'limit' and 'offset' query parameters.

42 User Manual 70ONMSI80 Rev. 000

 Chapter 3 REST API Quick Start
Advanced request - Full documentation

You are invited to read the full documentation for more details.

Full documentation
For a complete syntax of the requests, see:

PostgREST v7.0.0 Manual (https://postgrest.org/en/v7.0.0/api.html)

User Manual 70ONMSI80 Rev. 000 43

Chapter 3 REST API Quick Start
Advanced request - Full documentation

44 User Manual 70ONMSI80 Rev. 000

 4

Chapter 4 SQL API Quick Start

Topics discussed in this chapter are as follows:

• “Introduction” on page 46
• “Authentication” on page 46
• “Database connection example” on page 47
• “Data model” on page 48
• “Querying JSONb data” on page 51
• “Standard dashboards” on page 54

User Manual 70ONMSI80 Rev. 000 45

Chapter 4 SQL API Quick Start
Introduction

Introduction
The Fiber Analytics SQL API provides simple and direct SQL access to the fiber data
produced by ONMSi and OTU model 8kv2 and/or 5k.

This data is stored in a PostgreSQL 12 database, with the TimescaleDB extension and
mostly as JSONB data. Documentation can be found here:
• PostgreSQL JSON operators: https://www.postgresql.org/docs/12/functions-
json.html
• TimescaleDB operators: https://docs.timescale.com/api/latest/#timescaledb-api-
reference

Authentication

Pre-requisite
· A well configured FA server

· Valid Fiber Analytics licenses (ONMSi and OTUs)

Connection parameters
• Host: <fa-server>
• Port: 42006
• Database: fiberanalytics
• User: fiberanalytics
• Password: <password>
• TLS/SSL Mode: require

<fa-server> is the server hosting Fiber Analytics

<password> is the user-defined password for the fiberanalytics user. See below.

Set up the fiberanalytics user password

To finalize the fiberanalytics user login, you must create a password using the rfts_db
password command:

46 User Manual 70ONMSI80 Rev. 000

 Chapter 4 SQL API Quick Start
Database connection example

Password creation / update

#rfts_db password fiberanalytics

Fiberanalyics user new credentials:
- username: fiberanalytics
- password: L4fG7B1e

-c option allows user to define a custom password;

-l option allows the user to define length for auto-generation password.

Additional information
• The fiberanalytics database is a postgresSQL database, version 12.
• The timescale database extension (hypertable) is activated on this database.

Database connection example

DBeaver
You can get familiar to the data model structure while browsing it with DBeaver.

Connection settings

Figure 3 Connection settings

User Manual 70ONMSI80 Rev. 000 47

Chapter 4 SQL API Quick Start
Data model

Grafana
Grafana is a monitoring tool gaining in popularity and providing a simple querying inter-
face.

Setting up the datasource

Figure 4 DataSource SETTINGS

Data model
On the SQL API side, the data model is based on an ensemble of views: alarm,
build_test, home, measurement, monitoring_test and test_point.

Notes:
• When available, objects are identified by a universal identifier (uid). The numeric
part of this uid refers to the object id in ONMSi.
• Column types are JSONb, except for simple columns (dates, uids, etc);

48 User Manual 70ONMSI80 Rev. 000

 Chapter 4 SQL API Quick Start
Data model

The alarm view

Figure 5 Alarm view

The alarm view is composed of 6 columns:

• schema_version: the schema version of the JSON schema of the alarm;
• alarm_uid: unique identifier of the alarm;
• alarm: the alarm details;
• context: the context of the alarm;
• events: the event history of the alarm;
• fault: the fault related to the alarm.

The build_test view

Figure 6 Build test view

The build_test view is composed of 7 columns:

• schema_version: the schema version of the JSON schema of the build test;
• test_uid: the unique identifier of the build test;
• build_test: the build test details;
• context: the context of the build test;
• acquisition_date: the latest measurement date;
• measurement: the latest measurement cdm;
• onmsi_test: the onmsi test block enriching the measurement cdm.

User Manual 70ONMSI80 Rev. 000 49

Chapter 4 SQL API Quick Start
Data model

The Home view

Figure 7 Home view

The home view is composed of 7 columns:

• schema_version: the schema version of the JSON schema of the home;
• home_uid: the unique identifier of the build test;
• date_updated: the latest time the home or the measurement result was updated;
• home: the home details;
• context: the context of the home;
• peak_measurement_result: the latest peak measurement result;
• reference_peak_measurement_result: the reference peak measurement result.

The measurement view

Figure 8 Measurement view

The measurement view is composed of 6 columns:

• schema_version: the schema version of the JSON schema of the measurement;
• acquisition_date: latest time the home or the measurement result was updated;
• measurement: the measurement cdm;
• context: the context of the home;
• onmsi_test: the onmsi test block enriching the measurement cdm.

50 User Manual 70ONMSI80 Rev. 000

 Chapter 4 SQL API Quick Start
Querying JSONb data

The monitoring_test view

Figure 9 Monitoring test view

The monitoring_test view is composed of 6 columns:

• schema_version: the schema version of the JSON schema of the monitoring
test;
• test_uid: unique identifier of the monitoring test;
• monitoring_test: the monitoring test details;
• context: the context of the monitoring test;
• acquisition_date: the latest measurement date;
• measurement: the latest measurement cdm;
• onmsi_test: the onmsi test block enriching the measurement cdm.

The test_point view

Figure 10 Test point view

The test_point view is composed of 6 columns:

• schema_version: the schema version of the JSON schema of the test point;
• test_point_uid: unique identifier of the test point;
• date_updated: latest time the test point or the measurement result was updated;
• test_point: the test point details;
• context: the context of the test point;
• peak_measurement_result: the latest peak measurement result.

Querying JSONb data

Querying JSONb data is not trivial and requires some learning. You can find some
examples below.

User Manual 70ONMSI80 Rev. 000 51

Chapter 4 SQL API Quick Start
Querying JSONb data

Examples

By Top Domain Aggregation Alarm Query:

SELECT
COALESCE(alarm.context #>> '{domainTree,0,0,uid}','Null') AS
"Top Domains",
COUNT(*) AS "Number"
FROM
alarm AS alarm
GROUP BY
1
ORDER BY
1
This query results in the following table:

Which can ultimately be displayed like this:

By Type Aggregation Alarms Query:

SELECT
alarm.alarm #>> '{origin,type}' AS "Type",
COUNT(*) AS "Number"
FROM
alarm AS alarm
GROUP BY
1
This query results in the following table:

52 User Manual 70ONMSI80 Rev. 000

 Chapter 4 SQL API Quick Start
Querying JSONb data

Which can ultimately be displayed like this:

Geolocalization Alarm Query:

SELECT
initcap(alarm.alarm #>> '{origin,type}') AS origin,
1 AS value,
alarm.fault #>> '{geoLocation,latitude}' AS latitude,
alarm.fault #>> '{geoLocation,longitude}' AS longitude
FROM
alarm AS alarm
WHERE
alarm.alarm #>> '{clearStatus}' = 'UNCLEARED'
AND
alarm.fault #>> '{geoLocation,latitude}' IS NOT NULL
This query results in the following table:

Which can ultimately be displayed like this:

User Manual 70ONMSI80 Rev. 000 53

Chapter 4 SQL API Quick Start
Standard dashboards

Standard dashboards
Four Grafana dashboards are delivered with Fiber Analytics. They are dedicated to alarm
analysis and fiber quality analysis:

• Alarm Duration & compliance

• Alarm Geolocation
• Quality of optical network in terms of global linear attenuation
• Quality of fiber network in terms of optical event

Notes:

– Filters and parameters are accessible on top of the dashboard; however, data
are often filtered out implicitly when it was found convenient to do so.
– Data are available for download in a CSV format. Go to the panel header,
click on the arrow, then inspect, data and finally adjust with the option you
want.

1. Alarm Duration & compliance

Figure 11 Alarm duration and Compliance

This dashboard is related to the alarm duration and compliancy.

Filters and parameters

Implicit filter on quality-of-service alarms;

Grafana built-in time filter: for filtering alarms on a given period;

Domain: for filtering top domain by names;

Sub domain: for filtering sub domain by names;

Sub sub domain: for filtering sub sub domain by names;

54 User Manual 70ONMSI80 Rev. 000

 Chapter 4 SQL API Quick Start
Standard dashboards

Severity: for filtering alarms by severities (Critical, Major, Minor only);

Status: for filtering alarms by status (Cleared or Active);

SLA: Service Level Agreement, parameter used to determine alarm compliancy;

Panels
Alarms: Number of alarms according to filters.

Links: Number of links affected by the filtered alarms.

Cables: Number of cables affected by the filtered alarms.

Severity: Pie chart distribution of alarms severities.

Conformity: Pie chart distribution of alarms compliancy according to SLA threshold.

The drill-down fills up the Alarm Details panel.

Duration: Pie chart distribution of alarms duration. The drill-down fills up the Alarm
Details panel.

Alarm Details: Table listing the alarms on the link selected by drill down. Columns are
self-explanatory and the “More” column contains some available json data on the alarm.

Alarm Geolocation

Figure 12 Alarm Geolocation

This dashboard is related to the alarm geolocation.

Filters and parameters

Implicit filter on quality-of-service alarms;

Implicit filter on geo-localized alarms;

Grafana built-in time filter: for filtering alarms on a given period;

Domain: for filtering top domain by names;

User Manual 70ONMSI80 Rev. 000 55

Chapter 4 SQL API Quick Start
Standard dashboards

Sub domain: for filtering sub domain by names;

Sub sub domain: for filtering sub sub domain by names;

Severity: for filtering alarms by severities (Critical, Major, Minor only);

Status: for filtering alarms by status (Cleared or Active);

Panels
Alarms: Number of alarms according to filters.

Links: Number of links affected by the filtered alarms.

Cables: Number of cables affected by the filtered alarms.

Geolocalized Alarms: Map showing geo-localized alarms. Map requires an internet

connection, is freely accessible thanks to openstreetmap, but has to be used with
caution. Drill-down on geo-localized alarms fills up the Link Alarm Distribution panel.

Link Alarm Distribution: Histogram distribution of alarms of a link selected by drill-

down as a function of link length segment. Drill-down fills the Alarm Details panel.

Alarm Details: Table listing the alarms on the link selected by drill down. Columns are
self-explanatory and the “More” column contains some available json data on the alarm.

Quality of optical network in terms of global linear attenuation

Figure 13 Quality of Optical Network - Global linear attenuation

This dashboard is related to the analysis of links.

56 User Manual 70ONMSI80 Rev. 000

 Chapter 4 SQL API Quick Start
Standard dashboards

Filters and parameters

Implicit filter on fa-monitored tests;

Grafana built-in time filter: for computing link trend and displaying link linear attenu-
ation;

Domain: for filtering top domain by names;

Sub domain: for filtering sub domain by names;

Sub sub domain: for filtering sub sub domain by names;

Good link: threshold for good quality link;

Bad link: threshold for bad quality link;

Panels
Links: Number of links according to filters.

Cables: Number of cables according to filtered links.

Link Quality: Distribution of links quality according good and bad thresholds. The drill-
down on the pie chart fills up the Link Details panel.

Link Details: Table listing links according to a given link quality selected by drill-down.
Columns are self-explanatory. The “More” column aggregates some json-data available
for links (context, latest measurement, onmsi test). The drill-down fills up the Linear
Attenuation (dB/km), Event Distribution and the Event Details panels.

Linear Attenuation (dB/km): Representation of the linear attenuation of the link

selected by drill-down. Time range is related to the Grafana built-in time filter.

Event Distribution: Histogram distribution of the latest measurement events of the link
selected by drill-down as a function of link length segmentation.

Event Details: Table of the latest measurement events of the link selected by drill-
down. Column names are self-explanatory, and data is sorted from the worst loss to the
best to quickly identify bad events.

User Manual 70ONMSI80 Rev. 000 57

Chapter 4 SQL API Quick Start
Standard dashboards

Quality of fiber network in terms of optical event

Figure 14 Quality of fiber network - Optical event

This dashboard is related to the analysis of events.

Filters and parameters

Implicit filter on fa-monitored tests;

Grafana built-in time filter: not used;

Domain: for filtering top domain by names;

Sub domain: for filtering sub domain by names;

Sub sub domain: for filtering sub sub domain by names;

Good splice: loss threshold for good quality splice;

Bad splice: loss threshold for bad quality splice;

Good connector (loss): loss threshold for good quality connector;

Bad connector (loss): loss threshold for bad quality connector;

Good connector (reflectance): reflectance threshold for good quality connector;

Bad connector (reflectance): reflectance threshold for bad quality connector;

Good slope: loss threshold for good quality slope;

Bad slope: loss threshold for bad quality slope;

Panels
Events: Number of events according to filters.

Links: Number of links associated to the filtered events.

58 User Manual 70ONMSI80 Rev. 000

 Chapter 4 SQL API Quick Start
Standard dashboards

Cables: Number of cables associated to the filtered links.

Event Type: Distribution of events according to their type.

Splice (loss): Distribution of splice quality according to splice thresholds. The drill-
down fills up the Event Details panel.

Connector (loss): Distribution of connector quality according to loss connector thresh-

olds. The drill-down fills up the Event Details panel.

Connector (reflectance): Distribution of connector quality according to reflectance

connector thresholds. The drill-down fills up the Event Details panel.

Slope (slope): Distribution of slope quality according to slope thresholds. The drill-
down fills up the Event Details panel.

Events Details: Table listing events type and quality selected by drill-down. Columns
are self-explanatory. The “More” column aggregates some available json-data
(onmsiTest, context, latestMeasurement).

User Manual 70ONMSI80 Rev. 000 59

Chapter 4 SQL API Quick Start
Standard dashboards

60 User Manual 70ONMSI80 Rev. 000

70ONMSI80
Rev. 000, February 2023
English

VIAVI Solutions
North America: 1.844.GO VIAVI / 1.844.468.4284
Latin America +52 55 5543 6644
EMEA +49 7121 862273
APAC +1 512 201 6534
All Other Regions: viavisolutions.com/contacts
email [email protected]
address 7047 E. Greenway Pkwy, Suite 250, Scottsdale, AZ 85254, US