Openreach B2B Connector Guide

Openreach offers a B2B XML gateway for access to all products and technologies including FTTP and SOGEA. The B2B gateway uses ebXML standards and The Fibre Cafe has a connector to integrate with this gateway.

Authentication & Setup

Authentication with the gateway is CPA/key based. To enable us to set up the connector, the following information is required:

• Buyer DUNS
• CPA XML file from Openreach (if applicable)

Address Lookup

Address lookup uses the Openreach address matching service to return the BT/Openreach address identifiers (NAD key and District Code) which are used when sending requests to their gateway. It supports searching by UPRN and postal code/partial address.

The various identifiers are encapsulated into an AddressIdentifier object allowing a single request to contain all identifiers required by different suppliers.

For example:

{
  "identifier": {
    "id": "10091846447",
    "type": "UPRN",
    "additionalIdentifiers": [
      {
        "id": "A15104646284",
        "type": "NAD"
      },
      {
        "id": "LS",
        "type": "DistrictCode"
      }
    ]
  }
}

If a NAD key and District Code are already known, these can be provided directly to the other APIs without needing to perform an address lookup first. The order of identifiers in the AddressIdentifier object is not important.

Service Availability

The connector provides comprehensive service availability information including:

• Service specifications and existing line information including ONT information
• Available line profiles for each service type
• Additional line characteristics including minimum/maximum speeds
• Installation information and availability dates

Service Specifications

When returning service specifications (product family/access technology) for an address, the available line profiles are returned in the 'serviceCharacteristics' field:

"serviceSpecifications": [
  {
    "id": "FTTP",
    "name": "FTTP", 
    "serviceCharacteristics": [
      {
        "name": "LINE_PROFILE",
        "values": [
          "1",
          "2"
        ]
      }
    ]
  }
]

Only FTTP is supported in the initial release - SOGEA and SOTAP support is planned for a future release.

Line Characteristics

The 'lineCharacteristics' field for new or existing lines includes characteristics as defined on the line characteristics page:

"line": {
  ...
  "lineCharacteristics": [
    {
      "name": "MAX_DOWNSTREAM_MBPS", 
      "value": "1000"
    }
  ]
}

This includes minimum and maximum downstream/upstream speeds (where supplied), availability date and minimum lead time where returned.

Installation Types

Openreach supports 1 or 2 stage installations (the latter also known as 'KCI2 Assure'):

• STANDARD : When a standard appointment is necessary
• EXTENDED_STANDARD : 2 stage installation 'KCI2 Assure'; refer to corresponding INSTALL_NOTES line characteristic for details

Where installationType is not returned, an appointment is not required in the order. Note that this may change as the order progresses and an appointment may be required later - handled using the standard REAPPOINT/REAPPOINTED KCIs.

Existing Lines

For FTTP services, existing ONT information includes:

• ONT Reference
• ONT Location (Floor/Room/Position)
• ONT Port Type and Status

For copper lines, existing line information includes:

• Line ID
• NTE Location (Floor/Room/Position)

Stopped date is provided for stopped copper services.

Appointing

When a managed install is required (e.g. for a new line or ONT), appointment timeslots can be listed and reserved.

• Timeslots are classified as weekday, saturday, sunday and AM/PM
• The default SITE_VISIT_REASON Standard will be used where not provided as a service characteristic
• A 'Premium' or 'Advanced' SITE_VISIT_REASON can be requested instead - this must be provided during appointment availability and reservation as well as in ordering

Orders

Service Characteristics

The following service characteristics are required when placing orders:

• LINE_PROFILE : See line profiles table below
• RETAILER_ID : Unique identifier for the retailer provided by OFCOM

The following service characteristics are required when placing orders where there are existing services:

• ONT_REFERENCE : Existing ONT reference for FTTP orders using an existing ONT
• LINE_ID : Existing access line identifier for copper orders (SOGEA/SOADSL) with an existing line

These characteristics are optional and will be valid depending on the order type:

• MINIMUM_SPEED : Requested guaranteed minimum speed (also known as realtime) - default is 0
• ECC_CHARGEBAND : Excess construction charges (FTTP) - see charge bands below
• TRC_CHARGEBAND : Time related charges (Copper) - see charge bands below
• CARE_LEVEL : See care levels table below
• SITE_VISIT_REASON : See site visit reasons below
• COMPANY_NAME : Only applicable for Copper (SOGEA/SOADSL) orders
• PROJECT_REFERENCE : Applicable for Copper and FTTP provide journeys with Advanced SITE_VISIT_REASON
• ONT_FLOOR : ONT floor location for FTTP orders
• ONT_ROOM : ONT room location for FTTP orders
• ONT_POSITION : ONT position location for FTTP orders
• NTE_FLOOR : NTE floor location for Copper (SOGEA/SOADSL) orders
• NTE_ROOM : NTE room location for Copper (SOGEA/SOADSL) orders
• NTE_POSITION : NTE position location for Copper (SOGEA/SOADSL) orders

