PXC Artemis Connector Guide

PXC offers the Artemis API for access to all products and technologies offered on their network, covering FTTP and SOGEA. The API is based on TMForum API specifications - the Fibre Cafe has a connector to integrate with this API.

Authentication & Setup

Artemis API security uses MuleSoft credentials (ClientId and ClientSecret) to generate a JWT token.

Partners will be provided with these credentials which must be configured on the Fibre Cafe for each tenant.

Address Lookup

Address lookup uses the PXC Artemis address matching service to return the Openreach address identifiers (NAD/ALK and District Code) and UPRN which are used when sending requests to their API. 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 UPRN, 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.

The address lookup response includes the full address details and qualifier as well as the identifiers. The API does not currently provide additionalAttributes so this is not populated.

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

PXC offer dynamic types of service specification (product family/access technology) depending on their underlying supplier/technologies at an address and the partner type e.g.

• CityFibre: C-CFH-FTTP
• Openreach: C-OR-FTTP
• FreedomFibre: C-FF-FTTP or C-FF-FTTP-L3
• CommunityFibre: C-CF-FTTP or C-CF-FTTP-L3

An address may have multiple FTTP options if it is serviced by multiple suppliers.

When returning service specifications for an address, the available line profiles are returned in the 'serviceCharacteristics' field:

"serviceSpecifications": [
  {
    "id": "C-OR-FTTP",
    "name": "FTTP", 
    "serviceCharacteristics": [
      {
        "name": "LINE_PROFILE",
        "values": [
          "0.5/0.5",
          "40/10"
        ]
      }
    ]
  }
]

Only FTTP based services are supported in the initial release - SOGEA support is coming soon.

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 and availability date where returned.

Installation Types

PXC Artemis supports different installation types as supported by the underlying supplier:

• STANDARD : A standard appointment is necessary when placing the order
• EXTENDED_STANDARD : 2 stage installation (known as 'KCI2 Assure' with Openreach) - an additional survey is usually required.
• NON_STANDARD : Property has RFS (ready for service) status but has been marked as a non-standard installation.

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.

Not all PXC suppliers will use all installation types.

Existing Lines

For FTTP services, existing ONT information includes:

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

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 AM, PM or by all day (WEEKDAY, SATURDAY, SUNDAY) depending on supplier.

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

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

• CARE_LEVEL : See care levels table below

Line Profiles

A LINE_PROFILE characteristic is required for PXC Artemis orders. Line profiles are chosen by passing the appropriate product downstream/upstream speeds as follows:

The Fibre Cafe does not map these profiles and passes the value straight to the PXC Artemis API.

Care Levels

PXC Artemis offers different care levels but not all apply to all underlying suppliers or service specifications

The default care level for orders is Standard.

Order Amendments

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

• Change appointment / requested completion date
• Update contact details

Order Updates

Order updates (also known as KCIs or KSUs) are received from PXC Artemis 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 the connector and sent with an appropriate action or information type according to the supplier code and KCI content.

Service IDs

PXC Artemis 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 PXC Artemis (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"
    }
  }
}

Version History

Tenant API 1.16 / Tenant Updates API 1.14

• Initial connector release for PXC Artemis with support for FTTP orders.