Introduction

This API is a subset of NICC ALA standards ND1649 and ND1651, available from https://www.niccstandards.org.uk/publications/.

For clarity, the SOAP envelope is omitted from the remainder of the documentation. It should be noted that this is just SOAP delivery of XML messages, and is not a "web service" with WSDL.

In NICC terminology, the Active Network Operator who provides the service is the "seller", and the Service Provider who consumes the service is the "buyer".

Custom attributes are added using the XML namespace URL http://www.cityfibre.com/ala/ext1.

Messages are exchanged using SOAP exchanges over HTTPS POST, where the request is in the POST body and the response is in the HTTP response body. As per ND1651 section 14.2, messages are encapsulated in a SOAP envelope using Document/Literal style following WS-Basic Profile 1.0.

notifyOfOrderStatus messages are HTTPS POSTed to the buyer when available, at a pre-agreed callback URL.

The schema can be located here, with examples of the various messages located in the examples directory of this documentation pack. You can also find more detailed reading and examples in “Order Error Handling in ND1651 API Testing Approach” document which can also be found in this directory along with the New ISP Onboarding Test Scenario Verification.xlsx

An example of SOAP usage can be seen below:

Authentication

Authentication is by means of HTTPS client certificate. It is also restricted to pre-agreed source IP addresses.

Network and Firewall Configuration

Cityfibre provides two fixed-address API endpoints for redundancy:

Messages may be POSTed to either of these. For convenience there is also a round-robin DNS entry: api-gw.cityfibre.com (resolves to both addresses)

Required firewall configuration is as follows.

(1) For connectivity please refer to Customer API Connectivity

Data should be posted with Content-Type: text/xml. No SOAP-Action: header is required and it will be ignored if provided. All message types go to the same endpoint.

(2) For connections from Cityfibre to buyer: buyer must allow HTTPS inbound connections to buyer's systems from IP addresses 34.240.45.9 and 52.17.98.120, to whichever port their system accepts inbound connections on.

(If the buyer system allows IPv6 connectivity, then the source addresses will be from ranges 2a05:d018:9a3:b500::/56 and 2a05:d014:b31:f200::/56)

FTTP Process Overview

Customer and site information required for a Business Property

On creating an order, the Buyer must include as much information as possible about a site where Property Classification is Business or Other to ensure a successful installation. On creating an order, where necessary, a wayleave has been obtained, the install scope is under 15m externally and 10m internally on the ground floor, and two power sockets are available within 1m of the preferred location.

Name: Name of person available on-site on the day of installation who can provide internal access and has the authority to specify where the Optical Network Termination box will be located.

Email: Email address of the site contact specified above.

Phone number: Contact telephone number of the site contact for use on day of install.

Access Restrictions: Our install engineer will see what you enter here. Please advise things like: where can our van be safely parked, can you tell us alternative contact numbers for a keyholder other than the one above, for businesses, if the name above the door does not match our records; anything we need to be aware of on the day to achieve a successful entry.

If you know the preferred Optical Network Termination box location, please tell us.

Hazard Advice: If this is a commercial building built before 2000, please tell us where to find the asbestos register. If the building is not made of standard brick construction, please advise. If there is anything unusual, please tell us; a driveway laid with bespoke resin is just one example.

Project reference

Project references <cfh:projectReference> can be used to identify an order as being included in a particular project. A project reference, along with parameters of the project, will be pre-agreed between the Seller and the Buyer under a Formal Project Agreement. Parameters of the project will include a project name, start and end date, and any specific customer journey requirements.

If an invalid project reference is sent, or the project reference is sent outside of the start and end dates of the project, then the order will be rejected, and a 511 error code will be returned.

New Install

Availability Check

Query Address Search

To check the availability of a given location. The buyer should send a request containing either a postcode or a UPRN.

The seller is then going to respond with detailed information about the queried location. If the buyer queried using a UPRN, the response will contain only one location. On a postcode request, the seller might respond with multiple locations that match the given postcode.

The location details include among other fields:

• UPRN
• RFS (Ready For Service) status
• Cabinet Release Date
• LOC (Limit Of Construction) Codes
• Whether the order will be a preorder

LOC reasons are flags which indicate known issues with this property. If there are multiple flags for a location they will be separated by spaces.

An order can be accepted for any RFS_1, RFS_2, RFS_3 or RFS_4 property.

Furthermore, the seller can query products for a given location using the location’s UPRN.

Query Products for Location

The seller will then respond with a list of one or multiple available products (if any) along with information about the need for an appointment (yes/no/maybe). The response will be one of the below listed types:

Appointment

The buyer can query appointment availability, reserve an appointment and include the reservation key in the order request.

If this is not done, the order will go into a waiting state and not progress, the buyer will need to reserve an appointment and then amend the order to include the appointment reservation key before the order can complete.

Query Availability

Query Appointment Availability

The buyer can check the appointment availability by providing a UPRN and a product to the seller.

Then the seller may respond with an ‘Accepted’ response along with the available appointment slots.

Or if for some reason an appointment is not possible to book, the seller will respond with a ‘Rejected’ response and with the reason why there is no appointment availability for the given data.

