CityFibre - Service Diagnostics API

Download OpenAPI specification:Download

API Development Team: apiteam@cityfibre.com URL: https://www.cityfibre.com License: Apache 2.0 Terms of Service

Introduction

This documentation provides information on the Service Diagnostics API and how to access it.

Please note:

In this document, we use Buyer and Supplier for the Service Provider / CityFibre respectively and Reporter as the person within the Buyers Organisation.

This document describes the messages which can pass between Buyer and Supplier, and the various status changes and updates for diagnostic requests though-out the process.

Design Overview

See diagram Diagnostic_API_v1.1 for an overview of the flow.

Accessing the API

The API is accessed via HTTPS. Calls are made by POST, sending XML as the HTTP body.

Messages are exchanged using SOAP exchanges over HTTPS POST, where the request is in the POST body and the response is in the HTTP response body. Messages are encapsulated in a SOAP envelope using Document/Literal style following WS-Basic Profile 1.0.

    <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

        <soap:Body>

             ... single request or response element goes here ...

        </soap:Body>

    </soap:Envelope>

Integration Environments

CityFibre provides two pre-production environments for the Buyer to integrate with, to allow the Buyer to test the API endpoint before going live.

Authentication

Authentication is handled in the same way as the Order API and the authentication details provided apply to this API endpoint.

Below are the details for these environments:

CFSIT: https://api-gw.cityfibre.com:41223/cfsit/api2

CFStaging: https://api-gw.cityfibre.com:41223/cfstaging/api2

Production: https://api-gw.cityfibre.com:41223/prod/api2

Service Diagnostics

The Buyer can request diagnostic information for a serviceId reported in the request. The request will come synchronously and contain the serviceDiagnostic information.

The response to a requestServiceDiagnostics call contains the current state of the service and the utilisation status of the network path during the last busy period.

Request Service Diagnostics

When the request is received and the ServiceID is validated, the ServiceID is used to Diagnose the network, the found details are then returned to the Supplier in the supplierDiagnostics element of the faultDetails. The details returned are:

ONT Status (Status)

Service Up / Service Down
Dying Gasp
Last Date
Time this event was received
The change from the previous state

CFM Status (CFM Status)

Up/Down CF/Down ISP
Last Date
Time this event was received
The change from the previous state

UniPort Status (Uniport Status)

Up/Down
Last Date
Time this event was received
The change from the previous state

Please note – with UniPort Status the Status will continue to show as UP if the ONT Status is DOWN. This is due to the ONT not being able to communicate the UniPort status. In this instance the ONT Status should take priority in the diagnostic analysis. If UniPort Status is blank please use ONT & CFM Status to determine line condition.

In conjunction with the diagnostics process, nodes are classified within distinct lists based on their geographical context:

Local Configuration: Identified as ENNI - Interconnect - PON, these nodes signify local network interconnections.
National Configuration: Denoted as Interconnect - Handoff - ENNI - PON, these nodes represent national-level network interconnections.

Further, the operational status of these nodes is evaluated and categorized into the following states: Red, Orange, Green, and Unk (for unknown status).

For definition the POP is given a RAG status based upon peak loading over 5 minutes during the Busy Period, currently defined in Schedule 1.

For the PON, the RAG Status is based upon the peak loading over 15 minutes during the Busy Period currently defined in Schedule 1.

For confirmation the RAG status limits are below:

Red – 95% or higher
Amber – 80% or more to 94%
Green – Less than 79%

Based on the analysis of ONT Status, CFM (Connectivity Fault Management) Status, and Uniport Status, we can now provide a clearer picture of the end-user's service on our network. This enables us to offer the following 9 recommended Next Best Action codes to resolve potential issues effectively:

