openapi: 3.0.3
info:
  title: 'Fibre Cafe : Tenant Updates API'
  version: '1.14'
  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 this API -
    the Fibre Cafe's Tenant API. The

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


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

    called. Each tenant is responsible for implementing this API definition for
    the Fibre Cage to call.


    Examples of KCIs are where the order/problem state and/or order/problem
    fields have changed or to provide feedback

    on any requests e.g. amendment/cancellation submitted on the Tenant 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://api.provided_by_tenant.net/kcis
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. A KCI update may represent an unsolicited
      cease from the supplier.
paths:
  /kcis:
    post:
      tags:
        - KCIs
      summary: Endpoint to receive an update (KCI).
      description: >
        This endpoint is called by the Fibre Cafe to send an update (KCI) to the
        tenant.


        Each KCI will have timestamps showing when issued by the supplier and
        the Fibre Cafe

        as appropriate. The reason for the KCI will be provided along with the
        updated

        associated entity.
      operationId: handleKci
      security:
        - oauth2: []
      parameters:
        - name: X-Request-ID
          description: >-
            Unique identifier to link request and response events across the
            Fibre Cafe gateway - this will change with each request
          in: header
          required: true
          schema:
            type: string
        - name: X-Conversation-ID
          description: >-
            Identifier to track message journey across the Fibre Cafe gateway -
            this will match equivalent header from order creation
          in: header
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Update'
      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: true
        '400':
          description: >-
            Order update 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: Update 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: Update 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: TENANT_FAULT
                messages:
                  - An unexpected error occurred
        '503':
          description: Tenant Update API is temporarily unavailable
