Technical, Process & Testing Documents

Here are all the technical, process & testing documents you will need to implement One Touch Switch.

If you have any questions or need support, our TOTSCo Online Communities is a great place to go. You will be welcomed by the TOTSCo Team and industry experts on hand to answer any of your questions.

Or alternatively send us an email and we will get back to you as soon as we can.

technical-documents-image

Hub Testing Documents

For data and privacy purposes, our testing documents can be accessed via the Account Management Portal, any questions please contact us on enquiries@totsco.org.uk. 

 

Here are the documents you will need for testing:

Subject Area Document Title
Testing Documents
Simulator Testing TOTSCo Hub FQDN and IP Addresses v5
TOTSCo Hub Test Cases 4.9
Integration Testing TOTSCo Hub FQDN and IP Addresses v5
TOTSCo Generic Industry Test Scenarios – this document is available only via the Service Desk (service_desk@totsco.org.uk).

Technicial and Process Documents

We’ve identified a set of essential documents called ‘mandatory’ that everyone involved in the OTS process must become familiar with. Additionally, we have a collection of advisory documents, thoughtfully created by industry participants with TOTSCo’s facilitation to offer industry guidance. It’s crucial to note that these documents do not serve as legal or regulatory advice, nor do they bear the endorsement of Ofcom, ICO, or TOTSCo. As a result, they will consistently undergo updates and enhancements to evolve and better cater to the industry’s requirements.

Subject Area Document Title Current Version
Mandatory Documents
Technical Specification TOTSCo API Specification 1.1a
OTS Message Specification 1.1c
OTS Response Codes 1.0
OTS Process OTS Industry Process 4.3
OTS Industry Process Flows 4.3
One Touch Switch Message Delivery Policies 1.0
Advisory Documents
Best Practice Guides OTS Matching Best Practice Guide 1.0
OTS Additional Guidance on Exception Scenarios Best Practice Guide 1.0
OTS Message Examples 1.0
OTS Match Request and Response Scenarios Matrix 1.0
OTS Open Order Best Practice Guide 1.0
OTS Response Codes 1.0
The OTS Number Porting and Intra-Network Transfers Best Practice Guide 1.0

If you would like to raise a ‘change request’ to any of the documents above, please read the OTS Industry Change Control Process. Then complete the OTS Request for Change Form and send it to enquiries@totsco.org.uk. If you have any questions please contact us.

 

  1. OTS IP Change Control Jan 2023
  2. External OTS Request for Change Form

The OTS Number Porting and Intra-Network Transfers Best Practice Guide v1.0

 

The release of OTS Number Porting and Intra-Network Transfers Best Practice Guide v1.0 is released for industry.  The document provides best practice guidance on aligning the number port process with OTS.

One Touch Switch Message Specification v1.1c

Minor corrections made:

Alignment with Industry Process: The ‘ONTPortNumber’ in the Match Confirmation message has been revised to ‘PortNumber’, ensuring consistency with industry standards.

Enhanced Example Messages: Revisions throughout the document, with a specific reference to Appendix 10 of the Industry Process, detailing Openreach service identifiers.

API Specification v1.1a Adjustments: minor corrections and clarifications listed in the document’s change log.

Minor Corrections and Clarifications: Detailed in the document’s change log, these adjustments are in line with the Hub’s construction, and we do not foresee any impact on development activities.

For ease of reference, both documents are available in ‘clean’ and ‘marked up’ formats, allowing those familiar with the earlier versions to easily spot the changes.

OTS Additional Guidance on Exception Scenarios Best Practice Guide v1.0

The Additional Guidance on Exception Scenarios now serves as a guide specifically designed to cover the remaining scenarios that did not naturally fit into the other best practice guides.

OTS Message Examples v1.0

This document serves as a reference guide for constructing messages tailored to specific scenarios and service combinations, with a primary focus on match requests and match confirmations.

OTS Response Codes v1.0

The Response Codes list has been updated to include new codes for failure scenarios that have been identified by the group and has added additional guidance for how to proceed in the event each code is received

 

One Touch Switch Match Request and Response Scenarios v1.0 matrix

The Match Request and Response Scenarios provides a matrix of combinations of information that can be included in a match request along with the expected failure or confirmation outcome.

 

OTS Matching Best Practice Guide v1.0a

The OTS Matching Best Practice Guide provides guidance on the matching stage of the OTS process with a particular focus on address matching and suggestions of how to implement matching algorithms.

Changed to v1.0a to include a minor correction to reflect Openreach’s intent address formatting. No impact to the guidance in the document

 

 OTS Open Message Delivery Policies v1.0

This document focuses on how the hub will attempt to deliver messages between CPs.

 

 

 OTS Open Orders Best Practice Guide v1.0

This document focuses on customers who have an open order with their LRCP when the try to match or switch.

One Touch Switch Industry Process v4.3

 

This document provides a comprehensive overview of the complete industry process for One Touch Switch (OTS). It is essential for all suppliers offering fixed voice and broadband services to understand the OTS process from start to finish to effectively enable the OTS process.

 

The OTS process flows are a visual representation of the One Touch Switch Industry Process.

 

Archive Documents

The OTS NBICS and Number Porting Best Practice Guide v0.2

 