Reserve

Reserve Appointment

In order to reserve an appointment, the buyer should provide the UPRN, product and the appointment slot that they desire to the seller.

The seller can then reply with a successful response if such appointment can be booked along with the appointment details and a reservation key.

Or with a rejected response if there was any issue with booking the appointment along with the reason why such thing is not possible.

Order Submission

The order is created using an orderRequest message containing an <alaNewInstall> element. The Service Provider can choose between PPPoE Intermediate Agent or Layer 2 DHCP Relay Agent for authentication. This is a legacy field and regardless of selection the Service Provider is able to provide services using either protocol. DHCP and PPPoE discovery frames are modified to insert circuit ID and remote ID to assist the Service Provider in authentication.

Create New Install Order

The Seller provides the ability to order services that are provisioned with VLAN 0 or VLAN 911. This is enabled by the Service Provider passing a Line Profile specific to either VLAN 0 or VLAN 911. The available Line Profiles for buyers to choose from are described in Line Profiles.

The seller will then reply with an empty order response to acknowledge that the order request was received

Updates are returned in the form of notifyOfOrderStatus messages. The sequence of order states is as per ND1649 section 5.1:

• Pending
• Acknowledged (KCI1)
• Committed (KCI2)
  • ENNI Reserved
  • Missed Appointment
  • Warning
  • Cabinet Slip
• Completed or Rejected (KCI3)
  • Rejected with Reason

Note: The ‘Cabinet Slip’ example refers to a case where:

• buyer has booked an appointment for date D1, which is on or after the cabinet release date D0
• but prior to service going live, the cabinet release date has slipped from D0 to D2, which is now after the appointment date
• hence seller has been forced to rebook the original appointment

Pre Orders

CityFibre will accept pre orders for locations where the cabinet release date is in the future, where DR status is DR3 or below and RFS status is NOT_RFS_2

The buyer can query appointments and reserve appointments beyond the cabinet release date.

Orders placed as pre order will return a delay after KCI 2

Should the cabinet release date slip, orders will be automatically reappointed and a new date provided post the new cabinet live date.

Regrades

The Buyer can specify an order is a Regrade using the newOrderType field, on an RFS_4 property.

The seller (CityFibre) will handle the cease of the existing service, KCI updates will be sent to the Buyer as well as an unsolicited cease request.

Regrade orders can be cancelled using Cancel an Order. Orders can also be amended (Line profile or Requested Date) on a regrade order.

Product Change – No Access Change

Product and Access Change

1. Buyer checks availability

   • Property RFS Status is returned from Sellers Availability Check
   • Property is not RFS_4 follow standard Order Journey detailed above
   • Property is RFS_4 and has a cease, follow LP WLTO
   • Property is RFS_4 and has no cease, follow regrade flow

2. Buyer submits order.

   • On creating an order, the buyer will pass the UPRN of the existing service along with the relevant order details including the product and profile. In addition, for a regrade the buyer will need to send a requested date with the new order instead of an appointment date.
   • Orders placed on the current day will be processed at midnight of the following day.
   • Order delayed if:
     • Buyer does not include Requested Date - Expires in 30 days
   • Order rejected if:
     • Buyer order reference is missing or duplicate
     • Buyer order reference exceeds the maximum length (36 characters)
     • UPRN is missing or not numeric
     • Product is the same as active service
     • Product is non-FTTH product
     • Product not permitted for this account or location
     • Gross errors in service configuration (invalid attributes or values)

3. KCI.1 Order Acknowledged issued to Buyer

4. KCI.2 Order Committed issued to Buyer

5. Seller sends unsolicited cease to buyer

6. Amendments are checked and either everything is accepted or rejected

   • Reject any amendment to product or UPRN
   • Accept amendments to site info
   • Accept amendments to Requested Date
   • Accept amendments to service configuration (e.g. ENNI, SVLAN/CVLAN, line profile, PPPoE Agent-Remote-Id): check for gross errors
   • Cancellation of auxiliary services: OK

7. Cease is completed at midnight of the requested date. (Usually this happens at 00:00 and is complete by 2am).

8. Provision ONT

9. Seller sends KCI.3

Amending

The buyer may request to amend an order if it is still in early stages.

Amend Order

The seller can then accept or reject the amendment of the order

Furthermore, notifyOfOrderStatus requests will reflect the amendment request

Cancellation

It is possible for the buyer to request that an order be cancelled before it is completed. Orders may also be cancelled by the seller if it is no longer possible to progress an order.

Buyer Cancellation

The buyer may request to cancel the order if it is still in early stages.

Cancel Order

The seller will then reply with the status of the cancellation

This will also reflect the notifyOfOrderStatus requests

Seller Cancellation

The seller may cancel the order if it is no longer possible to proceed. The buyer will retrieve a notifyOfOrderStatus.

Modify

Once a service has gone live, changing the line profile or requesting a change of ENNI/VLAN is done by means of an orderRequest <alaModify>. This follows the same overall flow as a new install order, but it may jump straight from Pending to Completed.

Modify Order

The available profiles for buyers to choose from when modifying an order are shown below. We should note that the API call name should be included as part of the call:

