21C KBD Web Services On-Ramp User Guide
21CN Web Services KBD Diagnostics User Guide
Version 2.2
Getting the best from the Web-services Gateway
Legal notice
In confidence BTW and Contracted CPs
1
21C KBD Web Services On-Ramp User Guide
The contents contained in this document must not be forwarded or republished without the
written consent of BT Wholesale.
The 21C_KBD_Web_Services_User_Guide_v_2_2 Handbook changes regularly. Accordingly
extracts which are downloaded from this site and/or printed may become out of date. If users
retain such material and wish to refer to it at a later date, it is their responsibility to ensure that
it has not been superseded. BT can accept no responsibility for losses incurred due to out of
date information being used.
Copyright
© British Telecommunications plc, 2009. All rights reserved.
BT maintains that all reasonable care and skill has been used in the compilation of this
publication. However, BT shall not be under any liability for loss or damage (including
consequential loss) whatsoever or howsoever arising as a result of the use of this publication
by the reader, his servants, agents or any third party.
All third-party trademarks are hereby acknowledged.
 British Telecommunications plc
Registered Office 81 Newgate Street LONDON EC1A 7AJ
Registered in England no.1800000
Document History
Issue
1.0
2.0
2.1
Date
12/12/2008
29/06/2009
02/07/2009
Author
Krishna Reddy K
Chandranandan S
Chandranandan S
2.2
05/11/2009
Srilakshmi Gorur
Comments
Initial Draft.
Added 21C WBC Diagnostic services
Updated WSDL for WBC & review
comments from XML Design Team
Edited the guide to exclusively cater to 21C
KBD. Removed all WBC references in the
document. Proofread for better readability.
Changed nomenclature of customer from
TP to CP.
Enquiries and comments to Partner Enablement Management:
Email: b2b.pem@bt.com Tel: 01252696275
In confidence BTW and Contracted CPs
2
21C KBD Web Services On-Ramp User Guide
Contents
Introduction .............................................................................................................................. 4
What is On-Ramp For? ............................................................................................................ 4
1 Getting Started ...................................................................................................................... 5
1.1 Tell us more about your organisation and requirements ......................................... 5
1.2 On-Ramp set up details for KBD ................................................................................. 6
2 Security & Certificate Information ...................................................................................... 7
2.1 The BTW security requirements .................................................................................. 7
2.2 Digital Certificates ......................................................................................................... 7
2.3 Downloading a new Digital Certificate ........................................................................ 7
2.4 Sending us your Public Key ......................................................................................... 8
3 On-Ramp Testing .................................................................................................................. 9
3.1 Introduction to On-Ramp for KBD ............................................................................... 9
3.2 Duration of the On-Ramp tests .................................................................................. 10
3.3 Sending messages to On-Ramp ................................................................................ 10
3.3.1 A look at http .......................................................................................................... 11
3.3.2 About XML ............................................................................................................. 11
3.3.3 Sample KBD example with SOAP ......................................................................... 11
3.3.4 Curl Connectivity .................................................................................................... 13
3.3.5 WsTransport Web Service definition for KBD ........................................................ 15
3.3.6 What are the Diagnostic Services and what XML goes with them? ...................... 15
3.4 Receiving messages from On-Ramp ........................................................................ 15
3.4.1 Some more http ..................................................................................................... 15
3.4.2 Response Business payload for KBD .................................................................... 16
3.4.3 Exceptions ............................................................................................................. 16
3.5 Quality Gates ............................................................................................................... 17
3.5.1 Scenarios for XML KBD Diagnostics ..................................................................... 17
3.6 Message Handling ....................................................................................................... 19
4 In-Life Migration .................................................................................................................. 19
Glossary ................................................................................................................................. 20
In confidence BTW and Contracted CPs
3
21C KBD Web Services On-Ramp User Guide
About this User Guide
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.
Introduction
The Web Services Gateway is designed to allow BT Wholesale customers to buy and
manage a variety of telecommunication services electronically, by linking their own support
systems and processes with BT.
Knowledge Based Diagnostics (KBD) Service is implemented in aid of the BT Broadband
customer support process. The 21CN KBD Tool is invoked as a result of the customer facing
some technical issue with the service being provided. On the basis of information provided by
the Communications Provider (CP) and on the results returned by automatic testing tools and
other sources of information 21CN KBD Tool will suggest actions or ask more questions
which are relayed back to the CP. On the basis of the test data and answers to questions the
21CN KBD Tool will, if possible, provide a solution to the issue.
All KBD documents can be found on btwholesale.com at
http://www.btwholesale.com/pages/static/Applications/Faults/knowledge_based_diagnostics.h
tml
What is On-Ramp For?
Central to setting up your access to the WS Web Services Gateway are the tests PEM run
during what is termed the “On-Ramp” phase. These will allow you to:





