B2B Access Guide
BT Wholesale
Broadband Knowledge Based
Diagnostics (KBD) Business to
Business (B2B) Access User Guide
Issue 1.3 – 20th October 2014
Copyright British Telecommunications plc 2011
Page 1 of 35
B2B 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, 2011.
Registered office: 81, Newgate Street, London, EC1A 7AJ
Registered in England no. 1800000
Issue 1.3 – 20th October 2014
Copyright British Telecommunications plc 2011
Page 2 of 35
B2B Access Guide
Contents
1.
ABOUT THIS HANDBOOK .................................................................................................................................................. 4
1.1
1.2
2.
VERSION CONTROL ...................................................................................................................................... 4
FURTHER INFORMATION & COMMENTS........................................................................................................ 4
INTRODUCTION .................................................................................................................................................................... 5
2.1
2.2
2.3
2.4
2.5
3.
W HAT IS BT W HOLESALE ONRAMP FOR?.................................................................................................... 5
W HAT IS BT W HOLESALE ONRAMP NOT FOR? ............................................................................................ 5
W HEN IS ONRAMP TESTING APPLICABLE? ................................................................................................... 6
HOW IS ONRAMP USED? .............................................................................................................................. 7
HOW LONG WILL YOU USE ONRAMP FOR? ................................................................................................... 8
SETTING UP THE GATEWAY ............................................................................................................................................ 9
3.1
3.2
4.
YOUR SETUP ................................................................................................................................................. 9
BT W HOLESALE SIDE SET UP ....................................................................................................................... 9
SECURITY AND CERTIFICATE INFORMATION........................................................................................................... 11
4.1
4.2
5.
PRINCIPAL SECURITY REQUIREMENTS PLEASE NOTE THAT YOU WILL NEED TO: ...................................... 11
DOWNLOADING A NEW DIGITAL CERTIFICATE ............................................................................................. 11
ONRAMP PHASE ................................................................................................................................................................ 13
5.1
6.
CONFIRMING CONNECTIVITY WITH THE ONRAMP PLATFORM ..................................................................... 13
USING ONRAMP ................................................................................................................................................................. 15
6.1
6.2
6.3
6.4
6.5
6.6
7.
MESSAGES FROM YOU TO ONRAMP ........................................................................................................... 15
MESSAGES FROM ONRAMP TO YOU ........................................................................................................... 20
HTTP .......................................................................................................................................................... 20
YOUR RESPONSE TO ONRAMP ................................................................................................................... 24
ONRAMP EXIT CRITERIA .............................................................................................................................. 25
MESSAGE HANDLING................................................................................................................................... 28
SDK AND EMULATOR ....................................................................................................................................................... 29
7.1
7.2
7.3
7.4
7.5
8.
OVERVIEW .................................................................................................................................................. 29
BENEFITS .................................................................................................................................................... 30
INSTALLATION DETAILS ............................................................................................................................... 30
HOW TO USE THE ONRAMP EMULATOR ..................................................................................................... 31
GUIDELINES ................................................................................................................................................ 31
PILOT AND LIVE PHASE ................................................................................................................................................... 32
8.1
8.2
PILOT .......................................................................................................................................................... 32
LIVE ............................................................................................................................................................. 33
9.
GLOSSARY .......................................................................................................................................................................... 34
10.
DOCUMENT HISTORY ....................................................................................................................................................... 35
Issue 1.3 – 20th October 2014
Copyright British Telecommunications plc 2011
Page 3 of 35
B2B Access Guide
1. About this handbook
This document provides an overview of the Onramp 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
Enquiries and comments to Partner Enablement Management:
Email: wholesale.pem@bt.com Tel: 02034505229
Issue 1.3 – 20th October 2014
Copyright British Telecommunications plc 2011
Page 4 of 35
B2B Access Guide
2. Introduction
The Business to Business (B2B) Gateway is designed to help you to buy and manage a variety of
telecommunications services electronically, by linking your own support systems and processes with
ours.
In its simplest definition, a B2B process is any business process between two companies that uses
digital technology.
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 with the help of 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 of the automatic testing tools. These will be sent to you and when you answer, the
KBD Tool, will, if possible, find a solution to the issue.
This document will be helpful to you if you intend to use the BT Wholesale Onramp
Gateway/Emulator
Please note that the Onramp Emulator supports only the 21CN KBD services (and not 20CN KBD
services)
2.1 What is BT Wholesale Onramp 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) Creation, format conversion (if required), and installation of any certificates that may
be used to support the https connections.
c) Business level messages for passing across the B2B interface; for final testing, the
messages should come from and go back to your systems.
2.2 What is BT Wholesale Onramp not for?
Onramp does not:
a) Provide you with a full end-to-end testing environment
b) Faithfully reflect the performance in the production environment
c) Exhaustively test possible data values and error conditions sent to or returned by
Openreach
d) Facilitate load or performance testing
Issue 1.3 – 20th October 2014
Copyright British Telecommunications plc 2011
Page 5 of 35
B2B Access Guide
2.3 When is Onramp testing applicable?
For 21CN KBD services, if you are using the SDK Emulator rather than your own proprietary
software, this section will be helpful. That’s because you will need to update SDK as per the releases
on the Gateway.
2.3.1 SDK-Emulator Customers:
1) For 21CN KBD services, if you are new to the BT Wholesale B2B gateway, you would need to
mandatorily test against the BT Wholesale B2B Onramp Emulator to be able to go in-life.
2) If you are in the ‘Business as Usual’ phase on the Live BT Wholesale B2B gateway (using your
proprietary software) but new to the SDK-Emulator functionality, you would need to go through
the Onramp emulator process at least once so that you can go ahead and use the SDK product
on the Live systems.
All you have to do is follow this process:
a) Contact the Partner Enablement Management (PEM) team and let them know what
testing needs to be done. They will take you through what you need to do.
b) Then send the Onramp details (including the certificate that is being used for Live
connectivity and message signing) to the PEM team. Please refer section 3.2 below
of the document to understand these details.
c) The PEM team will create your Gateway profile on the Onramp systems using these
details. You will also get an Onramp Collaboration Protocol Agreement (CPA) that will
contain the services that need to be tested.
d) Once this is done, you can go ahead with the testing and let the PEM team know once
this is done.
e) The PEM team will then verify the testing and provide you the new Live Collaboration
Protocol Agreement (CPA) which will contain the services that have been tested (if
applicable)
3) If you have used the SDK-Emulator for testing 21CN KBD services and are currently on Live
(using the SDK Hermes as your API for posting the messages), and want a new service on Live,
it is mandatory to go through the above steps.
There are two ways to test your new SDK code; a) test against the Emulator installed in your
development servers or b) test against the Onramp Emulator.
The processes involved for both are:
If you perform the testing against the emulator deployed on your local servers, you
must drop an email to the PEM team (wholesale.pem@bt.com) containing the below
information on the successful testing performed:
The version of the SDK and emulator used for the testing.
Issue 1.3 – 20th October 2014
Copyright British Telecommunications plc 2011
Page 6 of 35
B2B Access Guide
The services tested. (Example: bcRequestKBDInitiate2v1)
The payload XML used for the testing (Ex: kbdInitiateRequest21C.xml, etc.)
If applicable, a new Live Collaboration Protocol Agreement (CPA) will be issued to you- this would
contain the services that have been tested.
If you would like to perform the testing for the new services against the Onramp
Emulator, please drop an email to the PEM team with your request.
A new Onramp Collaboration Protocol Agreement (CPA) will be issued for the testing.
2.3.2 Non SDK-Emulator Customers:
1) If you are new to the BT Wholesale B2B gateway for 21CN KBD services, you need to test either
against the B2B Onramp gateway or the Onramp Emulator to be able to ‘go live’.
2) If you are a customer currently on Live, and want a new service, you could either perform testing
against the BT Wholesale B2B Onramp gateway or the BT Wholesale B2B Onramp Emulator.
You can skip the testing if you want to, but you will definitely need to tell the PEM team who will then
be able to advise you on the XML to be used for the service, etc and ensure that you go through the
Live Pilot/Trial phase for the new service.
However, please note that it is always recommended to test against the Onramp systems (B2B
Onramp/Onramp Emulator) before using any service on the Live systems.
2.4 How is Onramp Used?
You are in almost complete control of the messages passed across the Onramp interface. This
control is exercised by inserting XML processing instructions (PI) in the messages you send to
Onramp. Apart from the PI, the XML is as specified for Production use. Onramp uses the PI to select
a corresponding example business level reply from a pre-prepared set held in a database.
Fig: 1.1 Block Diagram showing main components
Business messages can be classified as requests and notifications. Requests are initiated by you;
Onramp normally initiates notifications when the status of transactions change (initiated by your
request). You control both requests and notifications from your Onramp environment. You can also
request:
Issue 1.3 – 20th October 2014
Copyright British Telecommunications plc 2011
Page 7 of 35
B2B Access Guide
ReceiptAcknowledgementException – these can be generated by submitting bad
XML or good XML with a Data Universal Numbering System (DUNS) number
different to that expected.
Fig; 1.2 Block Diagram showing Request/Response path
The only message not controlled by you is:
EbXML Delivery Acknowledgement -- returned to acknowledge receipt of an ebXML
message.
2.5 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 setup on the Wholesale side takes no more than four working days from the provision of details.
The main causes of any delays are:
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 – 20th October 2014
Copyright British Telecommunications plc 2011
Page 8 of 35
B2B Access Guide
3. Setting up the Gateway
The Onramp Customer Support team, known as PEM can be contacted at wholesale.pem@bt.com,
may ask you for the following details as part of their task of building up a “Client Profile”. The
interface-specific parameters and requirements are:
3.1 Your setup
It is expected that you would need to arrange for firewall access on your side to access the Onramp
environment and to receive responses back from it.
BT Wholesale’s On-ramp details are as mentioned here below:
BT Wholesale Data Universal Numbering System (DUNS) number: 232510151
Onramp will accept messages from your gateway at the URL:
https://www.b2b.onramp2.btwholesale.bt.com/b2b/httpReceiver
The DNS www.b2b.onramp2.btwholesale.bt.com resolves to the IP address 62.239.186.17.
You will need to enable firewall for this IP address over port 443 on your side to send
messages to the onramp gateway
Onramp will send messages from the IP address 62.239.186.19 over port 443. You will
need to enable firewall for the IP address on your side to receive messages from the same.
3.2 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 your access up:
Name of 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 URL with default port 443 to which we will send responses/notifications. This is
required both during Onramp and Live set up.
Issue 1.3 – 20th October 2014
Copyright British Telecommunications plc 2011
Page 9 of 35
B2B Access Guide
Your IP addresses
These are the respective IP addresses from which the requests to the BT Wholesale Onramp/Live
will originate.
Your client certificate
The digital certificate issued from BT Wholesale Northside – G2 root CA certificate is required for
mutual authentication. And note that same certificate should be used when you move on to
production (live) B2B 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
B2B 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.
Your gateway
This is the gateway that you will use to exchange ebXML messages with BT. Ex., Axway Cyclone,
Hermes, etc.
The technology used to build your Gateway
This is the technology used to build your ebXML gateway. For example Java, Dot Net, PHP etc.
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.
Your preferred production date
As you will see, how long the Onramp tests go on 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 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.
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.
Issue 1.3 – 20th October 2014
Copyright British Telecommunications plc 2011
Page 10 of 35
B2B Access Guide
4. Security and certificate information
Before you can access our online services you need to have an appropriate firewall and digital
certificate and comply with our security requirements.
If you are in any doubt, please feel free to discuss any existing certificate related queries with our
Partner Enablement Management (PEM) team.
4.1 Principal security requirements
Please note that you will need to:
Confirm compliance with BS 7799.
Agree to the use of a BT generated and supplied Digital Certificate using BT as the certification
authority (BT acts as a private certification authority).
Have the ability to accept inbound connections to your organisation.
Support https/SSL connections when initiated by either end.
Have the ability to accept inbound https on TCP/IP port 443.
The presence of a firewall between the Internet and your organisation’s systems.
Have 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
Onramp process.)
Note there should be no other web/application servers running on the same system.
If a web server is required on the same machine, it must not use port number 443.
In addition, note that 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.
More detailed information about aspects of the above is contained within this user guide. Other
publications featured in our Help & Support section provide specific information. You can also
discuss any of these issues with the PEM Team.
4.2 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
Please follow the instructions provided in the below slide pack for getting your digital certificate.
Northside_G2_Digital
_Certificate_Instruction_Guide.pptx
Issue 1.3 – 20th October 2014
Copyright British Telecommunications plc 2011
Page 11 of 35
B2B Access Guide
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/.p12) 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), if required.
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.
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 – 20th October 2014
Copyright British Telecommunications plc 2011
Page 12 of 35
B2B Access Guide
5. Onramp phase
In order to use the BT Wholesale B2B Gateway, the PEM team will set up your account on the
Gateway.
5.1 Confirming connectivity with the Onramp platform
Basic connectivity from your gateway to our Onramp testing environment can be confirmed in three
ways, one after the other in the order as listed below, so as to increase the parameters being tested
with each test.
5.1.1 Telnet test
Simply by running the following telnet command from your server, you can establish very
basic connectivity between the two environments. Please note that this command only
proves if the firewalls are in place in the direction of the test. This command does not
prove that the certificates required for the session to be established are in place or not on
your side.
Here is an example of a Telnet command indicating connectivity between the two
environments, in the request path (CP BT)
C:\ telnet www.b2b.onramp2.btwholesale.bt.com 443
Trying 62.239.186.17
Connected to www.b2b.onramp2.btwholesale.bt.com
Escape character is '^]'.
Here is an example of a Telnet command indicating a lack of connectivity between the
two environments, in the request path (CP BT)
C:\ telnet www.b2b.onramp2.btwholesale.bt.com 443
Trying 62.239.186.17
telnet: Unable to connect to remote host: Connection timed out
5.1.2 Server status
The “Server status” option is a link that you can access on the computer your requests
are sent from. The link is as follows:
https://www.b2b.onramp2.btwholesale.bt.com/ServerStatus
When accessing this link it will ask you to present your certificate given to you by BT
Wholesale with a “Northside - G2” CA.
If you have the certificate in question installed on this browser and you select the right
certificate, you should get the “ServerStatus=OK” response. This indicates a successful
connection between the two environments.
If you do not have the certificates in place or select the wrong certificate you will get the
message “You are not authorized to view this page”.
Please note that “serverstatus” needs to be run from Internet Explorer only; Mozilla-type
browsers will not connect and these are likely to be withdrawn at some stage.
Issue 1.3 – 20th October 2014
Copyright British Telecommunications plc 2011
Page 13 of 35
B2B Access Guide
5.1.3 EBXML PING
Once the above two tests have successfully been completed, you can send the first
EBXML message from your gateway to the Onramp gateway. If your gateway supports
the EBXML Ping, we encourage you to try it as it is a very bare bones test which does not
include the complexity of the having the payload and the possible associated errors.
Please find below a SAMPLE Ping XML, this is only for your reference and will not work
if used as is.
An ebXML Pong message should be returned to your nominated URL (this is instead of
the ebXML Delivery Acknowledgement you should expect with business messages).
During the Onramp testing phase as with Production, only https connections over port 443
can be used.
If the above tests go well, your connectivity to Onramp will be in place and you will be able to use it
to conduct your tests and work your way through getting the quality gates (Onramp exit criteria) and
get a sign off. This means you can then go to the Production (live) platform.
Issue 1.3 – 20th October 2014
Copyright British Telecommunications plc 2011
Page 14 of 35
B2B Access Guide
6. Using Onramp
Messages are sent to Onramp by an https POST to the URL:
https://www.b2b.onramp2.btwholesale.bt.com/b2b/httpReceiver
The messages uses ebXML 2.0 messaging (basically SOAP with the business XML as an
attachment) which you may code explicitly or devolve to message handling software.
Realistic example messages are used in the following to illustrate interface usage. Variables are
signified by bold text; italics are used to signify data parameters at the CP level.
6.1 Messages from you to Onramp
Connection to Onramp is made using a Secure Sockets Layer (SSL) connection on port 443. All
Secure Sockets Layer (SSL) connections require a digital certificate on the 'server' end. It is at your
discretion whether this certificate is validated by the process known as “client authentication” which
may or may not be available in your software.
You then need to present a certificate we issued to you; this is “client authentication”, not specified
as part of Netscape's original Secure Sockets Layer (SSL) design which was for Consumer to
Business (C2B) connections, but not uncommon in Business to Business (B2B) connections.
The process to apply for the certificate is covered in section 2 of this document. The certificate needs
to be presented along with the corresponding Certificate Authority (CA).
The actual content of the messages as they go down the line (before encryption by Secure Sockets
Layer (SSL)) is structured as follows (users of Completely Off The Shelf message service handlers
can just concentrate on the business XML – identified as Test request - but may like to see how
their parameters are used)
First, some http.
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 much frustration.
As can trailing spaces after http header lines and before the CR-LF.
The following example is for XML Diagnostics
POST /b2b/httpReceiver HTTP/1.1
Host: www.b2b.onramp2.btwholesale.bt.com
SOAPAction: "ebXML"
Content-Type: multipart/related; type="text/xml"; boundary="someBoundaryValue";
start="ebXML_Message_Header"
--someBoundaryValue
Content-Type: text/XML
Content-ID: <ebXML_Message_Header>
Issue 1.3 – 20th October 2014
Copyright British Telecommunications plc 2011
Page 15 of 35
B2B Access Guide
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 not be 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 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.
Here is a SOAP example for XML 20CN KBD Initiate Request:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://schemas.xmlsoap.org/soap/envelope/
http://www.oasis-open.org/committees/ebxml-msg/schema/envelope.xsd">
<SOAP-ENV:Header xmlns:eb="http://www.oasis-open.org/committees/ebxml-msg/schema/msg-header-2_0.xsd"
xsi:schemaLocation="http://www..oasis-open.org/committees/ebxml-msg/schema/msg-header-2_0.xsd
http://www..oasis-open.org/committees/ebxml-msg/schema/msg-header-2_0.xsd">
<!-The ebXML section has these variables:
From/PartyId
CP Data Universal Numbering System (DUNS) number (123456789)
Role
CommunicationsProvider
Collaboration
Protocol
Agreement
(CPA)Id
BT_Wholesale_TestPartner_VDC_Onramp_cpa
ConversationId
Something unique RFC 2822 Internet Message Format
(http://www.faqs.org/rfcs/rfc2822.html) may help.
Onramp use the algorithm: "C" + current timestamp in milliseconds (format
"yyyyMMddHHmmssSSS") + "." new java.rmi.server.UID() + “@” + HostAddress
Service
bcBusinessTransactionDescription
Action
rqBusinessTransactionDescription or ReceiptAcknowledgement,
ReceiptAcknowledgementException,
MessageId
Something unique. RFC 2822 Internet Message Format
Issue 1.3 – 20th October 2014
Copyright British Telecommunications plc 2011
Page 16 of 35
B2B Access Guide
(http://www.faqs.org/rfcs/rfc2822.html) may help.
Onramp use the algorithm: "G" + current timestamp in milliseconds (format
"yyyyMMddHHmmssSSS") + "." new java.rmi.server.UID() + “@” + HostAddress
Timestamp
NB format : yyyy-mm-ddThh:mm:ss.mmmZ
-->
<eb:MessageHeader SOAP-ENV:mustUnderstand="1" eb:version="2.0">
<eb:From>
<eb:PartyId eb:type="urn:oasis:names:tc:ebXML-cppa:partyid-type:duns">123456789</eb:PartyId>
<eb:Role>ServiceProvider</eb:Role>
</eb:From>
<eb:To>
<eb:PartyId eb:type="urn:oasis:names:tc:ebXML-cppa:partyid-type:duns">232510151</eb:PartyId>
<eb:Role>WholesaleProvider</eb:Role>
</eb:To>
<eb:CPAId>BT_Wholesale_TestPartner_VDC_onramp_cpa</eb:CPAId>
<eb:ConversationId>2004-10-20T092346</eb:ConversationId>
<eb:Service eb:type=”string”>bcRequestKBDInitiatev1</eb:Service>
<eb:Action>rqRequestKBDInitiate</eb:Action>
<eb:MessageData>
<eb:MessageId>76b0f68de48fb4c6:7590db:ffb6c46d3c:-7fde</eb:MessageId>
<eb:Timestamp>2004-10-20T15:37:27.984Z</eb:Timestamp>
</eb:MessageData>
</eb:MessageHeader>
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">>
<! –
Signing the message for non-repudiation
The following section illustrates XML Digital Signature.
The SignatureValue is an encrypted digest (base64 encoded as 28 characters rather than the
40 character hex digest) of the DigestValues (hashes) of two References:
i) the ebXML before inclusion of Signature element (Reference URI=””)
ii) the payload (referenced in Reference URI=”cid:TestRequest”)
after C14N (standardising the XML to a common format by common usage of spaces, etc), and
uses an RSA type key at least 1024 bytes long.)
Writing your own code to perform message signing, or verification, is not recommended but
several implementations can be found.
-->
<ds:SignedInfo>
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
<ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
<ds:Reference URI="">
<! -Identifies the node-set (minus any comment nodes) of the XML resource containing the signature
-->
<ds:Transforms>
<ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
<ds:Transform Algorithm="http://www.w3.org/TR/1999/REC-xpath-19991116">
<XPath>not(ancestor-or-self::node()[@soap:actor="urn:oasis:names:tc:ebxml-msg:service:nextMSH"]|
self::node()[@soap:actor="http://schemas.xmlsoap.org/soap/actor/next"])
</XPath>
Issue 1.3 – 20th October 2014
Copyright British Telecommunications plc 2011
ancestor-or-
Page 17 of 35
B2B Access Guide
</ds:Transform>
<ds:Transform Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
</ds:Transforms>
<ds:DigestMethod
Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
<ds:DigestValue>VNh1JY0nZIdAvN0DH8FXY/hX4Ss=</ds:DigestValue>
</ds:Reference>
<ds:Reference URI="cid:Test Request">
<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
<ds:DigestValue>7q1IRSJRie4k3YZB3Zu0YxZ/aPU=</ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue>
tLeoo+ctIBnQiY2zxXY+mb6RKkNhILo9bhpPEloPQNA7pkjTk9U4UXRTKFanjj8I4oDIKvZ4
...
f0naT4i3FYT5WJVV9C+FIe0u6qk=
</ds:SignatureValue>
<ds:KeyInfo>
<ds:KeyValue>
<ds:RSAKeyValue>
<ds:Modulus>
4TmhrCzjsbtQQuq7MOzT3RUa5dFV6tc9+hY5fxgwiXXPaywczWowi3s04g5CpTIHDV
....
QzAqaHfi0VCNu+x+0aMinugQak9SG5Yyi25vLpk=
</ds:Modulus>
<ds:Exponent>AQAB</ds:Exponent>
</ds:RSAKeyValue>
</ds:KeyValue>
<ds:X509Data>
<ds:X509IssuerSerial>
<ds:X509IssuerName>CN=B2B PEM,O=BT Group Plc</ds:X509IssuerName>
<ds:X509SerialNumber>144076108064759518656542817138884233900</ds:X509SerialNumber>
</ds:X509IssuerSerial>
<ds:X509SubjectName>emailAddress=b2b.pem@bt.com,CN=BT
PEM,OU=company - BT,OU=Northside (client),O=BT Group
Plc</ds:X509SubjectName>
<ds:X509Certificate>
MIIC0jCCAjugAwIBAgIQbGQMkHV//URA+MaalDBKrDANBgkqhkiG9w0BAQQFADArMRUwEwYDVQQK
...
y31IYVOOibn83IOMwXsgbvL7IUFzkFJqjJO10NTx8aWixKKwPdpbrIONL9gjduUehoNkPa7wBuFe
DSVMbj+aZqU8lqmJKrkylEvy+jTkhD5DlqBDT4kV3Kt0Pg1xxYP7cBiW
</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</ds:Signature>
</SOAP-ENV:Header>
<SOAP-ENV:Body
xmlns:eb="http://www.ebxml.org/namespaces/messageHeader"
xsi:schemaLocation="http://www.ebxml.org/namespaces/messageHeader
http://ebxml.org/project_teams/transport/messageHeaderv0_99.xsd">
<eb:Manifest eb:version="2.0">
<eb:Reference xlink:href="cid:Test request" xlink:type="simple"></eb:Reference>
</eb:Manifest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
--someBoundaryValue
Content-Type: application/XML
Content-ID: <Test request>
Issue 1.3 – 20th October 2014
Copyright British Telecommunications plc 2011
Page 18 of 35
B2B Access Guide
<?xml version="1.0" encoding="UTF-8" ?>
<!-Following is an example for “KBDInitiateRequest”
<kbdInitiateRequest xsi:noNamespaceSchemaLocation="KBDB2BTest-1.0.2.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<!--***************Here is an example MESSAGE HEADER for an INITIATE REQUEST***************-->
<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 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 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>
Issue 1.3 – 20th October 2014
Copyright British Telecommunications plc 2011
Page 19 of 35
B2B Access Guide
Note: The service names and actions available for each service are described in Section 2.1 of the
T2R KBD - Template Solution Design - Draft 1.1 document and are also available in the
Collaboration Protocol Agreement (an XML file). EbXML-ready Message Handling Systems may be
able to import the CPA to automate much of their configuration.
6.2 Messages from Onramp to you
Connection from Onramp is made using an Secure Sockets Layer (SSL) connection on port 443. All
Secure Sockets Layer (SSL) connections require a digital certificate on the 'server' end; Onramp will
expect you to present a certificate for which we have a copy of the public key and the corresponding
Certificate Authority (CA) for “mutual authentication”.
You may find it convenient to use same client certificate that was issued during Onramp testing. You
may use the same certificate for client authentication as well.
If you choose to perform client-side authentication, then Onramp will present the BT Wholesale
Onramp server certificate public key.. A copy of the public key and Certificate Authority (CA) will
also be provided (in the Collaboration Protocol Agreement (CPA) if it is used, otherwise as a
separate file) as it will also be needed to validate the digital signature in each message (although
validation is not mandatory).
6.3 HTTP
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, 610)
You may get a timeout (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 fail to connect at all (like any system, there will be outages - normally scheduled
and communicated in advance)
6.3.1 Reliable messaging
When the connection is OK, you will get an ebXML Delivery Acknowledgement (also known as
Receipt, similar to an email receipt notification).
This may be hidden from you by an Off the Shelf Message Handling System (MHS) but will be a
rather less neat version of the possible sample provided below.
Content-Type: text/xml
SOAPAction: "ebXML"
Content-Length: 7022
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://schemas.xmlsoap.org/soap/envelope/
http://www.oasis-open.org/committees/ebxml-msg/schema/envelope.xsd">
Issue 1.3 – 20th October 2014
Copyright British Telecommunications plc 2011
Page 20 of 35
B2B Access Guide
<soap:Header xmlns:eb="http://www.oasis-open.org/committees/ebxml-msg/schema/msgheader-2_0.xsd"
xsi:schemaLocation="http://www.oasis-open.org/committees/ebxmlmsg/schema/msg-header-2_0.xsd
http://www.oasis-open.org/committees/ebxmlmsg/schema/msg-header-2_0.xsd">
<eb:MessageHeader eb:id="ID316455841141998769982cbu072a003" eb:version="2.0"
soap:mustUnderstand="1"><eb:From><eb:PartyId eb:type="urn:oasis:names:tc:ebXMLcppa:partyidtype:duns">232510151</eb:PartyId><eb:Role>WholesaleProvider</eb:Role></eb:From><eb:To><eb:Part
yId eb:type="urn:oasis:names:tc:ebXMLcppa:partyidtype:duns">123456789</eb:PartyId><eb:Role>ServiceProvider</eb:Role></eb:To><eb:CPAId>BT_Whol
esale_TestPartner_VDC_onramp_cpa</eb:CPAId>
<eb:ConversationId>0329040b-55b2-4275-90928a1faf89b385</eb:ConversationId><eb:Service>urn:oasis:names:tc:ebxmlmsg:service</eb:Service><eb:Action>Ackn
owledgment</eb:Action><eb:MessageData><eb:MessageId>M1141998769979.615866@cbu072a003843825930563
4289897</eb:MessageId><eb:Timestamp>2006-0310T13:52:49.979Z</eb:Timestamp><eb:RefToMessageId>M1141998769579.43077@cyclone1125933195045429953
</eb:RefToMessageId></eb:MessageData></eb:MessageHeader><eb:Acknowledgment
eb:id="ID315227511141998769979cbu072a003" eb:version="2.0"
soap:actor="urn:oasis:names:tc:ebxml-msg:actor:toPartyMSH"
soap:mustUnderstand="1"><eb:Timestamp>2006/03/
10T13:52:49.979Z</eb:Timestamp><eb:RefToMessageId>M1141998769579.43077@cyclone1125933195045429953
</eb:RefToMessageId><eb:From><eb:PartyId eb:type="urn:oasis:names:tc:ebXMLcppa:partyidtype:duns">232510151</eb:PartyId><eb:Role>WholesaleProvider</eb:Role></eb:From><ds:ReferenceU
RI=""
xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:Transforms>
<ds:Transform
Algorithm="http://www.w3.org/2000/09/xmldsig#envelopedsignature"/>
<ds:Transform
Algorithm="http://www.w3.org/TR/1999/REC-xpath19991116"><ds:XPath>not(ancestor-orself::node()[@soap:actor=&quot;urn:oasis:names:tc:ebxmlmsg:
service:nextMSH&quot;] | ancestororself::node()[@soap:actor=&quot;http://schemas.xmlsoap.org/soap/actor/next&quot;]
)</ds:XPath></ds:Transform>
<ds:Transform Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n20010315"/>
</ds:Transforms>
<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
<ds:DigestValue>AXjWwIGcxOQXo0wiay4hhT5UfAk=</ds:DigestValue>
</ds:Reference><ds:Reference
URI="cid:TestE1" xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
<ds:DigestValue>Irj8U6J3QqtzVJ1iE+y9PVO/YUs=</ds:DigestValue>
</ds:Reference></eb:Acknowledgment><ds:Signature
xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:SignedInfo>
<ds:CanonicalizationMethod
Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
<ds:SignatureMethod
Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
<ds:Reference URI="">
<ds:Transforms>
<ds:Transform
Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
<ds:Transform Algorithm="http://www.w3.org/TR/1999/REC-xpath-19991116"><ds:XPath>not(ancestororself::node()[@soap:actor=&quot;urn:oasis:names:tc:ebxmlmsg:
service:nextMSH&quot;] | ancestororself::node()[@soap:actor=&quot;http://schemas.xmlsoap.org/soap/actor/next&quot;]
)</ds:XPath></ds:Transform>
<ds:Transform
Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
Issue 1.3 – 20th October 2014
Copyright British Telecommunications plc 2011
Page 21 of 35
B2B Access Guide
</ds:Transforms>
<ds:DigestMethod
Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
<ds:DigestValue>6n4NAMKfYUzVi0EVTfdadDLCndw=</ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue>
Ez6T7H91CPXdcGxbXeTiNL8IiB9j31dlNQhUi9x1xTIuzdCGgflilpHBJafy0erSjeI686g+FI2VAfZBVjUkeintBHPKcC
tbQ1JQvUATvWqaDJ3HJGS1Fhc6uRCT+w7it0kgFdtRmp6zF6VFkk+2iEfP2C+wCU6TcasJ+d0PKuQ=
</ds:SignatureValue>
<ds:KeyInfo>
<ds:KeyValue>
<ds:RSAKeyValue>
<ds:Modulus>
qsJAIxkbPNgbu6+OCqS/nIF5R1izY5T475x4daVedCt8OEw5CB4ZNns29evGvoe0vvIDzoTjvtEL1FbNr8izcaG0JG
a0KmUwVi5l7puTFJ043hH6Xs4RvV+2IEmoaZRqHY6Ic3YQblU4m+k9iUu2fE6onY4gSfHI9TocJPVKFU8=
</ds:Modulus>
<ds:Exponent>AQAB</ds:Exponent>
</ds:RSAKeyValue>
</ds:KeyValue>
<ds:X509Data>
<ds:X509IssuerSerial>
<ds:X509IssuerName>CN=B2B PEM,O=BT Group Plc</ds:X509IssuerName>
<ds:X509SerialNumber>75401604589881139776868569778074274319</ds:X509SerialNumber>
</ds:X509IssuerSerial>
<ds:X509SubjectName>emailAddress=b2b.pem@bt.com,CN=B2BOnRamp,TI=B2B,OU=MailStop - Stadium
House,OU=EmployeeID -1,OU=PEM,O=BT,L=Cardiff,ST=Wales,C=UK</ds:X509SubjectName>
<ds:X509Certificate>
MIIDKTCCApKgAwIBAgIQOLnSINSLEHRhB8WRncHKDzANBgkqhkiG9w0BAQUFADAvMRUwEwYDVQQKEwx
CVCBHcm91cCBQbGMxFjAUBgNVBAMTDUIyQiBPcGVucmVhY2gwHhcNMDYwMjE2MDAwMDAwWhcNMDcw
MjE2MjM1OTU5WjCB3DELMAkGA1UEBhMCVUsxDjAMBgNVBAgUBVdhbGVzMRAwDZcwgZQwCQYDVR0TBA
IwADALBgNVHQ8EBAMCBaAwEQYJYIZIAYb4QgEBBAQDAgeAMFQGA1UdHwRNMEswSaBHoEWGQ2h0dHA
6Ly9vbnNpdGVjcmwudHJ1c3R3aXNlLmNvbS9CVEdyb3VwUGxjQjJCT3BlbnJlYWNoL0xhdGVzdENSTC5jcmw
wEQYKYIZIAYb4RQEGCQQDAQH/MA0GCSqGSIb3DQEBBQUAA4GBAK1D1fw8wbBjKzI17E0GRghEBoxiYEqT
hSRczZGYznJXBgloOlIB2iqDCdj5l4DoitLXBbVwYYYcY5tLIgutPeEB6tO1Ui0wd4eLlAPuUnqtMsDdoOvpnXFiB
WmYM/obnL5M8M+l51VVc9YcTGtvcWSAcw2ueTeoWaULkCYM4w0n
</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</ds:Signature></soap:Header><soap:Body xmlns:eb="http://www.oasis-open.org/committees/ebxmlmsg/schema/msgheader- 2_0.xsd" xsi:schemaLocation="http://www.oasisopen.org/committees/ebxmlmsg/schema/msg-header-2_0.xsd http://www.oasisopen.org/committees/ebxmlmsg/schema/msg-header-2_0.xsd"/></soap:Envelope>
Note: There is no attached payload for an ebXML Delivery Acknowledgement.
Issue 1.3 – 20th October 2014
Copyright British Telecommunications plc 2011
Page 22 of 35
B2B Access Guide
6.3.2 Business payload
On this interface, Onramp does not send receipt acknowledgements in addition to an ebXML
Delivery Acknowledgement; the ebXML delivery acknowledgement will be followed by the business
document corresponding to your input (as attachment in ebXML SOAP message).
The ebXML section for a business document has these variables:
ConversationId
As input on request
Service
bcBusinessTransactionDescription, as input
Action
rsBusinessTransactionDescription or
ReceiptAcknowledgementException
MessageId
GyyyyMMddHHmmssSSS .14cc8ce:10a3d2210d5:7d3b@123.123.123.123
RefToMessageId
As input on request
Timestamp
NB format : yyyy-mm-ddThh:mm:ss.mmmZ
6.3.3 Exceptions
It is also possible that your input will be rejected with:
a) ReceiptAcknowledgementException
(This is covered in Template Solution Design BPS Documents and XML
Interface Documents which you can find on the BT Wholesale B2B web pages
The Gateway might reject your input payload for some reason – eg inconsistency between
participants shown in ebXML and payload
b) It is also possible that you will get a SOAP fault eg:
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<soap:Fault>
<faultcode>soap:Client</faultcode>
<faultstring>Exception message: Unable to internalize message Stacktrace: javax.xml.soap.SOAPException: Unable
to internalize message at
com.cyclonecommerce.webservices.protocols.ebxml.Ebxml2Message.parseMimeMessage(Ebxml2Message.java:610
) at com.cyclonecommerce.webservices.soap.SOAPMessageImpl.parseMimeMessage
(SOAPMessageImpl.java:179) at
com.cyclonecommerce.webservices.soap.SOAPMessageImpl.&lt;init>(SOAPMessageImpl.java:123) at
com.cyclonecommerce.webservices.soap.security.AbstractSecureSOAPMessage.&lt;init>(AbstractSecureSOAPMess
age.java:239) at
com.cyclonecommerce.webservices.soap.security.xmldsig.AbstractXmlSecuritySOAPMessage.&lt;init>(AbstractXmlS
ecuritySOAPMessage.java:349) at
com.cyclonecommerce.webservices.soap.versions.ver1_1.SOAPMessage1_1Impl.&lt;init>(SOAPMessage1_1Impl.jav
a:26) at com.cyclonecommerce.webservices.protocols.ebxml.Ebxml2Message.&lt;init>(Ebxml2Message.java:57) at
Issue 1.3 – 20th October 2014
Page 23 of 35
Copyright British Telecommunications plc 2011
B2B Access Guide
com.cyclonecommerce.webservices.protocols.ebxml.EbxmlProtocolReceiver.parseEbxmlMessage(EbxmlProtocolRec
eiver.java:738) at
com.cyclonecommerce.webservices.protocols.ebxml.EbxmlProtocolReceiver.receive(EbxmlProtocolReceiver.java:925
) at
com.cyclonecommerce.tradingengine.messaging.config.ProtocolReceiverProxy.receive(ProtocolReceiverProxy.java:6
) at com.cyclonecommerce.tradingengine.messaging.handler.ProtocolReceiverState.d(ProtocolReceiverState.java:23)
at
com.cyclonecommerce.tradingengine.messaging.handler.ProtocolReceiverState.handleMessage(ProtocolReceiverSta
te.java:17) at
com.cyclonecommerce.tradingengine.messaging.handler.MessageHandlerJob.run(MessageHandlerJob.java:84) at
com.cyclonecommerce.tradingengine.cluster.failover.FailoverableJobTask.execute(FailoverableJobTask.java:2) at
com.cyclonecommerce.util.task.TaskScheduler$d_.primRun(TaskScheduler$d_.java:47) at
com.cyclonecommerce.lang.EventedThread.run(EventedThread.java:22)
Caused by: javax.xml.soap.SOAPException: Invalid SOAP Content-Type: multipart/related; type=text/xml;
boundary=someBoundaryValue; start=ebXML_Message_Header at
com.cyclonecommerce.webservices.protocols.ebxml.Ebxml2Message.parseMimeMessage(Ebxml2Message.java:639
)
... 15 more
</faultstring>
</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.
6.4 Your response to Onramp
You should reply to any message sent by the Gateway with an ebXML Delivery Acknowledgement.
If you do not reply (or the ebXML Delivery Acknowledgement fails to get back to the Gateway) the
message will be sent up to three more times at five minute intervals. It is possible for Onramp to
invoke further resends of failed messages when the problem has cleared.
Depending on the transaction, you may be expected to send a ReceiptAcknowledgement. The Time
To Ack Receipt is set to 0 in the Template Solution Design if a ReceiptAcknowledgement is NOT
required – this usually applies to the RequestResponse business transaction pattern), which will be
another SOAP message with a payload as suggested in the Template Solution Design document.
You can also send ReceiptAcknowledgementException on Onramp when applicable.
The ebXML Actions for these
ReceiptAcknowledgementException.
Business
Issue 1.3 – 20th October 2014
Copyright British Telecommunications plc 2011
Signals
are
ReceiptAcknowledgement,
Page 24 of 35
B2B Access Guide
6.5 Onramp exit criteria
These are the set of tests which need to be done on the Onramp systems before moving to the live
environment. Live server set up starts after the Onramp signoff.
You simply have to fill the exit criteria report 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. Quality Gate
does not constitute to complete functional testing.
The following sections describe separate scenarios for XML Knowledge Based Diagnostics (KBD).
6.5.1 Scenarios for 20CN Knowledge Based Diagnostics (KBD)
The following five test cases are mandatory and must be passed in order to complete KBD
Diagnostics Quality Gate.
Scenario 1: bcRequestKBDInitiatev1
Sender
1 CP
2 BT
3 BT
Message Type
KBDInitiateRequest
KBDInitiateAccepted
KBDQueryNotification
Scenario 2: bcRequestKBDResumev1
Sender
1 CP
2 BT
3 BT
Message Type
KBDQueryRequest
KBDQueryAccepted
KBDFinalResultNotification
Scenario 3: bcRequestKBDTerminatev1
Sender
1 CP
2 BT
Message Type
KBDTerminateRequest
KBDTerminateAccepted
Scenario 4: bcRequestKBDResend1
Sender
1 CP
2 BT
Message Type
KBDResendRequest
KBDResendAccepted
Issue 1.3 – 20th October 2014
Copyright British Telecommunications plc 2011
Page 25 of 35
B2B Access Guide
Scenario 5: bcQueryKBDTestHistoryv1
Sender
Message Type
1
CP
kbdTestHistoryRequest
2
BT
kbdTestHistoryAccepted
Scenario 8: bcRequestKBDPostDiagv1
Sender
Message Type
1
CP
kbdPostDiagRequest
2
BT
kbdTestHistoryAccepted
6.5.2 Scenarios for 21CN Old Knowledge Based Diagnostics (KBD)
Scenario 1: bcRequestKBDInitiate2v1
Sender
Message Type
CP
KBDInitiateRequest
BT
BT
KBDInitiateAccepted
KBDQueryNotification
Scenario 2: bcRequestKBDResume2v1
Sender
Message Type
CP
KBDQueryRequest
BT
KBDQueryAccepted
BT
KBDFinalResultNotification
Scenario 3: bcRequestKBDTerminate2v1
Sender
Message Type
CP
KBDTerminateRequest
KBD
KBDTerminateAccepted
Scenario 4: bcRequestKBDResend2v1
Sender
Message Type
CP
KBDResendRequest
KBD
KBDResendAccepted
Issue 1.3 – 20th October 2014
Copyright British Telecommunications plc 2011
Page 26 of 35
B2B Access Guide
Scenario 5: bcQueryKBDTestHistory2v1
Sender
Message Type
CP
KBDTestHistoryRequest
BT
KBDTestHistoryAccepted
Scenario 6: bcRequestKBDPostDiag2v1
Sender
Message Type
CP
KBDPostDiagRequest
BT
KBDTestHistoryAccepted
Note: About “RESEND [bcRequestKBDResend1]” functionality.
On the B2B onramp Gateway, the Resend functionality works as either accepted/rejected i.e. you can either choose
either accepted/rejected responses from the emulator.
But on the Production of the question” What would happen if the QueryNotification from KBD to CP is lost?”
This can result in a message loop where your system will be waiting indefinitely for a message from KBD, whilst
the KBD will be in turn waiting for the QueryRequest from you.
To avoid this situation, a resend option is available. Using the KBDResendRequest message; you can request
KBD to resend the last QueryNotification or KBDFinalResultNotification.
Please note, however, that a ResendRequest can be used only twice for a QueryNotification or
FinalResultNotification.
6.5.3 Scenarios for 21CN New Knowledge Based Diagnostics (KBD)
Scenario 1: bcRequestKBDInitiate2v1
Sender
Message Type
CP
KBDInitiateRequest
BT
BT
KBDInitiateAccepted
KBDFinalResultNotification
Scenario 2: bcQueryKBDTestHistory2v1
Sender
Message Type
CP
KBDTestHistoryRequest
BT
KBDTestHistoryAccepted
BT
KBDTestHistoryResult
Issue 1.3 – 20th October 2014
Copyright British Telecommunications plc 2011
Page 27 of 35
B2B Access Guide
6.6 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 (this will also test the Collaboration Protocol Agreement (CPA) for
completeness if you are using one to set up your Message Handling System (MHS)).
Issue 1.3 – 20th October 2014
Copyright British Telecommunications plc 2011
Page 28 of 35
B2B Access Guide
7. SDK and Emulator
7.1 Overview
Our Software Development Kit (SDK) and Emulator tools help you when using the 21CN
Knowledge Based Diagnostics (KBD) services. The KBD B2B SDK provides the tools, sample
code and documentation that the customers need to quickly and easily integrate with the BT
Wholesale B2B gateway.
The SDK provides a Java API which allows you to create, validate, send and receive 21CN KBD
B2B XML. The SDK is only available in Java you simply need to be able to integrate this into your
existing environment.
The SDK encapsulates the ebXML process through the use of the Hermes B2B Gateway. It also
provides a locally deployable test environment to allow simulated end-to-end testing before
connecting to BT.
The Emulator tool can be used to develop and test the integration of the SDK into the customer's
processing stack. It performs automatic validation of inbound messages and gives the facility to
generate the relevant responses. The Emulator gives you the ability to generate simulated BT
responses on demand.
Therefore the use of SDK-Emulator will mean a faster integration with BT systems.
The SDK code is to be used to connect to the Emulator deployed on the Onramp environment,
complete the testing and then use the code to place orders against the Live environment.
All you need to do is go to the link http://wssdk.wholesale.bt.com/SDKPortal/forms/loginform.html
and download the latest SDK/Emulator and documentation using the below credentials.
Username: btwkbd
Password: 21Ckbd
If you are currently live on the B2B gateway (using your own propriety software), and would like to
move to SDK messaging you simply need to go through Onramp process at least once to prove the
SDK access.
Please note that the SDK supports only 21CN Knowledge Based Diagnostics (KBD) services
and does not support 20CN Knowledge Based Diagnostics (KBD).
The point of contact for the customers during the SDK testing would be the Partner Enablement
Management (PEM) team (wholesale.pem@bt.com).
Issue 1.3 – 20th October 2014
Copyright British Telecommunications plc 2011
Page 29 of 35
B2B Access Guide
7.2 Benefits
Here is a quick look at the benefits that you can attain by using the SDK-Emulator functionality on
your side:
a) Emulator gives ability to generate simulated BT responses on demand.
b) Improved data validation prior to sending to BT.
c) Encapsulates ebXML process through uses of the Hermes B2B Gateway – signing of ebXML
messages is easier, quicker and can be done with no issues.
d) Faster integration with BT systems.
e) Save time with less reliance on documentation and sample XMLs.
f) Provides a locally deployable test environment to allow E2E testing before connecting to BT.
7.3 Installation details
The advantage of Emulator over the regular Onramp phase is that it allows you to deploy Emulator
in your own development environments to carry out the initial testing and get a hands-on experience
over its usability and functionalities.
So, there are three options of deployment available as you move from initial testing to production.
Connection of SDK to locally deployed Emulator in your own development environment.
Connection of SDK to Onramp BT Wholesale B2B environment - Emulator would be deployed
on the BT Wholesale Onramp gateway and you can use the web interface to control message
flow (receive the responses that you would like to obtain from BT for a business order)
Connection of SDK to live BT Wholesale B2B Gateway for use in production environment.
The prerequisites and all the details required for the installation of SDK and locally deployable
emulator is available in the installation guide that you will receive as a part of the SDK starter
package.
First go to http://wssdk.wholesale.bt.com/SDKPortal/forms/loginform.html
In order to get your copy of the SDK emulator you will need to use the below credentials and
login to the SDK Portal.
Username: btwkbd
Password: 21Ckbd
The installation guide gives you a detailed explanation of:
Deployment options
SDK Installation
Emulator setup
Running the SDK examples
Certificate setup on Apache tomcat server and Hermes
Issue 1.3 – 20th October 2014
Copyright British Telecommunications plc 2011
Page 30 of 35
B2B Access Guide
7.4 How to use the Onramp Emulator
The link to fire the desired responses on behalf of BT Wholesale and the access credentials will be
provided to you by the PEM Team.
At this link, you will be able to find the details of the XML posted (MessageID, time-stamp etc). You
will also be able to find the associated responses that can be sent from BT Wholesale for the request
posted.
You must ensure that you refer the XML Interface document and the Template solution documents
for 21CN KBD Services available on the Bt Wholesale Web site to understand the XML validations
for tags and the order journey for the services.
If you would like to use 21CN KBD services via SDK and Onramp Emulator, then please get in touch
with the PEM Team.
They will guide you further on the same.
7.5 Guidelines
a) It is mandatory that you perform a round of testing using the SDK against the Emulator
deployed on Onramp, before using the SDK code on the live systems for 21CN KBD services.
b) SDK would be updated in releases according to the fixes (if any) or for incorporating the new
services/functionalities offered by us. Therefore, you must ensure that you download the latest
release kit and use the same to test within your development servers, Emulator or for live
purposes.
c) If you are new to the B2B gateway, then sections 3 and 4 of this document which explain the
certificate application and extraction process along with the details that need to be provided for
the Onramp setup, are also appropriate for SDK too.
d) Using the Emulator functionality allows you to obtain responses which are very similar to the
responses sent by the actual live systems by the following means:
Validations that are in place to check that the correct values are used in the XMLs on
the Live systems will be covered by the emulator as well.
ii. Emulator allows you to choose the kind of response we could send across for your
requests. This essentially means that all the scenarios associated with an order
journey are incorporated in the Emulator thus allowing you to formulate test cases of
your own and understand the responses obtained from BT Wholesale for various
scenarios.
i.
e) Once you have completed the Onramp testing for the services that you have planned to use
on live, we will send you the Onramp exit criteria document. You will need to fill the document
with the details of the Onramp tests you have done. (Please note that the testing should be
done within five days before you submit the document.
f) Your point of contact for any SDK-Emulator related queries/issues would be the BT Wholesale
PEM team (wholesale.pem@bt.com)
Issue 1.3 – 20th October 2014
Copyright British Telecommunications plc 2011
Page 31 of 35
B2B Access Guide
8. Pilot and live phase
8.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 if
these apply. We will then carry out any final checks on your certificate configuration and, if you need
one, we will send you a new Collaboration Protocol Agreement (CPA) and send you an email to tell
you when your B2B Gateway services will be approved.
In technical terms, the only changes are:
Use https://www.b2b.btwholesale.bt.com/b2b/httpReceiver as the URL to address
messages to.
The DNS www.b2b.btwholesale.bt.com resolves to the IP addresses 193.113.4.149,
193.113.8.61 and 62.239.186.27.
You will need to make sure that the firewall on your side is in place for the above IP addresses
to send messages to BT Wholesale.
Production will send messages from one of the following three outgoing IP addresses
193.113.4.136
193.113.8.56
62.239.186.29
193.113.57.20
193.113.48.116
You will need to make sure that the firewall on your side is in place for the above IP addresses
to receive messages from BT Wholesale accordingly.
Change the CPA ID referenced in messages to the CPA ID from the production CPA newly
provided to you.
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 4 weeks if you are a new customer, and so if you have
any issues while placing orders against the live system please get in touch.
Issue 1.3 – 20th October 2014
Copyright British Telecommunications plc 2011
Page 32 of 35
B2B Access Guide
Within this period, you would need to
Test for all the services on live and contact the PEM team (wholesale.pem@bt.com) if you
face any issue.
Once you have completed testing for all the services, you will need to inform PEM about the
completion of tests.
These tests could be similar to those of the Onramp tests you had carried out earlier (in terms
of various services and XMLs used).
8.2 Live
If you face any issues after the two (or four) weeks of trial period, you will need to contact our first
line of support at broadband.eco.admin@bt.com .
Issue 1.3 – 20th October 2014
Copyright British Telecommunications plc 2011
Page 33 of 35
B2B Access Guide
9. Glossary
BT
BTW
CA
TP
CPAID
DUNS
DNS
IP
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
Internet Protocol
Office of the Telecommunications Adjudicator
Processing Instruction (XML terminology)
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 – 20th October 2014
Copyright British Telecommunications plc 2011
Page 34 of 35
B2B Access Guide
10. Document history
Issue
1.0
Date
04/02/2011
Author
PEM team
1.1
30-09-2011
BTW team
1.2
07/11/2011
PEM Team
1.3
21/10/2014
PEM Team
Issue 1.3 – 20th October 2014
Copyright British Telecommunications plc 2011
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 the User Guide to include
information about 21CN KBD SDK-Emulator
availability
Replaced the legacy gateway’s URL and IP
addresses with that of new gateway.
Removed references to Processing Instruction
and Simulator.
Added test scenarios for 21CN New KBD.
Page 35 of 35