Modify ENNI

When an order is placed, the seller defines an ENNI for the order and provides the buyer with a list of available ENNIs via the notifyOfOrderStatus request.

Then the buyer can modify the ENNI by sending back one of the codes returned in the <cfh:nniIdentifiers> list.

Any further notifyOfOrderStatus requests will contain the new ENNI.

To modify the ENNI, the buyer should send a modify orderRequest

Modify Line Profile

In addition to changing the line profile, sellers also have the ability to modify the line profile of their active service. This can be achieved through the use of the orderRequest call. The process of modifying a line profile follows a similar flow to that of a new install order.

For the Buyer to initiate the modification of a line profile they can send the line profile in <cfh:lineProfile>.

Once the line profile modification is successfully processed, all subsequent notifyOfOrderStatus requests will contain the updated line profile information.

Cease

A cease order follows the same flow with an <alaCease> order.

Cease Order

The <alaCease> element might contain a <requestedDate> element. If it is absent, then the cease will take place immediately. Otherwise, it will occur at the timestamp provided.

The seller will then start sending notifyOfOrderStatusRequests similarly to the standard order flow:

• Pending
• Acknowledged
• Committed
• Completed

The buyer can also cancel the cease by sending a <cancelOrderRequest> before the <requestedDate> timestamp that was provided in the <alaCease> request.

Also, the buyer might also modify the <requestedDate> by sending an <amendOrderRequest>.

Lastly if the contract terms provide for a cease notice period, but the <requestedDate> is less than that time in the future, then the service will be charged for the whole cease notice period.

FTTH Installation Process Diagrams

A visual representation of the FTTH installation process can be found in the FTTH Install process as documented below

1. Order contains: Product; URPN; Site info (contact info, access restrictions, hazards); appointment reservation key; optional service configuration; optional auxiliary services

2. Reject order if:

   • Buyer order reference is missing or duplicate
   • Buyer order reference exceeds the maximum length (36 characters)
   • UPRN is missing or not numeric
   • Product is non-FTTH product
   • Product not permitted for this account or location
   • Auxiliary services not recognised, or not permitted with this product, or not permitted for this account
   • Gross errors in service configuration (invalid attributes or values)
   • Property type not FTTH
   • Property RFS_Status_GIS__c is not RFS_1 (or NOT_RFS_2 for preorder) - if there is an appointment this will have been checked
   • Appointment reservation key (if provided) is for wrong UPRN or wrong product or has expired

3. If the order contains an appointment key: check it is for the correct UPRN, reserve it and add service ID to it. If reservation key has expired, scrub the appointment from the order

   • If the property requires an Extended Install (LOC flags "WSD" or "SUR") then the KCI2 notification will include delay code 203 Survey underway, and a case is opened.

4. Check cabinet release date. If there is an appointment, and the CRD is later than the appointment, then cancel the appointment and notify of slip. If the cabinet is not yet ready for service, KCI2 includes delay code 210 "Waiting cabinet ready" and go back to Wait Cabinet Ready.

5. Check amendments and either accept everything or reject

   • Reject any amendment to product or UPRN - All amendments to site info are acceptable
   • Amendments to appointment: check new appointment is for correct UPRN, if so accept it (Note: does XML allow removal of appointment without creation of new one?)
   • Amendments to service configuration (e.g. ENNI, SVLAN/CVLAN, line profile, PPPoE Agent-Remote-Id): check for gross errors
   • Amendments to auxiliary services: check new auxiliary services are valid for this product/account
   • Cancellation of auxiliary services: OK

6. a. Buyer cancel received: set Service state to Cancelled. Cancel the appointment reservation (if any). Terminate.

   b. Seller cancel: if the property is no longer serviceable, e.g. has gone to NOT_RFS_3. (Or should this raise a case instead?)

7. Perform network provisioning for selected ENNI/SVLAN/CVLAN. (If it fails we could raise a case, or just go into exception for now)

8. If the order does not have an appointment, send notify "delayed - waiting appointment" and go to Waiting appointment, otherwise proceed to issue job pack. If appointment date has passed, mark 'failed' and wait for reappointment

9. Wait for buyer to amend the order to add a new appointment or cancel. Timeout if no appointment received within 30 days.

10. Process amendments:

    • Reject any amendment to product or UPRN
    • All amendments to site info are acceptable
    • Amendments to appointment: check new appointment is for correct UPRN, if so accept it
    • Amendments to service configuration: check for gross errors.
    • Amendments to auxiliary services: check new auxiliary services are valid for this product/account
    • Cancellation of auxiliary services: OK

11. Issue the job pack to the installation partner

12. Waiting for response from installation partner. (We may also receive interim updates/notes during this time; ) 3 possible flows

    • If response is "success" go to Completed (WF0)
    • Depending on warning code go back to waiting for new appointment
    • Depending on warning code then open case, put in delay
    • If cancellation is received, then cancel the job with installation partner

13. Process amendments

    • Reject any amendment to product or UPRN
    • Amendments to site info: relay to installation partner (i.e. update installation job)
    • If change to appointment: cancel the job with installation partner, return to waiting for appointment (Note: does XML allow removal of appointment without creation of new one?)
    • Amendments/cancellations to auxiliary services: either reject, or update the job pack with installation partner