Test connectivity to and from BT Wholesale via the Internet. As part of the tests, CP
will be able to check any proxies and firewalls that may be on the routes involved.
Create, convert and install any Digital Certificates that may be used to support secure
https connections.
Test business level messages for KBD passing across the WS Web Services
interface. For final testing, the messages will come from and go back to the CP’s
system.
Pave the way to accessing a host of additional online services as these become
available.
Implementation of web services.
Testing of the interface itself may be done using test stubs but final testing should use
Data generated by and integrated with the CP backend systems.
In confidence BTW and Contracted CPs
4
21C KBD Web Services On-Ramp User Guide
1 Getting Started
CP’s WS Web Services Gateway customer support team is known as the PEM Team, where
PEM stands for “Partner Enablement Management”. They can be contacted at
b2b.pem@bt.com. PEM would ask you details so that they can build up a Client Profile.
1.1 Tell us more about your organisation and requirements
This requirement is to set up CP profile under BT Wholesale community.
Name of the CP 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.
CP DUNS number
The 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
DUNS number at http://express.dnbsearch.com/advFind.asp. Look for the option “Search by
DUNS Number”, enter your company’s 9-digit number and press “Search” to see the validated
result.
CP Communication Provider’s URLs
You can provide URL with default port 443 to which the BTW will send Notification.
CP IP addresses
These are the respective IP addresses to which BTW Web Services KBD System will send
responses to the CP.
CP Client Certificate
The digital certificate issued from BT Wholesale Northside to CP is required for Mutual
Authentication. And note that same certificate should be used by CP when he moves on to
production Web Services gateway. Complete instructions for applying for this certificate are
detailed below.
CP BT Account Manager
This is the member of the BT Account Team who confirmed your access to the BTW Web
Services KBD Gateway. The PEM team will liaise with your Account Manager as necessary.
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.
Technology used to build CP BTW KBD 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.
CP preferred Testing Date
Setting up an On-Ramp test can take as little as a week. However, each Trading Partner’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.
In confidence BTW and Contracted CPs
5
21C KBD Web Services On-Ramp User Guide
CP preferred Production Date
As you will see, how long the On-Ramp tests go on depends more on what tests you have
elected to carry out rather than any fixed lead times required by BT. If you have a proposed
Production date in mind, please let us know, but note that this is not a mandatory field 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.
CP 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.
1.2 On-Ramp set up details for KBD
On-Ramp will accept and respond synchronously messages at below given URLs for the
various diagnostic services available.
1. BTW DUNS number
232510151
2. URL:
https://www.ws-onramp1.wholesale.bt.com:5443/21cnkbd/1.0/KnowledgeBasedDiagnostic
It is expected that a CP will need to arrange firewall access. For access from the On-Ramp
Gateway:
217.140.45.140 is for traffic coming from BT to Trading Partner over port 443.
217.140.45.139 is for traffic coming from the Trading Partner to BT over port 5443.
In confidence BTW and Contracted CPs
6
21C KBD Web Services On-Ramp User Guide
2 Security & Certificate Information
A number of security measures need to be in place in order to use the BTW Web Services
KBD Gateway, both during the On-Ramp Test phase and in Production.
2.1 The BTW security requirements
Mandatory requirements and restrictions apply that must be fulfilled in ALL circumstances.
Failure to comply with any of these will prevent completion of any connectivity trials and OnRamp testing, and jeopardise access to the live Production environment.
In summary, the principal security requirements include:







Confirmation of compliance with BS7799.
Use of a BT generated and supplied Digital Certificate using BT as the certification
authority (BT acts as a private certification authority)
Ability to accept inbound connections to your organisation.
Support for https/SSL connections when initiated by either end.
Presence of a firewall between the Internet and your organisation’s systems would be
suggested.
A system access point that uses a static RIPE IP address, not just a fixed DNS name. (BT
access is IP address-specific and restricted: this information will be required by BT as part
of the On-Ramp process.)
In addition, Network Address Translation (NAT) may be used to isolate your internal
systems from the Internet and BT. this must be used if a private IP-addressed network is
used within your organisation.
2.2 Digital Certificates
Central to accessing BT’s online services is the installation of an appropriate firewall and the
required Digital Certificate on the client side.
At least one X 509 certificates will be needed. We will issue Client and Server Certificates
from the URLs specified below (see Section 2.3). These are used specifically for the OnRamp testing phase (different data will apply when you are ready to move to the In-Life
Production environment.).
If you are in any doubt, we recommend you discuss any existing certificates with the PEM
team.
2.3 Downloading a new Digital Certificate
IMPORTANT:
We recommend you use Internet Explorer and install the certificate
first on a PC.
The certificate is necessary for basic authentication but not tied to a DNS name and IP
address. You can transfer this certificate from one server to another as and when required.
Details of the relevant link you can select are as follows:
https://onsite.trustwise.com/services/BTGroupPlcNorthsideclient/digitalidCenter.htm
Once you have completed your online application on the Trustwise website, BT’s PEM team
will approve your certificate request from Trustwise and advise you by email.
In confidence BTW and Contracted CPs
7
21C KBD Web Services On-Ramp User Guide
You will also receive a URL address and a PIN number with instructions on how to install your
certificate(s).
IMPORTANT!
Make sure you use the same browser on the same machine as you
originally applied from.
To obtain a Certificate:




First, INSTALL CA
Next, ENROL
First name, last name, E-mail Address, Employee ID number, company are required
inputs but can be treated creatively – these contact details are used to alert you of any
specific certificate issues (usually renewal) so should preferably be for a generic support
group (CommsCo, plc, support@commsco.co.uk, 1, Comsco would be fine); Challenge
phrase may be needed later, and you are free to comment or not.
Inform PEM team at above given address, you have applied and authorization will
immediately generate an email explaining the installation process (basically go to a url
and input a PIN code from the email). Please use the same browser on the same
machine as you originally applied from.
2.4 Sending us your Public Key
With the correct Digital Certificate(s) downloaded, you need to carry out the following checks
so that we can progress your order to the next stage.
1. 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.
2. In these circumstances, you will also need to change the certificate’s format depending on
your software (a visit to www.openssl.org may provide useful).
3. You should also move the Certificate Authority to maintain the evidence of trust (by using
the “export all certificates in path” command). See below.
Now zip and send Public Key supplied with each certificate in order to allow BT to
authenticate the messages you send us and vice versa. This will allow us to set up the https
connection from the On-Ramp environment to your server and is also used for authentication
through the digital signature you send for your message.
The reason you will need to export the certificate (without Private Key) and send the file (for
example only .cer type) to the PEM team is because we do not automatically have a copy of
the Public Key which is needed to authenticate your signed messages (even though we
authorise its issue).
To export the Digital Certificate:
1. Open Internet Explorer; go to Tools, Internet Options, Content, Certificates where
you’ll find your new (Personal) certificate.
2. Select it and click the Export button.
3. Next, select No; do not export the private key.
4. Next, choose either binary or base-64 .cer
5. Save the file zip and email a copy to the PEM team.
If the CP does not use Windows we would suggest them to go for some standard tool instead
of IE (Internet Explorer). Key tool comes free with Java and its platform independent. That
can be found at java.sun.com
The next phase will be to move straight to the On-Ramp Test (see Section 3 below).
In confidence BTW and Contracted CPs
8
21C KBD Web Services On-Ramp User Guide
3 On-Ramp Testing
3.1 Introduction to On-Ramp for KBD
Communication takes place by way of a series of 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.
Currently WS On-Ramp gateway will generate synchronous responses along with the
Asynchronous notifications for the corresponding request messages
CP gateway sends a WS request over HTTPS to BTW W/S gateway.
CPs are in almost complete control of the messages passed across the On-Ramp interface.
This control is exercised through the insertion of XML tag element i.e. PI.
There are four types of requests sent to On-Ramp(refer Section 3.3.4); On-Ramp uses the PI
instruction Tag element to select a corresponding example Business level reply from a preprepared set held in a database stub.
The clear picture about the transaction process is explained below:
1.
CP sends initiate Request
BT sends Accepted/Rejected response responses to CP depending upon the PI
provided
BT Sends Query notification to CP after 1 min to the Accepted response to CP.
2.
CP initiates Query Request
BT sends Query Request Accepted/Rejected responses to CP depending upon
the PI provided
BT Sends Final Notification to CP after 1 min to the Accepted response to CP.
3.
CP sends Terminate Request
Terminate Accepted/Rejected responses will be generated from BT Web
Services. But there will not be any notification.
4.
Now coming to a scenario, what would happen if the QueryNotification from KBD to
CP is lost; obviously this lead to CP infinitely waiting for a message from KBD and
KBD in turn waiting for the QueryRequest from CP. In order to over-come such
unhappy situation, resend option is available to CPs.
CP sends Resend Request,
KBD resend the last Query Notification or Final Result Notification.
Note: But a ResendRequest can be used only twice for a QueryNotification or
FinalQueryNotification.
Business messages can be classified as Requests and Notifications. Requests are initiated
by CPs on On-Ramp; and asynchronous Notifications will be sends from BT Web Services as
specified for the above specified scenarios.
For asynchronous notifications from BT Web Services, for request messages, CP would
require hosting a WSDL File and you can find same under section 3.3.5.
The XML itself is as specified for Production use.
Note: When you move on to production gateway please remove PI from XML’s as this
is only for On-Ramp simulated responses.
The scope of the tests is NOT intended to:
 Provide a full end-to-end testing environment.
In confidence BTW and Contracted CPs
9
21C KBD Web Services On-Ramp User Guide