components:
  schemas:
    BaseUpdate:
      description: Abstract type - metadata about an update (KCI).
      type: object
      required:
        - id
        - supplier
        - sequenceNumber
        - deliveredOn
      properties:
        id:
          description: Unique identifier for this 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: 3456cf7d-4471-42e4-a5be-c24ed58a7aa6
        supplier:
          description: >-
            System identifier for a supplier on the Fibre Cafe that is
            associated with this order
          type: string
          pattern: ^\w{1,20}$
          example: SUPPLIER1
        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'
        receivedOn:
          description: Date/time when Fibre Cafe received this update
          type: string
          format: date-time
          example: '2022-01-10T09:00:00.000Z'
        deliveredOn:
          description: Date/time when Fibre Cafe delivered this update to the tenant API
          type: string
          format: date-time
          example: '2022-01-10T09:00:00.000Z'
        supplierNotes:
          description: >-
            The supplier has added these note(s) about the order relating to
            this KCI
          type: array
          items:
            $ref: '#/components/schemas/SupplierNote'
    UpdateInformational:
      description: KCI update - informational, no action required.
      allOf:
        - $ref: '#/components/schemas/BaseUpdate'
        - type: object
          required:
            - updateType
            - information
          properties:
            updateType:
              $ref: '#/components/schemas/InformationalUpdateType'
            information:
              $ref: '#/components/schemas/Information'
    UpdateActionRequired:
      description: KCI update - action required by tenant.
      allOf:
        - $ref: '#/components/schemas/BaseUpdate'
        - type: object
          required:
            - updateType
            - action
          properties:
            updateType:
              $ref: '#/components/schemas/ActionRequiredUpdateType'
            action:
              $ref: '#/components/schemas/Action'
    UpdateError:
      description: KCI update - error sending request to supplier.
      allOf:
        - $ref: '#/components/schemas/BaseUpdate'
        - type: object
          required:
            - updateType
            - error
          properties:
            updateType:
              $ref: '#/components/schemas/ErrorUpdateType'
            error:
              $ref: '#/components/schemas/SupplierFailure'
    TypedUpdate:
      description: Abstract type - metadata about an update (KCI).
      anyOf:
        - $ref: '#/components/schemas/UpdateInformational'
        - $ref: '#/components/schemas/UpdateActionRequired'
        - $ref: '#/components/schemas/UpdateError'
    ProvideServiceOrderUpdate:
      description: An update for a provide service order
      allOf:
        - $ref: '#/components/schemas/TypedUpdate'
        - type: object
          required:
            - entityType
            - entity
          properties:
            entityType:
              $ref: '#/components/schemas/ProvideOrderEntityType'
            entity:
              $ref: '#/components/schemas/ProvideServiceOrder'
    CeaseServiceOrderUpdate:
      description: An update for a cease service order
      allOf:
        - $ref: '#/components/schemas/TypedUpdate'
        - type: object
          required:
            - entityType
            - entity
          properties:
            entityType:
              $ref: '#/components/schemas/CeaseOrderEntityType'
            entity:
              $ref: '#/components/schemas/CeaseServiceOrder'
    ModifyServiceOrderUpdate:
      description: An update for a modify service order
      allOf:
        - $ref: '#/components/schemas/TypedUpdate'
        - type: object
          required:
            - entityType
            - entity
          properties:
            entityType:
              $ref: '#/components/schemas/ModifyOrderEntityType'
            entity:
              $ref: '#/components/schemas/ModifyServiceOrder'
    UnsolicitedCeaseServiceOrderUpdate:
      description: An update for an unsolicited cease service order
      allOf:
        - $ref: '#/components/schemas/TypedUpdate'
        - type: object
          required:
            - entityType
            - entity
          properties:
            entityType:
              $ref: '#/components/schemas/UnsolicitedCeaseOrderEntityType'
            entity:
              $ref: '#/components/schemas/UnsolicitedCeaseServiceOrder'
    ProvideEthernetOrderUpdate:
      description: An update for a provide ethernet order
      allOf:
        - $ref: '#/components/schemas/TypedUpdate'
        - type: object
          required:
            - entityType
            - entity
          properties:
            entityType:
              $ref: '#/components/schemas/ProvideEthernetOrderEntityType'
            entity:
              $ref: '#/components/schemas/ProvideEthernetOrder'
    ServiceTestUpdate:
      description: An update for an active service test
      allOf:
        - $ref: '#/components/schemas/TypedUpdate'
        - type: object
          required:
            - entityType
            - entity
          properties:
            entityType:
              $ref: '#/components/schemas/ServiceTestEntityType'
            entity:
              $ref: '#/components/schemas/ServiceTest'
    ServiceProblemUpdate:
      description: An update for a service problem
      allOf:
        - $ref: '#/components/schemas/TypedUpdate'
        - type: object
          required:
            - entityType
            - entity
          properties:
            entityType:
              $ref: '#/components/schemas/ServiceProblemEntityType'
            entity:
              $ref: '#/components/schemas/ServiceProblem'
    Update:
      type: object
      anyOf:
        - $ref: '#/components/schemas/ProvideServiceOrderUpdate'
        - $ref: '#/components/schemas/CeaseServiceOrderUpdate'
        - $ref: '#/components/schemas/ModifyServiceOrderUpdate'
        - $ref: '#/components/schemas/UnsolicitedCeaseServiceOrderUpdate'
        - $ref: '#/components/schemas/ProvideEthernetOrderUpdate'
        - $ref: '#/components/schemas/ServiceTestUpdate'
        - $ref: '#/components/schemas/ServiceProblemUpdate'
    ProvideServiceOrder:
      description: Represents an order for new service(s) at a particular address.
      type: object
      required:
        - id
        - orderType
        - supplier
        - status
        - address
        - serviceOrderItem
        - primaryContact
      properties:
        id:
          description: >-
            Unique reference identifying this service order (order number -
            generated by Fibre Cafe)
          type: number
          minimum: 1
          example: 123
        orderType:
          $ref: '#/components/schemas/ProvideOrderType'
        supplier:
          description: >-
            System identifier for a supplier on the Fibre Cafe that is
            associated with this order
          type: string
          pattern: ^\w{1,20}$
          example: DUMMY_SUPPLIER
        supplierOrderNumber:
          description: >-
            Order reference generated by the supplier once acknowledged (for
            information only)
          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 the reserved appointment (if applicable)
          type: number
          minimum: 1
          example: 345
        appointmentSupplierReference:
          description: >-
            Appointment reference generated by the supplier for a re-appointed
            timeslot (only returned if applicable)
          type: string
          minLength: 1
          maxLength: 50
          example: '123456543'
        appointmentTimeslot:
          allOf:
            - description: >-
                Represents a re-appointed timeslot from the supplier (only
                returned if applicable)
            - $ref: '#/components/schemas/Timeslot'
        requestedCompletionDate:
          description: >-
            Where not appointed, allows a date to be requested for the service
            activation.
          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
          example: Hazardous materials stored on site
          minLength: 1
          maxLength: 1000
        onSiteRestrictions:
          description: >-
            Information about restrictions on the site where the service will be
            installed
          type: string
          example: Restricted access
          minLength: 1
          maxLength: 1000
        notes:
          description: >-
            Any notes about the order. This may include additional information
            that is required
          type: string
          example: Lorem ipsum dolor sit amet...
          minLength: 1
          maxLength: 1000
        created:
          description: Date/time when the order was created
          type: string
          format: date-time
          example: '2022-01-01T09:09:33.001Z'
        updated:
          description: Date/time when the order was last updated
          type: string
          format: date-time
          example: '2022-01-01T09:45:39.001Z'
        serviceOrderAmendment:
          $ref: '#/components/schemas/ProvideServiceOrderAmendment'
        serviceOrderCancellation:
          $ref: '#/components/schemas/ServiceOrderCancellation'
    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 - e.g.
            for FTTH service

            - AUTHENTICATION_AGENT (DHCPRelayAgent, PPPIntermediateAgent, None)

            - REMOTE_ID

            - LINE_PROFILE

            - SERVICE_ID

            - ENNI_ID

            - SERVICE_VLAN_ID

            - CUSTOMER_VLAN_ID

            - CABLE_LINK_ID

            - CIRCUIT_REFERENCE

            - SITE_NAME

            - SITE_LOCATION

            - ONT_REFERENCE

            - ONT_SERIAL_NUMBER

            - ONT_PORT
          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: LINE_PROFILE
        value:
          description: Value for this characteristic
          type: string
          minLength: 1
          maxLength: 50
          example: 1G_1G
    ModifyServiceCharacteristic:
      description: Modify a characteristic or attribute of an active service.
      type: object
      allOf:
        - $ref: '#/components/schemas/ServiceCharacteristic'
        - type: object
          properties:
            action:
              $ref: '#/components/schemas/ModifyAction'
    ProvideServiceOrderAmendment:
      description: >
        Represents a previous request to amend an existing inflight provide
        order.

        Any value(s) supplied will replace the existing value.


        An amendment request has the following states:


        - PENDING : Supplier has received the amendment request and will accept
        or reject it shortly

        - FAILED_TO_SEND : The Fibre Cafe was unable to send the order amendment
        request

        - COMPLETED : The amendment request has been accepted by the supplier
        and applied to the order

        - REJECTED : The amendment request has been rejected by the supplier
      type: object
      required:
        - id
        - orderId
        - status
      properties:
        id:
          description: >-
            Unique identifier for this provide service order amendment request
            (generated by the Fibre Cafe)
          type: number
          minimum: 1
          example: 234
        orderId:
          description: Unique reference identifying the service order to be amended
          type: number
          minimum: 1
          example: 123
        supplierReference:
          description: >-
            Supplier reference for this amendment request (if available - for
            information only)
          type: string
          minLength: 1
          maxLength: 50
          example: A123X-1
        serviceCharacteristics:
          description: List of service characteristics for the service order item
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ServiceCharacteristic'
        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
        requestedCompletionDate:
          description: >-
            Where not appointed, allows a date to be requested for the service
            activation
          type: string
          format: date
          example: '2022-01-10'
        engineerTasks:
          $ref: '#/components/schemas/EngineerTasks'
        hazards:
          description: >-
            Hazard information about the site where the service will be
            installed
          type: string
          minLength: 1
          maxLength: 1000
        onSiteRestrictions:
          description: >-
            Information about restrictions on the site where the service(s) will
            be installed
          type: string
          minLength: 1
          maxLength: 1000
        notes:
          description: Notes about the order
          type: string
          minLength: 1
          maxLength: 1000
          example: Lorem ipsum dolor sit amet...
        status:
          $ref: '#/components/schemas/RequestStatus'
      example:
        id: 345
        orderId: 123
        appointmentReservationId: 234
        status: REJECTED
    ServiceOrderCancellation:
      description: >
        Represents a request from the tenant to cancel an inflight order.


        Cancellation requests have the following states:


        - PENDING : Supplier has received the cancellation request and will
        accept or reject it shortly

        - FAILED_TO_SEND : The Fibre Cafe was unable to send the order
        cancellation request

        - COMPLETED : The cancellation request has been accepted by the supplier
        and the order cancelled

        - REJECTED : The cancellation request has been rejected by the supplier
      type: object
      required:
        - id
        - orderId
        - reasonCode
        - status
      properties:
        id:
          description: >-
            Unique identifier for this service order cancellation request
            (generated by the Fibre Cafe)
          type: number
          minimum: 1
          example: 234
        orderId:
          description: Unique reference identifying the service order to be cancelled
          type: number
          minimum: 1
          example: 123
        supplierReference:
          description: >-
            Supplier reference for this cancellation request (if available - for
            information only)
          type: string
          minLength: 1
          maxLength: 50
          example: A123X-1
        reasonCode:
          $ref: '#/components/schemas/CancellationReasonCode'
        text:
          description: >-
            Textual reason for cancellation - provides more context as
            applicable
          type: string
          minLength: 1
          maxLength: 1000
          example: Delivery too long
        status:
          $ref: '#/components/schemas/RequestStatus'
    Information:
      description: >
        Represents an informational update from the supplier - these are given a
        reason type to aid with any process/flows

        on the tenant system.
      type: object
      required:
        - type
      properties:
        type:
          $ref: '#/components/schemas/InformationType'
        code:
          $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'
    Action:
      description: >
        Specifies that an action is required by the tenant to continue this
        order. For example, provide information or

        rebook an appointment.
      type: object
      required:
        - type
      properties:
        type:
          $ref: '#/components/schemas/ActionType'
        code:
          $ref: '#/components/schemas/ProblemCode'
        text:
          description: >-
            Textual information about this update - e.g. reason why reappoint is
            needed
          type: string
          minLength: 1
          maxLength: 1000
          example: Fault between Node and Toby.
        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'
    SupplierFailure:
      description: >
        Represents a failure that usually means this order has failed.

        The underlying cause will be returned but will likely require help from
        the Fibre Cafe support team or

        by contacting the supplier directly.

        Every error is uniquely identified via a UUID which should be reported
        to the support team as required.


        Possible error types:

        - NOT_AUTHORISED : An authorisation issue accessing the supplier API
        using the tenant's credentials.

        - INVALID_REQUEST : The request was rejected as invalid by the supplier
        API.

        - SUPPLIER_FAULT : The supplier API has encountered an unexpected error
        or is not responding to the Fibre Cafe.

        - SUPPLIER_TIMED_OUT : The Fibre Cafe did not receive a timely response
        from the supplier.

        - GATEWAY_FAULT : The Fibre Cafe gateway has encountered an unexpected
        error.
      allOf:
        - $ref: '#/components/schemas/Error'
    CeaseServiceOrder:
      description: Request to cease an existing live service
      type: object
      required:
        - id
        - orderType
        - supplier
        - serviceId
        - requestedCompletionDate
        - status
      properties:
        id:
          description: >-
            Unique reference identifying this cease service order (generated by
            the Fibre Cafe)
          type: number
          minimum: 1
          example: 123
        orderType:
          $ref: '#/components/schemas/CeaseOrderType'
        supplier:
          description: >-
            System identifier for a supplier on the Fibre Cafe that is
            associated with this order
          type: string
          pattern: ^\w{1,20}$
          example: DUMMY_SUPPLIER
        supplierOrderNumber:
          description: >-
            Order reference generated by the supplier once acknowledged (for
            information only)
          type: string
          minLength: 1
          maxLength: 50
          example: A123X
        serviceId:
          description: Identifier of an existing live service
          type: string
          minLength: 1
          maxLength: 50
          example: SI2345432345345
        serviceCharacteristics:
          description: >
            List of service characteristics providing auxiliary information
            about the service being ceased (required by some suppliers)

            e.g.

            - LINE_PROFILE

            - SERVICE_ASSET_ID
          type: array
          minItems: 0
          items:
            $ref: '#/components/schemas/ServiceCharacteristic'
        requestedCompletionDate:
          description: >-
            The requested date/time for the service to cease (time might not be
            supported by all suppliers)
          type: string
          format: date-time
          example: '2022-01-10T09:00:00.000Z'
        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'
        created:
          description: Date/time when the order was created
          type: string
          format: date-time
          example: '2022-01-01T09:09:33.001Z'
        updated:
          description: Date/time when the order was last updated
          type: string
          format: date-time
          example: '2022-01-01T09:45:39.001Z'
        serviceOrderAmendment:
          $ref: '#/components/schemas/CeaseServiceOrderAmendment'
        serviceOrderCancellation:
          $ref: '#/components/schemas/ServiceOrderCancellation'
    ServiceOrder:
      type: object
      oneOf:
        - $ref: '#/components/schemas/ProvideServiceOrder'
        - $ref: '#/components/schemas/ModifyServiceOrder'
        - $ref: '#/components/schemas/CeaseServiceOrder'
        - $ref: '#/components/schemas/UnsolicitedCeaseServiceOrder'
    CeaseServiceOrderAmendment:
      description: >
        Represents a previous request to amend an existing inflight cease order.

        Any value(s) supplied will replace the existing value.


        An amendment request has the following states:


        - PENDING : Supplier has received the amendment request and will accept
        or reject it shortly

        - FAILED_TO_SEND : The Fibre Cafe was unable to send the order amendment
        request

        - COMPLETED : The amendment request has been accepted by the supplier
        and applied to the order

        - REJECTED : The amendment request has been rejected by the supplier
      type: object
      required:
        - id
        - orderId
        - status
      properties:
        id:
          description: >-
            Unique identifier for this cease service order amendment request
            (generated by the Fibre Cafe)
          type: number
          minimum: 1
          example: 234
        orderId:
          description: Unique identifier for the cease service order to be amended
          type: number
          minimum: 1
          example: 123
        supplierReference:
          description: >-
            Supplier reference for this amendment request (if available - for
            information only)
          type: string
          minLength: 1
          maxLength: 50
          example: A123X-1
        requestedCompletionDate:
          description: The replacement requested date/time for the service to cease
          type: string
          format: date-time
          example: '2022-01-10T09:00:00.000Z'
        status:
          $ref: '#/components/schemas/RequestStatus'
        rejectionReasonText:
          description: Where this amendment was rejected, contains the reason
          type: string
          example: Requested completion date is in the past
    ModifyServiceOrder:
      description: >-
        Request to modify an existing live service - specify the replacement
        characteristic e.g. LINE_PROFILE
      type: object
      required:
        - id
        - orderType
        - supplier
        - serviceId
        - serviceCharacteristics
        - status
      properties:
        id:
          description: >-
            Unique identifier for this modify service order (generated by the
            Fibre Cafe)
          type: number
          minimum: 1
          example: 123
        orderType:
          $ref: '#/components/schemas/ModifyOrderType'
        supplier:
          description: >-
            System identifier for a supplier on the Fibre Cafe that is
            associated with this order
          type: string
          pattern: ^\w{1,20}$
          example: DUMMY_SUPPLIER
        supplierOrderNumber:
          description: >-
            Order reference generated by the supplier once acknowledged (for
            information only)
          type: string
          minLength: 1
          maxLength: 50
          example: A123X
        serviceId:
          description: Identifier of an existing live service
          type: string
          minLength: 1
          maxLength: 50
          example: SI2345432345345
        serviceCharacteristics:
          description: Service characteristics to be updated e.g. LINE_PROFILE
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ModifyServiceCharacteristic'
        requestedCompletionDate:
          description: The requested date/time for the modify service (if supported)
          type: string
          format: date-time
          example: '2022-01-10T09:00:00.000Z'
        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'
        created:
          description: Date/time when the order was created
          type: string
          format: date-time
          example: '2022-01-01T09:09:33.001Z'
        updated:
          description: Date/time when the order was last updated
          type: string
          format: date-time
          example: '2022-01-01T09:45:39.001Z'
        serviceOrderAmendment:
          $ref: '#/components/schemas/ModifyServiceOrderAmendment'
        serviceOrderCancellation:
          $ref: '#/components/schemas/ServiceOrderCancellation'
    ModifyServiceOrderAmendment:
      description: >
        Represents a previous request to amend an existing inflight modify
        order.

        Any value(s) supplied will replace the existing value.


        An amendment request has the following states:


        - PENDING : Supplier has received the amendment request and will accept
        or reject it shortly

        - FAILED_TO_SEND : The Fibre Cafe was unable to send the order amendment
        request

        - COMPLETED : The amendment request has been accepted by the supplier
        and applied to the order

        - REJECTED : The amendment request has been rejected by the supplier
      type: object
      required:
        - id
        - orderId
        - status
      properties:
        id:
          description: >-
            Unique identifier for this modify service order amendment request
            (generated by the Fibre Cafe)
          type: number
          minimum: 1
          example: 234
        orderId:
          description: Unique identifier for the modify service order to be amended
          type: number
          example: 123
        supplierReference:
          description: >-
            Supplier reference for this amendment request (if available - for
            information only)
          type: string
          minLength: 1
          maxLength: 50
          example: A123X-1
        serviceCharacteristics:
          description: Service characteristics to be updated e.g. LINE_PROFILE
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ModifyServiceCharacteristic'
        requestedCompletionDate:
          description: The requested date/time for the modify (if supported)
          type: string
          format: date-time
          example: '2022-01-10T09:00:00.000Z'
        status:
          $ref: '#/components/schemas/RequestStatus'
    UnsolicitedCeaseServiceOrder:
      description: Unsolicited cease for an existing live service.
      type: object
      required:
        - id
        - orderType
        - supplier
        - supplierOrderNumber
        - reason
        - serviceId
        - requestedCeaseDate
        - status
      properties:
        id:
          description: >-
            Unique reference identifying this unsolicited cease order (generated
            by the Fibre Cafe)
          type: number
          minimum: 1
          example: 123
        orderType:
          $ref: '#/components/schemas/UnsolicitedCeaseOrderType'
        supplier:
          description: >-
            System identifier for a supplier on the Fibre Cafe that is
            associated with this unsolicited cease order
          type: string
          pattern: ^\w{1,20}$
          example: DUMMY_SUPPLIER
        supplierOrderNumber:
          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'
        created:
          description: Date/time when the order was created
          type: string
          format: date-time
          example: '2022-01-01T09:09:33.001Z'
        updated:
          description: Date/time when the order was last updated
          type: string
          format: date-time
          example: '2022-01-01T09:45:39.001Z'
        serviceOrderCancellation:
          $ref: '#/components/schemas/ServiceOrderCancellation'
    ProvideEthernetOrder:
      description: >-
        Represents an Ethernet order for new service(s) between the sites
        provided.
      type: object
      required:
        - id
        - status
        - supplier
        - supplierQuoteId
        - siteInformation
        - ethernetOrderItems
      properties:
        id:
          description: >-
            Unique reference identifying this ethernet order (order number -
            generated by the Fibre Cafe)
          type: number
          minimum: 1
          example: 123
        status:
          $ref: '#/components/schemas/OrderStatus'
        supplier:
          description: >-
            System identifier for a supplier on the Fibre Cafe that is
            associated with this order
          type: string
          pattern: ^\w{1,20}$
          example: DUMMY_SUPPLIER
        supplierOrderNumber:
          description: >-
            Order reference generated by the supplier once acknowledged (for
            information only)
          type: string
          minLength: 1
          maxLength: 50
          example: A123X
        supplierQuoteId:
          description: >-
            A unique identifier of the quote item within the overall quote
            entity, as provided by the supplier
          type: string
          minLength: 8
          maxLength: 64
          example: SUPP2-QUO-ETH-5001
        siteInformation:
          type: array
          minItems: 2
          items:
            $ref: '#/components/schemas/EthernetSiteInformation'
        ethernetOrderItems:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/EthernetOrderItem'
        created:
          description: Date/time when the order was created
          type: string
          format: date-time
          example: '2022-01-01T09:09:33.001Z'
        updated:
          description: Date/time when the order was last updated
          type: string
          format: date-time
          example: '2022-01-01T09:45:39.001Z'
        committedDate:
          description: >-
            When the supplier first commits to fulfil the order this field will
            contain the expected completion date. Once set, this value will not
            change unless driven by the tenant/customer.
          type: string
          format: date-time
          example: '2022-01-01T09:09:33.001Z'
        targetDate:
          description: >-
            The current expected completion date - set once the order is
            committed. 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'
    EthernetOrderItem:
      description: Represents an Ethernet order item for new service.
      type: object
      required:
        - contractDetails
        - service
      properties:
        service:
          $ref: '#/components/schemas/Service'
        contractDetails:
          $ref: '#/components/schemas/ContractItem'
        requestedCompletionDate:
          description: >-
            Where not appointed, allows a date to be requested for the service
            activation.
          type: string
          format: date
          example: '2022-01-10'
        technicalContact:
          $ref: '#/components/schemas/Contact'
    Wayleave:
      description: Particulars regarding permissions at a given site.
      allOf:
        - type: object
          required:
            - wayleaveOwner
          properties:
            wayleaveOwner:
              description: >-
                Set to true if the organisation placing the order has wayleave
                permissions, otherwise set to false.
              type: boolean
              example: true
            wayleaveCharacteristics:
              description: >-
                Information about restrictions on the site where the service
                will be installed.
              type: array
              minItems: 1
              items:
                $ref: '#/components/schemas/Characteristic'
            wayleaveContact:
              $ref: '#/components/schemas/Contact'
        - oneOf:
            - title: wayleaveCharacteristics
              required:
                - wayleaveCharacteristics
            - title: wayleaveContact
              required:
                - wayleaveContact
    Characteristic:
      description: A generic attribute associated to an entity.
      type: object
      required:
        - name
        - value
      properties:
        name:
          description: Name of the characteristic
          type: string
          minLength: 1
          maxLength: 50
          pattern: ^[A-Z_]{5,50}
          example: POINT_OF_INTERCONNECT
        value:
          description: Value for this characteristic
          type: string
          minLength: 1
          maxLength: 50
          example: 1G1G
    Service:
      description: The details regarding the Ethernet service
      type: object
      required:
        - serviceSpecification
        - serviceCharacteristic
      properties:
        serviceSpecification:
          $ref: '#/components/schemas/ServiceSpecification'
        serviceCharacteristic:
          type: array
          minItems: 0
          items:
            $ref: '#/components/schemas/Characteristic'
    ContractLength:
      description: A generic entity to capture the duration of a contract
      type: object
      required:
        - value
        - unit
      properties:
        value:
          description: The length of the contract
          type: integer
          minimum: 0
          example: 36
        unit:
          description: The duration unit of the contract
          type: string
          enum:
            - MONTH
            - YEAR
          example: MONTH
    ContractItem:
      description: A generic entity to capture the contract details of a product/service.
      type: object
      required:
        - contractLength
        - billingFrequency
      properties:
        contractLength:
          $ref: '#/components/schemas/ContractLength'
        billingFrequency:
          description: The frequency the product/service will be invoiced by the supplier
          type: string
          enum:
            - MONTHLY
            - QUARTERLY
            - ANNUALLY
        priceAlteration:
          description: >-
            A price override/promotion code available between the tenant and
            supplier
          type: string
          minLength: 8
          maxLength: 64
    Site:
      description: Provides details for each of the Ethernet sites as part of the quote.
      type: object
      required:
        - name
        - postcode
        - role
        - address
      properties:
        name:
          description: The name of the site
          type: string
          example: Strategic Imperative Offices
        address:
          $ref: '#/components/schemas/AddressIdentifier'
        postCode:
          description: Postal code
          type: string
          minLength: 1
          maxLength: 12
          example: TW184LG
        role:
          $ref: '#/components/schemas/SiteRole'
        siteCharacteristics:
          type: array
          minItems: 0
          items:
            $ref: '#/components/schemas/Characteristic'
    EthernetSiteInformation:
      description: Details of the Ethernet Site for the order
      type: object
      allOf:
        - $ref: '#/components/schemas/Site'
        - type: object
          required:
            - wayleave
            - primaryContact
            - secondaryContact
          properties:
            wayleave:
              $ref: '#/components/schemas/Wayleave'
            primaryContact:
              $ref: '#/components/schemas/Contact'
            secondaryContact:
              $ref: '#/components/schemas/Contact'
            hazards:
              description: >-
                Hazard information about the site where the service will be
                installed
              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 installed
              type: string
              example: Restricted access
              minLength: 1
              maxLength: 1000
            notes:
              description: >-
                Any additional notes about the  site. This may include
                additional information that is required
              type: string
              example: Lorem ipsum dolor sit amet...
              minLength: 1
              maxLength: 1000
    ServiceTest:
      description: Basic details returned as part of the transacting of the Service Test.
      type: object
      required:
        - id
        - status
        - created
        - updated
        - serviceId
        - problemType
        - serviceSpecification
        - supplier
        - characteristics
      properties:
        id:
          description: >-
            Unique reference identifying this service test (test number -
            generated by the Fibre Cafe)
          type: number
          minimum: 1
          example: 123
        status:
          $ref: '#/components/schemas/ServiceTestStatus'
        created:
          description: Date/time when the service test was created
          type: string
          format: date-time
          example: '2022-01-01T09:09:33.001Z'
        updated:
          description: Date/time when the service test was last updated
          type: string
          format: date-time
          example: '2022-01-01T09:45:39.001Z'
        serviceId:
          description: Identifier of an existing live service
          type: string
          minLength: 1
          maxLength: 50
          example: SI2345432345345
        problemType:
          description: |
            The type of problem being experienced with the service.
            - CPE
            - CUSTOMER
            - OUTAGE
            - PERFORMANCE
            - STABILITY
            - SYNCHRONISATION
          type: string
          pattern: ^[\w_]{3,15}
        serviceSpecification:
          $ref: '#/components/schemas/ServiceSpecification'
        supplier:
          description: >-
            System identifier for a supplier on the Fibre Cafe that is
            associated with this service
          type: string
          pattern: ^[\w_]{1,20}
          example: DUMMY_SUPPLIER
        supplierReference:
          description: >-
            Supplier reference for this service test (if available - for
            information only)
          type: string
          minLength: 1
          maxLength: 50
          example: A12345
        characteristics:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ServiceTestCharacteristic'
        result:
          $ref: '#/components/schemas/ServiceTestResult'
    ServiceTestResult:
      description: Result of a service test request.
      type: object
      required:
        - testValidity
        - testOutcome
      properties:
        testValidity:
          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'
        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:
          $ref: '#/components/schemas/TestOutcome'
    TestOutcome:
      description: The outcome of the service test execution.
      type: object
      required:
        - testResult
        - code
      properties:
        testResult:
          description: RAG Status on the service test execution
          type: string
          enum:
            - UNAVAILABLE
            - RED
            - AMBER
            - GREEN
            - FAILED
          example: AMBER
        code:
          description: Codes representing the test result
          type: string
          pattern: ^[A-Z_]{5,35}
          example: NO_FAULT_FOUND
        description:
          description: >-
            A textual description of the service test and associated next steps
            (if available)
          type: string
          maxLength: 256
        supplierCodes:
          description: 'Supplier code(s) representing the test result '
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 50
            example: D1234
        supplierText:
          description: Text from the supplier explaining the test result (where available)
          type: string
          minLength: 1
          maxLength: 1000
    TestMeasure:
      description: The specific metrics returned as part of the service test execution.
      type: object
      required:
        - metricName
        - metricValue
      properties:
        metricName:
          description: The name of the metric being reported
          type: string
          maxLength: 64
          pattern: ^[A-Z_]{5,25}
          example: ONT_LIGHT_LEVEL
        captureDateTime:
          description: The date-time the measurement was captured
          type: string
          format: date-time
          example: '2022-01-01T09:45:39.001Z'
        metricValue:
          description: A measurement of the metric
          type: string
          maxLength: 128
          example: '-14.5'
        unitOfMeasure:
          description: A unit of measurement used to measure the metric
          type: string
          maxLength: 128
          example: decibel
        ruleViolation:
          description: >-
            Confirms if the measurement is below the agreed thresholds and a
            rule violation has occurred
          type: boolean
          example: false
        ruleSeverity:
          description: The severity of the violation
          type: string
          enum:
            - SEVERE
            - MAJOR
            - MINOR
            - WARNING
            - N/A
          example: WARNING
    ServiceTestCharacteristic:
      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
    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: Basic details returned as part of the transacting of the Service Problem
      type: object
      required:
        - id
        - status
        - created
        - updated
        - problemType
        - problemText
        - serviceId
        - serviceSpecification
        - supplier
        - serviceTestId
        - characteristics
        - primaryContact
        - notes
      properties:
        id:
          description: >-
            Unique reference identifying this service problem (generated by the
            Fibre Cafe)
          type: number
          minimum: 1
          example: 123
        status:
          $ref: '#/components/schemas/ProblemStatus'
        created:
          description: Date/time when the service problem was created
          type: string
          format: date-time
          example: '2022-01-01T09:09:33.001Z'
        updated:
          description: Date/time when the service problem was last updated
          type: string
          format: date-time
          example: '2022-01-01T09:45:39.001Z'
        externalIdentifier:
          description: >-
            The communications provider (CP) identifier for the problem. Used
            for reference purposes only
          type: string
          minLength: 1
          maxLength: 64
          example: DS-2345432345345
        supplierIdentifier:
          description: >-
            Problem reference generated by the supplier once acknowledged (for
            information only)
          type: string
          minLength: 1
          maxLength: 50
          example: A123X
        problemType:
          description: >-
            The type of problem being raised. This will be advised or inferred
            as part of the service test result
          type: string
          pattern: ^[\w_]{5,50}
          example: PERFORMANCE
        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'
        supplier:
          description: >-
            System identifier for a supplier on the Fibre Cafe that is
            associated with this service problem
          type: string
          pattern: ^[\w_]{1,20}
          example: DUMMY_SUPPLIER
        serviceTestId:
          description: >-
            Identifier of a current service test that has been performed against
            the service prior to raising the service problem
          type: number
          minimum: 1
          example: 123
        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
        parentServiceProblemId:
          description: >-
            Unique reference for an issue that is believed to be related, for
            example a multiline network outage
          type: number
          example: 2443435345
        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'
        serviceProblemAmendment:
          $ref: '#/components/schemas/ServiceProblemAmendment'
        serviceProblemCancellation:
          $ref: '#/components/schemas/ServiceProblemCancellation'
    ServiceProblemCancellation:
      description: >-
        Represents a request from the tenant to cancel an inflight service
        problem. This will need to be approved and confirmed or rejected by the
        supplier.
      type: object
      required:
        - id
        - status
        - serviceProblemId
        - reasonCode
      properties:
        id:
          description: >-
            Unique reference identifying this service problem (generated by the
            Fibre Cafe)
          type: number
          minimum: 1
          example: 123
        status:
          $ref: '#/components/schemas/RequestStatus'
        serviceProblemId:
          description: Unique reference identifying the service problem to be cancelled
          type: number
          minimum: 1
          example: 123
        reasonCode:
          $ref: '#/components/schemas/ServiceProblemCancellationReasonCode'
        text:
          description: >-
            Textual reason for cancellation - provides more context as
            applicable
          type: string
          minLength: 1
          maxLength: 1000
          example: Issue appears to have rectified itself.
    ServiceProblemAmendment:
      description: >-
        Represents a request from the tenant to amend an inflight service
        problem. This will need to be approved and confirmed or rejected by the
        supplier.
      type: object
      required:
        - id
        - status
        - serviceProblemId
      properties:
        id:
          description: >-
            Unique reference identifying this service problem amendment
            (generated by the Fibre Cafe)
          type: number
          minimum: 1
          example: 123
        status:
          $ref: '#/components/schemas/RequestStatus'
        serviceProblemId:
          description: Unique reference identifying the service problem to be amended
          type: number
          minimum: 1
          example: 123
        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.
        characteristics:
          description: Update any characteristics of the problem
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ServiceProblemCharacteristic'
        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
        primaryContact:
          $ref: '#/components/schemas/Contact'
        secondaryContact:
          $ref: '#/components/schemas/Contact'
        appointmentReservationId:
          description: Unique identifier for the new reserved appointment
          type: number
          minimum: 1
          example: 345
    ServiceProblemResolution:
      description: Details of resolution to a service problem request.
      type: object
      required:
        - id
        - serviceProblemId
        - status
        - resolvedDate
        - resolutionDetails
      properties:
        id:
          description: >-
            Unique reference identifying this service problem resolution
            (generated by the Fibre Cafe)
          type: number
          minimum: 1
          example: 123
        serviceProblemId:
          description: >-
            Unique reference identifying the service problem (generated by the
            Fibre Cafe)
          type: number
          minimum: 1
          example: 123
        status:
          $ref: '#/components/schemas/ServiceProblemResolutionStatus'
        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_]{5,50}
            example: EXCEEDED_SLA_TIME_TO_REPAIR
        tenantNotes:
          description: >-
            Text from the tenant giving notes or reason for rejection - as
            applicable
          type: string
          minLength: 1
          maxLength: 1000
          example: Issue still persists
    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 test provided by the supplier regarding the problem
            resolution
          type: string
          maxLength: 256
        supplierCodes:
          description: Code(s) 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_]{5,50}
            example: DAMAGED_ONT
    AddressIdentifier:
      description: Address identifier for location including type of identifier.
      allOf:
        - $ref: '#/components/schemas/SecondaryAddressIdentifier'
        - type: object
          properties:
            additionalIdentifiers:
              description: >-
                Additional address identifiers where available/required for
                subsequent operations
              type: array
              minItems: 1
              items:
                $ref: '#/components/schemas/SecondaryAddressIdentifier'
    SecondaryAddressIdentifier:
      description: Additional address identifier for location including type of identifier.
      type: object
      required:
        - id
        - type
      properties:
        id:
          description: Address identifier of given type
          type: string
          minLength: 1
          maxLength: 20
          example: A00000031882
        type:
          description: Type of address identifier
          type: string
          pattern: ^[A-Za-z]{1,15}$
          example:
            - UPRN
            - NAD
            - ROBT
            - DistrictCode
    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
    SupplierNote:
      description: >-
        Represents a note from the supplier - depending on the supplier, notes
        may be categorised by type.
      type: object
      required:
        - note
        - created
      properties:
        note:
          description: Note added by the supplier
          type: string
          minLength: 1
          maxLength: 4096
          example: Lorem ipsum dolor sit amet...
        type:
          description: Type of note if available
          type: string
          minLength: 1
          maxLength: 50
          example:
            - Engineer Note
            - Site Visit Note
            - Customer Update
        created:
          description: Date/time when the note was created
          type: string
          format: date-time
          example: '2022-01-01T09:09:33.001Z'
    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_FOUND : Requested entity was not found

        - SUPPLIER_FAULT : An unexpected problem originating from the supplier
        API

        - SUPPLIER_TIMED_OUT : The Fibre Cafe did not receive a timely response
        from the supplier

        - GATEWAY_FAULT : An unexpected problem originating on the Fibre Cafe
        gateway

        - TENANT_FAULT : An unexpected problem reported by the tenant API
      type: object
      required:
        - uuid
        - code
        - messages
      properties:
        uuid:
          description: Unique identifier of this error - for tracing purposes
          type: string
          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: Invalid value for field x - accepted values are y
    InformationalUpdateType:
      description: The type of update - informational
      type: string
      enum:
        - INFORMATIONAL
    ActionRequiredUpdateType:
      description: The type of update - action required
      type: string
      enum:
        - ACTION_REQUIRED
    ErrorUpdateType:
      description: The type of update - error
      type: string
      enum:
        - ERROR
    UpdateType:
      anyOf:
        - $ref: '#/components/schemas/InformationalUpdateType'
        - $ref: '#/components/schemas/ActionRequiredUpdateType'
        - $ref: '#/components/schemas/ErrorUpdateType'
    InformationType:
      description: >
        Type of informational update:


        - CREATED : Entity has been created by supplier (unsolicited cease)

        - ACKNOWLEDGED : Supplier has acknowledged receipt (KCI1)

        - COMMITTED : Supplier has committed to fulfillment (KCI2)

        - DELAY : There is a problem causing a delay

        - RESUMED : The problem causing the delay has been resolved without
        impact on target date

        - REAPPOINTED : Supplier has re-appointed (if not suitable then treat as
        a REAPPOINT)

        - RESCHEDULED : Supplier makes an unsolicited change to the target date

        - ADDITIONAL : Supplier has flagged that additional information is
        available

        - RESUBMIT : The tenant needs to resubmit

        - WARNING : Supplier has flagged a warning

        - UPDATE : Supplier has made a generic update not covered by other types

        - AMENDED : Supplier has accepted and applied the requested amendment

        - CANCELLED : Supplier has accepted and applied the requested
        cancellation

        - TERMINATED : Supplier has terminated this request without fulfilling
        it

        - COMPLETED : Supplier has completed the request (KCI3)
      type: string
      enum:
        - CREATED
        - ACKNOWLEDGED
        - COMMITTED
        - DELAY
        - RESUMED
        - REAPPOINTED
        - RESCHEDULED
        - ADDITIONAL
        - RESUBMIT
        - WARNING
        - UPDATE
        - AMENDED
        - CANCELLED
        - TERMINATED
        - COMPLETED
    ActionType:
      description: >
        Type of action required from the tenant for this update:


        - INFORMATION_REQUIRED : Supplier requires additional information from
        the tenant

        - REAPPOINT : Supplier requires the tenant to re-appoint

        - RESUBMIT : Supplier requires the tenant to resubmit the request as it
        failed

        - CONFIRM : Supplier has resolved the request and is awaiting acceptance
        or rejection

        - 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:
        - INFORMATION_REQUIRED
        - REAPPOINT
        - RESUBMIT
        - CONFIRM
        - CONTACT_CUSTOMER
        - CONTACT_REAPPOINT
    ModifyAction:
      description: >
        Action required for modifying a service characteristic - where
        supported/required by the supplier.


        - ADD : Add or replace (where supported) a service characteristic with
        this new value

        - DELETE : Remove this service characteristic

        - NONE : No change to this service characteristic - provided for
        information only
      type: string
      enum:
        - ADD
        - DELETE
        - NONE
    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.
      type: string
      enum:
        - RECEIVED_BY_GATEWAY
        - SENT_TO_SUPPLIER
        - FAILED_TO_SEND
        - REJECTED
        - ACKNOWLEDGED
        - IN_PROGRESS
        - PENDING
        - HELD
        - PENDING_AMENDMENT
        - PENDING_CANCELLATION
        - CANCELLED
        - FAILED
        - PARTIAL
        - COMPLETED
      example: PENDING_CANCELLATION
    RequestStatus:
      description: State model for amendment and cancellation requests.
      type: string
      enum:
        - RECEIVED_BY_GATEWAY
        - PENDING
        - FAILED_TO_SEND
        - COMPLETED
        - REJECTED
      example: REJECTED
    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:
        - RECEIVED_BY_GATEWAY
        - SENT_TO_SUPPLIER
        - FAILED_TO_SEND
        - REJECTED
        - IN_PROGRESS
        - FAILED
        - COMPLETED
      example: IN_PROGRESS
    ProblemStatus:
      description: >-
        Service problem lifecycle adapted from TMF656 - update events (KCIs)
        will be sent to the tenant as the service problem transitions from one
        state to the other.
      type: string
      enum:
        - RECEIVED_BY_GATEWAY
        - SENT_TO_SUPPLIER
        - FAILED_TO_SEND
        - REJECTED
        - ACKNOWLEDGED
        - IN_PROGRESS
        - PENDING
        - HELD
        - NETWORK_INCIDENT
        - PENDING_AMENDMENT
        - PENDING_CANCELLATION
        - CANCELLED
        - RESOLVED
        - COMPLETED
      example: ACKNOWLEDGED
    ServiceProblemResolutionStatus:
      description: State model for service problem resolution.
      type: string
      enum:
        - PENDING
        - REJECTED
        - ACCEPTED
      example: REJECTED
    ProvideOrderType:
      description: The type of order - new, (re)start, takeover, transfer or swap
      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'
    Timeslot:
      description: Represents a new appointment timeslot by the supplier.
      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'
    ProblemCode:
      description: >
        Code representing problem - these may be sent as informational or action
        required updates

        depending on whether the tenant is required to resolve the problem.


        - 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

        - NOT_IMPLEMENTED

        - NO_LONGER_REQUIRED

        - OTHER

        - PARTIAL_INSTALL

        - PLANNING_ISSUE

        - PROPERTY_UNOCCUPIED

        - REJECTION

        - ROUTER_NOT_AVAILABLE

        - SITE_UNSAFE

        - SURVEY_REQUIRED

        - TELECARE_ISSUE

        - TIMED_OUT

        - UNABLE_TO_ATTEND

        - UNKNOWN_FAULT

        - WAYLEAVE_ISSUE
      type: string
      pattern: ^[A-Z_]{5,30}$
      example: NETWORK_ISSUE
    CancellationReasonCode:
      description: |
        Code representing reason for cancellation

        - COST_ISSUE
        - CUSTOMER_CHANGED_MIND
        - INSTALL_FAILED
        - NETWORK_ISSUE
        - NO_LONGER_REQUIRED
        - PROBLEM_WITH_ORDER
        - OTHER
      type: string
      pattern: ^[A-Z_]{5,30}$
      example: CUSTOMER_CHANGED_MIND
    ServiceProblemCancellationReasonCode:
      description: |
        Codes representing reason for cancellation of the service problem:

        - ISSUE_RESOLVED
        - CUSTOMER_NETWORK_ISSUE
        - NO_LONGER_REQUIRED
        - OTHER
      type: string
      pattern: ^[A-Z_]{5,50}
      example: CUSTOMER_NETWORK_ISSUE
    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_]{5,30}$
        example: TEST_SINGLE_DEVICE
    SiteRole:
      description: The role of the site in an Ethernet connection
      type: string
      enum:
        - A-END
        - B-END
        - MULTI-POINT
    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
      pattern: ^[A-Z_]{5,30}$
      example: CHANGE_OF_CP
    ProvideOrderEntityType:
      description: >-
        The primary entity type this KCI regards (will be supplied in entity
        field) - provide service order
      type: string
      enum:
        - PROVIDE_ORDER
    CeaseOrderEntityType:
      description: >-
        The primary entity type this KCI regards (will be supplied in entity
        field) - cease order
      type: string
      enum:
        - CEASE_ORDER
    ModifyOrderEntityType:
      description: >-
        The primary entity type this KCI regards (will be supplied in entity
        field) - modify order
      type: string
      enum:
        - MODIFY_ORDER
    UnsolicitedCeaseOrderEntityType:
      description: >-
        The primary entity type this KCI regards (will be supplied in entity
        field) - unsolicited cease order
      type: string
      enum:
        - UNSOLICITED_CEASE_ORDER
    ProvideEthernetOrderEntityType:
      description: >-
        The primary entity type this KCI regards (will be supplied in entity
        field) - provide ethernet order
      type: string
      enum:
        - PROVIDE_ETHERNET_ORDER
    ServiceTestEntityType:
      description: >-
        The primary entity type this KCI regards (will be supplied in entity
        field) - service test
      type: string
      enum:
        - SERVICE_TEST
    ServiceProblemEntityType:
      description: >-
        The primary entity type this KCI regards (will be supplied in entity
        field) - service problem
      type: string
      enum:
        - SERVICE_PROBLEM
    EntityType:
      description: >
        The primary entity type this KCI regards (will be supplied in entity
        field).
      anyOf:
        - $ref: '#/components/schemas/ProvideOrderEntityType'
        - $ref: '#/components/schemas/CeaseOrderEntityType'
        - $ref: '#/components/schemas/ModifyOrderEntityType'
        - $ref: '#/components/schemas/UnsolicitedCeaseOrderEntityType'
        - $ref: '#/components/schemas/ProvideEthernetOrderEntityType'
        - $ref: '#/components/schemas/ServiceTestEntityType'
        - $ref: '#/components/schemas/ServiceProblemEntityType'
    ErrorCode:
      description: Fibre Cafe error codes
      type: string
      enum:
        - GATEWAY_FAULT
        - INVALID_REQUEST
        - MALFORMED_REQUEST
        - NOT_AUTHORISED
        - NOT_FOUND
        - NOT_IMPLEMENTED
        - SUPPLIER_FAULT
        - SUPPLIER_TIMED_OUT
        - TENANT_FAULT
  securitySchemes:
    oauth2:
      description: >
        The Fibre Cafe can support a number of different authentication
        mechanisms e.g. OAuth2, Mutual TLS, Basic Auth.

        We recommend the industry standard [OAuth 2.0
        protocol](https://oauth.net/2/) client credentials flow where possible.
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /token
          scopes: {}
