CityFibre

CityFibre have an existing SOAP API using a subset of NICC ALA standards ND1649 and ND1651 : https://ala-api.docs.cityfibre.com.

The Fibre Cafe has a connector to integrate with this API.

CityFibre Connector (Tenant API 1.11 / Tenant Updates API 1.9)

Regrade Orders

The new order type of 'SWAP' has been added to the connector to support regrade orders as now supported by the CityFibre API. This allows for changes to the underlying service specification (product). These orders are placed in the same way as other provide orders but with the existing service ID provided and orderType set to SWAP.

Service Availability

In line with the general improvement for service availability, when returning service specifications (products in CityFibre terminology) for an address, the available line profiles that can be used for service orders of that type will be returned in the 'serviceCharacteristics' field. e.g.

Copy
Copied
"serviceSpecifications": [
  {
    "id": "ftthl2r",
    "serviceCharacteristics": [
      {
        "name": "LINE_PROFILE",
        "values": [
          "1",
          "2"
        ]
      }
    ]
  }
]

CityFibre Connector (Tenant API 1.7 / Tenant Updates API 1.5)

The connector has been updated to support the latest changes in the Tenant and Tenant Updates API. The changes are detailed below. To update to use this connector version, please contact us.

Changes in this version are identified below.

Address Search

This is not supported by this connector.

Service Availability

The line field within siteInformation is now only used to indicate that a new line can be installed (the type field has been deprecated and will be removed in a future update). Where the line field is not present then this means that the property is at capacity and only an existing line can be taken over.

Existing line information is now returned separately in the existingLines field - CityFibre do not yet expose detail other than a PROPERTYATCAPACITY code. This will now be mapped to an existing line with a dummy placeholder for the ONT reference/port pending CityFibre providing this information.

New line can be installed:

Copy
Copied
{
  "siteInformation": {
    "line": {
      "installationType": "STANDARD",
      "constraints": [
        {
          "code": "WAYLEAVE_SHARED",
          "text": "string"
        }
      ]
    }
  }
}

Existing line can be taken over/transferred:

Copy
Copied
{
  "siteInformation": {
    "existingLines": [
      {
        "installationType": "STANDARD",
        "ontReference": "ONT0000000000",
        "ports": [
          {
            "portNumber": 1,
            "status": "ACTIVE"
          }
        ]
      }
    ]
  }
}

The CityFibre connector will only return fibre lines so lineType should be considered 'FIBRE'.

ENNI and site name/location are not provided as before - other new elements such as tenantActive, productType and lineCharacteristics are also not provided by the CityFibre API.

Note that the presence of the installationType field implies that an appointment is required - where this is not present then the order can be placed un-appointed with a requestedCompletionDate.

Appointment Management

No changes

Order Management

Note: these API versions introduce the following changes that are not used by this connector:

  • The action field when modifying service characteristics in a Modify order.
  • The serviceCharacteristics array in a Cease order.

If these values are supplied then the connector will disregard them.

Order Updates

Supplier Notes

Currently, any notes returned from CityFibre in KCIs are appended to the string based notes field submitted in the order. These have now been separated into a new supplierNotes field on the KCI. This is an array of notes that will only be populated where CityFibre attached notes to that particular KCI.

Copy
Copied
{
  "entity": {},
  "supplierNotes": [
    {
      "note": "Lorem ipsum dolor sit amet...",
      "created": "2023-01-01T09:00:00.001Z"
    }
  ],
  "information": {}
}

Unsolicited reappoints

CityFibre may on occasion re-appoint the order themselves rather than request the tenant reappoints via an ACTION_REQUIRED : REAPPOINT KCI. This may be after direct discussion with the end customer.

In this scenario, this will come through as an unsolicited reappoint: INFORMATIONAL : REAPPOINTED.

The following fields will be in populated within the KCI order:

Copy
Copied
{
  "entity": {
    "appointmentSupplierReference": "123456543",
    "appointmentTimeslot": {
      "timeslotStartDateTime": "2022-01-10T08:00:00.000Z",
      "timeslotEndDateTime": "2022-01-10T13:00:00.000Z"
    }
  },
  "information": {
    "type": "REAPPOINTED"
  }
}
  • appointmentSupplierReference - new appointment reference from the supplier
  • appointmentTimeslot - new appointment timeslot

