openapi: 3.0.3
info:
  title: 'Fibre Cafe : Supplier Updates API'
  version: '1.8'
  description: >
    # Introduction


    The Fibre Cafe is a scalable, unified platform to support L2C provisioning,
    in-life modification/cease and

    T2R trouble resolution between communication providers (CP) and network
    operators or aggregators.


    CPs are known as 'tenants' on the Fibre Cafe and communicate with the Fibre
    Cafe's Tenant API. The

    network operators and aggregators providing the underlying services are
    known as 'suppliers' and provide

    the Supplier API.


    Where suppliers need to send updates back to the tenant (KCIs - Keep
    Customer Informed) then this API should be

    called. Examples of KCIs are where the order state and/or order fields have
    changed or to provide feedback on any

    requests e.g. amendment/cancellation submitted on the supplier API
    asynchronously.


    Unsolicited ceases can also be sent via this API - these will be represented
    as a new order in the system that

    follows a similar but reduced order flow.

    __


    © 2022-2026 Strategic Imperatives
servers:
  - url: https://prod.fibregateway.com/v1
tags:
  - name: KCIs
    description: >
      KCI (Keep Customer Informed) updates are sent from a supplier to the
      tenant to provide order updates.

      For example, updates about an inflight order for a new service may include
      order state changes, delays

      and requests for information.
paths:
  /kcis:
    post:
      tags:
        - KCIs
      summary: Send an update (KCI).
      description: >
        This endpoint is called to send an update (KCI) about an inflight
        service provide,

        cease or modify order back to the tenant.


        Each KCI must have a unique reference and a timestamp when issued. The
        reason

        for the KCI must also be provided along with related fields.


        The KCI must contain the latest version of the related order which must
        be identifiable

        by the Fibre Cafe generated order ID and/or supplier order reference.
      operationId: handleOrderUpdate
      security:
        - oauth2: []
      parameters:
        - name: X-Request-ID
          description: >-
            Unique identifier to link request and response events across the
            Fibre Cafe gateway
          in: header
          required: true
          schema:
            type: string
        - name: X-Conversation-ID
          description: Identifier to track message journey across the Fibre Cafe gateway
          in: header
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KCI'
      responses:
        '204':
          description: Operation successful - update was received and will be processed
          headers:
            X-Request-ID:
              description: >-
                Unique identifier to identify request and response events across
                the Fibre Cafe gateway
              schema:
                type: string
              required: true
            X-Conversation-ID:
              description: >-
                Identifier to track message journey across the Fibre Cafe
                gateway
              schema:
                type: string
              required: false
        '400':
          description: >-
            KCI was rejected - request was malformed or missing mandatory
            parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                uuid: ae2b3f5b-9fe1-4127-a4e5-13eac457080d
                code: MALFORMED_REQUEST
                messages:
                  - Problems parsing JSON
        '401':
          description: KCI was rejected - unauthorised
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                uuid: 423d0696-5bde-453f-bbdd-25c73d48a9a9
                code: NOT_AUTHORISED
                messages:
                  - Not authorised to use this endpoint
        '403':
          description: The client is not permitted to access this resource.
        '422':
          description: KCI was rejected - request was invalid or failed validation rules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                uuid: b6ef6865-fafc-46c7-8c97-b5272cfc4668
                code: INVALID_REQUEST
                messages:
                  - Address identifier type was not recognised
        '500':
          description: Unexpected system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                uuid: 0884e75c-5424-456d-ac61-bef2010b7962
                code: GATEWAY_FAULT
                messages:
                  - An unexpected error was encountered
        '503':
          description: Fibre Cafe KCI API is temporarily unavailable