14. Update network provisioning (ENNI/SVAN/CVLAN/PPPoE/Line Profile) while waiting for installation

15. Perform ONT provisioning while waiting for installation

16. Waiting for case. Case closed successfully, go to waiting for new appointment; case cancelled, cancel order. Or we can receive cancel from buyer.

17. Notify completion; include warning if result no CPE or speedcheck failed.

Gaining Provider Led Switches (GPLS)

This process is for when an end customer wants to move from one Buyer (Losing Provider) to another Buyer (Gaining Provider) on the Sellers network. In this scenario the end customer has contacted the Gaining Provider first to initiate a Gaining Provider Led Switch process.

As a key principle for Gaining Provider Led Switch Orders, any amendments to install and cease dates will be aligned to ensure a smooth transition for the end customer.

Placing Gaining Provider Led Switch Orders

When placing an order on a property with an RFS Status of RFS_4, the Buyer must specify whether this is a Gaining Provider Led Switch Order, using newOrderType field with a value of “Switch”, this will ensure the correct journey is applied to the order, with the subsequent lead times. This does not apply for properties that have a RFS Status of RFS_1, RFS_2 or RFS_3.

If the newOrderType is not specified on an RFS_4 order, and the Buyer owns the existing service at the property, then the order will be treated as a Regrade order.

Gaining Provider Led Switch orders will default to a non-appointed provision, unless Install Options requiring an engineer installation are requested, or an ONT swap is required.

Lead times (Customer Requested Dates and Install Appointments)

Gaining Provider Led Switch orders have a next business day lead time that covers the NOT+ (Notice of Termination Plus) required lead time for requested date, or two business days for appointment date if managed install.

Customer Requested Dates should be sent with a Date only, if a specific time is also sent, this will be aligned to midnight of the same day.

Gaining Provider Led Switch Order Process

1. End Customer / Gaining Provider checks availability of product(s)

   • The Gaining Provider can query products for a given location using the location’s UPRN.

   • The seller will then respond with a list of the available products (if any) along with information about the need for an appointment (yes/no/maybe).

2. Customer Requests Appointment Date if Managed Install is Required

   • The Gaining Provider can check the appointment availability by providing a UPRN and a product to the seller.

   • Then the seller may respond with an "Accepted" response along with the available appointment slots. If an appointment is not possible to book, the seller will respond with a "Rejected" response and with the reason why there is no appointment availability for the given data.

3. Customer Reserves Desired Appointment

   • To reserve an appointment, the Gaining Provider should provide the UPRN, product and the appointment slot that they desire to the seller.

   • The seller will reply with a successful response if such appointment can be booked along with the appointment details and a reservation key. Or with a rejected response if there was any issue with booking the appointment along with the reason for the rejection.

4. Gaining Provider submits the Order Request

   • The order must be submitted with a newOrderType of "Switch" and either an Appointment Reservation Key for a Managed Install or a Customer Requested Date. Please ensure the correct lead times are applied, to ensure the order is not rejected.

5. Seller sends KCI Order "Pending" to Gaining Provider

6. Seller validates Order

   • If the order request cannot be fulfilled the Seller will send a KCI "Rejected"

   • Seller validates Reserved Appointment if one is provided

7. Plan & Manage Switch Request

   • Seller creates "New Install Order" for Gaining Provider

   • Seller creates the "Cease Order" on behalf of Losing Provider if there is no in-flight Cease Order.

   • Seller links the Cease Order from the Losing Provider and the New Install Order from the Gaining Provider

   • Where Seller identifies an In-flight Cease Order it will be aligned to New Install Order Requested Date

8. Seller creates Cease Order on behalf of Losing Provider

   • Seller sends KCI "Unsolicited Cease Request" to Losing Provider

   • Seller sends KCI Cease "Pending" to Losing Provider

   • Seller sends KCI1 Cease "Acknowledged" to Losing Provider

   • Seller sends KCI2 Cease "Committed" to Losing Provider

9. Seller sends KCI1 Order "Acknowledged" to Gaining Provider

10. Seller sends KCI2 Order "Committed" to Gaining Provider

11. Wait for "Switch" Date

    • This will either be the Customer Requested Date or the Appointment Date for a Managed Install Order

12. Cease Losing Provider Service

13. Send KCI3 Cease "Completed" to Losing Provider

14. Provision Gaining Provider Service

15. If managed Install, wait for confirmation of installation for Managed Install journey

16. Send KCI3 Order "Completed” to Gaining Provider

Cease of Existing Services

The Seller will handle the cease of the existing service, on behalf of the Losing Provider, for Switch orders. KCI updates will be sent to both Gaining Provider for the New Install Order and the Losing Provider for the Unsolicited Cease Order. Where a Cease Order is already in flight, the requested date will be aligned to the Gaining Provider New Install Order requested date.

When an Unsolicited Cease is sent to a Losing Provider, it will state that it is the result of a Switch.