If this is not suitable then it can be treated as a REAPPOINT.

New Informational Types

Some KCIs that previously had an informational type of UPDATE will now have further context and come through as described below:

  • CREATED : Indicates that CityFibre has created a new order - see Unsolicited Ceases below.
  • ACKNOWLEDGED : Indicates that the order has been ACKNOWLEDGED
  • RESUMED : The problem causing the delay has been resolved without impact on target date.
  • ADDITIONAL : CityFibre has updated the order - this indicates that additional information is available.
  • WARNING : CityFibre has updated the order and flagged a warning but not introduced a delay.
  • TERMINATED : CityFibre has not fulfilled the order and indicated it has failed/cancelled - terminal.
  • COMPLETED : CityFibre has completed the order (KCI3 milestone).

The intention behind these new types is to allow actions to be taken without having to also inspect the payload. For example, previously a completed order would have been sent as a generic UPDATE KCI and the order status would have to be checked to discover the order complete milestone has been reached (KCI3). This will now be sent with the type of COMPLETED (order status will still be set as appropriate as well).

The ADDITIONAL informational type is used where CityFibre provide more information, for example, they have provided the SERVICE_ID service characteristic in this KCI. WARNING is used where CityFibre send a warning without a delay. For example, a survey is required but is not anticipated to cause any delay at this point. A code will usually be provided to categorise the warning in the same way as a delay.

Unsolicited Ceases

CityFibre have now implemented Gaining Provider-Led Switching and will create a Cease order on behalf of the losing provider, sending the "Unsolicited Cease" as a KCI. CityFibre will also send an "Unsolicited Cease" during a product regrade order.

CityFibre do not currently provide the reason for the unsolicited cease - it will default to CHANGE_OF_CP. Hence, there will be no indication if the unsolicited cease is due to working line takeover.

An initial KCI will be sent once the unsolicited cease has been received - at this point CityFibre consider the cease as "pending". The initial KCI will have the informational type of CREATED and will contain the new order with a generated order ID. A further KCI will then follow to acknowledge the cease and a further KCI for committed as per the usual order flow. Once the switch is complete, a final completed KCI will be sent.

Example of an initial unsolicited cease (some metadata fields omitted for brevity):

Copy
Copied
{
  "id": "3456cf7d-4471-42e4-a5be-c24ed58a7aa6",
  "updateType": "INFORMATIONAL",
  "entityType": "UNSOLICITED_CEASE_ORDER",
  "entity": {
    "id": "1234567",
    "orderType": "UNSOLICITED_CEASE",
    "supplier": "CITYFIBRE",
    "supplierOrderNumber": "CFH123456543",
    "reason": "CHANGE_OF_CP",
    "serviceId": "SI2345432345345",
    "status": "RECEIVED_BY_GATEWAY",
    "requestedCeaseDate": "2024-01-01T09:09:33.001Z"
  },
  "information": {
    "type": "CREATED"
  }
}

Amendment requests are not permitted for an inflight unsolicited cease.

Cancel requests under the specific reason codes covered in the main Unsolicited Cease documentation are permitted.

Switching

To prepare for Ofcom One Touch Switch, CityFibre have implemented both Gaining and Losing Provider Led Switching. Full details of these including sequence diagrams are available on the CityFibre documentation and will not be reproduced here. These should be studied alongside this connector documentation to understand the process and any differences.

More information on switching with the Fibre Cafe API is available here. Note that the CityFibre API does not currently differentiate between the different order types but an appropriate order type should still be provided so that any future updates to the API will be supported. UPDATE: CityFibre will support the different switch/takeover order types from July 2024.

Problem Codes

CityFibre have introduced new delay and warning codes - mappings have been updated to cater for these - refer to the problem code matrix for the full set. Where both a delay and warning code is provided, the warning code will take precedence. A future update is coming shortly to allow both to be exposed along with the new "next best action" information.

CityFibre Connector (Tenant API 1.3 / Tenant Updates API 1.2)

The initial connector was created for use with the Tenant API version 1.3 and the Tenant Updates API version 1.2

Authentication