components:
  schemas:
    KCI:
      oneOf:
        - $ref: '#/components/schemas/ServiceOrderUpdate'
        - $ref: '#/components/schemas/ServiceTestUpdate'
        - $ref: '#/components/schemas/ServiceProblemUpdate'
        - $ref: '#/components/schemas/ReportableIncident'
    BaseUpdate:
      description: Abstract type - metadata about an update (KCI).
      type: object
      required:
        - id
        - sequenceNumber
        - issuedOn
        - reasonCode
      properties:
        id:
          description: Unique identifier for this service order update (UUID)
          type: string
          pattern: >-
            ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
          example: 5251cf7d-7971-42e4-a5be-c24ed58a7aa6
        sequenceNumber:
          description: Sequence number of this KCI to ensure ordering
          type: number
          minimum: 1
          example: 1
        issuedOn:
          description: Date/time when supplier issued this update
          type: string
          format: date-time
          example: '2022-01-10T09:00:00.000Z'
        reasonCode:
          $ref: '#/components/schemas/ReasonCode'
        problemCode:
          $ref: '#/components/schemas/ProblemCode'
        text:
          description: Textual information about this update - e.g. reason for the delay
          type: string
          minLength: 1
          maxLength: 1000
          example: Resolving network issue
        supplierCode:
          deprecated: true
          description: >-
            Supplier's reason or problem code - deprecated: replaced by
            supplierCodes array to allow for multiple underlying supplier codes
          type: string
          minLength: 1
          maxLength: 50
          example: '313'
        supplierCodes:
          description: Supplier's reason or problem code - where available
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 50
            example: '313'
        supplierNotes:
          description: Note(s) about the order relating to this KCI
          type: array
          items:
            $ref: '#/components/schemas/SupplierNote'
    ProvideServiceOrderUpdate:
      description: >-
        Represents an KCI update to an order to provide a new service at a
        particular address.
      allOf:
        - $ref: '#/components/schemas/BaseUpdate'
        - type: object
          required:
            - provideServiceOrder
          properties:
            provideServiceOrder:
              $ref: '#/components/schemas/ProvideServiceOrder'
    CeaseServiceOrderUpdate:
      description: Represents an KCI update to an order to cease an active service.
      allOf:
        - $ref: '#/components/schemas/BaseUpdate'
        - type: object
          required:
            - ceaseServiceOrder
          properties:
            ceaseServiceOrder:
              $ref: '#/components/schemas/CeaseServiceOrder'
    ModifyServiceOrderUpdate:
      description: Represents an KCI update to an order to modify an active service.
      allOf:
        - $ref: '#/components/schemas/BaseUpdate'
        - type: object
          required:
            - modifyServiceOrder
          properties:
            modifyServiceOrder:
              $ref: '#/components/schemas/ModifyServiceOrder'
    UnsolicitedCeaseServiceOrderUpdate:
      description: Represents an unsolicited cease for an active service.
      allOf:
        - $ref: '#/components/schemas/BaseUpdate'
        - type: object
          required:
            - unsolicitedCeaseServiceOrder
          properties:
            unsolicitedCeaseServiceOrder:
              $ref: '#/components/schemas/UnsolicitedCeaseServiceOrder'
    ServiceTestUpdate:
      description: >-
        Represents an KCI update to a service test request to perform a
        diagnostics check on an active service.
      allOf:
        - $ref: '#/components/schemas/BaseUpdate'
        - type: object
          required:
            - serviceTest
          properties:
            serviceTest:
              $ref: '#/components/schemas/ServiceTest'
    ServiceProblemUpdate:
      description: >-
        Represents an KCI update to a service problem request to raise a problem
        on an active service.
      allOf:
        - $ref: '#/components/schemas/BaseUpdate'
        - type: object
          required:
            - serviceProblem
          properties:
            serviceProblem:
              $ref: '#/components/schemas/ServiceProblem'
    ReportableIncident:
      description: >-
        Represents an unsolicited notification relating to an incident/outage
        notified by the supplier to the tenant.
      allOf:
        - $ref: '#/components/schemas/BaseUpdate'
        - type: object
          required:
            - reportableIncident
          properties:
            reportableIncident:
              $ref: '#/components/schemas/ReportableIncidentType'
    ServiceOrderUpdate:
      oneOf:
        - $ref: '#/components/schemas/ProvideServiceOrderUpdate'
        - $ref: '#/components/schemas/CeaseServiceOrderUpdate'
        - $ref: '#/components/schemas/ModifyServiceOrderUpdate'
        - $ref: '#/components/schemas/UnsolicitedCeaseServiceOrderUpdate'
    ServiceOrder:
      oneOf:
        - $ref: '#/components/schemas/ProvideServiceOrder'
        - $ref: '#/components/schemas/CeaseServiceOrder'
        - $ref: '#/components/schemas/ModifyServiceOrder'
        - $ref: '#/components/schemas/UnsolicitedCeaseServiceOrder'
    ProvideServiceOrder:
      description: >-
        Represents the current details of an order to provide a new service at a
        particular address. Orders must be identifiable via the Fibre Cafe
        generated ID and unique supplier reference if available.
      type: object
      required:
        - id
        - tenant
        - status
        - address
        - serviceOrderItem
        - primaryContact
      properties:
        id:
          description: >-
            Unique identifier for this provide service order - generated by the
            Fibre Cafe
          type: number
          minimum: 1
          example: 123
        orderType:
          $ref: '#/components/schemas/OrderType'
        tenant:
          description: The tenant that placed the order on the Fibre Cafe
          type: string
          minLength: 1
          maxLength: 50
          example: TENANT1
        supplierOrderReference:
          description: >-
            Unique reference identifying this service order - supplier order
            reference
          type: string
          minLength: 1
          maxLength: 50
          example: A123X
        status:
          $ref: '#/components/schemas/OrderStatus'
        address:
          $ref: '#/components/schemas/AddressIdentifier'
        serviceOrderItem:
          $ref: '#/components/schemas/ServiceOrderItem'
        primaryContact:
          $ref: '#/components/schemas/Contact'
        secondaryContact:
          $ref: '#/components/schemas/Contact'
        appointmentReservationId:
          description: >-
            Unique identifier for appointment - Fibre Cafe generated identifier
            (if applicable). Populate when appointed and ID known.
          type: number
          minimum: 1
          example: 234
        appointmentReservationReference:
          description: >-
            Unique reference identifying the appointment - supplier reference
            (if applicable). Populate when appointed and ID not known.
          type: string
          minLength: 1
          maxLength: 50
          example: A234X
        appointmentTimeslot:
          allOf:
            - description: >-
                Represents a re-appointed timeslot by the supplier (only send if
                applicable)
            - $ref: '#/components/schemas/Timeslot'
        requestedCompletionDate:
          description: >-
            Where not appointed, allows a date to be requested for the service
            activation. This is set by the tenant/customer.
          type: string
          format: date
          example: '2022-01-10'
        committedDate:
          description: >-
            When the supplier first commits to fulfil the order this field will
            contain the expected completion date. Once set, this value cannot
            change.
          type: string
          format: date-time
          example: '2022-01-01T09:09:33.001Z'
        targetDate:
          description: >-
            The current expected completion date. This can be different to the
            committedDate if the order has been delayed for any reason, and can
            change possibly multiple times.
          type: string
          format: date-time
          example: '2022-01-01T09:09:33.001Z'
        engineerTasks:
          $ref: '#/components/schemas/EngineerTasks'
        hazards:
          description: >-
            Hazard information about the site where the service will be
            installed
          type: string
          minLength: 1
          maxLength: 1000
          example: Hazardous materials stored on site
        onSiteRestrictions:
          description: >-
            Information about restrictions on the site where the service(s) will
            be installed
          type: string
          minLength: 1
          maxLength: 1000
          example: Restricted access
        notes:
          description: Represents a note or supplementary information added to an order
          type: string
          minLength: 1
          maxLength: 1000
          example: Lorem ipsum dolor sit amet...
        serviceOrderAmendmentId:
          description: >-
            Unique identifier for an amendment request - generated by the Fibre
            Cafe. Populate when update is about amendment and ID known.
          type: number
          minimum: 1
          example: 345
        serviceOrderAmendmentReference:
          description: >-
            Unique reference identifying an amendment request - supplier
            reference. Populate when update is about amendment and ID not known
          type: string
          minLength: 1
          maxLength: 50
          example: 123-1
        serviceOrderCancellationId:
          description: >-
            Unique identifier for a cancellation request - generated by the
            Fibre Cafe. Populate when update is about cancellation and ID known.
          type: number
          minimum: 1
          example: 345
        serviceOrderCancellationReference:
          description: >-
            Unique reference identifying a cancellation request - supplier
            reference. Populate when update is about cancellation and ID not
            known
          type: string
          minLength: 1
          maxLength: 50
          example: 123-1
    ServiceOrderItem:
      description: Order for a service that the supplier provides at the selected address.
      type: object
      required:
        - serviceSpecification
        - serviceCharacteristics
      properties:
        serviceSpecification:
          $ref: '#/components/schemas/ServiceSpecification'
        serviceCharacteristics:
          description: List of service characteristics for the service order item
          type: array
          minItems: 0
          items:
            $ref: '#/components/schemas/ServiceCharacteristic'
    ServiceSpecification:
      description: Details of a service the supplier provides at the selected address.
      type: object
      required:
        - id
      properties:
        id:
          description: Unique identifier for this service specification
          type: string
          minLength: 1
          maxLength: 50
          example: ftthl2r
        name:
          description: Name of the service
          type: string
          minLength: 1
          maxLength: 50
          example: FTTH
    ServiceCharacteristic:
      description: A characteristic or attribute of an available service.
      type: object
      required:
        - name
        - value
      properties:
        name:
          description: Name of the service characteristic
          type: string
          minLength: 1
          maxLength: 50
          example: SERVICE_VLAN_ID
        value:
          description: Value for this characteristic
          type: string
          minLength: 1
          maxLength: 50
          example: '20'
    CeaseServiceOrder:
      description: >-
        Represents the current details of an order to cease an existing live
        service. Orders must be identifiable via the Fibre Cafe generated ID and
        unique supplier reference if available.
      type: object
      required:
        - id
        - tenant
        - status
      properties:
        id:
          description: >-
            Unique identifier for this cease service order - generated by the
            Fibre Cafe
          type: number
          minimum: 1
          example: 123
        orderType:
          allOf:
            - $ref: '#/components/schemas/OrderType'
            - example: CEASE
        tenant:
          description: The tenant that placed the order on the Fibre Cafe
          type: string
          minLength: 1
          maxLength: 50
          example: TENANT1
        supplierOrderReference:
          description: >-
            Unique reference identifying this service order - supplier order
            reference
          type: string
          minLength: 1
          maxLength: 50
          example: A123X
        serviceId:
          description: Identifier of an existing live service
          type: string
          example: SI2345432345345
        requestedCompletionDate:
          description: >-
            The requested date/time for the service to cease (time where
            supported). This is set by the tenant/customer.
          type: string
          format: date-time
          example: '2022-01-01T09:09:33.001Z'
        committedDate:
          description: >-
            When the supplier first commits to fulfil the order this field will
            contain the expected completion date. Once set, this value cannot
            change.
          type: string
          format: date-time
          example: '2022-01-01T09:09:33.001Z'
        targetDate:
          description: >-
            The current expected completion date. This can be different to the
            committedDate if the order has been delayed for any reason, and can
            change possibly multiple times.
          type: string
          format: date-time
          example: '2022-01-01T09:09:33.001Z'
        status:
          $ref: '#/components/schemas/OrderStatus'
        serviceOrderAmendmentId:
          description: >-
            Unique identifier for an amendment request - generated by the Fibre
            Cafe. Populate when update is about amendment and ID known.
          type: number
          minimum: 1
          example: 345
        serviceOrderAmendmentReference:
          description: >-
            Unique reference identifying an amendment request - supplier
            reference. Populate when update is about amendment and ID not known
          type: string
          minLength: 1
          maxLength: 50
          example: 123-1
        serviceOrderCancellationId:
          description: >-
            Unique identifier for a cancellation request - generated by the
            Fibre Cafe. Populate when update is about cancellation and ID known.
          type: number
          minimum: 1
          example: 345
        serviceOrderCancellationReference:
          description: >-
            Unique reference identifying a cancellation request - supplier
            reference. Populate when update is about cancellation and ID not
            known
          type: string
          minLength: 1
          maxLength: 50
          example: 123-1
    ModifyServiceOrder:
      description: >-
        Represents the current details of an order to modify an existing live
        service - specify the replacement characteristic e.g. LINE_PROFILE.
        Orders must be identifiable via the Fibre Cafe generated ID and unique
        supplier reference if available.
      type: object
      required:
        - id
        - tenant
        - status
      properties:
        id:
          description: >-
            Unique identifier for this modify service order - generated by the
            Fibre Cafe
          type: number
          minimum: 1
          example: 123
        orderType:
          allOf:
            - $ref: '#/components/schemas/OrderType'
            - example: MODIFY
        tenant:
          description: The tenant that placed the order on the Fibre Cafe
          type: string
          minLength: 1
          maxLength: 50
          example: TENANT1
        supplierOrderReference:
          description: >-
            Unique reference identifying this service order - supplier order
            reference
          type: string
          minLength: 1
          maxLength: 50
          example: A123X
        serviceId:
          description: Identifier of an existing live service
          type: string
          example: SI2345432345345
        serviceCharacteristics:
          description: Service characteristics to be updated e.g. LINE_PROFILE
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ServiceCharacteristic'
        requestedCompletionDate:
          description: >-
            The requested date/time for the modify (where supported). This is
            set by the tenant/customer.
          type: string
          format: date-time
          example: '2022-01-01T09:09:33.001Z'
        committedDate:
          description: >-
            When the supplier first commits to fulfil the order this field will
            contain the expected completion date. Once set, this value cannot
            change.
          type: string
          format: date-time
          example: '2022-01-01T09:09:33.001Z'
        targetDate:
          description: >-
            The current expected completion date. This can be different to the
            committedDate if the order has been delayed for any reason, and can
            change possibly multiple times.
          type: string
          format: date-time
          example: '2022-01-01T09:09:33.001Z'
        status:
          $ref: '#/components/schemas/OrderStatus'
        serviceOrderAmendmentId:
          description: >-
            Unique identifier for an amendment request - generated by the Fibre
            Cafe. Populate when update is about amendment and ID known.
          type: number
          minimum: 1
          example: 345
        serviceOrderAmendmentReference:
          description: >-
            Unique reference identifying an amendment request - supplier
            reference. Populate when update is about amendment and ID not known
          type: string
          minLength: 1
          maxLength: 50
          example: 123-1
        serviceOrderCancellationId:
          description: >-
            Unique identifier for a cancellation request - generated by the
            Fibre Cafe. Populate when update is about cancellation and ID known.
          type: number
          minimum: 1
          example: 345
        serviceOrderCancellationReference:
          description: >-
            Unique reference identifying a cancellation request - supplier
            reference. Populate when update is about cancellation and ID not
            known
          type: string
          minLength: 1
          maxLength: 50
          example: 123-1
    UnsolicitedCeaseServiceOrder:
      description: Unsolicited cease for an existing live service.
      type: object
      required:
        - tenant
        - supplierOrderReference
        - reason
        - serviceId
        - requestedCeaseDate
        - status
      properties:
        orderType:
          allOf:
            - $ref: '#/components/schemas/OrderType'
            - example: UNSOLICITED_CEASE
        tenant:
          description: The tenant that placed the order on the Fibre Cafe
          type: string
          minLength: 1
          maxLength: 50
          example: TENANT1
        supplierOrderReference:
          description: Order reference provided by the supplier
          type: string
          minLength: 1
          maxLength: 50
          example: A123X
        reason:
          $ref: '#/components/schemas/UnsolicitedCeaseReason'
        serviceId:
          description: Identifier of the existing live service to be ceased
          type: string
          minLength: 1
          maxLength: 50
          example: SI2345432345345
        retailerId:
          description: Gaining retailer ID (OFCOM RID of the gaining CP)
          type: string
          minLength: 1
          maxLength: 50
          example: XXX
        requestedCeaseDate:
          description: The requested date/time for the service to cease
          type: string
          format: date-time
          example: '2022-01-10T09:00:00.000Z'
        committedDate:
          description: >-
            Date/time committed to the cease order. Once set, this value does
            not usually change.
          type: string
          format: date-time
          example: '2022-01-01T09:09:33.001Z'
        targetDate:
          description: >-
            The current expected completion date. This can be different to the
            committedDate if the order has been delayed for any reason, and can
            change possibly multiple times.
          type: string
          format: date-time
          example: '2022-01-01T09:09:33.001Z'
        status:
          $ref: '#/components/schemas/OrderStatus'
    AddressIdentifier:
      description: Address identifier for location associated with the service order.
      type: object
      required:
        - id
        - type
      properties:
        id:
          description: Address identifier of provided type e.g. UPRN
          type: string
          minLength: 1
          maxLength: 20
          example: '200004033694'
        type:
          description: Type of addressId provided e.g. UPRN
          type: string
          pattern: ^[A-Z_]{1,10}
          example: UPRN
    Contact:
      description: >-
        Represents a contact available at the given address - primary contact
        must be provided.
      type: object
      required:
        - name
        - phoneNumber
      properties:
        name:
          description: Contact name
          type: string
          minLength: 1
          maxLength: 100
          example: John Smith
        email:
          description: Contact email address (if available)
          type: string
          pattern: ^\S{1,64}@\S{2,254}$
          example: john@smith.com
        phoneNumber:
          description: Contact phone number
          type: string
          pattern: ^\+?[\d\s\-#]{8,50}$
          example: 01234 567890
    Timeslot:
      description: Represents a new appointment timeslot.
      type: object
      required:
        - timeslotStartDateTime
        - timeslotEndDateTime
      properties:
        timeslotStartDateTime:
          description: Start date/time for this timeslot
          type: string
          format: date-time
          example: '2022-01-10T09:00:00.000Z'
        timeslotEndDateTime:
          description: End date/time for this timeslot
          type: string
          format: date-time
          example: '2022-01-10T13:00:00.000Z'
    SupplierNote:
      description: Represents a note about this KCI update.
      type: object
      required:
        - note
        - created
      properties:
        note:
          description: Note text
          type: string
          minLength: 1
          maxLength: 4096
          example: Lorem ipsum dolor sit amet...
        type:
          description: Type of note as applicable e.g. Site Visit Notes, Customer Update
          type: string
          pattern: ^[A-Z_]{1,30}
          example: Engineer Note
        created:
          description: Date/time when the note was created
          type: string
          format: date-time
          example: '2022-01-01T09:09:33.001Z'
    ServiceTest:
      description: >
        Details of a service test. A service test must be performed against the
        service, prior to raising any service

        problem. This service test should classify the outcome into Red, Amber
        or Green, also supporting exception scenarios.

        The next steps in the journey will depend on this result and any
        additional details provided.
      type: object
      required:
        - id
        - tenant
        - status
        - serviceId
        - serviceSpecification
        - problemType
      properties:
        id:
          description: >-
            Unique identifier for this service test request (generated by the
            Fibre Cafe)
          type: number
          minimum: 1
          example: 23467
        tenant:
          description: The tenant that requested the service test
          type: string
          minLength: 1
          maxLength: 50
          example: TENANT1
        supplierReference:
          description: >-
            Unique reference identifying this service test (test reference -
            generated by the supplier)
          type: string
          pattern: ^[A-Z0-9_]{5,25}
          example: SI_243843R
        status:
          $ref: '#/components/schemas/ServiceTestStatus'
        serviceId:
          description: Identifier of an existing live service
          type: string
          minLength: 1
          maxLength: 50
          example: SI2345432345345
        serviceSpecification:
          $ref: '#/components/schemas/ServiceSpecification'
        problemType:
          $ref: '#/components/schemas/ServiceProblemType'
        result:
          $ref: '#/components/schemas/ServiceTestResult'
    ServiceProblemCharacteristic:
      description: >-
        A generic characteristic object to support extendable data sets. All
        characteristics will be referenced in developer documentation.
      type: object
      required:
        - name
        - value
      properties:
        name:
          description: Name of the characteristic
          type: string
          minLength: 1
          maxLength: 50
        value:
          description: Value for this characteristic
          type: string
          minLength: 1
          maxLength: 50
    ServiceProblem:
      description: >-
        Represents a request to raise a new problem on an existing active
        service.
      type: object
      required:
        - id
        - tenant
        - status
        - problemType
        - problemText
        - serviceId
        - serviceSpecification
        - serviceTestId
        - characteristics
        - primaryContact
        - notes
      properties:
        id:
          description: >-
            Unique identifier for this service problem request (generated by the
            Fibre Cafe)
          type: number
          minimum: 1
          example: 23467
        tenant:
          description: The tenant that raised the service problem
          type: string
          minLength: 1
          maxLength: 50
          example: TENANT1
        supplierReference:
          description: >-
            Unique reference identifying this service problem as generated by
            the supplier
          type: string
          pattern: ^[A-Z0-9_]{5,25}
          example: SI_RE233827673
        status:
          $ref: '#/components/schemas/ServiceProblemStatus'
        problemType:
          $ref: '#/components/schemas/ServiceProblemType'
        problemText:
          description: The description of problem being raised as defined by the end user.
          type: string
          minLength: 10
          maxLength: 80
          example: The service keeps dropping between 6pm and 9pm every evening.
        serviceId:
          description: Identifier of an existing live service
          type: string
          minLength: 1
          maxLength: 50
          example: SI2345432345345
        serviceSpecification:
          $ref: '#/components/schemas/ServiceSpecification'
        address:
          $ref: '#/components/schemas/AddressIdentifier'
        serviceTestId:
          description: >-
            Unique identifier (generated by the Fibre Cafe) of a current service
            test that has been performed against the service prior to raising
            the service problem.
          type: number
          example: TEST_233827673
        serviceTestReference:
          description: >-
            The unique supplier reference of a current service test that has
            been performed against the service prior to raising the service
            problem.
          type: string
          pattern: ^[A-Z0-9_]{5,25}
          example: TEST_233827673
        characteristics:
          description: List of characteristics providing context on the problem
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ServiceProblemCharacteristic'
        primaryContact:
          $ref: '#/components/schemas/Contact'
        secondaryContact:
          $ref: '#/components/schemas/Contact'
        appointmentReservationId:
          description: Unique identifier for the reserved appointment (if applicable)
          type: number
          minimum: 1
          example: 345
        appointmentReservationReference:
          description: >-
            Unique reference identifying the appointment - supplier reference
            (if applicable)
          type: string
          minLength: 1
          maxLength: 50
          example: A234X
        parentServiceProblemId:
          description: >-
            Unique reference for an issue that is believed to be related, for
            example a multiline network outage
          type: number
          minimum: 1
          example: 12345
        parentServiceProblemReference:
          description: >-
            Unique reference identifying the parent problem - supplier reference
            (if applicable)
          type: string
          pattern: ^[A-Z0-9_]{1,25}
          example: SI_RE23380000
        hazards:
          description: Hazard information about the site where the service will be restored
          type: string
          example: Hazardous materials stored on site
          minLength: 1
          maxLength: 1000
        onSiteRestrictions:
          description: >-
            Information about restrictions on the site where the service will be
            restored
          type: string
          example: Restricted access
          minLength: 1
          maxLength: 1000
        notes:
          description: >-
            Notes about the problem which are required by the supplier. This
            includes additional information that may be required - refer to
            developer portal
          type: string
          example: Lorem ipsum dolor sit amet...
          minLength: 1
          maxLength: 1000
        serviceProblemResolution:
          $ref: '#/components/schemas/ServiceProblemResolution'
        serviceProblemAmendmentId:
          description: >
            Unique identifier for this service problem amendment request
            (generated by the Fibre Cafe).

            Required when updates are provided on ServiceProblemAmendments
          type: number
          minimum: 1
          example: 23467
        supplierServiceProblemAmendmentReference:
          description: >-
            Unique reference identifying this service problem amendment as
            generated by the supplier
          type: string
          pattern: ^[A-Z0-9_]{5,25}
          example: SI_RE233827673
        serviceProblemCancellationId:
          description: >
            Unique identifier for this service problem cancellation request
            (generated by the Fibre Cafe)

            Required when updates are provided on ServiceProblemCancellations
          type: number
          minimum: 1
          example: 23467
        supplierServiceProblemCancellationReference:
          description: >-
            Unique reference identifying this service problem cancellation as
            generated by the supplier
          type: string
          pattern: ^[A-Z0-9_]{5,25}
          example: SI_RE233827673
    Characteristic:
      description: A characteristic or attribute of the associated object type.
      type: object
      required:
        - name
        - value
      properties:
        name:
          description: Name of the object characteristic
          type: string
          pattern: ^[A-Z_]{5,50}
          example: END_USER_CPE
        value:
          description: Value for this characteristic
          type: string
          minLength: 1
          maxLength: 50
          example: Zyzel DX3301
    ServiceTestResult:
      description: Result of a service test request once available.
      type: object
      required:
        - testOutcome
      properties:
        testOutcome:
          $ref: '#/components/schemas/TestOutcome'
        testMeasures:
          description: >-
            The specific metrics returned as part of the service test execution
            (where available)
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/TestMeasure'
    TestOutcome:
      description: The outcome of the service test execution.
      type: object
      required:
        - testResult
        - category
        - codes
        - validity
      properties:
        testResult:
          description: >-
            RAG Status on the service test execution. FAILED represents a
            situation where the supplier is unable to perform the service test.
          type: string
          enum:
            - RED
            - AMBER
            - GREEN
            - FAILED
          example: AMBER
        category:
          description: Category representing the test result
          type: string
          pattern: ^[A-Z_]{5,35}
          example: ACCESS_NETWORK
        codes:
          description: >-
            Unique code(s) representing the test result. The list of potential
            codes need to be supplied to Fibre Cafe as part of the engagement.
          type: array
          items:
            type: string
            pattern: ^[A-Z0-9]{3,20}
            example: D1234
        text:
          description: >-
            A textual description of the service test outcome and associated
            next steps
          type: string
          maxLength: 512
          example: >
            The test indicates there is a potential problem on the supplier
            access network before the distribution point.

            Please raise a service problem for further investigation
        validity:
          description: >-
            The time until the test results are no longer valid. If test is
            invalid, it is set to now
          type: string
          format: date-time
          example: '2022-01-01T09:45:39.001Z'
    TestMeasure:
      description: The specific metrics returned as part of the service test execution.
      type: object
      required:
        - captureDateTime
        - metricName
        - metricValue
      properties:
        captureDateTime:
          description: The date-time the measurement was captured
          type: string
          format: date-time
          example: '2022-01-01T09:45:39.001Z'
        metricName:
          description: The name of the metric being reported
          type: string
          maxLength: 64
          pattern: ^[A-Z_]{5,25}
          example: ONT_STATUS
        metricValue:
          description: A measurement of the metric
          type: string
          maxLength: 64
          example: 'OFF'
        unitOfMeasure:
          description: A unit of measurement used to measure the metric
          type: string
          maxLength: 64
          example: N/A
        ruleViolation:
          description: >-
            Confirms if the measurement is below the agreed thresholds and a
            rule violation has occurred
          type: boolean
          example: true
        ruleSeverity:
          description: The severity of the violation
          type: string
          enum:
            - SEVERE
            - MAJOR
            - MINOR
            - WARNING
            - N/A
          example: MINOR
    ServiceProblemResolution:
      description: Details of resolution to a service problem request.
      type: object
      required:
        - supplierReference
        - resolvedDate
        - resolutionDetails
      properties:
        supplierReference:
          description: >-
            Unique reference identifying this service problem resolution
            (provided by supplier)
          type: string
          minLength: 1
          maxLength: 50
          example: '1234'
        resolvedDate:
          description: Date/time the problem was resolved by the supplier
          type: string
          format: date-time
          example: '2022-01-10T09:00:00.000Z'
        closedDate:
          description: Date/time the problem was closed by the tenant or supplier
          type: string
          format: date-time
          example: '2022-01-10T09:00:00.000Z'
        resolutionDetails:
          $ref: '#/components/schemas/ResolutionDetails'
        slaViolation:
          description: Indicates if the resolution has violated the agreed SLAs
          type: array
          minItems: 1
          items:
            type: string
            pattern: ^[\w_]{1,50}
            example: EXCEEDED_SLA_TIME_TO_REPAIR
    ResolutionCode:
      description: >-
        A code published on the developer portal to uniquely identify the
        problem resolution.
      type: string
      pattern: ^[\w_]{5,25}
      enum:
        - ACCESS_ISSUE
        - BACKHAUL_CORE_NETWORK
        - CUSTOMER_FAULT
        - CUSTOMER_FAULT_B_END
        - CUSTOMER_FAULT_EQUIPMENT
        - CUSTOMER_FAULT_MODEM
        - CUSTOMER_FAULT_WIRING
        - EXTERNAL_REIN
        - INTERNAL_REIN
        - LINE_TEST_NORMAL
        - NETWORK_CABLING
        - NETWORK_ISSUE
        - NETWORK_UPLIFT
        - NO_FAULT_FOUND
        - NOT_REPRODUCIBLE
        - OTHER
        - PLANNED_ENGINEERING_WORKS
        - PROBLEM_CANCELLED
        - SERVICE_RESTRICTION
        - SUPPLIER_CPE_ISSUE
      example: NETWORK_ISSUE
    ResolutionDetails:
      description: Details of resolution to a service problem request.
      type: object
      required:
        - resolutionCode
      properties:
        resolutionCode:
          $ref: '#/components/schemas/ResolutionCode'
        resolutionText:
          description: >-
            Detailed text provided by the supplier regarding the problem
            resolution
          type: string
          maxLength: 256
        supplierCodes:
          description: Code(s) provided by the supplier regarding the resolution
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 50
            example: R9
        faultCode:
          description: Code(s) provided by the supplier regarding the problem fault
          type: array
          minItems: 1
          items:
            type: string
            pattern: ^[\w_]{1,50}
            example: DAMAGED_ONT
    ReportableIncidentType:
      description: >-
        Represents a general incident currently being experienced by the
        supplier.
      type: object
      required:
        - supplierReference
        - status
        - created
        - incidentType
        - incidentText
      properties:
        supplierReference:
          description: Unique reference for the incident as generated by the Supplier
          type: string
          pattern: ^[A-Z0-9_]{1,25}
          example: SI_RE233827673
        status:
          $ref: '#/components/schemas/IncidentStatus'
        created:
          description: Date/time when the incident was created
          type: string
          format: date-time
          example: '2022-01-01T09:45:39.001Z'
        updated:
          description: Date/time when the incident was last updated
          type: string
          format: date-time
          example: '2022-01-01T09:45:39.001Z'
        estimatedResolutionTime:
          description: >-
            Date/time when the incident is estimated to be resolved by the
            supplier.
          type: string
          format: date-time
          example: '2022-01-01T09:45:39.001Z'
        incidentType:
          $ref: '#/components/schemas/IncidentType'
        incidentText:
          description: The description of incident being raised as defined by the supplier.
          type: string
          minLength: 10
          maxLength: 240
          example: >-
            A fibre line break has been identified in Manchester in the Trafford
            Area.
        affectedServiceIds:
          description: List of known service id directly affected by the incident
          type: array
          minItems: 1
          items:
            type: string
            minLength: 1
            maxLength: 50
            example: SI2345432345345
        affectedServiceSpecifications:
          description: >-
            List of known service specifications directly affected by the
            incident
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ServiceSpecification'
        notes:
          description: Notes about the incident which are provided by the supplier.
          type: string
          example: Lorem ipsum dolor sit amet...
          minLength: 1
          maxLength: 1000
        slaViolation:
          description: Indicates if the resolution has violated the agreed SLAs
          type: array
          minItems: 1
          items:
            type: string
            pattern: ^[\w_]{1,50}
            example: EXCEEDED_SLA_TIME_TO_REPAIR
    Error:
      description: >
        Represents an error with code to denote origin/cause.


        - INVALID_REQUEST : Request was well-formed/syntactically correct but
        did not pass validation requirements

        - MALFORMED_REQUEST : Request was not valid JSON or missing mandatory
        parameters

        - NOT_AUTHORISED : User was not authenticated and/or authorised to use
        endpoint

        - NOT_IMPLEMENTED : Endpoint has not been implemented by the supplier

        - GATEWAY_FAULT : An unexpected problem originating on the Fibre Cafe
        gateway
      type: object
      required:
        - uuid
        - code
        - messages
      properties:
        uuid:
          description: Unique identifier of this error (UUID) - for tracing purposes
          type: string
          pattern: >-
            ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
          example: 87432dfb-2e47-4532-a1b7-4b113d48867d
        code:
          $ref: '#/components/schemas/ErrorCode'
        messages:
          description: Message describing the error
          type: array
          minItems: 1
          items:
            type: string
            example: e.g. Invalid value for field x - accepted values are y
    ProvideOrderType:
      description: >-
        The type of order - provide (new, (re)start, takeover, transfer, swap),
        cease or modify.
      type: string
      enum:
        - NEW
        - START
        - TAKEOVER
        - TRANSFER
        - SWAP
    CeaseOrderType:
      description: The type of order - cease
      type: string
      enum:
        - CEASE
    ModifyOrderType:
      description: The type of order - modify
      type: string
      enum:
        - MODIFY
    UnsolicitedCeaseOrderType:
      description: The type of order - unsolicited cease
      type: string
      enum:
        - UNSOLICITED_CEASE
    OrderType:
      description: The type of order
      anyOf:
        - $ref: '#/components/schemas/ProvideOrderType'
        - $ref: '#/components/schemas/CeaseOrderType'
        - $ref: '#/components/schemas/ModifyOrderType'
        - $ref: '#/components/schemas/UnsolicitedCeaseOrderType'
    ReasonCode:
      description: >
        Reason for this KCI - this must be provided along with the latest
        updated entity (serviceOrder, serviceProblem,

        serviceTest, reportableIncident).


        - CREATED : Supplier has created a new entity e.g. unsolicited cease or
        reportable incident 
          - new serviceOrder containing the unsolicited cease order (as applicable)
          - status can be ACKNOWLEDGED or IN_PROGRESS as appropriate for unsolicited cease
          - new reportableIncident with appropriate status (as applicable)
        - ACKNOWLEDGED : Acknowledge receipt without committing
          - entity status should be ACKNOWLEDGED
        - COMMITTED : Commit to fulfilment
          - serviceOrder committedDate must be updated (as applicable)
          - entity status should be IN_PROGRESS
        - UPDATE : A general update
          - entity must be updated
        - INFORMATION_REQUIRED : Tenant must pass an amend request with the
        specified additional information
          - problemCode can be provided
          - supplierCode can be provided if available
          - required information must be stated in text
        - DELAY : There is a problem causing a delay
          - problemCode must be provided (optionally with text description)
          - supplierCode can be provided if available
          - entity status may be updated (usually this is accompanied with a status change to HELD)
        - RESUBMIT : Tenant must resubmit the request

        - RESUMED : The problem has been resolved without impact on target date
          - entity status should be IN_PROGRESS
        - REAPPOINT : Tenant must reserve a new appointment and pass an amend
        request with the new reservation id
          - problemCode must be provided
          - supplierCode can be provided if available
          - further information can be provided in text
        - REAPPOINTED : Supplier has arranged a new appointment with the end
        customer
          - entity appointmentTimeslot / appointmentSupplierReference provided
          - serviceOrder targetDate updated (as applicable)
        - RESOLVED : The request is resolved
          - entity status should be RESOLVED.
        - ADDITIONAL : Supplier is flagging that new information has been
        provided
          - entity contains new service characteristics or additional information
        - WARNING : There is a (potential) problem that is not causing a delay
        yet
          - problemCode must be provided (optionally with text description)
          - supplierCode can be provided if available
        - AMENDED : Supplier has accepted and applied the requested amendment
          - serviceOrder or serviceProblem must be updated
          - serviceOrderAmendmentId or serviceProblemAmendmentId should be provided
        - CANCELLED : Supplier has cancelled the order or service problem
          - problemCode must be provided
          - supplierCode can be provided if available
          - serviceOrderCancellationId or serviceProblemCancellationId should be provided where cancellation was requested by tenant
        - ORDER_REJECTED : The order has been rejected
          - reason must be stated in text
          - problemCode can be provided
          - supplierCode can be provided if available
        - REJECTED : The service test or problem request has been rejected 
          - reason must be stated in text
          - problemCode can be provided
          - supplierCode can be provided if available
        - AMENDMENT_REJECTED : Tenant has previously sent an amendment request
        that has been rejected
          - reason must be stated in text
          - serviceOrderAmendmentId or serviceProblemAmendmentId must be provided
        - CANCELLATION_REJECTED : Tenant has previously sent a cancellation
        request that has been rejected
          - reason must be stated in text
          - serviceOrderCancellationId or serviceProblemCancellationId must be provided
        - FAILED : The request has failed to complete successfully
          - problemCode must be provided
          - supplierCode can be provided if available
          - entity status should be FAILED
        - COMPLETED : The request is complete
          - entity status should be COMPLETED or PARTIAL
        - CONTACT_CUSTOMER : Supplier has requested the tenant to contact the
        customer to continue

        - CONTACT_REAPPOINT : Supplier requires the tenant to re-appoint but
        suggests contacting the customer first
      type: string
      enum:
        - CREATED
        - ACKNOWLEDGED
        - COMMITTED
        - UPDATE
        - INFORMATION_REQUIRED
        - DELAY
        - RESUBMIT
        - RESUMED
        - REAPPOINT
        - REAPPOINTED
        - RESOLVED
        - ADDITIONAL
        - WARNING
        - AMENDED
        - CANCELLED
        - ORDER_REJECTED
        - REJECTED
        - AMENDMENT_REJECTED
        - CANCELLATION_REJECTED
        - FAILED
        - COMPLETED
        - CONTACT_CUSTOMER
        - CONTACT_REAPPOINT
    OrderStatus:
      description: >
        Order lifecycle adapted from TMF641 - order update events (KCIs) will be
        forwarded to

        the tenant as the order transitions from one state to the other.


        Where KCI represents an order state change, this must be populated with
        the new value.
      type: string
      enum:
        - REJECTED
        - ACKNOWLEDGED
        - IN_PROGRESS
        - PENDING
        - HELD
        - CANCELLED
        - FAILED
        - PARTIAL
        - COMPLETED
      example: PENDING
    EngineerTasks:
      description: |
        Engineer tasks to be performed at installation appointment.

        - INSTALL_ROUTER
        - TEST_SINGLE_DEVICE
        - ADDITIONAL_CABLING
        - TEST_MULTIPLE_DEVICES
        - INSTALL_BBU
        - VOICE_REINJECTION
        - PROVE_IP_VOICE
        - ENSURE_TELECARE
      type: array
      items:
        type: string
        pattern: ^[A-Z_]{1,25}
        example: TEST_SINGLE_DEVICE
    ProblemCode:
      description: Codes representing types of problems.
      type: string
      enum:
        - ACCESS_ISSUE
        - ACTIVATION_FAILED
        - ADDITIONAL_WORK
        - APPOINTMENT_NOT_REQUIRED
        - CAPACITY_ISSUE
        - COST_ISSUE
        - CUSTOMER_CHANGED_MIND
        - FAULT_AT_NODE
        - FAULT_AT_ONT
        - FAULT_AT_POP
        - INFORMATION_REQUIRED
        - INSTALL_FAILED
        - INVALID_REQUEST
        - LINKED_ORDER_ISSUE
        - NETWORK_ISSUE
        - NETWORK_UNAVAILABLE
        - NO_LONGER_REQUIRED
        - OTHER
        - PARTIAL_INSTALL
        - PLANNING_ISSUE
        - PROPERTY_UNOCCUPIED
        - ROUTER_NOT_AVAILABLE
        - SITE_UNSAFE
        - SUPPLIER_FAULT
        - SURVEY_REQUIRED
        - TELECARE_ISSUE
        - TIMED_OUT
        - UNABLE_TO_ATTEND
        - UNKNOWN_FAULT
        - WAYLEAVE_ISSUE
      example: NETWORK_ISSUE
    UnsolicitedCeaseReason:
      description: >
        The reason provided for the unsolicited cease:


        - CHANGE_OF_CP : Customer is switching to another CP

        - WORKING_LINE_TAKEOVER : Customer is moving address and is taking over
        the line

        - CP_REQUEST : CP requested change to service/technology that has ended
        this service
      type: string
      enum:
        - CHANGE_OF_CP
        - WORKING_LINE_TAKEOVER
        - CP_REQUEST
      example: CHANGE_OF_CP
    ServiceTestStatus:
      description: >
        Service test lifecycle adapted from TMF653 - update events (KCIs) will
        be sent to the tenant as the test 

        transitions from one state to the other
      type: string
      enum:
        - PENDING
        - IN_PROGRESS
        - REJECTED
        - FAILED
        - COMPLETED
      example: IN_PROGRESS
    ServiceProblemType:
      description: >
        Codes representing the type of problem being encountered by the end
        user:


        - OUTAGE

        - PERFORMANCE

        - STABILITY

        - SYNCHRONISATION

        - CUSTOMER

        - CPE
      type: string
      pattern: ^[A-Z_]{5,25}
      example: STABILITY
    ServiceProblemStatus:
      description: >-
        Service problem lifecycle adapted from TMF656 - update events (KCIs)
        will be sent from the supplier as the service problem transitions from
        one state to the other.
      type: string
      enum:
        - REJECTED
        - ACKNOWLEDGED
        - IN_PROGRESS
        - HELD
        - NETWORK_INCIDENT
        - PENDING_AMENDMENT
        - PENDING_CANCELLATION
        - CANCELLED
        - RESOLVED
        - COMPLETED
      example: ACKNOWLEDGED
    IncidentType:
      description: |
        Codes representing the type of incident being reported by the supplier:
        - NETWORK_OUTAGE
        - PERFORMANCE
        - MAINTENANCE
        - STABILITY
        - OTHER
      type: string
      pattern: ^[A-Z_]{5,25}
      example: MAINTENANCE
    IncidentStatus:
      description: The current status of the incident from the Supplier
      type: string
      enum:
        - NEW
        - UNDER_INVESTIGATION
        - IN_PROGRESS
        - HELD
        - RESOLVED
      example: NEW
    ErrorCode:
      description: Fibre Cafe error codes
      type: string
      enum:
        - INVALID_REQUEST
        - MALFORMED_REQUEST
        - NOT_AUTHORISED
        - NOT_FOUND
        - NOT_IMPLEMENTED
        - GATEWAY_FAULT
  securitySchemes:
    oauth2:
      description: >
        All requests to the Fibre Cafe must be authenticated and include a valid
        access token. The

        Fibre Cafe uses the industry standard [OAuth 2.0
        protocol](https://oauth.net/2/).
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /auth/supplier/access-token
          scopes: {}
