TOTSCO journey (to help other CPs)

I have done many blogs, so this is a summary, mainly aimed at other CPs. I hope it helps.

Gotchas

I am going to try and cover some gotchas, but a lot can be avoided by checking out ProposedChanges.md

Get on board

If you are a communications provider doing residential, fixed location, broadband or telephone service you have to do this shit, sorry. OFCOM rules, and so law. Get to totsco.org.uk and sign up. There is a deadline of 12th September 2024 for all retail CPs covered by this to be ready.

You may, instead, be able to use a managed access provider, but that sounds iffy to me as they need access to all your data, and you probably still have to do most of the work to integrate with your systems I expect. To be quite honest, it is not that hard.

How long?

I spent a week on this initially - much was cleaning up our address records, and reading specs, before coding it. I made a test system as part of this, but nothing like NOTSCO. I have done various small bits since, and spent several days integrating to our ordering, but mostly it has been waiting for TOTSCO. I spent another week making the NOTSCO platform from scratch, and wish I had done that first. Total elapsed time a little over 5 weeks. I'll not doubt do more once we are live and we encounter some unexpected edge cases.

The specifications

There are a load of specifications, and a few you need to read are:

• API specification
• OTS message specification
• Industry Process
• Error codes list
• Network Operators list
• Example messages

But there is a lot, and not very well structured, or consistent. I suggest also checking ProposedChanges.md

API to TOTSCO

The basic steps in talking to/from TOTSCO are not hard. They have a choice of authentication and we chose OAUTH2. After the basic OAUTH2 you are basically sending JSON payloads each way to/from the hub, and the format is simple with an envelope and payload. There are loads of tools and libraries to handle such APIs.

Watch out for my correlationID section in ProposedChanges.md as this caused me to waste a day, at least, as I assumed the examples implied a longer term correlationID. You need one on every message you send, and may as well be unique to each message, so you can correlate a reply. You need to correlated the reply for a match request anyway, and should for other messages as they can come back as messageDeliveryFailure, so can't just use the switch order reference to handle the reply.

OTS messages

The next level is the OTS switching messages. These fall in two parts. The match request and reply, and then the set of switch order starting, updating, cancelling, and triggering.

You may want to make a system for sending and receiving these, and then integrating that in to your ordering and customer management systems. I chose to make a library with some good command line options for testing and then a higher level integration of that library in our ordering system.

Making a match request

In principle this is actually quite easy, there are not many options or fields. The only hard part is correctly forming an address, and if you can, using UPRN. For IAS that can be it. If you don't get a match you can ask customer for account number and circuit ID and add that. For number porting you have a telephone number, which is the crucial component. We use BT/Openreach address tools which make this relatively easy, and provide a UPRN, but O/S have an AddressBase product which is good as well.

Matching an address, and sending a response

This is slightly harder, the main gotchas are address matching - the industry process has a huge section on that, and matching surname, on which is says much less. Removing accents and changing ß to ss, are the main thing for a surname. Even so, matching is probably not too hard, and you can always expect an account number to enhance the match if not sure. You do need to automate this, as the SLA is 60 seconds. You do need to contact the customer (e.g. email) if you match, including early termination fees.

Handling a match response

In many ways this is the hard part as you can get a lot of different answers even for a simple match request - maybe numbers are in a block and some will be ceased if you port one. Maybe there is a number tied to a broadband line - which is a whole new can of worms as losing provider may have a retain option buy you know you are changing to SOGEA which kills the number. Ultimately you need to then pick one, or give your customer a choice, somehow explaining the actually meaning of these options. That can be tricky to do in a clear way.

Bear in mind you may have to continue without using One Touch Switching, as before, as the customer may not want to switch their existing service, or they may have a business service.

Getting a switch order

This is actually really easy, you get told the switch order (which you saved from the match), and you just need to put in your customer database and update the customer (e.g. email). Any migration (e.g. broadband or number port) happens as normal anyway. The switch order messages allow you to record the handover date (plannedDate and activationDate). If not a migrate then that is the same as a customer ceasing by other means. You do need to work out early termination changes, but probably have the processes for that, and billing, all in place from the notice of termination system.

Generating a switch order

Again this is pretty easy. We opted to send the order as part of customer order process, and then any other messages on a daily job - advising if a change of date, cancelled, or completed. The actual ordering system are the same as they were before, doing a migrate or a new install in the same way as normal, but just these extra outgoing messages at the key stages.

Simulator

TOTSCO run a simulator which is crap, but may be worth getting out of the way early. They will allow you to short cut that if you manage a message both ways showing connectivity. We could not go further because their fixed messages were not valid, so we had no switch order to start, so skipped all but one message.

Pre-production testing

The next step is a slight fiasco - you need to team up with a buddy CP who is on the pre-production platform. We did this with two CPs, one of which turned out to be just starting, and it was like watching paint dry. The other was all ready, had a very slick system, and we got through all tests in 90 minutes - most of which was each of us working around our normal systems to fool them that an order had started and finished and so on. But getting TOSTCO to find a buddy CP can take ages, and the whole thing is basically pot luck, there is no checking against a reference system or to the specification.

Oh, and for extra fiasco, we were expected to do 1000 messages. This is not like testing 1000 different addresses or something, just that we did a 1000 messages. A command starting "repeat 1000 ..." was used, and took a few minutes.

Production testing

If pre-production testing was a fiasco, production testing is a joke!

They booked a two hour slot for this. It requires one message. They actually insisted on one exchange of messages each way (4 messages in total).

It took 15 minutes, and the reason it took so long was they were seemingly hand crafting the messages they sent, so each message they sent took some minutes to prepare. This is beyond stupid, if you ask me. They even managed to hand craft an invalid message which meant waiting for them to eventually send a correct one.

But the criteria is just that - a pair of message exchanges, and you are live on production. Once again, no test against a reference system, and no testing to the specification.

Want to do it right?

I got so pissed off I created NOSTCO, which provides an unofficial, independent, free, test environment for One Touch Switching development. It allows you to try a lot of messages, each way, with a lot of different combinations - particularly important for handling the myriad of possible switch match responses.

What is really good is that it analyses each message, and reports any issues, with reference to the specification. It allows you a playground to work through development, testing as you go, from the most basic connectivity, to completing the whole sequence of switch match and order, each way.

It makes a scorecard of message types, so you can see you have good coverage, and allows a range of fixed nasty messages to test your error handling and edge cases.

Not over yet

Of course the real fun will start when we start doing live switches with other CPs.

Good luck!