Web Services Access Guide
BT Wholesale
Broadband Knowledge Based
Diagnostics (KBD) Web Services
Access User Guide
Issue 1.3 – 05th September, 2014
Copyright British Telecommunications plc 2012
Page 1 of 29
Web Services Access Guide
Legal and Confidentiality Statement
The information contained in this document is confidential information as per your terms and
conditions with BT. Please treat it accordingly do not forward, republish or permit unauthorised
access.
For the avoidance of doubt, the information contained in this document is for
information purposes only and does not constitute part of the contractual
terms and conditions.
All rights are reserved to BT and or its Licensors.
© British Telecommunications plc, 2012.
Registered office: 81, Newgate Street, London, EC1A 7AJ
Registered in England no. 1800000
Issue 1.3 – 05th September, 2014
Copyright British Telecommunications plc 2012
Page 2 of 29
Web Services Access Guide
Contents
1.
ABOUT THIS HANDBOOK .................................................................................................................................................. 4
1.1
1.2
2.
INTRODUCTION .................................................................................................................................................................... 5
2.1
2.2
2.3
3.
DOWNLOADING A NEW DIGITAL CERTIFICATE ............................................................................................... 9
ONRAMP TESTING ............................................................................................................................................................. 10
5.1
5.2
5.3
5.4
5.5
6.
BT W HOLESALE SIDE SET UP ....................................................................................................................... 7
YOUR ONRAMP SETUP.................................................................................................................................. 8
SECURITY & CERTIFICATE INFORMATION .................................................................................................................. 9
4.1
5.
W HAT IS BT W HOLESALE ONRAMP INTENDED FOR?................................................................................... 5
W HAT IS BT W HOLESALE ONRAMP NOT INTENDED FOR? ........................................................................... 5
HOW LONG WILL YOU USE ONRAMP FOR? ................................................................................................... 6
SETTING UP THE GATEWAY ............................................................................................................................................ 7
3.1
3.2
4.
VERSION CONTROL ...................................................................................................................................... 4
FURTHER INFORMATION & COMMENTS........................................................................................................ 4
INTRODUCTION TO ONRAMP FOR KBD ...................................................................................................... 10
MESSAGES FROM YOU TO ONRAMP ........................................................................................................... 10
MESSAGES FROM ONRAMP TO YOU ........................................................................................................... 20
ONRAMP EXIT CRITERIA .............................................................................................................................. 22
MESSAGE HANDLING................................................................................................................................... 25
PILOT AND LIVE PHASES ................................................................................................................................................ 26
6.1
6.2
PILOT .......................................................................................................................................................... 26
LIVE ............................................................................................................................................................. 27
7.
GLOSSARY .......................................................................................................................................................................... 28
8.
DOCUMENT HISTORY ....................................................................................................................................................... 29
Issue 1.3 – 05th September, 2014
Copyright British Telecommunications plc 2012
Page 3 of 29
Web Services Access Guide
1. About this handbook
This document provides an overview of the On-Ramp Process to help Communications Providers
(CPs).Realistic sample messages are used in this user guide to illustrate interface usage.
Variables are indicated by bold italic text; used to signify data parameters at the client level.
1.1 Version Control
Please ensure that you have the latest version of this Handbook.
1.2 Further Information & Comments.
Please refer to the B2B and Web Services pages on the BT Wholesale web site for further
information.
Any enquiries and comments should be made to the Team :
Email: wholesale.pem@bt.com Tel: 02034505229
Issue 1.3 – 05th September, 2014
Copyright British Telecommunications plc 2012
Page 4 of 29
Web Services Access Guide
2. Introduction
The Web Services Gateway is designed to allow you to manage a variety of telecommunication
services electronically, by linking your support systems and processes with BT.
Designed specifically for you, this user guide traces the initial set up of your system, with helpful
hints and technical information to get you started.
It will lead you through the testing phase and into the establishment of the Knowledge Based
Diagnostics (KBD) live environment and the BT Broadband customer support process. The KBD
Tool can be used if, or when, you have any technical issues with your service.
The KBD Tool will suggest actions or ask more questions based on the information you have given
and any results from the automatic testing tools. These will be sent to you and when you answer,
the KBD Tool, will, if possible, find a possible solution to the issue.
2.1 What is BT Wholesale Onramp intended for?
The Onramp environment is available to BT Wholesale customers so that they can test:
a) Connectivity to and from BT Wholesale Gateway via the Internet and any proxies
and firewalls that may be on the routes involved.
b) The creation, format conversion (if required), and installation of any certificates that
may be used to support the https connections.
c) To pave the way to accessing a host of additional online services as these become
available.
d) Implementation of web services.
Testing of the interface may be done using test stubs but final testing should use
data generated by and integrated with your backend systems.
2.2 What is BT Wholesale Onramp not intended for?
Onramp does not:
a) Provide you with a full end-to-end testing environment
b) Faithfully replicate the performance in the production environment
c) Exhaustively test possible data values and error conditions sent to or returned by BT
Wholesale
d) Facilitate load or performance testing
e) Validate specific data such as phone numbers (DN - Directory Numbers), Post
Codes (PCs) or Service IDs.
Issue 1.3 – 05th September, 2014
Copyright British Telecommunications plc 2012
Page 5 of 29
Web Services Access Guide
2.3 How long will you use Onramp for?
The testing phase on Onramp systems depends on the complexity of your management and
development processes. Fundamental connectivity testing can take anything from one day to over
a month and message testing may take days or months. However, in normal circumstances the
set-up on the Wholesale side should take no more than four working days from the provision of
details.
The main causes of any delays are due to:
Incorrectly-configured digital and Certificate Authority (CA) certificates on web servers
Firewall and proxy setup problems
Development and integration with your backend systems
Issue 1.3 – 05th September, 2014
Copyright British Telecommunications plc 2012
Page 6 of 29
Web Services Access Guide
3. Setting up the Gateway
The Onramp Customer Support team, known as PEM
( Team can be contacted at
wholesale.pem@bt.com, may ask you for the following details as part of their task of building up
your “Client Profile”. The interface-specific parameters and requirements are also detailed below.
3.1 BT Wholesale side set up
All you need to do is tell us more about your organisation and requirements. The PEM Team will
need the following information to set you up:
Name of the your organisation
This will be used for creating your profile under BT Wholesale community: this was arranged when
you originally registered your interest with your BT Wholesale Account Manager.
Your DUNS number
The Data Universal Numbering System (DUNS) number is a unique identifier for your
organisation, issued globally by Dun and Bradstreet. Your Company Secretary (or equivalent)
should hold a record of this information. Although you cannot search for it online, you can verify
your Data Universal Numbering System (DUNS) number at:
http://express.dnbsearch.com/advFind.asp
Look for the option “Search by Data Universal Numbering System (DUNS) Number”, enter your
company’s 9-digit number and press “Search” to see the validated result.
Your URL
You can provide an URL with default port 443 to which the BT Wholesale will send the
asynchronous Notification messages. This is needed both for Onramp testing and on Live.
Your IP addresses
These are the Internet Facing IP Addresses from which the requests to the BT Wholesale
Onramp would originate.
Your client certificate
The digital certificate issued from BT Wholesale Northside - G2 CA certificate is required for
mutual authentication. And note that same certificate should be used when you move on to
production (LIVE) Web Services Gateway. Complete instructions for applying for this certificate
are detailed later in this document.
Your BT Account Manager
This is the member of the BT Account Team who confirmed your access to the BT Wholesale
Web Services Gateway. The PEM team will liaise with your Account Manager as necessary.
Your technical contact’s name, email and phone number
This is the person in your organisation whom the PEM team will contact directly to discuss any
technical issues.
Issue 1.3 – 05th September, 2014
Copyright British Telecommunications plc 2012
Page 7 of 29
Web Services Access Guide
The technology used to build your Gateway
Depending on the resources and set up of your organisation, you can, if you prefer, work in
partnership with a third party team or individuals you appoint.
Your preferred testing date
Setting up an Onramp test can take as little as a week. However, everyone’s circumstances are
unique and our PEM Team will be well placed to discuss a realistic schedule with you. As long as
the lead times are realistic, we will work with you to ensure we begin testing by the date you have
chosen.
You preferred production date
As you will see, how long the Onramp tests last depends more on what tests you have chosen to
carry out rather than any fixed lead times required by us. If you have a proposed Production date
in mind, please let us know, but note that this is not a mandatory requirement at this stage. Your
Production date can be agreed later with the PEM Team as we work together to progress for
moving on to production gateway.
Your production support contact’s details
As our customers move into the In-Life phase known as “Production”, many prefer to appoint a
different contact to monitor and maintain their systems. Please enter the details of the person we
should contact in case of problems with your Production system.
3.2 Your Onramp setup
Onramp will accept and respond synchronously to messages at below given URLs for the various
diagnostic services available.
BT Data Universal Numbering System (DUNS) number: 232510151
URL for 20CN services:
https://www.wsr-onrampws-robt.bt.co.uk:5443/BTW_KnowledgeBaseDiag
URL for 21CN services:
https://www.wsr-onrampws-robt.bt.co.uk:5443/21cnkbd4.0/KnowledgeBasedDiagnostics
It is expected that a CP will need to arrange firewall access for access to/from the OnRamp Gateway:
193.113.8.226 and 193.113.8.225 is for traffic coming from BT to Communication Provider over
port 443.
193.113.8.224 is for traffic coming from the Communication Provider to BT over port 5443.
Issue 1.3 – 05th September, 2014
Copyright British Telecommunications plc 2012
Page 8 of 29
Web Services Access Guide
4. Security & Certificate Information
A number of security measures need to be in place in order to use the BT Wholesale Web
Services Gateway, both during the Onramp Test phase and in Production.
Before you can access our online services you need to have an appropriate firewall and digital
certificate.
If you are in any doubt, please feel free to discuss any existing certificates with our PEM Team.
4.1 Downloading a new digital certificate
A client certificate will carry out the entire basic authentication you require but is not tied to a
Domain Name System (DNS) name and IP address. You can transfer this certificate from one
computer to another as and when required.
You may apply for a client certificate using this link:
https://onsite.trustwise.com/services/BTGroupPlcNorthsideG2/digitalidCenter.htm
Northside_G2_Digital
_Certificate_Instruction_Guide.pptx
With the correct digital certificate downloaded, you need to carry out the following activities:
1. Back up the entire digital certificate and keep it safe as you would do for any other company
asset.
2. If you are changing to a new system, you will need to export the certificate (with private key,
type .pfx) to move it to a separate server box.
3. In these circumstances, you will also need to change the certificate’s format depending on
your requirements (a visit to www.openssl.org may prove helpful).
4. You should also move the Certificate Authority to maintain the evidence of trust (by using the
“export all certificates in path” command).
IMPORTANT:
1) We recommend, and are only able to support, the use of latest version of Internet
Explorer (versions from and above 7.0) for installation and extraction of the certificate
to and from your computer. IE 11 has compatibility issues. You will have to add
trustwise.com to the compatibility settings in IE11. (Tools Compatibility View
Settings)
2) The digital certificate cannot be enrolled/installed in a Linux machine. So, you will have
to use a Windows system for the same.
3) The digital certificate also cannot be enrolled/installed in Google Chrome Browser.
Issue 1.3 – 05th September, 2014
Copyright British Telecommunications plc 2012
Page 9 of 29
Web Services Access Guide
5. Onramp testing
5.1 Introduction to Onramp for KBD
Communication between you and Onramp is by requests from your systems and synchronous
responses & asynchronous notifications from BT. You can carry out as many tests as your business
requires. This may depend on the size and complexity of your organisation.
The Onramp gateway will generate synchronous responses along with the Asynchronous
notifications for the corresponding request messages.
Your gateway sends a request over HTTPS to BT Wholesale W/S gateway.
5.2 Messages from you to Onramp
Messages are sent to sentry Onramp Knowledge Based Diagnostics (KBD) by an https POST to
URL:
20CN services:
https://www.wsr-onrampws-robt.bt.co.uk:5443/BTW_KnowledgeBaseDiag
21CN services:
https://www.wsr-onrampws-robt.bt.co.uk:5443/21cnkbd4.0/KnowledgeBasedDiagnostics
5.2.1 A look at http
The following example is for XML Diagnostics.
POST /RequestTest HTTP/1.1
Host: www.wsr-onrampws-robt.bt.co.uk
SOAPAction: "RequestTest"
Content-Type: type="text/xml";
Content-length: 1234
Issue 1.3 – 05th September, 2014
Copyright British Telecommunications plc 2012
Page 10 of 29
Web Services Access Guide
5.2.2 About XML
Now the XML
Additional elements and attributes may or may not be acceptable. Part of the purpose of
Onramp is to ensure that your software does not add any extra data, which causes conflicts
with the software used by Onramp – if it doesn't conflict, feel free to do as you will but Onramp
will guarantee that the software will not conflict at some time in the future.
Few standards are so simple that they can be implemented without potential problems of
interpretation when interacting with other implementations so testing is essential. In other
interfaces even the placing of comments has been known to cause problems; that “SHOULD
NOT” be so but it is unwise to assume it “WILL NOT” be so.
The BT Wholesale gateway uses XML business payloads that make use of namespaces: use
of namespace aware XML software is strongly recommended. Explicit use of namespace
identifiers is less open to misunderstanding than implicit usage and is likely to improve
interoperability, whatever the standards say about equivalence. The namespace identifier
values should not be critical, but this will not be guaranteed.
5.2.3 Sample Knowledge Based Diagnostics (KBD) example with SOAP
The BT Wholesale Knowledge Based Diagnostics (KBD) Vordel Gateway uses XML business payloads that make use
of namespaces: therefore we strongly recommend that you use namespace-aware XML software. This is because
explicit use of namespace identifiers is less open to misunderstanding than implicit usage. It is also likely to improve
interoperability, irrespective of claims about equivalence. The namespace identifier values shouldn’t be critical, but we
can’t guarantee this unfortunately.
Here is a SOAP example for XMLKnowledge Based Diagnostics (KBD) Initiate Request:
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body><rul:invokerules xmlns:rul="http://rules.kmtool.bt.com">
<rul:arg0><![CDATA[<kbdInitiateRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation=" B2B-KBD.xsd">
<kmTestHeader>
<MessageId>CP1_MSG1</MessageId>
<!--MessageId:- The unique identifier is generated by the CP party forrequests. -->
<TestDate>08/07/2008 07:34:15</TestDate>
<!--date format DD/MM/YYYY HH:MM:SS The date that a request (KBDInitiateRequest, KBDQueryRequest,
KBDTerminateRequest) was created by the CP. -->
<TestReference>
<ConductorReference>
<InvokeIdentifier>
<RefNum>CP1_Ref1</RefNum>
<!-- RefNum unique identifier of the test being requested. It must be globally unique and must
be present in all messages. -->
</InvokeIdentifier>
</ConductorReference>
</TestReference>
<TestParty>
<ConductorParty>
<Party PartyID="987654321" AgencyID="DUNS">
<!-- Dun’s id of CP -->
<TestContact>
<DetailedContact>
<!-- Details of the CP contact performing test -->
Issue 1.3 – 05th September, 2014
Copyright British Telecommunications plc 2012
Page 11 of 29
Web Services Access Guide
<ContactName>Michael Jackson</ContactName>
<Telephone>02071059053</Telephone>
<TelephoneExtension>4777</TelephoneExtension>
<Email>Michal.Jackson@Neverland.com</Email>
<Title>Mr</Title>
<FirstName>Michael</FirstName>
<Initials>MJ</Initials>
</DetailedContact>
</TestContact>
</Party>
</ConductorParty>
<PerformerParty>
<Party PartyID="232510151" AgencyID="DUNS">
<!-- Dun’s id of BT Wholesale-->
</Party>
</PerformerParty>
</TestParty>
</kmTestHeader>
<kmToolMessage>
<controlNode>
<userRequest>INITIATE</userRequest>
<KBDInstance>NEW</KBDInstance>
<!-- It should be set to INITIATE / INITIATE_SUPERLITE for kbdinitiate request -->
</controlNode>
<customer>
<circuitID>CBUK30053780</circuitID>
<!-- Pass cbuk to be tested here or serviced or telephone number in respective tags.
<serviceId></serviceId>
<telNo></telNo> -->
</customer>
<customerQueries> <!- Mandatory for INITIATE but not required for INITIATE_SUPERLITE-->
<question>
<questionId>2:1</questionId>
<sequenceId>1</sequenceId>
<groupId>Initiate:1</groupId>
<isRequired>false</isRequired>
<questionStr>Product Type</questionStr>
<actualAnswer></actualAnswer>
<questionGroupTimestamp>2012-10-01T12:00:00</questionGroupTimestamp>
<userMessage>Answer Required</userMessage>
<reanswerFlag>false</reanswerFlag>
<expectedAnswers>
<options>
<value>WBC</value>
<valueType />
<childQIDs>
<questionID>3:1</questionID>
<isMandatory>true</isMandatory>
</childQIDs>
</options>
</expectedAnswers>
</question>
<question>
<questionId>3:1</questionId>
<sequenceId>1</sequenceId>
<groupId>Initiate:1</groupId>
<isRequired>false</isRequired>
<questionStr>What type of KBD test do you want to run?</questionStr>
<actualAnswer></actualAnswer>
Issue 1.3 – 05th September, 2014
Copyright British Telecommunications plc 2012
Page 12 of 29
Web Services Access Guide
<questionGroupTimestamp>2012-10-01T12:00:00</questionGroupTimestamp>
<userMessage>Answer Required</userMessage>
<reanswerFlag>false</reanswerFlag>
<expectedAnswers>
<options>
<value>Intrusive</value>
<valueType />
<childQIDs>
<questionID>4:1</questionID>
<isMandatory>true</isMandatory>
</childQIDs>
</options>
<options>
<value>Non Intrusive</value>
<valueType />
</options>
</expectedAnswers>
</question>
<question>
<questionId>4:1</questionId>
<sequenceId>1</sequenceId>
<groupId>Initiate:1</groupId>
<isRequired>false</isRequired>
<questionStr>Please select the type of problem being experienced</questionStr>
<actualAnswer></actualAnswer>
<questionGroupTimestamp>2012-10-01T12:00:00</questionGroupTimestamp>
<userMessage>Answer Required</userMessage>
<reanswerFlag>false</reanswerFlag>
<expectedAnswers>
<options>
<value>Performance</value>
<valueType />
<childQIDs>
<questionID>8:1</questionID>
<isMandatory>false</isMandatory>
</childQIDs>
</options>
<options>
<value>Connection</value>
<valueType />
<childQIDs>
<questionID>8:1</questionID>
<isMandatory>false</isMandatory>
</childQIDs>
</options>
<options>
<value>TV Connect Problem</value>
<valueType />
<childQIDs>
<questionID>7:1</questionID>
<isMandatory>true</isMandatory>
</childQIDs>
</options>
<options>
<value>IPv6</value>
<valueType />
<childQIDs>
<questionID>5:1</questionID>
<isMandatory>true</isMandatory>
Issue 1.3 – 05th September, 2014
Copyright British Telecommunications plc 2012
Page 13 of 29
Web Services Access Guide
</childQIDs>
</options>
<options>
<value>Real Time QOS</value>
<valueType />
<childQIDs>
<questionID>5:1</questionID>
<isMandatory>true</isMandatory>
</childQIDs>
</options>
<options>
<value>Wholesale Content Connect</value>
<valueType />
<childQIDs>
<questionID>5:1</questionID>
<isMandatory>true</isMandatory>
</childQIDs>
</options>
</expectedAnswers>
</question>
<question>
<questionId>5:1</questionId>
<sequenceId>1</sequenceId>
<groupId>Initiate:1</groupId>
<isRequired>true</isRequired>
<questionStr>To run an Enhanced TAM Network Check provide the End User logon
Username. Note: This is mandatory for IPV6 issues. To run a standard TAM check enter NA (not case
sensitive).</questionStr>
<actualAnswer></actualAnswer>
<questionGroupTimestamp>2012-10-01T12:00:00</questionGroupTimestamp>
<userMessage>Answer Required</userMessage>
<reanswerFlag>false</reanswerFlag>
<expectedAnswers>
<options>
<value></value>
<valueType />
<childQIDs>
<questionID>6:1</questionID>
<isMandatory>true</isMandatory>
</childQIDs>
</options>
</expectedAnswers>
</question>
<question>
<questionId>6:1</questionId>
<sequenceId>1</sequenceId>
<groupId>Initiate:1</groupId>
<isRequired>true</isRequired>
<questionStr>To run an Enhanced TAM Network Check provide the End User logon
Password Note: This is mandatory for IPV6 issues. To run a standard TAM check enter NA (not case
sensitive).</questionStr>
<actualAnswer></actualAnswer>
<questionGroupTimestamp>2012-10-01T12:00:00</questionGroupTimestamp>
<userMessage>Answer Required</userMessage>
<reanswerFlag>false</reanswerFlag>
<expectedAnswers>
<options>
<value></value>
<valueType />
Issue 1.3 – 05th September, 2014
Copyright British Telecommunications plc 2012
Page 14 of 29
Web Services Access Guide
<childQIDs>
<questionID>9:1</questionID>
<isMandatory>true</isMandatory>
</childQIDs>
</options>
</expectedAnswers>
</question>
<question>
<questionId>7:1</questionId>
<sequenceId>1</sequenceId>
<groupId>Initiate:1</groupId>
<isRequired>true</isRequired>
<questionStr>Please select the type of problem being experienced with the TV
Connect service</questionStr>
<actualAnswer></actualAnswer>
<questionGroupTimestamp>2012-10-01T12:00:00</questionGroupTimestamp>
<userMessage>Answer Required</userMessage>
<reanswerFlag>false</reanswerFlag>
<expectedAnswers>
<options>
<value>Performance</value>
<valueType />
<childQIDs>
<questionID>8:1</questionID>
<isMandatory>true</isMandatory>
</childQIDs>
</options>
<options>
<value>Channel access</value>
<valueType />
<childQIDs>
<questionID>10:1</questionID>
<isMandatory>true</isMandatory>
</childQIDs>
</options>
</expectedAnswers>
</question>
<question>
<questionId>8:1</questionId>
<sequenceId>1</sequenceId>
<groupId>Initiate:1</groupId>
<isRequired>true</isRequired>
<questionStr>Is the problem you are experiencing Permanent or
Intermittent?</questionStr>
<actualAnswer></actualAnswer>
<questionGroupTimestamp>2012-10-01T12:00:00</questionGroupTimestamp>
<userMessage>Answer Required</userMessage>
<reanswerFlag>false</reanswerFlag>
<expectedAnswers>
<options>
<value>Permanent</value>
<valueType />
<childQIDs>
<questionID>5:1</questionID>
<isMandatory>true</isMandatory>
</childQIDs>
</options>
<options>
<value>Intermittent</value>
Issue 1.3 – 05th September, 2014
Copyright British Telecommunications plc 2012
Page 15 of 29
Web Services Access Guide
<valueType />
<childQIDs>
<questionID>5:1</questionID>
<isMandatory>true</isMandatory>
</childQIDs>
</options>
</expectedAnswers>
</question>
<question>
<questionId>9:1</questionId>
<sequenceId>1</sequenceId>
<groupId>Initiate:1</groupId>
<isRequired>true</isRequired>
<questionStr>Is the BET equipment powered ON?</questionStr>
<actualAnswer></actualAnswer>
<questionGroupTimestamp>2012-10-01T12:00:00</questionGroupTimestamp>
<userMessage>Answer Required</userMessage>
<reanswerFlag>false</reanswerFlag>
<expectedAnswers>
<options>
<value>Yes</value>
<valueType />
</options>
<options>
<value>No</value>
<valueType />
</options>
<options>
<value>Don’t Know</value>
<valueType />
</options>
</expectedAnswers>
</question>
<question>
<questionId>10:1</questionId>
<sequenceId>1</sequenceId>
<groupId>Initiate:1</groupId>
<isRequired>true</isRequired>
<questionStr>Is the customer able to see the ‘free to view’ IPTV test
channel?</questionStr>
<actualAnswer></actualAnswer>
<questionGroupTimestamp>2012-10-01T12:00:00</questionGroupTimestamp>
<userMessage>Answer Required</userMessage>
<reanswerFlag>false</reanswerFlag>
<expectedAnswers>
<options>
<value>Yes</value>
<valueType />
<childQIDs>
<questionID>8:1</questionID>
<isMandatory>true</isMandatory>
</childQIDs>
</options>
<options>
<value>No</value>
<valueType />
<childQIDs>
<questionID>11:1</questionID>
<isMandatory>true</isMandatory>
Issue 1.3 – 05th September, 2014
Copyright British Telecommunications plc 2012
Page 16 of 29
Web Services Access Guide
</childQIDs>
</options>
</expectedAnswers>
</question>
<question>
<questionId>11:1</questionId>
<sequenceId>1</sequenceId>
<groupId>Initiate:1</groupId>
<isRequired>true</isRequired>
<questionStr>Can you confirm that all end user checks have been performed, the
customer is directly connected to the home hub, there is no interference from other devices and the customer has all
the correct set top box entitlement?</questionStr>
<actualAnswer></actualAnswer>
<questionGroupTimestamp>2012-10-01T12:00:00</questionGroupTimestamp>
<userMessage>Answer Required</userMessage>
<reanswerFlag>false</reanswerFlag>
<expectedAnswers>
<options>
<value>Yes</value>
<valueType />
<childQIDs>
<questionID>8:1</questionID>
<isMandatory>true</isMandatory>
</childQIDs>
</options>
<options>
<value>No</value>
<valueType />
<childQIDs>
<questionID>8:1</questionID>
<isMandatory>true</isMandatory>
</childQIDs>
</options>
</expectedAnswers>
</question>
</customerQueries>
</kmToolMessage>
</kbdInitiateRequest>]]></rul:arg0>
</rul:invokerules>
</soapenv:Body></soapenv:Envelope>
5.2.4 Curl connectivity
A simple end-to-end connectivity test can be carried out using curl (you can download an SSL
enabled version - available for most platforms - from http://curl.haxx.se if you do not already have
it). The command to use will be based on this version which works in Windows (Linux needs extra
escaping)
curl -i -k -E certname.pem:password -x proxy.whatever:8080 --data-binary “@testWS.txt” -H "Content-Type:
text/xml; charset=\"utf-8\"" https://www.wsr-onrampws-robt.bt.co.uk:5443/WBC_T2R_116
-E specifies your client certificate required by Wholesale for authentication
-x specifies your proxy; leave out if you are not using one
-k turns off server verification
use of quotes and escape characters may be OS dependent so the above is to be treated as a guide only; refer to curl
documentation as a check, and be prepared to try a different version in case of trouble (that sorted out problems on
more than one occasion)
Issue 1.3 – 05th September, 2014
Copyright British Telecommunications plc 2012
Page 17 of 29
Web Services Access Guide
testWS.txt is a text file containing:
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope mlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body><rul:invokerules xmlns:rul="http://rules.kmtool.bt.com">
<rul:arg0><![CDATA[<<kbdQueryRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="F:\Dipali\T&amp;D\KMTool\21CN\WBC-T2R-538\CR0055\KBD-B2B.xsd">
<kmTestHeader>
<MessageId>CP1_MSG2</MessageId>
<!--MessageId:- The identifier is generated by the CP party for kbdQueryRequest-->
<TestDate>08/07/2008 07:34:25</TestDate>
<!--date format DD/MM/YYYY HH:MM:SS The date that a request (KBDInitiateRequest, KBDQueryRequest,
KBDTerminateRequest) was created by the CP. -->
<TestReference>
<ConductorReference>
<InvokeIdentifier>
<RefNum>CP1_Ref1</RefNum>
<!-- same as in kbdInitiateRequest . -->
</InvokeIdentifier>
</ConductorReference>
<PerformerReference>
<InvocationIdentifier>
<RefNum>KBD_CaseId1</RefNum>
<!-- RefNum unique identifier of the test. It must be unique test identifier in KBD and must be present in all
messages. -->
</InvocationIdentifier>
</PerformerReference>
</TestReference>
<TestParty>
<ConductorParty>
<Party PartyID="987654321" AgencyID="DUNS">
<!-- Dun’s id of CP -->
<TestContact>
<DetailedContact>
<!-- Details of the CP contact performing test -->
<ContactName>Michael Jackson</ContactName>
<Telephone>02071059053</Telephone>
<TelephoneExtension>4777</TelephoneExtension>
<Email>Michal.Jackson@Neverland.com</Email>
<Title>Mr</Title>
<FirstName>Michael</FirstName>
<Initials>MJ</Initials>
</DetailedContact>
</TestContact>
</Party>
</ConductorParty>
<PerformerParty>
<Party PartyID="232510151" AgencyID="DUNS">
<!-- Dun’s id of BT Wholesale-->
</Party>
</PerformerParty>
</TestParty>
</kmTestHeader>
<kmToolMessage>
<controlNode>
<userRequest>RESUME</userRequest>
<!-- set to RESUME for KBDQuery -->
</controlNode>
<customer>
<circuitID>CBUK30053780</circuitID>
</customer>
Issue 1.3 – 05th September, 2014
Copyright British Telecommunications plc 2012
Page 18 of 29
Web Services Access Guide
1.
2.
3.
-->
<!-- CP to populate:
The actualAnswer to the valid answer from the option provided by KBD
sequenceId should be populated by CP to determine the path user has taken while answering question group
While submitting question group back to KBD questionGroupTimestamp should be populated by CP
<customerQueries>
<question>
<questionId>28:1</questionId>
<sequenceId>1</sequenceId>
<!-- sequenceId should be populated with sequence the user is answering the questions
within the question group -->
<groupId>BIP2</groupId>
<isRequired>true</isRequired>
<questionStr>The user has a working session currently. We did not find any problem
in the network. Do you still want to continue with analysis?</questionStr>
<actualAnswer>NO</actualAnswer>
<!-- actualAnswer should be populated with one of the valid options provided by KBD. If a
Date is required then sent back date in required format. If some action is required complete that action and continue
with flow -->
<questionGroupTimestamp>08/07/2008 07:34:25</questionGroupTimestamp>
<!-- questionGroupTimestamp should be populated with timestamp when the question group
is submitted. DD/MM/YYYY hh:mm:ss -->
<userMessage>Answer Required</userMessage>
<reanswerFlag>false</reanswerFlag>
<expectedAnswers>
<options>
<value>YES</value>
<valueType/>
</options>
<options>
<value>NO</value>
<valueType/>
</options>
</expectedAnswers>
</question>
</customerQueries>
</kmToolMessage>
</kbdQueryRequest>]]></rul:arg0></rul:invokerules>
</soapenv:Body></soapenv:Envelope>
5.2.5 WsTransport Web Service definition for Knowledge Based Diagnostics
(KBD)
To receive results from BT, you will need to host this Web Service Definition Language (WSDL).
Issue 1.3 – 05th September, 2014
Copyright British Telecommunications plc 2012
Page 19 of 29
Web Services Access Guide
5.2.6 What are the Knowledge Based Diagnostics (KBD) Services and what
XML goes with them?
The diagnostic services available as Knowledge Based Diagnostics (KBD)Web Service are:
KMWSTestService
The Business services falling under this diagnostic service are as follows
For 20CN and Old 21CN KBD:
Service name
Initiate Request
Query Request
Terminate Request
Resend Request
PostDiagRequest
TestHistoryRequest
Root node (Request/Response Type)
kbdInitiateRequest
kbdQueryRequest
kbdTerminateRequest
kbdResendRequest
kbdPostDiagRequest
kbdTestHistoryRequest
If the QueryNotification sent from Knowledge Based Diagnostics (KBD) to you is lost a message
loop may occur where your system will be waiting indefinitely for a message from KBD, and the
KBD will be in turn waiting for the QueryRequest from you. To get round this you can use the resend option.
Using KBDResendRequest message you can get the Knowledge Based Diagnostics (KBD) to resend the last QueryNotification or KBDFinalResultNotification.
Please note, however, you can only use the ResendRequest twice for a QueryNotification or
FinalQueryNotification.
For New 21CN KBD:
Service name
Initiate Request
TestHistoryRequest
Root node (Request/Response Type)
kbdInitiateRequest
kbdTestHistoryRequest
5.3 Messages from Onramp to you
5.3.1 Some more http
HTTP/1.1 415 Unsupported Media Type
Date: Mon, 07 Aug 2006 16:59:40 GMT
Content-Type: text/xml; charset="utf-8"
Server: Forum Sentry
Content-Length: 794
<soap:Envelope xmlns:soap=”....
...
</soap:Envelope
Issue 1.3 – 05th September, 2014
Copyright British Telecommunications plc 2012
Page 20 of 29
Web Services Access Guide
You should get an http 200 OK response, but there will be occasions when you don't:
You may get a security failure (e.g. 403)
You may get something else (e.g. 500)
You may get an error (e.g. if you specify an incorrect path in the URL.e.g. with your Data
Universal Numbering System (DUNS) instead of BT)
You may get a timeout exception when there is no connectivity.
You may fail to connect at all (like any system, there will be outages - normally scheduled
and communicated in advance)
5.3.2 Response Business payload for Knowledge Based Diagnostics (KBD)
If a valid request reaches Onramp, we will send back an Accepted/rejected XML response
depending on your chosen processing information (which will come from BT Wholesale
Knowledge Based Diagnostics (KBD) Sentry).
The response would be different based on the type of Request:
For 20CN and Old 21CN KBD:
Type of Request
Initiate Request
Query Request
Terminate Request
Resend Request
Resend Request
PostDiag Request
TestHistory Request
Response
InitiateAccepted/InitiateRejected and Notification
QueryAccepted/QueryRejected and Notification
TerminateAccepted/TerminateRejected
ResendAccepted/ResendRejected
Query Notification or KBDFinalResultNotification
PostDiagAccepted/PostDiagRejected
TestHistoryAccepted/TestHistoryRejected
For New 21CN KBD:
Type of Request
Initiate Request
TestHistory Request
Response
InitiateAccepted/InitiateRejected and
KBDFinalResultNotification
TestHistoryAccepted/TestHistoryRejected and
KBDTestHistoryResultNotification
If we get an invalid request you will receive an as explained in the next section.
5.3.3 Exceptions
It is possible that your input will be rejected with an AcceptanceAcknowledgementException (when
the Gateway passes your input to other systems but they either reject it before processing or fail to
return it). This will actually be presented as a SOAP Exception with the exception string set to:
“BTWHOLESALE HAS EXPERIENCED A PROBLEM”
Indeed, all problems should be returned as SOAP faults. Sometimes, but not always, they will
contain sufficient information for you to understand the cause of the problem:
Issue 1.3 – 05th September, 2014
Copyright British Telecommunications plc 2012
Page 21 of 29
Web Services Access Guide
Security Exception
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<soap:Fault>
<faultcode>soap:Server</faultcode>
<faultstring>BTWHOLESALE HAS EXPERIENCED A PROBLEM WITH YOUR REQUEST SEE BELOW FOR
TECHNICAL REASON :- Unauthorized request</faultstring>
<detail>
<fs:Detail
xmlns:fs="http://www.forumsystems.com/2004/04/soap-fault-detail">
<fs:SystemName>AP001STY01</fs:SystemName>
<fs:User>987654301D</fs:User>
<fs:Policy>Line Characteristic WSDL Policy</fs:Policy>
<fs:TaskList></fs:TaskList>
<fs:Task></fs:Task>
</fs:Detail>
</detail>
</soap:Fault>
</soap:Body>
</soap:Envelope>
The PEM Team will usually be able to see these in logs. Assistance will be
given by suggesting an explanation and where changes may be needed.
5.4 Onramp exit criteria
These are the set of tests which need to be done on the Onramp systems before moving to the
live environment. The Live server set up starts after the Onramp signoff.
You simply have to fill in the Quality Gate report (with the details of the Onramp tests performed)
and send this to the PEM Team.
They will then verify the tests performed and provide the signoff from Onramp.
Please Note: Completing the Quality Gates only proves that your system is capable of handling
more than one and also all kinds of request and response messages simultaneously. The Quality
Gate does not constitute to complete functional testing.
Issue 1.3 – 05th September, 2014
Copyright British Telecommunications plc 2012
Page 22 of 29
Web Services Access Guide
The following sections describe separate scenarios for XML Knowledge Based Diagnostics (KBD).
5.4.1 Scenarios for 20CN Knowledge Based Diagnostics (KBD)
The following 8 test cases are mandatory and must be passed in order to completeKnowledge Based Diagnostics
(KBD)Diagnostics Quality Gate.
Scenario 1: Knowledge Based Diagnostics (KBD) Initiate Request Accepted
Sender
1 CP
2 BT
3 BT
Message Type
kbdInitiateRequest
A response XML indicating
that kbdInitiate Request is
Accepted.
After 1 min Query
Notification will be sent
Scenario 2: Knowledge Based Diagnostics (KBD) Request Query Accepted
Sender
1 CP
2 BT
3 BT
Message Type
kbdQueryRequest
A response XML indicating
the Request Query
Accepted.
After 1 min Final Result
Notification will be sent
Scenario 3: Knowledge Based Diagnostics (KBD) Request Terminate Accepted
Sender
Message Type
1 CP
kbdTerminateRequest
2 BT
A response XML indicating
the Request Terminate
Accepted.
Scenario 4: Knowledge Based Diagnostics (KBD) Request Resend Accepted
Sender
1 CP
2 BT
3 BT
Message Type
kbdResendRequest
A response XML indicating
that kbdResend Request is
Accepted.
Final Result Notification will
be sent
Issue 1.3 – 05th September, 2014
Copyright British Telecommunications plc 2012
Page 23 of 29
Web Services Access Guide
Scenario 5: Knowledge Based Diagnostics (KBD) Request Query Test History Accepted
Sender
Message Type
1 CP
kbdQueryRequest
2 BT
A response XML indicating
the Request Query Test
History Accepted.
Scenario 6: Knowledge Based Diagnostics (KBD) Request KBDPostDiag Accepted
Sender
Message Type
1 CP
kbdPostDiagRequest
2 BT
A response XML indicating
the Request PostDiag
Accepted.
5.4.2 Scenarios for Old 21CN Knowledge Based Diagnostics (KBD):
Scenario 1: Knowledge Based Diagnostics (KBD) Initiate Request
Sender
Message Type
1 CP
KBDInitiateRequest
2 KBD
KBDInitiateAccepted
Scenario 2: Knowledge Based Diagnostics (KBD) Resume Request
Sender
Message Type
1 CP
KBDQueryRequest
2 KBD
KBDQueryAccepted
Scenario 3: Knowledge Based Diagnostics (KBD)Terminate Request
Sender
Message Type
1
CP
KBDTerminateReques
t
2
KBD
KBDTerminateAccept
ed
Issue 1.3 – 05th September, 2014
Copyright British Telecommunications plc 2012
Page 24 of 29
Web Services Access Guide
Scenario 4: Knowledge Based Diagnostics (KBD) Resend Request
Sender
Message Type
1
CP
KBDResendRequest
2
KBD
KBDResendAccepted
Scenario 5: Knowledge Based Diagnostics (KBD) Post Diag Request
Sender
Message Type
1 CP
kbdPostDiagRequest2
1C
2 KBD
kbdPostDiagAccepted
21C
Scenario 6: Knowledge Based Diagnostics (KBD) TestHistoryRequest
Sender
Message Type
1 CP
kbdTestHistoryReques
t
2 KBD
kbdTestHistoryAccept
ed21C
5.4.3 Scenarios for New 21CN Knowledge Based Diagnostics (KBD):
Scenario 1: Knowledge Based Diagnostics (KBD) Initiate Request
Sender
Message Type
1 CP
KBDInitiateRequest
2 KBD
KBDInitiateAccepted
Scenario 2: Knowledge Based Diagnostics (KBD) TestHistoryRequest
Sender
Message Type
1 CP
kbdTestHistoryReques
t
2 KBD
kbdTestHistoryAccept
ed21C
5.5 Message handling
Once connection is established, the wrapping, unwrapping, acknowledgements and receipting need
to be demonstrated. This is done by simulating business transactions. You should test ALL the
services which you want to use it on Production.
Issue 1.3 – 05th September, 2014
Copyright British Telecommunications plc 2012
Page 25 of 29
Web Services Access Guide
6. Pilot and live phases
6.1 Pilot
The PEM Team will sign off your Gateway after ensuring that your system will not negatively
affect the Production platform in terms of incorrect, missing or excess messages. Then you will be
given access to the live Production platform.
After this, the PEM ( Team will confirm any operational changes to your IP address and your URL.
We will then carry out any final checks on your certificate configuration and, , and send you an
email to tell you when the requested services via the Web Services Gateway will be approved.
In technical terms, the only changes involved for going live – on an agreed date after the PEM Team
have confirmed any operational changes for KBD to your IP address/URL/certificate configuration
are:
KBD
20CN:
https://www.ws.wholesale.bt.com:5443/BTW_KnowledgeBaseDiag
21CN:
https://www.ws.wholesale.bt.com:5443/21cnkbd4.0/KnowledgeBasedDiagnostics
You will need to arrange firewall access for access to/from the Live Gateway:
193.113.8.225 and 193.113.4.228 is for traffic coming from BT to Communication Provider over
port 443.
193.113.8.223 and 193.113.4.57 is for traffic coming from the Communication Providers to BT over.
Production is the first time that:
Your organisation will be connecting to the real back-end systems of BT Wholesale
You will be able to test specific details of lines, exchanges and so on
Your requests will get full validation against all back end systems which you did not have
during the Onramp testing
You get back the full range of Notifications at times reflecting the full business processes
and system performance
Any TimeToPerform constraints will be applied
Your systems will be processing more than limited test data returned from BT.
Once you are on live on the production gateway. The PEM Team will support you for a two week
trial period if you are an existing customer and for four (4) weeks if you are a new customer. If you
have any issues while placing orders against the live system please get in touch with the PEM
Team at wholesale.pem@bt.com .
Issue 1.3 – 05th September, 2014
Copyright British Telecommunications plc 2012
Page 26 of 29
Web Services Access Guide
Within this week trial period, you will need to:
Fill in the Test Plan as provided to you by your CRM with the details of all the tests
performed and return it to your CRM. Kindly contact the PEM Team
(wholesale.pem@bt.com) if you face any issue during this period.
Once you have completed testing for all the services, you will need to inform the PEM
Team about the completion of tests.
These tests will be similar to those of the Onramp tests you had carried out earlier (in terms
of various services and XMLs used).
6.2 Live
If you face any issues after the two (or four) weeks of the trial period, you will need to contact our
first line of support at broadband.eco.admin@bt.com.
Issue 1.3 – 05th September, 2014
Copyright British Telecommunications plc 2012
Page 27 of 29
Web Services Access Guide
7. Glossary
BT
BTW
CA
TP
CUPID
DUNS
DNS
IP
OTA
SOAP
SSL
KBD
WS
WSDL
CP
ServiceId
British Telecommunications plc (not to be confused with business transaction)
BT Wholesale
Certificate Authority
Trading Partner (essentially same as Communications Provider or Service Provider)
Communications Provided Identifier (previously known as LOPID) from
Ofcom
(http://www.ofcom.org.uk/telecoms/ioi/numbers/numbers_administered/#cupid)
Data Universal Numbering System, a unique nine-digit sequence issued by Dun &
Bradstreet, recognised as the universal standard for identifying and keeping track of
over 100 million businesses worldwide.
Domain Naming System
Internet Protocol
Office of the Telecommunications Adjudicator
Simple Object Access Protocol
Secure Sockets Layer, a protocol developed by Netscape for transmitting private
documents via the Internet. SSL uses a cryptographic system that uses two keys to
encrypt data − a public key known to everyone and a private or secret key known only
to the recipient of the message. Both Netscape Navigator and Internet Explorer
support SSL, and many Web sites use the protocol to obtain confidential user
information, such as credit card numbers. By convention, URLs that require an SSL
connection start with https: instead of http.
Knowledge Base Diagnostic
Web Services
Web Service Definition Language
Communications Provider
The service identifier of the end user service. The format is BBEUnnnnnnnn, i.e. four
letters as shown followed by eight digits.
Issue 1.3 – 05th September, 2014
Copyright British Telecommunications plc 2012
Page 28 of 29
Web Services Access Guide
8. Document history
Issue
1.0
Date
04/02/2011
Author
PEM Team
1.1
30-09-2011
1.2
26/01/2012
1.3
05/09/2014
BT Wholesale
Team
BT Wholesale
Team
PEM Team
Comments
Combined 20CN and 21CNKnowledge Based
Diagnostics (KBD)User Guides to eliminate
duplication of information
Aligned to One-Voice & new BT
Wholesale.com guidelines & templates
Updated 20CN and 21CN WSDL files under
Section 5.2.5
Replaced Sentry IP addresses with Vordel
ones.
Replaced Sentry onramp URLs with Vordel
ones
Removed references to Processing
Instructions
Added information pertaining to 21CN New
KBD
Issue 1.3 – 05th September, 2014
Copyright British Telecommunications plc 2012
Page 29 of 29
