B2B Access Guide
BT Wholesale
Broadband Knowledge Based
Diagnostics (KBD) Business to
Business (B2B) Access User Guide
Issue 1.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 1 of 39
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.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 2 of 39
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? ................................................................................................... 6
W HAT IS BT W HOLESALE ONRAMP NOT FOR? ............................................................................................ 6
W HEN IS ONRAMP TESTING APPLICABLE? ................................................................................................... 6
HOW IS ONRAMP USED? .............................................................................................................................. 8
HOW LONG WILL YOU USE ONRAMP FOR? ................................................................................................... 9
SETTING UP THE GATEWAY ............................................................................................................................. 10
3.1
3.2
4.
YOUR SETUP ............................................................................................................................................... 10
BT W HOLESALE SIDE SET UP ..................................................................................................................... 10
SECURITY AND CERTIFICATE INFORMATION ............................................................................................. 13
4.1
4.2
5.
DOWNLOADING A NEW DIGITAL CERTIFICATE ............................................................................................. 13
SENDING US YOUR PUBLIC KEY OF THE CERTIFICATE ................................................................................ 13
ONRAMPING PHASE ............................................................................................................................................ 15
5.1
6.
CONFIRMING CONNECTIVITY WITH THE ONRAMP PLATFORM ..................................................................... 15
USING ONRAMP .................................................................................................................................................... 17
6.1
6.2
6.3
6.4
6.5
6.6
7.
MESSAGES FROM YOU TO ONRAMP ........................................................................................................... 17
MESSAGES FROM ONRAMP TO YOU ........................................................................................................... 22
HTTP.......................................................................................................................................................... 22
YOUR RESPONSE TO ONRAMP ................................................................................................................... 26
ONRAMP EXIT CRITERIA .............................................................................................................................. 27
MESSAGE HANDLING .................................................................................................................................. 31
SDK AND EMULATOR .......................................................................................................................................... 32
7.1
7.2
7.3
7.4
7.5
8.
OVERVIEW .................................................................................................................................................. 32
BENEFITS .................................................................................................................................................... 33
INSTALLATION DETAILS ............................................................................................................................... 33
HOW TO USE THE ONRAMP EMULATOR ..................................................................................................... 34
GUIDELINES ................................................................................................................................................ 34
PILOT AND LIVE PHASE ..................................................................................................................................... 36
8.1
8.2
PILOT .......................................................................................................................................................... 36
LIVE............................................................................................................................................................. 37
9.
GLOSSARY ............................................................................................................................................................. 38
10.
DOCUMENT HISTORY .......................................................................................................................................... 39
Issue 1.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 3 of 39
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: 02034505227
Issue 1.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 4 of 39
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.
We have now introduced a new functionality called the “Onramp Emulator” for 21CN KBD
services.
Please note that the Onramp Emulator currently supports 21CN KBD services (and
not 20CN KBD services)
This document will be helpful to you intend to use the BT Wholesale B2B Onramp Gateway
and the BT Wholesale Onramp Emulator (which is available only for 21CN KBD services).
The major differences between the Onramp testing against the BT Wholesale B2B Onramp
gateway and BT Wholesale Onramp Emulator areBT Wholesale B2B Onramp gateway
BT Wholesale Onramp Emulator
Requires insertion of Processing
Instruction (PI) in the payload XML to
obtain the stubbed responses
Does not require a Processing Instruction
(PI) to obtain a response
The response XML can be obtained as per
the PI used in the XML request.
The Customer has the ability to access
the emulator Graphic User Interface
(GUI) and fire the responses on our
behalf.
This offers a connectivity platform rather
than a testing platform.
Emulator gives you a more realistic
approach to testing the XMLs Software
Development Kit. (SDK) and Emulator are
to be used together for testing.
Issue 1.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 5 of 39
B2B Access Guide
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
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.
Issue 1.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 6 of 39
B2B Access Guide
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.
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.
Issue 1.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 7 of 39
B2B Access Guide
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:
AcceptanceAcknowledgementException messages – these are normally
generated because of problems in, or detected by, Onramp’s backend
processing systems - through the use of a processing instruction (PI).
ReceiptAcknowledgementException – these can be generated by submitting
bad XML or good XML with a Data Universal Numbering System (DUNS)
number different to that expected.
Issue 1.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 8 of 39
B2B Access Guide
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 set-up 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.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 9 of 39
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.onramp1.b2b.btwholesale.com/exchange/232510151
Onramp will send messages from one of the following four IP addresses.
193.113.57.20
193.113.57.21
193.113.48.116
193.113.48.118
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
Issue 1.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 10 of 39
B2B Access Guide
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.
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 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.
The technology used to build your Gateway
Depending on the resources and set up of your organisation, you can, if you prefer, work in
partnership with a third party team or individuals you appoint.
Your preferred testing date
Setting up an Onramp test can take as little as a week. However, everyone’s circumstances
are unique and our PEM team will be well placed to discuss a realistic schedule with you.
As long as the lead times are realistic, we will work with you to ensure we begin testing by
the date you have chosen.
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
Issue 1.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 11 of 39
B2B Access Guide
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.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 12 of 39
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.
If you are in any doubt, please feel free to discuss any existing certificates with our PEM
team.
4.1 Downloading a new digital certificate
A client certificate will carry out the entire basic authentication you require but is not tied to a
Domain Name System (DNS) name and IP address. You can transfer this certificate from
one computer to another as and when required.
You may apply for a client certificate using this link.
https://onsite.trustwise.com/services/BTGroupPlcNorthsideclient/digitalidCenter.htm
To get your certificate:
Start by clicking on the “INSTALL CA” option on the page and follow the
instructions that will help you to install the CA
Next click on the “ENROL” option.
Enter your first name, last name, E-mail Address, Employee ID number and
company - 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); a
Challenge phrase may be needed later, and please also add a note in the text
box provided in the comment option to tell us where you would use the certificate.
4.2 Sending us your public key of the certificate
To export your 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 (if you wish to only export the public key), do not export the private
key.
4. Next, choose either binary or base-64 .cer or a .p7b (with or without a Certificate of
Authority (CA))
5. Save the file in a folder of your choice. And please keep this folder safe.
Now, zip this exported public key and email a copy to the PEM team so that we can
authenticate the messages you send us and set you up with the https connection from the
Onramp environment to your server.
Issue 1.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 13 of 39
B2B Access Guide
The reason you will need to export the public part of the certificate (without private key) and
send the file to the PEM team is because we do not automatically have a copy of the public
key.
With the correct digital certificate downloaded, you need to carry out the following activities:
1. Back up the entire digital certificate and keep it safe as you would do for any other
company asset.
2. If you are changing to a new system, you will need to export the certificate (with
private key, type .pfx) to move it to a separate server box.
3. In these circumstances, you will also need to change the certificate’s format
depending on your requirements (a visit to www.openssl.org may prove useful).
4. You should also move the Certificate Authority to maintain the evidence of trust (by
using the “export all certificates in path” command).
IMPORTANT: We recommend and are only able to support the use of latest version of
Internet Explorer (versions from and above 6.0) for installation and extraction of the
certificate to and from your computer.
Issue 1.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 14 of 39
B2B Access Guide
5. Onramping 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 the 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 does not prove that the certificates required for the session to be
established are in place or not.
Here is a Sample of a Telnet command indicating connectivity between the two
environments, in the request path (CP BT)
C:\ telnet 217.140.45.133 443
Trying 217.140.45.133...
Connected to 217.140.45.133.
Escape character is '^]'.
Here is a Sample of a Telnet command indicating a lack of connectivity between
the two environments, in the request path (CP BT)
C:\ telnet 217.140.45.133 443
Trying 217.140.45.133...
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.onramp1.b2b.btwholesale.com/ServerStatus
When accessing this link it will ask you to present your certificate given to you by
BT Wholesale with a “Northside” 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.
Issue 1.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 15 of 39
B2B Access Guide
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.
3.1.1 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.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 16 of 39
B2B Access Guide
6. Using Onramp
Messages are sent to Onramp by an https POST to URL:
https://www.onramp1.b2b.btwholesale.com/exchange/232510151
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 /exchange/ 232510151 HTTP/1.1
Host: www.onramp1.b2b.btwholesale.com
SOAPAction: "ebXML"
Content-Type: multipart/related; type="text/xml"; boundary="someBoundaryValue";
start="ebXML_Message_Header"
--someBoundaryValue
Content-Type: text/XML
Issue 1.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 17 of 39
B2B Access Guide
Content-ID: <ebXML_Message_Header>
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-header2_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/Party ID
Role
CPA ID
Conversation
ID
Service
Action
Message ID
Time stamp
CP DUNS number (123456789)
Communications Provider
BT_Wholesale_CPname_cpa
Something unique RFC 2822 Internet Message Format
(http://www.faqs.org/rfcs/rfc2822.html) may help.
Onramp uses the algorithm: "C" + current timestamp in milliseconds (format
"yyyyMMddHHmmssSSS") + "." new java.rmi.server.UID() + “@” +
HostAddress
bcBusinessTransactionDescription
rqBusinessTransactionDescription
or
ReceiptAcknowledgement,
ReceiptAcknowledgementException,
AcceptanceAcknowledgementException (for Business Signals)
Something unique. RFC 2822 Internet Message Format
(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
NB format : yyyy-mm-ddThh:mm:ss.mmmZ
-->
Issue 1.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 18 of 39
B2B Access Guide
<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_CPname_BT_Wholesale_TestPartner1_XMLRMigration_cpa_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"]|
ancestor-or-self::node()[@soap:actor="http://schemas.xmlsoap.org/soap/actor/next"])
</XPath>
</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>
Issue 1.2 – 7th November 2011
Page 19 of 39
Copyright British Telecommunications plc 2011
B2B Access Guide
</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>
<?xml version="1.0" encoding="UTF-8" ?>
<!-Following is an example for “KBDInitiateAccepted” showing an appropriate PI as required for
generation of sample business responses on Onramp.
The Onramp Processing Instruction follows – positive (Acceptance Request) in this case.
-->
<? BTW_B2B_OnRamp_Test_Id ?B2B_BTW_KBD_bcRequestKBDInitiatev1_KBDInitiateAccepted?>
<!-Remember: PIs should not be included on Production.
Issue 1.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 20 of 39
B2B Access Guide
-->
<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.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 21 of 39
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/
Issue 1.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 22 of 39
B2B Access Guide
http://www.oasis-open.org/committees/ebxml-msg/schema/envelope.xsd">
<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:PartyId eb:type="urn:oasis:names:tc:ebXMLcppa:partyidtype:duns">123456789</eb:PartyId><eb:Role>ServiceProvider</eb:Role></eb:To><eb:CPAId>B
T_Wholesale_CPname_BT_Wholesale_TestPartner1_XMLRMigration_cpa_cpa</eb:CPAId>
<eb:ConversationId>0329040b-55b2-4275-90928a1faf89b385</eb:ConversationId><eb:Service>urn:oasis:names:tc:ebxmlmsg:service</eb:Service><eb:Actio
n>Acknowledgment</eb:Action><eb:MessageData><eb:MessageId>M1141998769979.615866@cbu072a003
8438259305634289897</eb:MessageId><eb:Timestamp>2006-0310T13:52:49.979Z</eb:Timestamp><eb:RefToMessageId>M1141998769579.43077@cyclone1125933195045
429953</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@cyclone1125933195045
429953</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:Refe
renceURI=""
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
Issue 1.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 23 of 39
B2B Access Guide
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>6n4NAMKfYUzVi0EVTfdadDLCndw=</ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue>
Ez6T7H91CPXdcGxbXeTiNL8IiB9j31dlNQhUi9x1xTIuzdCGgflilpHBJafy0erSjeI686g+FI2VAfZBVjUkeintB
HPKcCtbQ1JQvUATvWqaDJ3HJGS1Fhc6uRCT+w7it0kgFdtRmp6zF6VFkk+2iEfP2C+wCU6TcasJ+d0PK
uQ=
</ds:SignatureValue>
<ds:KeyInfo>
<ds:KeyValue>
<ds:RSAKeyValue>
<ds:Modulus>
qsJAIxkbPNgbu6+OCqS/nIF5R1izY5T475x4daVedCt8OEw5CB4ZNns29evGvoe0vvIDzoTjvtEL1FbNr8izc
aG0JGa0KmUwVi5l7puTFJ043hH6Xs4RvV+2IEmoaZRqHY6Ic3YQblU4m+k9iUu2fE6onY4gSfHI9TocJPV
KFU8=
</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>
MIIDKTCCApKgAwIBAgIQOLnSINSLEHRhB8WRncHKDzANBgkqhkiG9w0BAQUFADAvMRUwEwYDVQ
QKEwxCVCBHcm91cCBQbGMxFjAUBgNVBAMTDUIyQiBPcGVucmVhY2gwHhcNMDYwMjE2MDAwMD
AwWhcNMDcwMjE2MjM1OTU5WjCB3DELMAkGA1UEBhMCVUsxDjAMBgNVBAgUBVdhbGVzMRAwDZ
cwgZQwCQYDVR0TBAIwADALBgNVHQ8EBAMCBaAwEQYJYIZIAYb4QgEBBAQDAgeAMFQGA1UdHw
RNMEswSaBHoEWGQ2h0dHA6Ly9vbnNpdGVjcmwudHJ1c3R3aXNlLmNvbS9CVEdyb3VwUGxjQjJCT3
BlbnJlYWNoL0xhdGVzdENSTC5jcmwwEQYKYIZIAYb4RQEGCQQDAQH/MA0GCSqGSIb3DQEBBQUAA
4GBAK1D1fw8wbBjKzI17E0GRghEBoxiYEqThSRczZGYznJXBgloOlIB2iqDCdj5l4DoitLXBbVwYYYcY5t
LIgutPeEB6tO1Ui0wd4eLlAPuUnqtMsDdoOvpnXFiBWmYM/obnL5M8M+l51VVc9YcTGtvcWSAcw2ueTe
oWaULkCYM4w0n
</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.
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).
Issue 1.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 24 of 39
B2B Access Guide
The ebXML section for a business document has these variables:
Conversation ID
Service
Action
Message ID
Ref-to-Message ID
Timestamp
As input on request
bcBusinessTransactionDescription, as input
rsBusinessTransactionDescription or
ReceiptAcknowledgementException,
AcceptanceAcknowledgementException
GyyyyMMddHHmmssSSS .14cc8ce:10a3d2210d5:7d3b@123.123.123.123
As input on request
Note the format : yyyy-mm-ddThh:mm:ss
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) AcceptanceAcknowledgementException
(This is covered in Template Solution Design document)
Gateway passes your input to other systems but they either reject it before
processing or fail to return it
c) 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.j
ava: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>(AbstractSecureSO
APMessage.java:239) at
com.cyclonecommerce.webservices.soap.security.xmldsig.AbstractXmlSecuritySOAPMessage.&lt;init>(Abstra
ctXmlSecuritySOAPMessage.java:349) at
com.cyclonecommerce.webservices.soap.versions.ver1_1.SOAPMessage1_1Impl.&lt;init>(SOAPMessage1_1
Impl.java:26) at
com.cyclonecommerce.webservices.protocols.ebxml.Ebxml2Message.&lt;init>(Ebxml2Message.java:57) at
com.cyclonecommerce.webservices.protocols.ebxml.EbxmlProtocolReceiver.parseEbxmlMessage(EbxmlProt
ocolReceiver.java:738) at
com.cyclonecommerce.webservices.protocols.ebxml.EbxmlProtocolReceiver.receive(EbxmlProtocolReceiver.j
ava:925) at
com.cyclonecommerce.tradingengine.messaging.config.ProtocolReceiverProxy.receive(ProtocolReceiverProx
y.java:6) at
com.cyclonecommerce.tradingengine.messaging.handler.ProtocolReceiverState.d(ProtocolReceiverState.java
Issue 1.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 25 of 39
B2B Access Guide
:23) at
com.cyclonecommerce.tradingengine.messaging.handler.ProtocolReceiverState.handleMessage(ProtocolRec
eiverState.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.j
ava: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 AcceptanceAcknowledgementException or
ReceiptAcknowledgementException on Onramp when applicable.
The ebXML Actions for these Business Signals are ReceiptAcknowledgement,
ReceiptAcknowledgementException, AcceptanceAcknowledgementException.
On-Ramp is a flexible phase which can be tailored to the particular tests you wish to run. To
discuss these and any other related issues, please contact the PEM team
Issue 1.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 26 of 39
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 XML 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
Message Type
Processing Instruction
1 CP
KBD Request
<?BTW_B2B_OnRamp_Test_Id
2 BT
A response indicating
that kbdInitiate Request
is Accepted
?B2B_BTW_KBD_bcRequestKBDInitiatev1_kbdIniti
ateAccepted?>
Scenario 2: bcRequestKBDResumev1
Sender
1 CP
2 BT
Message Type
Processing Instruction
KBD Request message
to resume Diagnostic
A response indicating
that kbdResume
Request is Accepted
<?BTW_B2B_OnRamp_Test_Id
?B2B_BTW_KBD_bcRequestKBDResumev1_kbdQ
ueryAccepted?>
Scenario 3: bcRequestKBDTerminatev1
Sender
1 CP
Message Type
Processing Instruction
Request message to
terminate test
<?BTW_B2B_OnRamp_Test_Id
Issue 1.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 27 of 39
B2B Access Guide
?B2B_BTW_KBD_bcRequestKBDTerminatev1_kbd
TerminateAccepted?>
2 BT
A response indicating
the kbd Terminate
request is accepted.
Scenario 4: bcNotifyOfKBDQueryv1
Sender
1 CP
2 BT
Message Type
A notification containing
a query from BT
Wholesale gateway.
Processing Instruction
<?BTW_B2B_OnRamp_Test_Id
?B2B_BTW_KBD_bcNotifyOfKBDQueryv1_AUTON
OTIFICATION?>
BT onramp Sends
same XML in response
Scenario 5: bcNotifyOfKBDFinalResultv1
Sender
Message Type
Processing Instruction
A final test result
1 CP
notification from BT
Wholesale gateway
2 BT
BT onramp Sends
same XML in response
<?BTW_B2B_OnRamp_Test_Id
?B2B_BTW_KBD_bcNotifyOfKBDFinalResultv1_AU
TONOTIFICATION?>
Scenario 6: bcRequestKBDResend1
Sender
Message Type
Processing Instruction
1 CP
kbdResendRequest
<?BTW_B2B_OnRamp_Test_Id
2
A response indicating
that kbdResend
Request is Accepted
?B2B_BTW_KBD_bcRequestKBDResendv1_kbdRe
BT
sendAccepted?>
Scenario 7: bcQueryKBDTestHistoryv1
1
2
Sender
Message Type
Processing Instruction
CP
kbdTestHistoryRequest
<?BTW_B2B_OnRamp_Test_Id
BT
A response indicating that
kbd TestHistory Request
is Accepted
?B2B_BTW_KBD_bcQueryKBDTestHistoryv1_k
bdTestHistoryAccepted?>
Scenario 8: bcRequestKBDPostDiagv1
Sender
Message Type
1
CP
kbdPostDiagRequest
2
BT
A response indicating that
kbd PostDiag Request is
th
Issue 1.2 – 7 November 2011
Processing Instruction
<?BTW_B2B_OnRamp_Test_Id
?B2B_BTW_KBD_bcRequestKBDPostDiagv1_k
Copyright British Telecommunications plc 2011
Page 28 of 39
B2B Access Guide
Accepted
bdPostDiagAccepted?>
6.5.2 Scenarios for 21CN XML Knowledge Based Diagnostics
(KBD)
Scenario 1: bcRequestKBDInitiate2v1
Sender
Message Type
Processing Instruction
CP
KBDInitiateRequest
KBD
KBDInitiateAccepted
<?BTW_B2B_OnRamp_Test_Id
?B2B_BTW_KBD_bcRequestKBDInitiate2v1_
kbdInitiateAccepted21C?>
Scenario 2: bcRequestKBDResume2v1
Sender
Message Type
CP
KBDQueryRequest
KBD
KBDQueryAccepted
Processing Instruction
<?BTW_B2B_OnRamp_Test_Id
?B2B_BTW_KBD_bcRequestKBDResume2v1
_kbdQueryAccepted21C?>
Scenario 3: bcRequestKBDTerminate2v1
Sender
Message Type
CP
KBDTerminateRequest
KBD
KBDTerminateAccepted
Processing Instruction
<?BTW_B2B_OnRamp_Test_Id
?B2B_BTW_KBD_bcRequestKBDTerminate2v
1_kbdTerminateAccepted21C?>
Scenario 4: bcRequestKBDResend2v1
Sender
Message Type
CP
KBDResendRequest
KBD
KBDResendAccepted
Processing Instruction
<?BTW_B2B_OnRamp_Test_Id
?B2B_BTW_KBD_bcRequestKBDResend2v1
_kbdResendAccepted21C?>
Scenario 5: bcNotifyOfKBDFinalResult2v1
Sender
Message Type
CP
KBDFinalResultNotification
KBD
BT Onramp Sends same XML
in response
Processing Instruction
<?BTW_B2B_OnRamp_Test_Id
?B2B_BTW_KBD_bcNotifyOfKBDFinalResult
2v1_AUTONOTIFICATION?>
Issue 1.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 29 of 39
B2B Access Guide
Scenario 6: bcNotifyOfKBDQuery2v1
Sender
Message Type
CP
KBDQueryNotification
KBD
BT Onramp Sends same XML
in response
Processing Instruction
<?BTW_B2B_OnRamp_Test_Id
?B2B_BTW_KBD_bcNotifyOfKBDQuery2v1_
AUTONOTIFICATION?>
Scenario 7: bcQueryKBDTestHistory2v1
Sender
Message Type
Processing Instruction
CP
kbdTestHistoryRequest
<?BTW_B2B_OnRamp_Test_Id
BT
kbdTestHistoryAccepted21C
?B2B_BTW_KBD_bcQueryKBDTestHistory2
v1_kbdTestHistoryAccepted21C?>
Scenario 8: bcRequestKBDPostDiag2v1
Sender
Message Type
Processing Instruction
CP
kbdPostDiagRequest
<?BTW_B2B_OnRamp_Test_Id
?B2B_BTW_KBD_bcRequestKBDPostDiag2
BT
kbdTestHistoryAccepted21C
v1_kbdPostDiagAccepted21C?>
Note: About “RESEND [bcRequestKBDResend1]” functionality.
On the B2B onramp Gateway, the Resend functionality works as either accepted/rejected i.e. responses will
be sent as either accepted/rejected depending upon the PI.
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.
Issue 1.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 30 of 39
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)).
The Processing Instructions (PIs) will take the form:
<?BTW_B2B_OnRamp_Test_Id ?KEY1?>
All the possible Processing Instructions can be found in the XL sheet provided here below.
20CN_KBD_PI_Sheet 21CN_KBD_PI_Sheet
.xls
.xls
AUTONOTIFICATION
For AutoNotification you would need to send a request on Onramp using the service value
of the required notification, Action value as “AutoNotification” and the Notification XML
payload (Available in the Business Process Specification Schema (BPSS)). Please note,
unlike production behavior, on Onramp you would need to request for an AutoNotification
explicitly.
Issue 1.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 31 of 39
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 register (using the link below) with your correct Data Universal
Numbering System (DUNS) ID then can download the latest SDK/Emulator and
documentation from the link - http://wssdk.wholesale.bt.com/SDKPortal/
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.
At the moment SDK only supports 21CN Knowledge Based Diagnostics (KBD)
services only and does not support 20CN Knowledge Based Diagnostics (KBD).
The point of contact for the customers during the SDK testing would be the Partnership
Enablement Management (PEM )team (wholesale.pem@bt.com).
Issue 1.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 32 of 39
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/
In order to get your copy of the SDK you will need to register on the SDK Portal using
the link above. You will need to provide your company’s 9 digit Data Universal
Numbering System (DUNS) ID during this process.
The installation guide gives you a detailed explanation of:
Deployment options
SDK Installation
Emulator setup
Running the SDK examples
Issue 1.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 33 of 39
B2B Access Guide
Certificate setup on Apache tomcat server and Hermes
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.
iii. Use of a processing instruction (PI) in the XML payload is not required. is
unlike the Onramp test systems where the payload for each XML needs to be
altered by adding the PI for obtaining the responses.
i.
Issue 1.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 34 of 39
B2B Access Guide
iv.
Emulator allows you to adhere to the order journey.
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.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 35 of 39
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.com/exchange/232510151 as the URL to
address messages to.
Change the CPA ID referenced in messages to the CPA ID from the production CPA
newly provided to you.
Production will send messages from one of the following four outgoing IP addresses
193.113.57.20
193.113.57.21
193.113.48.116
193.113.48.118
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.
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.
Issue 1.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 36 of 39
B2B Access Guide
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.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 37 of 39
B2B Access Guide
9. Glossary
BT
BTW
CA
TP
CUPID
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.2 – 7th November 2011
Copyright British Telecommunications plc 2011
Page 38 of 39
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
Issue 1.2 – 7th November 2011
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
Page 39 of 39
