openapi: 3.1.0
info:
  version: ''
  title: CityFibre - Service Diagnostics API
  termsOfService: https://www.cityfibre.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  description: >
    # 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.


    <figure align="center">
      <img alt="Diagnostic API v1.1" src="/Diagnostic_API_v1.1.jpg" />
      <figcaption style="font-size: 12px">Diagnostic API v1.1</figcaption>
    </figure>


    # 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.


    ```xml

    <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](https://api-gw.cityfibre.com:41223/cfsit/api2)


    CFStaging:
    [https://api-gw.cityfibre.com:41223/cfstaging/api2](https://api-gw.cityfibre.com:41223/cfstaging/api2)


    Production:
    [https://api-gw.cityfibre.com:41223/prod/api2](https://api-gw.cityfibre.com:41223/prod/api2)
servers:
  - url: https://api-gw.cityfibre.com:41223/prod/api2
    description: Main (production) server
  - url: https://api-gw.cityfibre.com:41223/cfstaging/api2
    description: CFStaging server
  - url: https://api-gw.cityfibre.com:41223/cfsit/api2
    description: CFSit server
tags:
  - name: Service Diagnostics
    description: >
      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.
x-tagGroups:
  - name: API
    tags:
      - Service Diagnostics
  - name: Files
    tags:
      - XSD File
      - Revision History
paths:
  /requestServiceDiagnostics:
    post:
      summary: Request Service Diagnostics
      operationId: requestServiceDiagnostics
      description: "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.\nThe details returned are:\n\nONT Status (Status)\n- Service Up / Service Down\n- Dying Gasp\n- Last Date\n- Time this event was received\n- The change from the previous state\n\nCFM Status (CFM Status)\n- Up/Down CF/Down ISP\n- Last Date\n- Time this event was received\n- The change from the previous state\n\nUniPort Status (Uniport Status)\n- Up/Down\n- Last Date\n- Time this event was received\n- The change from the previous state\n\nPlease note – with UniPort Status the Status will continue to show as UP if the ONT Status is DOWN.\nThis is due to the ONT not being able to communicate the UniPort status. \nIn this instance the ONT Status should take priority in the diagnostic analysis. \nIf UniPort Status is blank please use ONT & CFM Status to determine line condition.\n\nIn conjunction with the diagnostics process, nodes are classified within distinct lists based on their geographical context:\n  - Local Configuration: Identified as ENNI - Interconnect - PON, these nodes signify local network interconnections.\n  - National Configuration: Denoted as Interconnect - Handoff - ENNI - PON, these nodes represent national-level network interconnections.\n\nFurther, the operational status of these nodes is evaluated and categorized into the following states: Red, Orange, Green, and Unk (for unknown status).\n\nFor definition the POP is given a RAG status based upon peak loading over 5 minutes during the Busy Period, currently defined in Schedule 1.\n\nFor the PON, the RAG Status is based upon the peak loading over 15 minutes during the Busy Period currently defined in Schedule 1.\n\nFor confirmation the RAG status limits are below:\n\n\tRed – 95% or higher\n\tAmber – 80% or more to 94%\n\tGreen – Less than 79%\n\nBased 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. \nThis enables us to offer the following 9 recommended Next Best Action codes to resolve potential issues effectively:\n\n| Code | Current Status | Result Description | Next Best Action |\n|------|----------------|--------------------|------------------|\n| AOK001 | Service Working | ONT, Connectivity & Port Status results are all Up | We do not believe there is an issue on our network |\n| 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 |\n| 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 |\n| 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 |\n| 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 |\n| 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 |\n| 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 |\n| 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 |\n| STF001 | Unable to Check Network Status | The Service Test has not been able to run | Please continue to raise an incident |"
      security:
        - Certificate: []
      tags:
        - Service Diagnostics
      requestBody:
        $ref: '#/components/requestBodies/requestServiceDiagnostics'
      responses:
        '200':
          $ref: '#/components/responses/serviceDiagnosticsResponse'
        '400':
          $ref: '#/components/responses/brokenXML'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/unauthenticated'
  /serviceDiagnostics.txt:
    get:
      summary: Get the XSD for the Service Diagnostics
      operationId: getServiceDiagnosticsXSD
      security: []
      servers:
        - url: https://service-diagnostics.docs.cityfibre.com
          description: Get the XSD schema
      description: |
        <button style="background-color: rgb(0, 101, 251) color: white">
          <a target="_blank" href="https://service-diagnostics.docs.cityfibre.com/serviceDiagnostics.txt?download=true" download>
            Download XSD
          </a>
        </button>
      tags:
        - XSD File
      x-example:
        - lang: curl
          label: XSD
          source:
            $ref: ../../../assets/serviceDiagnostics.txt
  /changeLog.txt:
    get:
      summary: Revision history for the Documentation
      operationId: getRevisionHistory
      security: []
      servers:
        - url: https://service-diagnostics.docs.cityfibre.com
          description: Get the revision history for the documentation
      x-codeSamples:
        - lang: curl
          label: Curl
          source: >
            curl -X GET
            "https://service-diagnostics.docs.cityfibre.com/changeLog.txt"
        - lang: python
          label: Python
          source: |
            import requests
            url = "https://service-diagnostics.docs.cityfibre.com/changeLog.txt"
            response = requests.get(url)
            print(response.content.decode())
      description: >+
        <h4> Ten most recent changes made to these docs </h4>


        | Date       |
        Change                                                                      
        |

        |------------|------------------------------------------------------------------------------| 

        | 16/09/2024 | Added NBA (Next Best Action) codes to XSD and the
        explanations for them      |

        | 25/07/2024 | Removed incidents from
        currentStatus                                         |

        | 17/05/2024 | Added the Revision History
        document                                          |

        | 18/04/2024 | Added the explanations for UniPort Status
        values                             |

        | 11/04/2024 | Added currentUniportStatus field to the XSD
        schema                           |

        | 03/04/2024 | Added the node utilisation for Local and National
        Configurations             |

        | 08/03/2024 | Added the explanations for ONT Status and CFM Status
        values                  |

        | 16/02/2024 | Fixed the buyerIdentifier field in the XSD
        schema                            |

        | 15/02/2024 | Added the Service Diagnostic API
        diagram                                     |

        | 12/02/2024 | Updated the servicePathUsage field in the XSD
        schema                         |


        <h4> Download full change log here:</h4>


        <button>
          <a target="_blank" href="https://service-diagnostics.docs.cityfibre.com/changeLog.txt?download=true" download>
            Download Change Log
          </a>
        </button>

      tags:
        - Revision History
components:
  securitySchemes:
    Certificate:
      type: mutualTLS
      description: MutualTLS Certificate
  schemas:
    apiVersion:
      type: string
      maxLength: 36
      example: 1
      description: The API version
    buyer:
      type: object
      required:
        - buyerIdentifier
      properties:
        buyerIdentifier:
          type: string
          maxLength: 36
          example: SPDEV1
          description: Unique identifier of the buyer
      description: The Service Provider who consumes the service is the buyer
    message:
      type: object
      required:
        - messageId
        - correlationId
        - sentAt
      properties:
        messageId:
          type: string
          description: A unique ID to identify the message
          maxLength: 36
          example: b68b2cf4-475e-11e1-a92e-fb2ff6467c99
        sentAt:
          type: string
          description: The timestamp when the message has been sent
          format: date-time
          example: '2012-01-20T18:30:43Z'
      description: >-
        The meta-data of the request. It includes information regarding the
        message UUID, transaction ID and the sent timestamp
    serviceId:
      type: string
      maxLength: 36
      example: S12345
      description: Unique Identifier for the service
    requestServiceDiagnostics:
      type: object
      description: >-
        To request a diagnostics for a service. The buyer should send a request
        containing information about the service and the buyer.
      required:
        - apiVersion
        - message
        - buyer
        - serviceId
      properties:
        apiVersion:
          $ref: '#/components/schemas/apiVersion'
        buyer:
          $ref: '#/components/schemas/buyer'
        message:
          $ref: '#/components/schemas/message'
        serviceId:
          $ref: '#/components/schemas/serviceId'
    status:
      type: string
      maxLength: 36
      example: up
      description: Status of service
    at:
      type: string
      format: date-time
      example: '2018-05-16T12:01:00Z'
      description: Time at which status was updated
    from:
      type: string
      maxLength: 36
      example: down
      description: Status it changed from
    to:
      type: string
      maxLength: 36
      example: up
      description: Status it changed to
    lastStatusChange:
      type: object
      properties:
        at:
          $ref: '#/components/schemas/at'
        from:
          $ref: '#/components/schemas/from'
        to:
          $ref: '#/components/schemas/to'
    currentCFMStatus:
      type: object
      properties:
        status:
          description: one of `Up`, `Down`, `Up CF`, `Down CF`, `Up ISP`, `Down ISP`
          $ref: '#/components/schemas/status'
        lastStatusChange:
          $ref: '#/components/schemas/lastStatusChange'
    currentUniportStatus:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/status'
        lastStatusChange:
          $ref: '#/components/schemas/lastStatusChange'
    currentStatus:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/status'
        lastStatusChange:
          $ref: '#/components/schemas/lastStatusChange'
    nodeName:
      type: string
      maxLength: 36
      example: ENNI
      description: Name of node
    nodeStatus:
      type: string
      maxLength: 36
      example: green
      description: Status of node
    servicePathUsage:
      type: array
      description: An array of node utilisations
      items:
        type: object
        description: Available node utilisation details
        properties:
          nodeUtilisation:
            type: object
            properties:
              nodeName:
                $ref: '#/components/schemas/nodeName'
              nodeStatus:
                $ref: '#/components/schemas/nodeStatus'
    nextBestAction:
      type: object
      required:
        - code
        - title
        - description
      properties:
        code:
          type: string
          description: >-
            The code of the Next Best Action. Can be one of `AOK001`, `CFH001`,
            `CFH002`, `CFH003`, `DYG001`, `ISP001`, `ISP002`, `ISP003`, `STF001`
          maxLength: 10
          example: AOK001
        title:
          type: string
          description: The title of the Next Best Action
          example: Service Working
        description:
          type: string
          description: The description of the Next Best Action
          example: >-
            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.
    errorMessage:
      type: object
      maxLength: 36
      description: Error Message
      example: Some failure
    serviceDiagnosticsResponse:
      oneOf:
        - type: object
          required:
            - apiVersion
            - buyer
            - message
            - serviceId
            - currentCFMStatus
            - currentStatus
            - servicePathUsage
          title: Service Diagnostics Accepted
          description: Service Diagnostics can provide you with the result of the request.
          properties:
            apiVersion:
              $ref: '#/components/schemas/apiVersion'
            buyer:
              $ref: '#/components/schemas/buyer'
            message:
              $ref: '#/components/schemas/message'
            serviceId:
              $ref: '#/components/schemas/serviceId'
            currentCFMStatus:
              description: Current CFM Status
              $ref: '#/components/schemas/currentCFMStatus'
            currentUniportStatus:
              description: Current Uniport Status
              $ref: '#/components/schemas/currentUniportStatus'
            currentStatus:
              description: Current Status
              $ref: '#/components/schemas/currentStatus'
            servicePathUsage:
              $ref: '#/components/schemas/servicePathUsage'
            nextBestAction:
              description: Next Best Action
              $ref: '#/components/schemas/nextBestAction'
        - type: object
          required:
            - apiVersion
            - message
            - buyer
            - serviceId
            - errorMessage
          title: Service Diagnostics Rejected
          description: Service Diagnostics can reject the amendment up front.
          properties:
            apiVersion:
              $ref: '#/components/schemas/apiVersion'
            buyer:
              $ref: '#/components/schemas/buyer'
            message:
              $ref: '#/components/schemas/message'
            serviceId:
              $ref: '#/components/schemas/serviceId'
            errorMessage:
              $ref: '#/components/schemas/errorMessage'
    fault:
      type: object
      required:
        - faultcode
        - faultmessage
      properties:
        faultcode:
          type: string
          readOnly: true
        faultmessage:
          type: string
          readOnly: true
        detail:
          type: string
          readOnly: true
    brokenXMLResponse:
      description: Broken XML (400 Bad Request)
      type: object
      properties:
        fault:
          $ref: '#/components/schemas/fault'
    unauthorizedResponse:
      description: Unauthorized
      type: object
      properties:
        fault:
          $ref: '#/components/schemas/fault'
    unauthenticatedResponse:
      description: Unauthenticated
      type: object
      properties:
        fault:
          $ref: '#/components/schemas/fault'
  requestBodies:
    requestServiceDiagnostics:
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/requestServiceDiagnostics'
          examples:
            Request:
              summary: Requesting Diagnostics for a Service
              value: >
                <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>
  responses:
    serviceDiagnosticsResponse:
      description: Service Diagnostics Response
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/serviceDiagnosticsResponse'
          examples:
            Accepted Local:
              summary: Accepted Local
              value: >
                <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>
            Accepted National:
              summary: Accepted National
              value: >
                <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>
                  <currentStatus>
                    <status>up</status>
                    <lastStatusChange>
                      <at>2018-05-16T12:01:00Z</at>
                      <from>down</from>
                      <to>up</to>
                    </lastStatusChange>
                  </currentStatus>
                  <servicePathUsage>
                    <nodeUtilisation>
                      <nodeName>Interconnect</nodeName>
                      <nodeStatus>green</nodeStatus>
                    </nodeUtilisation>
                    <nodeUtilisation>
                      <nodeName>Handoff</nodeName>
                      <nodeStatus>green</nodeStatus>
                    </nodeUtilisation>
                    <nodeUtilisation>
                      <nodeName>ENNI</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>
            Rejected:
              summary: Rejected (e.g. wrong/invalid order reference)
              value: >
                <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>
                  <errorMessage>serviceId not found</errorMessage>
                </serviceDiagnostics>
    brokenXML:
      description: Broken XML (400 Bad Request)
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/brokenXMLResponse'
          examples:
            BrokenXML:
              summary: Broken XML
              value: >
                <soap:Envelope
                xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
                  <soap:Body>
                    <soap:Fault>
                      <faultcode>soap:Client</faultcode>
                      <faultstring>XML parsing error</faultstring>
                      <detail>not well-formed (invalid token): line 1, column 9</detail>
                    </soap:Fault>
                  </soap:Body>
                </soap:Envelope>
    unauthorized:
      description: Unauthorized
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/unauthorizedResponse'
          examples:
            Unauthorized:
              summary: Unauthorized
              value: >
                <soap:Envelope
                xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
                  <soap:Body>
                    <soap:Fault>
                      <faultcode>soap:Client</faultcode>
                      <faultstring>Unauthorized</faultstring>
                    </soap:Fault>
                  </soap:Body>
                </soap:Envelope>
    unauthenticated:
      description: Unauthenticated
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/unauthenticatedResponse'
          examples:
            Unauthenticated:
              summary: Unauthenticated
              value: >
                <soap:Envelope
                xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
                  <soap:Body>
                    <soap:Fault>
                      <faultcode>soap:Client</faultcode>
                      <faultstring>Unauthenticated</faultstring>
                    </soap:Fault>
                  </soap:Body>
                </soap:Envelope>