If the Gaining Provider cancels the Switch Order, then the Unsolicited Cease will be automatically cancelled. Where there was already a Cease Order in flight this will not be cancelled.

Amendments to Gaining Provider Led Switch Orders

Amendments to Customer Requested Date, Appointment Date and Service Configuration can be submitted by the Gaining Provider and will be accepted and actioned up to the PONR of the business day before the install.

As a key principle for Gaining Provider Led Switches, any amendments to install and cease dates will be aligned to ensure a smooth transition for the end customer.

1. Gaining Provider submits Amend Order Request
2. Seller Responds with Amendment Pending
3. Validate Amend Request
4. If the amend request cannot be fulfilled the Seller will send KCI "Amendment Rejected" to Gaining Provider
5. Seller Processes the Amend Request
6. Seller sends KCI "Amendment Accepted" to Gaining Provider
7. If the Switch Date has been amended the Seller will send KCI "Amendment Accepted" to Losing Provider with the new date

Working Line Takeovers (WLTO)

This process covers when an end customer is moving home, and the property they are moving into already has an active service provisioned. In this scenario the end customer has contacted the Gaining Provider to request a new service.

Placing a Working Line Takeover Order

When placing an order on an RFS_4 property, the Buyer must specify whether this is a WLTO using newOrderType field, this will ensure the correct journey is applied to the order, with the subsequent lead times. This does not apply for RFS_1, RFS_2 or RFS_3.

If the newOrderType is not specified on an RFS_4 order, and the Buyer owns the existing service at the property, then it will be assumed as a Regrade order.

Working Line Takeover orders will default to a non-appointed provision, unless Install Options requiring an engineer installation are requested, or an ONT swap is required.

Lead times (Customer Requested Dates and Install Appointments)

Working Line Takeover orders have a 10 business day lead time that covers the NOT+ (Notice of Termination Plus) required lead time for requested date, or appointment date if managed install.

Working Line Takeover orders where the Gaining Provider is also the Losing provider, and owns the existing service = 2 days

Customer Requested Dates should be sent with a Date only, if a specific time is also sent, this will be aligned to midnight of the same day.

WLTO Order Process

1. End Customer / Gaining Provider checks availability of product(s)

   • The Gaining Provider can query products for a given location using the location’s UPRN.

   • The seller will then respond with a list of the available products (if any) along with information about the need for an appointment (yes/no/maybe).

2. Customer Requests Appointment Date if Managed Install is Required

   • The Gaining Provider can check the appointment availability by providing a UPRN and a product to the seller.

   • Then the seller may respond with an "Accepted" response along with the available appointment slots. If an appointment is not possible to book, the seller will respond with a "Rejected" response and with the reason why there is no appointment availability for the given data.

3. Customer Reserves Desired Appointment

   • To reserve an appointment, the Gaining Provider should provide the UPRN, product and the appointment slot that they desire to the seller.

   • The seller will reply with a successful response if such appointment can be booked along with the appointment details and a reservation key. Or with a rejected response if there was any issue with booking the appointment along with the reason for the rejection.

4. Gaining Provider submits the Order Request

   • The order will be submitted with a newOrderType of "WLTO" and either an Appointment Reservation Key for a Managed Install or a Customer Requested Date. Please ensure the correct lead times are applied, to ensure the order is not rejected.

5. Send KCI Order "Pending" to Gaining Provider

6. Validate Order

   • If the order request cannot be fulfilled the Seller will send a KCI "Rejected"

   • Seller validates Reserved Appointment if one is provided

7. Plan & Manage Switch Request

   • Seller creates "WLTO Order" for Gaining Provider

   • Seller creates the "Cease Order" on behalf of Losing Provider if there is no in-flight Cease Order.

   • Seller links the Cease Order from the Losing Provider and the WLTO Order from the Gaining Provider

   • Where Seller identifies an In-flight Cease Order it will be aligned to WLTO Order Requested Date

8. Seller creates Cease Order on behalf of Losing Provider

   • Seller sends KCI "Unsolicited Cease Request" to Losing Provider

   • Seller sends KCI Cease "Pending" to Losing Provider

   • Seller sends KCI1 Cease "Acknowledged" to Losing Provider

   • Seller sends KCI2 Cease "Committed" to Losing Provider

9. Seller sends KCI1 Order "Acknowledged" to Gaining Provider

10. Seller sends KCI2 Order "Committed" to Gaining Provider

11. Wait for "Cease Order" Date

    • This will either be the Customer Requested Date or the Appointment for the managed install date of the “WLTO Order”, or the Requested Date of the Cease Order where the Losing Provider has taken control.

12. Cease Losing Provider Service

13. Send KCI3 “Cease Order” Complete to the Losing Provider

14. Provision Gaining Provider Service

15. If managed Install, wait for confirmation of installation for Managed Install journey

16. Send KCI3 Order "Completed” to Gaining Provide

Cease of Existing Services

The Seller will handle the cease of the existing service, on behalf of the Losing Provider, for WLTO Orders. KCI updates will be sent to both Gaining Provider for the WLTO Order and the Losing Provider for the Unsolicited Cease Order. Where a Cease Order is already in flight, this will be linked to the WLTO Order, and where the WLTO Order Requested Date is before the Cease Order Requested Date, the WLTO Requested Date will be aligned to the Cease Order Requested Date.