Code	Current Status	Result Description	Next Best Action
AOK001	Service Working	ONT, Connectivity & Port Status results are all Up	We do not believe there is an issue on our network
CFH001	Potential Service Issue Detected	ONT is down indicating a potential Fibre issue	Please continue to raise this incident as Total Loss of Service with as much detail as possible including which lights on the ONT are on
CFH002	Potential Service Issue Detected	ONT is Up, however Connectivity messaging indicates a potential CityFibre issue	Please continue to raise this incident as Total Loss of Service with as much detail as possible including which lights on the ONT are on
CFH003	Potential Service Issue Detected at the End User Premises	ONT is Up, however Connectivity and Port messaging indicates no connection to the ONT Ethernet Port	Our latest checks show that the service may not be working as expected
DYG001	CityFibre ONT Powered Off	ONT messaging is reporting a power supply issue	Our latest checks show that the ONT is not connected to a power supply or has been powered off
ISP001	Potential Service Issue Detected at the End Users Premises	ONT is Up, however Connectivity and Port messaging indicates no connection to the ONT Ethernet Port	Our latest checks show that the service may not be working as expected
ISP002	Potential Service Issue Detected at the End Users Premises	ONT is Up, however Connectivity and Port messaging indicates a connectivity issue with the End-Users Router	Our latest checks show that the service may not be working as expected
ISP003	Service Working	ONT, Connectivity Results are all Up. However please check the connection to the ONT Ethernet Port	Our latest checks show that the service is working as expected
STF001	Unable to Check Network Status	The Service Test has not been able to run	Please continue to raise an incident

SecurityCertificate

Request

Request Body schema: application/xml

apiVersion required	string (apiVersion) <= 36 characters The API version
required	object (buyer) The Service Provider who consumes the service is the buyer
required	object (message) The meta-data of the request. It includes information regarding the message UUID, transaction ID and the sent timestamp
serviceId required	string (serviceId) <= 36 characters Unique Identifier for the service

Responses

200

Service Diagnostics Response

400

Broken XML (400 Bad Request)

401

Unauthorized

403

Unauthenticated

post/requestServiceDiagnostics

Request samples

application/xml

<requestServiceDiagnostics xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="../faultReport.xsd">
  <apiVersion>1.0</apiVersion>
  <buyerIdentifier>SPDEV1</buyerIdentifier>
  <sentAt>2018-05-16T12:01:00Z</sentAt>
  <messageId>unique-message-id</messageId>
  <serviceId>S0012345</serviceId>
</requestServiceDiagnostics>

Response samples

application/xml

<serviceDiagnostics xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="../faultReport.xsd">
  <apiVersion>1.0</apiVersion>
  <buyerIdentifier>SPDEV1</buyerIdentifier>
  <sentAt>2018-05-16T12:01:00Z</sentAt>
  <messageId>unique-message-id</messageId>
  <serviceId>S0012345</serviceId>
  <currentCFMStatus>
    <status>Up</status>
    <lastStatusChange>
      <at>2020-03-24T21:44:30</at>
      <from>Down</from>
      <to>Up</to>
    </lastStatusChange>
  </currentCFMStatus>
  <currentUniportStatus>
    <status>Up</status>
    <lastStatusChange>
      <at>2024-03-20T12:09:11</at>
      <from>Down</from>
      <to>Up</to>
    </lastStatusChange>
  </currentUniportStatus>
  <currentStatus>
    <status>up</status>
    <lastStatusChange>
      <at>2018-05-16T12:01:00Z</at>
      <from>down</from>
      <to>up</to>
    </lastStatusChange>
  </currentStatus>
  <servicePathUsage>
    <nodeUtilisation>
      <nodeName>ENNI</nodeName>
      <nodeStatus>green</nodeStatus>
    </nodeUtilisation>
    <nodeUtilisation>
      <nodeName>Interconnect</nodeName>
      <nodeStatus>green</nodeStatus>
    </nodeUtilisation>
    <nodeUtilisation>
      <nodeName>PON</nodeName>
      <nodeStatus>green</nodeStatus>
    </nodeUtilisation>
  </servicePathUsage>
  <nextBestAction>
    <code>AOK001</code>
    <title>Service Working</title>
    <description>Our latest checks show that the service is working as expected. There does not appear to be an issue within the CityFibre network. We do not believe there is an issue for CityFibre to fix. You can still raise an incident if you wish, however there may be a charge if no CityFibre fault is found.</description>
  </nextBestAction>
</serviceDiagnostics>

XSD File

Get the XSD for the Service Diagnostics

get/serviceDiagnostics.txt

Request samples