Faithfully reflect performance in a live Production environment.
Exhaustively test possible data values either sent to or returned by BT.
Validate specific data such as phone numbers (DN - Directory Numbers), Post Codes
(PCs) or Service IDs.
3.2 Duration of the On-Ramp tests
Mandatory tests are conducted depending on the number of tests you require, this process
will typically last 1-3 weeks.
The set-up on the On-Ramp side takes no more than three days from provision of your
details. The duration of the On-Ramp testing phase depends on the size of your organisation
and the complexity of its management and development processes. Connectivity can take as
little as one day to test, but in some instances may take more than four weeks to establish.
Likewise, message handling can take days or weeks.
Delays generally result from badly configured certificates and CAs on web servers. They can
also stem from firewall and proxy set-up problems, and development and integration
difficulties with your Operational Support System (OSS).
However, the most common reason for delays is the time required to develop a client system
that integrates fully with the BTW KBD Web Services Gateway.
3.3 Sending messages to On-Ramp
Messages are sent to Web Services On-Ramp KBD by an https POST to URL:
https://www.ws-onramp1.wholesale.bt.com:5443/21cnkbd/1.0/KnowledgeBasedDiagnostic
The message comes as a payload in SOAP body which you may code explicitly or devolve to
message handling software. 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.
A few reminders
As we’ve seen, connection to On-Ramp is made using an SSL connection on port 5443. All
SSL connections require a Digital Certificate on the “server” end. It’s at your discretion
whether this certificate is validated by the process known as “mutual authentication” which
may or may not be available in your software.
On-Ramp will further require you to present a certificate issued to you by the PEM team.
This is known as “mutual authentication”, something not specified as part of Netscape's
original SSL design which was for Consumer to Business (C2B) connections, but not
uncommon in Business to Business (B2B) connections.
See “Section 2 – Security & Certificate Information” above for more information.
In confidence BTW and Contracted CPs
10
21C KBD Web Services On-Ramp User Guide
3.3.1 A look at http
The structure of typical message content as it goes down the line (before encryption by SSL)
is shown in the example Request Test below.
If you are coding at a low level, please ensure that the http uses DOS style CR-LF and not
UNIX style LF. Failure to do this can cause unnecessary frustration, as will trail spaces after
http header lines and before the CR-LF.
The following example is for XML Diagnostics.
POST /RequestTest HTTP/1.1
Host: www.ws-onramp1.wholesale.bt.com
SOAPAction: "RequestTest"
Content-Type: type="text/xml";
Content-length: 1234
3.3.2 About XML
Additional elements and attributes may or may not be acceptable. Part of the purpose of OnRamp testing is to ensure that your software does not add any extra unnecessary data which
might cause conflicts with the software used by On-Ramp.
If no conflicts exist, your solution may be acceptable, but the PEM team is not obliged to
guarantee that it 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. That’s the reason why testing is so essential. In other interfaces, even
the placing of comments has been known to cause problems. Although it’s right to
expect that these should not cause problems, it is unwise to assume that they will not.
3.3.3 Sample KBD example with SOAP
The BTW KBD Web Services Gateway uses XML business payloads that make use of
namespaces: use of namespace-aware XML software is therefore strongly recommended.
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 should not be critical, but this will not be
guaranteed.
Here is a SOAP example for XML 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
xsi:noNamespaceSchemaLocation="KBDB2BTest1.0.4.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
In confidence BTW and Contracted CPs
11
21C KBD Web Services On-Ramp User Guide
<?BTW_B2B_OnRamp_Test_Id
?B2B_BTW_KBD_bcRequestKBDInitiate2v1_kbdInitiateAccepted21C?>
<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 -->
<ContactName>Michael Jonathan</ContactName>
<Telephone>02071059053</Telephone>
<TelephoneExtension>4777</TelephoneExtension>
<Email>Michael.Jonathan@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 KBD -->
</Party>
</PerformerParty>
</TestParty>
</kmTestHeader>
<kmToolMessage>
<controlNode>
<userRequest>INITIATE</userRequest>
<!-- It should be set to INITIATE 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>
</kmToolMessage>
</kbdInitiateRequest>]]></rul:arg0>
</rul:invokerules>
</soapenv:Body></soapenv:Envelope>
In confidence BTW and Contracted CPs
12
21C KBD Web Services On-Ramp User Guide
3.3.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.wsonramp1.wholesale.bt.com:5443/21cnkbd/1.0/KnowledgeBasedDiagnostic
-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)
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>
xsi:noNamespaceSchemaLocation="KBDB2BTest-1.0.2.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<?BTW_B2B_OnRamp_Test_Id
?B2B_BTW_KBD_bcRequestKBDResumev2v1_kbdQueryAccepted21C?>
<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 -->
In confidence BTW and Contracted CPs
13
21C KBD Web Services On-Ramp User Guide
<TestContact>
<DetailedContact>
<!-- Details of the CP contact performing test -->
<ContactName>Michael Jonathan</ContactName>
<Telephone>02071059053</Telephone>
<TelephoneExtension>4777</TelephoneExtension>
<Email>Michal.Jonathan@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 KBD -->
</Party>
</PerformerParty>
</TestParty>
</kmTestHeader>
<kmToolMessage>
<controlNode>
<userRequest>RESUME</userRequest>
<!-- set to RESUME for KBDQuery -->
</controlNode>
<customer>
<circuitID>CBUK30053780</circuitID>
</customer>
<!-- CP to populate:
1.The actualAnswer to the valid answer from the option provided by KBD
2.sequenceId should be populated by CP to determine the path user has taken while
answering question group
3.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 7: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>
In confidence BTW and Contracted CPs
14
21C KBD Web Services On-Ramp User Guide
<options>
<value>NO</value>
<valueType/>
</options>
</expectedAnswers>
</question>
</customerQueries>
</kmToolMessage>
</kbdQueryRequest>]]></rul:arg0></rul:invokerules>
</soapenv:Body></soapenv:Envelope>
3.3.5 WsTransport Web Service definition for KBD
Trading Partner has to host this WSDL to receive results from BT
3.3.6 What are the Diagnostic Services and what XML goes
with them?
The diagnostic services available as KBD Web Service are:
 KMWSTestService