When an Unsolicited Cease is sent to a Losing Provider, it will state that this is the result of a WLTO Order.

Where the Gaining Provider cancels the WLTO Order, then the Unsolicited Cease Order will be automatically cancelled. Where there was already a Cease Order in flight this will not be cancelled.

Unsolicited Cease

For an Unsolicited Cease related to a Working Line Takeover Order, a Cancel Other code can be used by the Losing Provider

‘9190 SP REQUESTED CANCEL OTHER - END USER NOT MOVING’.

Amendments to Working Line Takeovers Orders

Amendments to Customer Requested Date, Appointment Date and Service Configuration can be submitted by the Gaining Provider and will be actioned up to the PONR of the business day before the install.

As a key principle for Working Line Takeover Orders, where any amendments to install and cease dates are requested, the Install date must be on or after the Cease Date. A Losing Provider can take control of the Cease Date by amending the requested date of the Unsolicited Cease Order. Once the Losing Provider has taken control of the WLTO Order, the Gaining provider can still amend the Service Configuration and the Requested Date. Only amendments to Requested Date where the date requested is after the Losing Providers Requested Cease Date will be accepted.

Amendments to Working Line Takeovers Orders by the Gaining Provider Process

N.B. This process only represents changes to the Requested Date or Appointment Date where the WLTO Order has a Managed Install. Service Configuration related Amendments will be accepted up to the PONR.

1. Gaining Provider submits Amend Order Request

2. Validate Amend Request

   • If the amend request cannot be fulfilled the Seller will send KCI "Amendment Rejected" to Gaining Provider

3. Seller Responds with “Amend Requested Date / Amend Appointment Date” Pending

4. Where the Losing Provider “Has Control” of the WLTO Order Date

   • If the Amended Requested Date is after the Requested Cease Date the Amended Requested Date / Appointment Date is Accepted “Amend Requested Date / Appointment Date Accepted”

   • If the Amended Requested Date is before the Requested Cease Date the Amended Requested Date is Rejected “Amend Requested Date Rejected”

5. If the Losing Provider does not “Have Control”

   • Amend the Requested Date of the Cease Order to the Gaining Provider Amended Requested Date

   • Seller notifies the Losing Provider Requested Date Amended “GCP Amended Requested Date”

   • Seller notifies the Gaining Provider “Amend Requested Date / Appointment Date Accepted”

6. If Managed Install and amended Appointment Date is after the PONR, Amend Request is rejected “Amend Appointment Date Rejected”

Amendments to Working Line Takeovers Orders by the Losing Provider Process

1. Losing Provider submits Amend Cease Order Request

2. Seller validates the Amend Request

   • If the amend request cannot be fulfilled the Seller will send KCI "Amendment Rejected" to Losing Provider

3. Seller Responds with “Amend Requested Date” Pending

4. If the Amended Requested Date is before the WLTO Requested Date the Amended Requested Date is Accepted “Amend Requested Date / Appointment Date Accepted”

5. Where the Amended Requested Date is after the Requested WLTO Date

   • If the WLTO Order is not Managed Install, the Amended Requested Date is Accepted “LCP Amended Requested Date”

   • If the WLTO Order is Managed Install and after PONR, the Amended Requested Date is Rejected “Amend Requested Date Rejected” to Losing Provider

   • If the WLTO Order is Managed Install and after PONR, delay WLTO Order and send Delay Reappoint notification “LCP Amended Requested Date” to Gaining Provider

   • Manage Reappointment with Gaining Provider

6. Update Losing Provider Amended Requested Date

7. Notify Amend Requested Date Accepted

8. Losing Provider now “Has Control” for the WLTO Order Date

One Touch Switch

In support of the One Touch Switch launch in October, the seller will make the below changes.

• Removal of 10 day lead time on non-appointed switches

• Ability for losing provider to cancel an unsolicited switch on a cease

Additional information about the ONT installed at the property will be returned in QueryInstallation, this will include the ONT Identifier (serial number) and the ONT port.

Remote Activation

RFS_3 properties are eligible for non-appointed remote activations. If the Buyer does not wish to include any auxiliary products (i.e. CPE Install), then a non-appointed activation can be ordered, for next working day onwards.

If the RFS_3 property requires an ONT Swap or CPE Install, then this will require an appointment, and the standard lead times will be applied.

ONT Swaps

If the product being ordered requires a higher bandwidth than the current ONT supports, then an engineer appointment may be required to change the ONT installed at the property.

When querying for products at a property with an installed ONT(RFS_3 or RFS_4) we will perform a check of the ONT type that is currently installed against the products that are available to check if the products that are being returned will support the installed ONT type.

You can view whether an appointment is required by performing a Query Products for Location request. In the response you will be able to see whether an appointmentRequired is yes/maybe/no.

• If the installed ONT type does not support the product you are querying then an appointment will be required and you will receive yes in the query products for location response.
• If the installed ONT type does support the product you are querying then an appointment will not be required and you will receive maybe in the query products for location response.

