Service availability is the typical entry point for tenants to begin ordering from suppliers. This determines:
- Can the supplier provide service at this address?
- What can be ordered?
First, refer to Service Availability to get an understanding of concepts such as service specifications and line profiles, and then review the Supplier API specification for Service Availability using the Supplier API menu at the top of this page.
The key sections are:
serviceSpecifications - what service is available e.g. FTTP and what speeds (line profiles). You will need to determine what these are (e.g. product id, code or name) to allow tenants to select an appropriate product/service in the order:
"serviceSpecifications": [
{
"id": "FTTP",
"serviceCharacteristics": [
{
"name": "LINE_PROFILE",
"values": [ .. ]
}
]
}
]siteInformation - what is available at the address. At a minimum you will need to state if a new line can be installed, if installation/engineer visit is required (presence of installationType dictates this) and any existing lines (active or not - and whether they need an engineer visit):
"siteInformation": {
"newLine": true,
"installationType": "STANDARD",
"existingLines": [
{
"ont": {
"ontReference": "ONT0000123123",
"ports": [
{
"portNumber": 1,
"status": "ACTIVE",
}
]
}
},
{
"installationType": "STANDARD",
"ont": {
"ontReference": "ONT0000789000",
"ports": [
{
"portNumber": 1,
"status": "STOPPED",
}
]
}
}
]
}Note: in the second existing line example, the presence of installationType indicates that an engineer visit would be required e.g. where the ONT is not responding. If the line can be started without an engineer visit then installationType should be omitted.
There are other fields that should be filled as appropriate/available e.g.
- Any constraints or LOCs that apply:
"constraints": [ … ],- Handover point information:
"enniId": "S1889",
"siteName": "string",
"siteLocation": "string",- ONT ancillary information:
"serialNumber": "1234567890",
"manufacturer": "Nokia",
"floor": "1",
"room": "Reception",
"position": "string",- ONT port information including indication that the port is in use by the current tenant:
"tenantActive": false,
"stoppedDate": "2022-01-01T13:45:00.000Z"- Additional line characteristics:
"lineCharacteristics": [ … ]If you cannot provide service it is expected that you populate unavailabilityReasons and do not return any serviceSpecifications (i.e. empty array).
"serviceSpecifications": [],
"unavailabilityReasons": [
{
"code": "NOT_PLANNED",
"text": "Outside coverage area"
}
]Refer to Appointing for more details - pay particular attention to date-time format to ensure timeslots are correct throughout the year.
Tenants will expect to be able to place new and existing line orders.
- New - install of a service to replace or add to existing service(s)
- Start - use an existing inactive service e.g. stopped ONT port
- Transfer - also known as a switch or migration - change of CP.
- Takeover - Working Line Takeover (WLTO) - customer change of address
- Modify - change an existing service e.g. line profile/speed change
- Cease - end an active service
Additionally, if applicable a swap order may be supported:
- Swap - change to an existing service requiring engineer visit
Refer to Service Characteristics for a full set of available characteristics that the tenant can send on the order. The supported characteristics should be listed on the onboarding template for tenants to later consume.
Common service characteristics sent on orders:
- LINE_PROFILE - line speed/product being ordered
- REMOTE_ID - remote identifier for authentication
- RETAILER_ID - end-party buying the service
- ONT_REFERENCE - reference to an existing service where appropriate
Note: RETAILER_ID is particularly important when the tenant is a reseller or wholesaler/aggregator.
Where supported, tenants can send Engineer Tasks to request additional work to be carried out in the engineer appointment.
When placing an order, the Fibre Cafe can handle synchronous or asynchronous responses to handle the older 2 stage order confirmation that BT/Openreach use or a single synchronous confirmation.
Returning 201 from the POST /orders endpoint will instruct the Fibre Cafe that the order has been validated and accepted. The returned order status will determine whether the order is ACKNOWLEDGED (KCI1) or COMMITTED (KCI2). The Fibre Cafe will send appropriate KCIs based on this.
If the order was ACKNOWLEDGED, the supplier will need to send the COMMITTED KCI once any pre-processing is complete and the order is now committed for delivery.
Returning 201 from the POST /orders endpoint will instruct the Fibre Cafe that the supplier will be taking care of KCIs. The supplier will need to send appropriate KCIs to acknowledge (KCI1) and commit (KCI2) the order.
KCIs (Keep Customer Informed) are updates about the progress of an order and must be sent to the Fibre Cafe Supplier Updates API.
More details of these updates are available along with full example KCIs. It is mandatory to send some service characteristics before an order completes e.g. SERVICE_ID.
You can view the OpenAPI description for Supplier Updates API using the Supplier API menu at the top of this page. There are payload examples provided for a range of different programming languages/tools and the ability to download the OpenAPI schema.
For testing purposes, a test tenant can be created so that you can check end-to-end requests via the Fibre Cafe to your API - i.e. as if you are a tenant of the Fibre Cafe ordering your service. To receive KCIs, you can either use the Tenant API GET endpoint to receive the order and KCIs - or optionally create a simple KCI receiver.
The appropriate API to implement in this case is the Tenant Updates API. You can download the OpenAPI schema using the Tenants API menu at the top of the page and load into tools such as Postman or Swagger Editor to create a simple mock server implementation for the Tenants Updates API.
Now refer to Supplier Onboarding for test scenarios and sign off details.