The OTS NBICS and Number Porting Best Practice Guide v0.2 is released for industry feedback. The document provides best practice guidance on aligning the number port process with OTS. Please provide any comments to enquiries@totsco.org.uk by 01/12/2023.

One Touch Switch Message Specification v1.1b

We have corrected a small error in the status field on page 27.

 

OTS Message Examples v0.1

FEEDBACK – requested by 3 November 2023 to enquiries@totsco.org.uk

This document serves as a reference guide for constructing messages tailored to specific scenarios and service combinations, with a primary focus on match requests and match confirmations.

OTS Additional Guidance on Exception Scenarios Best Practice Guide v0.4

FEEDBACK – requested by 10 November 2023 to enquiries@totsco.org.uk 

The Additional Guidance on Exception Scenarios now serves as a guide specifically designed to cover the remaining scenarios that did not naturally fit into the other best practice guides.

TOTSCo can confirm the release of TOTSCo Hub API Specification v1.1. This document contains the additional API keys and mutual Transport Layer Security (mTLS) security implementation options.

Please note that API Key and mTLS will be available in our test environments from 20 October.

 

 OTS Open Orders Best Practice Guide v0.2

This document focuses on customers who have an open order with their LRCP when the try to match or switch.

OTS Matching Best Practice Guide v1.0

The OTS Matching Best Practice Guide provides guidance on the matching stage of the OTS process with a particular focus on address matching and suggestions of how to implement matching algorithms.

 

One Touch Switch Match Request and Response Scenarios Matrix v0.3 

The Match Request and Response Scenarios provides a matrix of combinations of information that can be included in a match request along with the expected failure or confirmation outcome.

One Touch Switch Response Codes v0.4

The Response Codes list has been updated to include new codes for failure scenarios that have been identified by the group and has added additional guidance for how to proceed in the event each code is received.

 OTS Matching Best Practice Guide v0.3

The OTS Matching Best Practice Guide provides guidance on the matching stage of the OTS process with a particular focus on address matching and suggestions of how to implement matching algorithms.

One Touch Switch Message Specification v1.1

 

This document explains the OTS messaging formats and how they are used. Crucial information for the technical experts to make sure your messages are coded correctly to enable the OTS process to work.

 

This document contains a list of response codes to be included in any failure messages you would send as a losing provider as well as any message delivery failure notifications sent by the hub.

One Touch Switch Message Specification v1.1a

We have corrected a small error in the definition of UPRN.

 

Here are the TOTSCo Hub Test Cases v4.1 which lists the different test case examples, TOTSCo would like all Communication Providers (CP’s) Hub Users to test. This will allow CP’s to test their secure and authorised connections to the TOTSCo API Service, as well as all expected responses to all calls the CP API services make to the TOTSCo API service.

TOTSCo Hub API Specification v1.0

TOTSCo can confirm the release of TOTSCo Hub API Specification v1.0. This document contains the Directory API and oAuth2 security implementation.

Following industry feedback, we will be adding the security implementation options to use API keys and mutual Transport Layer Security (mTLS) when connecting to the hub. A further API Spec featuring these additions will be released in due course.

This document explains the OTS messaging formats and how they are used. Crucial information for the technical experts to make sure your messages are coded correctly to enable the OTS process to work.

The OTS process flows are a visual representation of the One Touch Switch Industry Process.

This document provides a comprehensive overview of the complete industry process for One Touch Switch (OTS). It is essential for all suppliers offering fixed voice and broadband services to understand the OTS process from start to finish to effectively enable the OTS process.

Following a thorough review of our security protocols, considering industry feedback and insights from our Technical Working Group, we are releasing a revised API Specification V0.5.

This document features the finalised Letterbox API specification, including envelope elements and the validation process. We are diligently working towards finalising the directory API and security implementation, and we will issue a definitive version as soon as this process is completed.

This document features the draft envelope structure as well as a draft Directory Letterbox API specification. Vital information for technical experts as it provides the guidance needed to effectively interface with the TOTSCo Hub.

Explanatory Notes

TOTSCo are pleased to announce the circulation for review only, of the One Touch Switch Developers Guide V.0.3. This is a minor update to version v.0.0.1, which was released on 31st October 2022.

The changes from v.0.0.1 to v.0.3 include:

  1. Reformatted JSON examples for consistency
  2. Fixed typos. Updated diagrams.
  3. Augmented message types by prefixing with “residential” making it easier for developers to find, group and categorise logical elements
  4. Splitting out Match Elements and Order Elements (see 2)
  5. Consistency between “Request”, “Confirmation” and “Failure” message types
  6. Added more “Response” Codes (see separate Spreadsheet) to align with the Industry Process and Exception Handling – The original Response Codes were        not “Granular” enough.
  7. Added grcpBrandName to the residentialSwitchMatchRequest, permitting the GRCP to specify the brand name to be used in communications sent by the LRCP.

The API specification has been updated to reflect reviews and comments since its initial publication.

These documents are being circulated to industry for review. We welcome comments on these draft documents and we will consider these before we finalise the documents for publication and place them under formal change control.

Our preferred format for review comments is inline comments within the Word Document itself. We would appreciate each CP sending only one document with review comments as this will speed up the review process.

Please send any feedback by close of play on Friday 17/02/2023 by email to enquiries@totsco.org.uk.