If an order is placed against a property with an installed ONT and the product does not support the installed ONT type then the order will require an appointment otherwise it will be rejected.

Auto Compensation

Introduction

Ofcom introduced the Voluntary Code of Practice for an Automatic Compensation Scheme that enables Communications Providers to calculate and make automatic compensation payments to end customers where there has been a delay in the provision or repair of their service and where an appointment has been missed.

Key Principles

Provision Missed Appointment Notification

Introduction

Provision Missed Appointment Notification is one of a number of related requirements that support CPs deliver accurate delay and missed appointment compensation for non-end customer failures, i.e. failures encountered that were not the end customer’s fault, and introduces additional KCI notifications to the CP with details of missed appointments and additional attributes for a late provision order.

Requirement Details

Currently the SLAs that are covered by CityFibre only cover the payment to CPs for any delay or missed appointments. They do not consider SLA or SLG payments for end customers.

This requirement only covers the technical changes to the API to support additional KCI notifications. Manual processes related to Auto Compensation Reporting from CityFibre will be covered separately but may be referenced below.

Scope

Missed Appointment Notification

Late Provision Notification

Introduction

Requirement Details

This requirement only covers the technical changes to the API to support additional KCI notifications. Manual processes related to Auto Compensation Reporting from CityFibre will be covered separately but may be referenced below.

Scope

Late Provision Notification

MBORC – Rules for Auto Compensation

The existing MBORC process will be reused for Auto Compensation.

N = Auto Compensation does not apply (i.e. excluded due to MBORC)

Y = Auto Compensation applies (i.e. MBORC exclusion is not applicable)

NA = Not Applicable - MBORC not relevant

Exclusion Reason Codes

Next Best Action

Should an FTTP order be delayed, a delay code will be provided along with a recommended next best action to take.

For example a delay code of 220 may be returned for ‘Pet Behaviour’, with the recommended Next Best Action message "Before reappointing, please engage customer and mitigate on-site pet animal hazard. Reappoint with the customer after completion of contact and agreed action."

For an example of a message containing a next best action, see the notify of order status webhooks

Case Comments

A case may be raised by the Seller, to deal with an issue related to an order, for example if there has been an installation issue.

These cases will enable a two way conversation via case comments between the Seller and the Buyer, using KCI notifications and order amendments.

If a Case has already been closed, and the Buyer sends a new comment, this amendment will be rejected.

Ethernet Process Overview

Ethernet Availability Check

Ethernet services for businesses differ from FTTP as they offer symmetric committed information rates and transparently deliver packets without the PPPoE/DHCP authentication used in FTTP. These services may be delivered over the Full Fibre or Metro networks.

Query Address Search

Query Address Search

The buyer sends the seller a request containing either a postcode or a UPRN.

The seller then responds with detailed information about the queried location. If the buyer queried using a UPRN, the response will contain only one location. On a postcode request, the seller might respond with multiple locations that match the given postcode.

The seller then queries the products available at a given location using the location’s UPRN as the address key.

Query Products for Location

Query Products for Location

The seller will then respond with the following information. One or multiple products if available at that location, whether an appointment is required (“maybe”) and the indicative distance in meters from the centre of the postcode submitted to the nearest CityFibre network asset (for Metro Ethernet results).

Ethernet Products can be seen in the Products Reference

Installation Statuses

Build costs are likely to be within the standard installation charge.

Amber:

There are likely to be some additional construction charges in addition to the standard installation fee. There are likely to be additional checks needed before your order is processed and additional build time if your order is accepted.

Red:

There are likely to be significant additional construction charges on top of the standard installation fee. There are likely to be additional checks needed before your order is processed and additional build time if your order is accepted.

Customer API Connectivity

API Environment Introduction

CityFibre have three API environments: CFSIT, CFStaging and Production

Pre-Production

CFSIT is considered a development sandbox for customer system integration testing. This environment will allow customers to:

• query availability
• query products for locations
• query appointments
• reserve appointments
• create an order
• perform in-flight changes e.g. appointments and line profile amendments
• Test Post codes will be provided to ensure that testing can be performed by customers in advance and CityFibre will ensure that there are sufficient properties to cover the various test scenarios.

CFStaging is the environment where customers and CityFibre can collaboratively complete end-to-end functional verification before enabling access in Production. Test Scenarios are included in the document named: New ISP Onboarding Test Scenario Verification.xlsx

• Orders can be progressed using an internal tool, where access will be provided to the ISP by CityFibre. (Note this tool is not available in Production)
• The ISP will have to complete the test either collaboratively with CityFibre, or in their own time and return the completed document noted above with all mandatory tests completed.
• Test Post codes will be provided to ensure that testing can be performed by customers in advance and CityFibre will ensure that there are sufficient properties to cover the various test scenarios.

Production

• Live environment

API Setup Process

The process starts with access being provided to the pre-production environments, once the customer has provided the information specified below.

Customers can use CFSIT as a sandbox during their development for testing purposes.

