Supplier API Upcoming Changes

This page documents upcoming changes/API releases that impact the Supplier API and Supplier Updates API.

Where feasible, changes will be backwards compatible to allow existing supplier integrations to continue working. However, some changes may be required to fully support the features that tenants wish to use on the tenant API.

Supplier API 1.7 / Supplier Updates API 1.3

The initial release of the supplier API focused on NEW provide orders only. Whilst the API allows for returning lineType to specify NEW vs START/TAKEOVER lines and existing ONTs, this was not fully implemented and has a number of shortcomings that means it cannot fully satisfy the latest tenant API requirements. Unsolicited cease notifications were also not supported.

This release aims to address these requirements whilst retaining support for the previous version.

Service Availability

The siteInformation type has been updated as follows:

  • lineType field is no longer used (will be ignored when present)
  • New field newLine introduced to specify whether a new line can be installed (default is true when not present)
  • installationType is now optional
  • onts array is no longer used
  • New array existingLines introduced to detail any existing service(s)
  • New field lineId introduced - usually used by copper-based FTTC services
  • New field lineCharacteristics introduced to specify additional information about line

Note: the last 2 fields are not used by most supplier integrations.

The ont type has been updated as follows:

  • Optional ONT manufacturer field has been introduced
  • Optional ONT location fields: floor , room , position have been introduced
  • Mandatory ports field is now an array of OntPort type rather than string :
    • portNumber is mandatory
    • status is optional but should be populated if possible
    • tenantActive should only be populated if reflecting the actual status of on tenant network
    • stoppedDate should only be populated where line is inactive

The installationType fields are used to indicate installation and hence an appointment is required. It is present at root siteInformation level for new lines and also within existingLines. Where it is not present, this is now considered to mean that an appointment is not required.

New Lines

Where a new line can be installed (presence of an existing line may or may not allow this), the newLine field should be true and installationType populated as appropriate. If only 1 line is permitted and there is already an existing line, the newLine field should be false with the root siteInformation.installationType omitted.

Existing Lines

Where there are 1 or more existing lines, the existingLines array should be populated. Where an appointment is required, the installationType field within the existing line should be populated as appropriate. Where an appointment is not required, this field should be omitted.

Orders

The order management APIs remain largely the same - however note that the /service-order-cancellations endpoint will need to support Unsolicited Cease orders as described below (orderType: UNSOLICITED_CEASE)

To support switch, transfer and takeover of existing lines, the tenant can now create orders for one of these distinct orderType:

  • START
  • TAKEOVER
  • TRANSFER

When placing one of these types, the tenant will use the service availability endpoint to retrieve and send an existing ONT/port in these standard service characteristics:

  • ONT_REFERENCE
  • ONT_PORT

Order Updates (KCIs)

Alongside support for sending unsolicited ceases, this update also brings the Supplier Updates API into line with new features on the Tenant Updates API.

Unsolicited Cease

This version introduces support for suppliers sending an Unsolicited Cease to tenants as part of Gaining Provider-Led Switching. These are sent using the same KCI endpoint with the introduction of a new UnsolicitedCeaseServiceOrder type and CREATED reason code.

Upon sending the unsolicited cease order to the Fibre Gateway, they will be represented as an order in addition to provide, modify or cease - the primary difference being that they were created by the supplier. However:

  • Amendment requests are not permitted for an inflight unsolicited cease order.
  • Cancel requests are permitted under the specific reason codes covered in the main Unsolicited Cease documentation.

Unsolicited Cease orders have KCIs but follow a simpler order process as described in the main documentation above. To ensure consistency across suppliers, the Fibre Gateway can send KCIs on behalf of the supplier - this is driven by the status of the order as received:

  • status = ACKNOWLEDGED; send Unsolicited Cease CREATED KCI and then the ACKNOWLEDGED KCI
  • status = IN_PROGRESS; send Unsolicited Cease CREATED KCI, then the ACKNOWLEDGED and the COMMITTED KCI

The first option allows the supplier to send the COMMITTED KCI at a later point to initial creation of the unsolicited cease.

Once the switch is complete, a final COMPLETED KCI must be sent by the supplier.

Supplier Notes

Whilst orders contain a notes field for the tenant to provide information to suppliers, there was not a dedicated place for the supplier to attach notes e.g. site visit notes, updates, engineer reports, etc. This has been rectified with the introduction of the supplierNotes array on KCIs. Multiple notes can be added and the type field allows the notes to be categorised.

Unsolicited Reappoints

The reappoint mechanism when dealing with missed appointments is usually tenant led via an ACTION_REQUIRED : REAPPOINT KCI. However, based on agreed circumstances (e.g. after direct discussion with the end customer or if necessary for customer retention), suppliers are now able to send new appointment details in KCIs.

In this scenario, an INFORMATIONAL KCI should be sent with new reasonCode: REAPPOINTED. The new appointment details must be populated in the order appointmentTimeslot and appointmentSupplierReference should be updated as appropriate.

New Reason/Problem Codes

The available reasons (reasonCode) for a KCI have been extended to provide more granular codes:

  • CREATED : this KCI contains a new unsolicited cease order - described above
  • ACKNOWLEDGED : this KCI acknowledges the order - accompanied by status change to ACKNOWLEDGED
  • REAPPOINTED : a new appointment has been arranged - described above
  • RESUMED : the problem causing the delay has been resolved without impact on target date
  • ADDITIONAL : this KCI contains additional information from the supplier - new service characteristic(s) e.g. SERVICE_ID
  • WARNING : this KCI warns of a (potential) problem but is not introducing a delay - accompanied by a problem code and text
  • COMPLETED : The order is complete - accompanied by status change to COMPLETED/PARTIAL

Aside from WARNING, the Fibre Gateway will attempt to automatically detect these reasons where they are provided as the more generic UPDATE reason code.

In addition, there are now some additional problem codes that can be used to cover other scenarios:

  • ADDITIONAL_WORK - further work has been identified which results in a delay
  • COST_ISSUE - additional cost has been identified that is not covered by the agreed contract/charge band
  • INVALID_REQUEST - order or amendment/cancellation request is not valid
  • LINKED_ORDER_ISSUE - an associated order has an issue/delay that is impacting this order