The four Business services falling under this diagnostic service are:
Service Name
Initiate Request
Query Request
Terminate Request
Resend Request
Root Node (Request/Response Type)
kbdInitiateRequest
kbdQueryRequest
kbdTerminateRequest
kbdResendRequest
What would happen if the QueryNotification from KBD to CP is lost; Obviously this
lead to CP infinitely waiting for a message from KBD and KBD in turn waiting for the
QueryRequest from CP.
In order to avoid such unhappy situation, resend option is available to CPs. Using
KBDResendRequest message; CP can request KBD to resend the last QueryNotification or
KBDFinalResultNotification.
But a ResendRequest can be used only twice for a QueryNotification or
FinalQueryNotification.
3.4 Receiving messages from On-Ramp
3.4.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
In confidence BTW and Contracted CPs
15
21C KBD Web Services On-Ramp User Guide
Content-Length: 794
<soap:Envelope xmlns:soap=”....
...
</soap:Envelope
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
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)
3.4.2 Response Business payload for KBD
If a valid request reaches On-Ramp, a response will be sent back Accepted/rejected XML
from BTW KBD Web Services depending on CP chosen PI.
The response would be different based on the type of Request:
InitiateAccepted/InitiateRejected and Notification for Initiate Request.
QueryAccepted/QueryRejected and Notification for Query Request.
TerminateAccepted/QueryRejected for Terminate Request.
QueryNotification or KBDFinalResultNotification for Resend Request.
In case of any invalid request exceptions will be thrown as in section 3.4.3 below.
3.4.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:
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>
In confidence BTW and Contracted CPs
16
21C KBD Web Services On-Ramp User Guide
</detail>
</soap:Fault>
</soap:Body>
</soap:Envelope>
PEM will usually be able to see these in logs. Assistance will be given by suggesting an
explanation and where changes may be needed.
NOTE:
Section 8.2 of BTW Web Services 21CNKBD Interface Design Issue V3.0 explains all
possible exceptions and error messages. Kindly refer the same.
3.5 Quality Gates
Concluding the On-Ramp phase is a series of mandatory Quality Gates which you will be
expected to clear. This process takes approximately two days.
The purpose of the Quality Gates is to allow you to demonstrate that your own B2B system
meets the requirements set out by BT Wholesale, before being allowed to move to the BTW
KBD Web Services Production Gateway. The requirements are represented by a set of
mandatory scenarios that you must execute on the On-Ramp system. The following sections
describe separate scenarios for XML KBD Diagnostics.
3.5.1 Scenarios for XML KBD Diagnostics
The following 6 test cases are mandatory and must be passed in order to complete KBD
Diagnostics Quality Gate.
The following test cases are mandatory and must be passed in order to complete
BTWholesale KBD Services Quality Gate
Scenario 1: bcRequestKBDInitiate2v1
Sender
Message Type
1 CP
KBDInitiateRequest
2 KBD
KBDInitiateAccepted
Processing Instruction
B2B_BTW_KBD_bcRequestKBDInitiate2v1_kbdInitiateAc
cepted21C
Scenario 2: bcRequestKBDResumev2v1
Sender
Message Type
1 CP
KBDQueryRequest
2 KBD
KBDQueryAccepted
In confidence BTW and Contracted CPs
Processing Instruction
B2B_BTW_KBD_
bcRequestKBDResume2v1_kbdQueryAccepted21C
17
21C KBD Web Services On-Ramp User Guide
Scenario 3: bcRequestKBDTerminate2v1
Sender
Message Type
1
CP
KBDTerminateReques
t
2
KBD
KBDTerminateAccept
ed
Processing Instruction
B2B_BTW_KBD_bcRequestKBDTerminate2v1_kbdTermi
nateAccepted21C
Scenario 4: bcRequestKBDResend2v1
Sender
Message Type
1
CP
KBDResendRequest
2
KBD
KBDResendAccepted
Processing Instruction
B2B_BTW_KBD_bcRequestKBDResend2v1_kbdResend
Accepted21C
Scenario 5: bcNotifyOfKBDFinalResult2v1
Send
er
Message Type
1
CP
KBDFinalResultNotific
ation
2
KBD
NotifyOfKBDFinalRes
ult
Processing Instruction
B2B_BTW_KBD_bcNotifyOfKBDFinalResult2v1_AUTON
OTIFICATION
Scenario 6: bcNotifyOfKBDQueryv12v1
Sender
Message Type
Processing Instruction
B2B_BTW_KBD_
1 CP
KBDQueryNotification
2 KBD
NotifyOfKBDQuery
In confidence BTW and Contracted CPs
bcNotifyOfKBDQuery2v1_AUTONOTIFICATION
18
21C KBD Web Services On-Ramp User Guide
3.6 Message Handling
Once connection can be made, the wrapping, unwrapping and receipting need to be
demonstrated. This is done by simulating business transactions. You should test all the
services, which you want to use. The Processing Instructions (PIs) will take the form:
<?BTW_B2B_OnRamp_Test_Id ?KEY1?>
21C KBD via Web
Services.xls
4 In-Life Migration
Once all the On-Ramp tests and Quality Gates have been carried out, And when the PEM
team is are happy that your system will not cause any problem to the Production platform in
terms of incorrect, missing or excess messages, you will be given access to the live
Production platform.
Once the firewall is in place, the PEM team will confirm any operational changes to the CP’s
IP address or CP’s End Point URL if these apply. Final checks will be carried out on the CP’s
certificate configuration and will then be advised by an email when CP’s BTW KBD Web
Services Gateway services will be approved.
In technical terms, the only changes involved for going live – on an agreed date after PEM
have confirmed any operational changes for KBD to your IP address/URL/certificate
configuration are:
https://www.ws.wholesale.bt.com:5443/21cnkbd/1.0/KnowledgeBasedDiagnostic
It is expected that a CP will need to arrange firewall access. For access from the Live
Gateway:
217.140.45.140 is for traffic coming from BT to Trading Partner
217.140.45.137 is for traffic coming from the Trading Partner to BT.
Production is the first time that:





your organisation will be connecting to real back end systems;
you will be able to test specific details of lines, exchanges and so on;
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.
The PEM team will continue to welcome queries from you after you move from On-Ramp to
the Production environment, but anything giving rise to operational problems should be
reported directly to the E-Contact Team at: broadband.eco.admin@bt.com.
In confidence BTW and Contracted CPs
19
21C KBD Web Services On-Ramp User Guide
Glossary
BT
BTW
CA
TP
CUPID
DUNS
DNS
OTA
PI
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
Office of the Telecommunications Adjudicator
Processing Instruction (XML terminology)
Simple Object Access Protocol
Secure Socket Layer
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.
In confidence BTW and Contracted CPs
20