When the customer is ready, access to CFStaging will be given in order to complete the end-to-end verification. A joint session can be held to verify the scenarios listed below, or the customer can complete the scenarios in isolation. The completed Test Scenario document should be returned to CityFibre detailing the completed mandatory tests. The verification is designed to ensure that the customer is able to complete all the necessary API calls systematically.

Typical Process Flow

1. Customer provides technical details for pre-production and production environments
2. CityFibre configure pre-production environments
3. Customer use CSFIT for development
4. Verification of end-to-end verification in CFStaging
5. CityFibre configure production environment
6. Customer use production for live availability and orders

Required Information

In order for CityFibre to set up the environments for the customer, the following details for Pre-Production and Production are required.

Client SSL certificate for validating authentication

• This needs to be a valid certificate issued by a recognised Certification Authority and the pem file sent to CityFibre as a text file.
• This can be a simple Email Identity Verification certificate from a vendor like Comodo (e.g. https://comodosslstore.com/email-identity/email-certificate)
• CityFibre will need a separate one for Pre-Production (i.e. one that covers both CFSIT and CFStaging) and one for Production.
• The customer will have to ensure that the relevant certificate is included with all calls to the API.
• CityFibre validate the Distinguished Name on the certificate matches what we’re expecting for the included buyer Identifier when the customer calls our API with the certificate.

A secure SOAP HTTP endpoint

• This is for CityFibre to send the XML notifications to the customer.
• This is the endpoint that we send all KCI notifications to.
• A separate endpoint is required for each environment.

A list or range of IP addresses

• Required for CityFibre to whitelist access for each environment’s API.

CityFibre will assign a Unique Buyer Identifier for each environment and provide this to the customer in advance. These must then be used for all API calls for the relevant environment.

Test Scenarios

The individual API calls are included in the document named New ISP Onboarding Test Verificaion.xlsx and cover the following End-to-end, in flight and in life scenarios:

• Availability check to live service.
  • The Customer will be provided with access to a tool that will enable them to progress an order through the stages to complete (separate documentation will be provided for this tool).
  • The Customer will need to provide the KCI notifications in XML format.
• In flight Amend (e.g. appointment or line profile amendment)
  • The Customer will need to provide the Buyer or Seller reference and what the change was so that CityFibre can verify success.
• Service Cease
  • The Customer will need to provide the Buyer or Seller reference so that CityFibre can verify the cease order has been created.
• In life Modify (e.g. line profile change)
  • The Customer will need to provide the Buyer or Seller reference and what the change was so that CityFibre can verify success.

Reference

RFS Statuses

LOC Codes

Products

Note that product availability is determined by contract so not all products are available to all buyers.

The available products depend on the contract between the buyer and the seller.

Product availability to a location should always be checked via the Query Products for Location API call before placing an order.

FTTP Products

Ethernet Products

Auxiliary Services

Line Profiles

The Seller provides the ability to order services that are provisioned with VLAN 0 or VLAN 911.

Line profiles will be returned in the query products response. The line profiles returned will be those eligible for the product selected, and the Buyer.

The allowed values depend on the contract between the buyer and the seller.

Residential FTTP and Business FTTP Standard

Residential FTTP 160

Business FTTP

Business FTTP 160

Layer 2 FTTP 2.5Gbps Business and Layer 2 FTTP 2.5Gbps Residential

Layer 2 FTTP 1.2Gbps Business and Layer 2 FTTP 1.2Gbps Residential

Layer 2 FTTP 2.0Gbps Business and Layer 2 FTTP 2.0Gbps Residential

Layer 2 FTTP 1.2Gbps Business Asymmetric and Layer 2 FTTP 1.2Gbps Asymmetric

Installation Process

CityFibre categorise all premises as either a Standard, Extended Standard or Non-Standard Installation. Rates and appointment SLAs for these types of installation are as per the Service Provider agreement.

Standard Installation

To identify a premise as a Standard Installation the Service Provider should assume: PRE-RFS: That any UPRN without any value in the LOC Field will be a Standard Installation POST-RFS: That any UPRN with RFS code RFS_1 and no value in the LOC field is a Standard Installation

Extended Standard Installation

To identify a premise as an Extended Standard Installation the Service Provider should assume: PRE-RFS: That any UPRN with a value of SUR or WSD in the LOC Field will be an Extended Standard Installation POST-RFS: That any UPRN with RFS code RFS_1 and a value of SUR or WSD value in the LOC field is an Extended Standard Installation

Non-Standard Installation

To identify a premise as a Non-Standard Installation the Service Provider should assume: PRE-RFS: That any UPRN with a value of MDU or UEL or UST in the LOC Field will be a Non-Standard Installation POST-RFS: That any UPRN with RFS code RFS_1 and a value of MDU or UEL or UST value in the LOC field is a Non-Standard Installation

Status and Error Codes

The following status codes are defined. This list may be extended, and all unknown codes should be treated as "other reason". The text displayed below is not the same as the text returned by the API. These are just descriptions of what the codes mean. For testing/development the buyer should use the codes to identify errors/warnings etc. The API messages may change at any time without warning but the codes will retain their meaning.

informationCode

None currently defined

delayCode

warningCode or cancellationReasonCode

errorCode

Next Best Actions