Line Profiles

A LINE_PROFILE characteristic is required for Openreach orders. Line profiles map to downstream/upstream speeds as follows:

Excess Construction Charges (ECC)

Charge bands to support extra construction charges - also known as upper cost bands for SOGEA/SOADSL services. The default charge band where not provided is '0' (£0).

Care Levels

The default care level for FTTP orders is Level 2.

Site Visit Reasons

The default site visit reason for appointments and appointed orders is 'Standard'; for unappointed orders is 'No site visit'.

Order Amendments

Amendment and cancellation requests can be made for inflight orders. The following amendments are permitted:

• Change appointment
• Update contact details
• Update order notes
• Change to ECC_CHARGEBAND or TRC_CHARGEBAND characteristics
• Change to SITE VISIT REASON e.g. to 'Premium' or 'Prove Telecare'

Where an order amendment is placed, Openreach require additional information in the form of amendment reasons. This includes pre-pone/expedite where the appointment is moved earlier, re-appoint reasons and authorisation for ECC. This is handled automatically where possible by the Fibre Cafe but some intervention may be required depending on the scenario.

Order Updates

Order updates (also known as KCIs or KSUs) are received from Openreach and processed by the connector to update order status and information - the KCIs automatically forwarded to the tenant.

Information and Action Types

KCIs are categorised by then connector and sent with an appropriate action or information type according to the supplier code and KCI content.

The connector supports 'Next Best Action' types 'CONTACTCUSTOMER' and 'CONTACTREAPPOINT' to guide tenants on the best action to take where orders require manual intervention:

• CONTACT_CUSTOMER : Customer contact required to continue order or cancel order
• CONTACT_REAPPOINT : Customer declined, wayleave issue or access/safety issue to be resolved ahead of new appointment

Supplier Codes

The connector returns the codes provided by Openreach in the KCIs. In some scenarios, a single KCI from Openreach may be split into multiple KCIs by the Fibre Cafe, but where a single KCI is sent, all supplier codes will be returned in the supplierCodes array:

"supplierCodes": [
  "510", "2001"
]

Service and Line IDs

Openreach provides the SERVICE_ID and ONT_REFERENCE in a service characteristic before the order completes:

{
  "entity": {
    "serviceOrderItem": {
      "serviceCharacteristics": [
        {
          "name": "SERVICE_ID",
          "value": "BBEU12345678"
        }
      ]
    }
  }
}

Supplier Notes

Supplier notes are attached to KCIs as received from Openreach (free text):

{
  "entity": {
    "supplierNotes": [
      {
        "note": "Lorem ipsum dolor sit amet...",
        "type": "Site Visit Notes", 
        "created": "2024-05-21T17:02:19.652Z"
      }
    ],
    "information": {
      "type": "ADDITIONAL",
      "text": "Adhoc Note to CP",
      "supplierCode": "550"
    }
  }
}

Unsolicited Ceases

Unsolicited ceases are used by Openreach and will be sent as an unsolicited cease KCI. An initial CREATED KCI will be sent once the gateway has received the unsolicited cease, followed by an acknowledged KCI and further KCIs as per the usual order flow. Once the switch is complete, a final completed KCI will be sent.

Example initial KCI for an unsolicited cease:

{
  "id": "12f59a1e-6911-478c-ad5f-12592752990a",
  "updateType": "INFORMATIONAL", 
  "entityType": "UNSOLICITED_CEASE_ORDER",
  "entity": {
    "id": "1234567",
    "orderType": "UNSOLICITED_CEASE",
    "supplier": "OPENREACH",
    "supplierOrderNumber": "1-1124746841144665030934",
    "reason": "CHANGE_OF_CP",
    "serviceId": "BBEU12345678", 
    "status": "RECEIVED_BY_GATEWAY",
    "requestedCeaseDate": "2024-01-01T09:09:33.001Z"
  },
  "information": {
    "type": "CREATED"
  }
}

Unsolicited Reappoints

Openreach may occasionally re-appoint orders themselves rather than request the tenant reappoints via an ACTION_REQUIRED : REAPPOINT KCI. This comes through as an unsolicited reappoint: INFORMATIONAL : REAPPOINTED.

The following fields will be populated within the KCI order to show the new appointment details:

{
  "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 Openreach
• appointmentTimeslot : New appointment timeslot

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

Version History

Tenant API 1.15 / Tenant Updates API 1.13

• Initial connector release for Openreach