XSD
Node.js
JavaScript
PHP
Python

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema elementFormDefault="qualified"
    xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:import namespace="http://schemas.xmlsoap.org/soap/envelope/" schemaLocation="http://schemas.xmlsoap.org/soap/envelope/" />

    <xs:element name="requestServiceDiagnostics" type="requestServiceDiagnosticsType"/>
    <xs:element name="serviceDiagnostics" type="serviceDiagnosticsType"/>


    <!-- Buyer can request diagnostics for a service -->
    <xs:complexType name="requestServiceDiagnostics">
        <xs:all>
            <xs:element name="apiVersion" type="xs:string"/>
            <xs:element name="buyerIdentifier" type="xs:string" />
            <xs:element name="sentAt" type="xs:dateTime" />
            <xs:element name="messageId" type="xs:string"/>
            <xs:element name="serviceId" type="xs:string"/>
        </xs:all>
    </xs:complexType>

    <!-- Response to a diagnostics request

    Includes the current status and the last "busy period" utilisation

    Current status includes up/down, last status change time and any ongoing incidents affecting the service.
    Usage includes a red/amber/green rating for each part of the network path, as well as the period it was calculated for.

    -->
    <xs:complexType name="requestServiceDiagnosticsType">
        <xs:all>
            <xs:element name="apiVersion" type="xs:string"/>
            <xs:element name="buyerIdentifier" type="xs:string" />
            <xs:element name="sentAt" type="xs:dateTime" />
            <xs:element name="messageId" type="xs:string"/>
            <xs:element name="serviceId" type="xs:string"/>
        </xs:all>
    </xs:complexType>

    <xs:complexType name="serviceDiagnosticsType">
        <xs:all>
            <xs:element name="apiVersion" type="xs:string"/>
            <xs:element name="buyerIdentifier" type="buyerIdentifier" />
            <xs:element name="sentAt" type="xs:dateTime" />
            <xs:element name="messageId" type="xs:string"/>
            <xs:element name="serviceId" type="xs:string"/>
            <xs:element minOccurs="0" name="currentStatus" type="currentStatusType"/>
            <xs:element minOccurs="0" name="currentCFMStatus" type="currentStatusType"/>
            <xs:element minOccurs="0" name="currentUniportStatus" type="currentStatusType"/>
            <xs:element minOccurs="0" name="servicePathUsage" type="serviceUsageType"/>
            <xs:element minOccurs="0" name="nextBestAction" type="nextBestActionType"/>
            <xs:element minOccurs="0" name="discoveredPON" type="xs:string"/>
            <xs:element minOccurs="0" name="errorMessage" type="xs:string"/>
        </xs:all>
    </xs:complexType>

    <xs:simpleType name="buyerIdentifier">
        <xs:restriction base="xs:string">
            <xs:maxLength value="36" />
        </xs:restriction>
    </xs:simpleType>

    <xs:complexType name="currentStatusType">
        <xs:all>
            <xs:element name="status" type="xs:string"/>
            <xs:element name="lastStatusChange">
                <xs:complexType>
                    <xs:all>
                        <xs:element name="at" type="xs:dateTime"/>
                        <xs:element name="from" type="xs:string"/>
                        <xs:element name="to" type="xs:string"/>
                    </xs:all>
                </xs:complexType>
            </xs:element>
        </xs:all>
    </xs:complexType>

    <xs:complexType name="serviceUsageType">
        <xs:sequence>
            <xs:element name="period" minOccurs="0" maxOccurs="1">
                <xs:complexType>
                    <xs:all>
                        <xs:element name="from" type="xs:dateTime"/>
                        <xs:element name="to" type="xs:dateTime"/>
                    </xs:all>
                </xs:complexType>
            </xs:element>
            <xs:element minOccurs="0" maxOccurs="unbounded" name="nodeUtilisation" type="nodeStatusType"/>
        </xs:sequence>
    </xs:complexType>

    <xs:complexType name="nodeStatusType">
        <xs:all>
            <xs:element name="nodeName" type="xs:string"/>
            <xs:element minOccurs="0" name="nodeValue" type="xs:string"/>
            <xs:element name="nodeStatus" type="xs:string"/>
        </xs:all>
    </xs:complexType>

    <xs:complexType name="nextBestActionType">
        <xs:all>
            <xs:element name="code" type="xs:string"/>
            <xs:element name="title" type="xs:string"/>
            <xs:element name="description" type="xs:string"/>
        </xs:all>
    </xs:complexType>

</xs:schema>

Revision History

Revision history for the Documentation

Ten most recent changes made to these docs

Download full change log here:

get/changeLog.txt

Request samples

Curl
Python
Node.js
JavaScript
PHP

curl -X GET "https://api.redocly.com/registry/assets/cityfibre/Service%20Diagnostics/v1/changeLog.txt"