#6. TOTSCo Integration

Connected Services Framework (CSF) — Part 2: Implementation — Version 2.0

#6.1 Overview

TOTSCo operates centralised hubs for both One Touch Switch (OTS) residential switching and Switching for Business (SforB). Both hubs use the same JAM message envelope specification and the same OAuth 2.0 over TLS 1.3 transport that the CSF uses, which gives the two networks strong compatibility at the message layer. For SforB, TOTSCo can participate in the CSF as a Hub Managed Access Provider (HMAP) — routing messages between its connected CPs and the wider CSF network.

This chapter describes how the CSF and TOTSCo interoperate. The detailed implementation plan has been shared separately with TOTSCo and is available on request from the TAG.

CP migration path (SforB and non-OTS only). A CP currently using TOTSCo for SforB (and / or for niche bilateral exchanges or other non-OTS protocols) who wishes to become a MAP of 1 on the CSF for that traffic is covered by Part 1 §7.4 MAP-of-1 Onboarding (incl. TOTSCo → CSF Migration). The CSF treats this as a first-class adoption path; the strong JAM-envelope compatibility makes the move a transport switch rather than a business change. OTS is out of scope — OTS is Ofcom-mandated to use TOTSCo as the single industry platform, so a CP that operates OTS MUST continue to use TOTSCo for OTS traffic. The migration applies to SforB and other non-OTS protocols only.

#6.2 Integration Principles

• Zero to low impact on existing TOTSCo infrastructure
• The CSF uses the same JAM message specification and OAuth 2.0 authentication as TOTSCo
• No modifications to the TOTSCo letterbox API are required
• TOTSCo's existing OTS connections with MAPs can be reused

#6.3 Registering CSF Endpoints

Impact: Zero to Low

It is highly probable that existing MAPs already have connectivity with TOTSCo from OTS or SforB. Any new MAP or MAP-of-1 joining the CSF must also register with TOTSCo following their existing procedures:

• Provide IP addresses for allowlisting
• Exchange OAuth 2.0 or API key credentials
• Confirm message exchange conforms to the JAM Specification

The only additional requirement is a Directory API endpoint URL for TOTSCo to retrieve the MAP's CSF registry.

#6.3.1 Dedicated, locked-down HMAP interfaces — both directions

The CSF and TOTSCo deliberately adopt a per-partner, dedicated-endpoint operating model in both directions. This mirrors how TOTSCo already runs OTS and SforB today — every CP and MAP that connects to the TOTSCo Hub does so through an endpoint TOTSCo provisions specifically for that partner.

Why locked down. The architectural commitment to TOTSCo is that the HMAP interface is steady-state. The CSF can — and will — continue to evolve at its own cadence; that evolution happens behind each MAP's standard CSF interface, not through the dedicated HMAP interface TOTSCo consumes. This keeps TOTSCo's integration a one-time build, not an evergreen one, and isolates TOTSCo's regulated OTS operations from any CSF iteration.

Best Practice (legacy heading retained for backward compatibility of cross-references). All MAPs should configure a dedicated, locked-down HMAP interface for TOTSCo. This is mandatory in the operating model described above and is the only pattern this section supports.

#6.4 Directory Collection

Impact: Medium

TOTSCo must collect the CP Registry from each MAP on the CSF network. This involves:

1. Accessing each MAP's CP Registry endpoint using existing OAuth 2.0 credentials
2. Converging the collected CP Registries into a Master Registry — either merged with the existing TOTSCo directory or maintained separately
3. Updating periodically — every 5 minutes, hourly, or daily, at TOTSCo's discretion

The CSF CP Registry is intentionally a strict superset of the TOTSCo directory structure for OTS and SforB, making convergence straightforward. TOTSCo can choose to retain all data, or use the CSF-specific fields (signing[], expanded resource[], contact[], outage[]) for the value they add, or ignore them entirely — none of those choices break TOTSCo's existing parser.

Dual-process directory in TOTSCo today. TOTSCo's pre-production Directory v2 already serves both OTS and GPLB (SforB) entries from a single list, distinguishing them by processSupport[].process. MAPs that want a single-process view filter on an identity query parameter:

https://preprod.otshub.totsco.co.uk/directory/v2/entry?listType=RCPID&identity=all
https://preprod.otshub.totsco.co.uk/directory/v2/entry?listType=RCPID&identity=ots
https://preprod.otshub.totsco.co.uk/directory/v2/entry?listType=RCPID&identity=gplb

The production model is expected to follow the same shape. The CSF's Master Registry follows the same convention (processSupport[].process carries OTS, GPLB, and future process tags), so TOTSCo can apply its existing filter logic unchanged.

The number of CSF MAPs is anticipated not to exceed ten initially.

#6.5 RCPID Format Handling

Impact: Low

The SforB Message Specification defines source and destination identity fields as strings (up to 256 characters). The CSF uses UUIDv4 (36 characters) — well within this constraint.

In practice:

• CSF MAP sending to TOTSCo: Uses the destination RCPID from the TOTSCo directory (typically 4-character OTS format)
• TOTSCo sending to CSF MAP: Uses the destination RCPID from its Master Registry (UUIDv4 format, collected from CSF CP Registries)

TOTSCo automatically acquires all CP UUIDs when collecting MAP registries. Both CSF and TOTSCo already accept UUIDv4 for correlation IDs.

#6.6 API Compatibility

Impact: Zero

TOTSCo uses the industry JAM Specification for message exchange — the same standard used by the CSF. The CSF validates the JSON envelope identically and uses OAuth 2.0 over TLS 1.3.

The 8xxx PKI error codes are CSF-specific and are not sent to TOTSCo. No API modifications are required on the TOTSCo side.

#6.7 Message Flow: CSF to TOTSCo

In CSF, CP 1 and MAP A are treated as a single unit at the transport layer — the MAP handles all CSF message exchange, and the CP only gives the MAP internal instructions and receives internal nudges back when action is required. This is true whether the CP is operating as a MAP-of-1 (CP and MAP are literally the same entity) or is a CP being served by a separate MAP. The mermaid diagram below uses a grouping box to make this visible.

#6.8 Message Flow: TOTSCo to CSF

The same CSF grouping applies on the inbound side — MAP A receives the message from TOTSCo on behalf of CP 1, and CP 1 is notified internally if the message requires action.

#6.9 PKI Considerations

TOTSCo, as an HMAP, is not required to implement DKIM/PKI signing when exchanging messages on behalf of its CPs. This is by design — to minimise integration cost for hub operators.

However:

• TOTSCo is strongly recommended to implement the full CSF CP Registry format for SforB, as its CP clients benefit significantly from the additional contact and support information
• TOTSCo is not precluded from implementing PKI if desired — the CSF framework supports it
• When a CSF MAP receives a message from TOTSCo's dedicated endpoint, it knows the message comes from a trusted hub and applies hub-specific validation rules rather than PKI verification

#6.10 Passthrough Headers

When TOTSCo forwards a message from a CSF MAP to its own CPs, the X-CSF-SIGNATURE header SHOULD be left intact. This provides end-to-end trust verification — the destination CP (or its MAP) can verify the original signing even after hub forwarding.

#6.11 Support and Diagnostics

By accessing CSF registries, TOTSCo gains direct access to MAP contact details (phone, email, URL with availability hours), enabling prompt issue resolution.

The CSF registry provides more detailed contact information than currently available through OTS, including:

• MAP and CP support hours
• Multiple contact methods with purpose tags (sales, support, technical)
• Service status URLs for real-time operational monitoring

#6.12 Further Information

These documents are available on request from the TAG.