HTTPS client certificate at tenant level.

Service Availability

Address information is provided.

Site information is provided for NEW lines where a service can be provided. CityFibre currently make no distinction between where the service is already installed, active or not. This means that there could be an active service with another provider and the transfer/migration is hidden from the tenant. Existing lines are not currently populated.

CityFibre return RFS (Ready For Service) status codes to determine whether a property can have a service installed or not. The NOT_RFS_* codes and RFS_0 are mapped to appropriate UnavailabilityReasons.

All 3 levels of installation types are used depending on the CityFibre LOC (limit of construction) code provided:

  • EXTENDED_STANDARD : WSD | SUR
  • NON_STANDARD : MDU | UEL | UST
  • STANDARD (otherwise)

Availability constraints are mapped from LOC codes and provided as appropriate.

  • SURVEY_REQUIRED : SUR
  • BUSINESS_PARK : BP
  • FEASIBILITY_CHECK : FCK
  • WAYLEAVE_OWNER : WAY
  • WAYLEAVE_SHARED : WSD
  • WAYLEAVE_PRIVATE : PRRD
  • WAYLEAVE_UNADOPTED : ADRD
  • WAYLEAVE_REFUSED : WREF
  • UNECONOMIC_LENGTH : UEL
  • UNECONOMIC_SURFACE : UST
  • OTHER (otherwise)

Details of the full set of RFS and LOC codes are available on the CityFibre API documentation: https://ala-api.docs.cityfibre.com/#section/Reference

Service ready date is provided.

ENNI and site name/location are not provided.

Appointing

CityFibre have the following timeslots for appointments:

  • Mon-Fri 0800-1300
  • Mon-Fri 1300-1800
  • Sat 0800-1300
  • Sat 1300-1800

Orders

The following service characteristics are required when placing orders (with original CityFibre mapped name):

  • AUTHENTICATION_AGENT (CityFibre API: pppoeIntermediateAgent | l2DhcpRelayAgent)
  • REMOTE_ID (CityFibre API: aucRemoteId)
  • LINE_PROFILE (CityFibre API: lineProfile)

Line profiles are mapped on a 1 to 1 basis to CityFibre line profiles - available values will vary according the tenant to supplier agreement.

The following engineer tasks are available (with original CityFibre mapped code):

  • INSTALL_ROUTER (CityFibre API: CPEInst1)
  • TEST _ SINGLE _ DEVICE (CityFibre API: ResSingDev)
  • TEST _ MULTIPLE _ DEVICES (CityFibre API: ResThreeDev)
  • INSTALL_BBU (CityFibre API: ResBBU1)

Note: The CityFibre API does not have a generic "notes" field so only hazards and onSiteRestrictions fields are populated on orders. Any text in the notes field will not be sent to CityFibre.

Modify orders allow the following characteristics to be changed:

  • LINE_PROFILE
  • ENNI_ID
  • SERVICE _ VLAN _ ID
  • CUSTOMER _ VLAN _ ID

Amendment and cancellation requests can be made for inflight orders. There are limitations to what amendments can be done with the CityFibre API and only 1 item can be amended per request - a CR has been requested to improve this behaviour.

Order Updates

CityFibre share the terminology used by BT/Openreach for KCI milestones:

  • KCI1 - Order is acknowledged
  • KCI2 - Order is committed
  • KCI3 - Order is complete (or rejected)

Orders will initially enter a "pending" state prior to KCI1. Other KCIs are sent around these milestones and will have an appropriate sequence number.

CityFibre provide the following service characteristics in KCIs (with original CityFibre mapped name):

  • SERVICE_ID (CityFibre API: serviceIdentifier)
  • ENNI_ID (CityFibre API: nniIdentifier)
  • SERVICE _ VLAN _ ID (CityFibre API: nniSVlanId)
  • CUSTOMER _ VLAN _ ID (CityFibre API: nniCVlandId)

Where there is a delay or warning code, CityFibre provide numeric codes - these are mapped to an appropriate ProblemCode and returned in the supplierCode field. The full set of CityFibre problem codes and how they are mapped to Fibre Cafe codes is available in this matrix.

Note: where CityFibre provide both a delay and warning code, the warning code takes precedence.