21C Broadband Web Services Access User Guide - BT Wholesale

balecomputerΑσφάλεια

3 Νοε 2013 (πριν από 3 χρόνια και 5 μήνες)

106 εμφανίσεις

Web Services Access Guide

Issue 2.
7



1
7
th

October
2011


Page
1

of
25

Copyright


British Telecommunications plc 20
11





























21CN Web Services Access User
Guide



B
T
W
holesale

Web Services Access Guide

Issue 2.
7



1
7
th

October
2011


Page
2

of
25

Copyright


British Telecommunications plc 20
11

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 Telecommu
nications plc, 2011.

Registered office: 81, Newgate Street, London, EC1A 7AJ

Registered in England no. 1800000














Web Services Access Guide

Issue 2.
7



1
7
th

October
2011


Page
3

of
25

Copyright


British Telecommunications plc 20
11

Contents

1.

ABOUT THIS HANDBOO
K

................................
................................
................................
................................
.....

4

1.1

V
ERSION
C
ONTROL

................................
................................
................................
................................
......

4

1.2

F
URTHER
I
NFORMATION
.

................................
................................
................................
..............................

4

2.

INTRODUCTION

................................
................................
................................
................................
.......................

5

2.1

W
HAT IS
BT

W
HOLESALE
O
NRAMP FOR
?

................................
................................
................................
...

5

2.2

W
HAT IS
BT

W
HOLESALE
O
NRAMP NOT FOR
?

................................
................................
............................

5

2.3

H
OW LONG WILL YOU USE

O
NRAMP FOR
?

................................
................................
................................
...

6

3.

SETTING UP THE GATEW
AY

................................
................................
................................
...............................

7

3.1

BT

W
HOLESALE SIDE SET UP

................................
................................
................................
.......................

7

3.2

Y
OUR
O
NRAMP SETUP

................................
................................
................................
................................
.

8

4.

SECURITY & CERTIFICA
TE INFORMATION

................................
................................
................................
...

10

4.1

D
OWNLOADING A NEW DIG
ITAL CERTIFI
CATE

................................
................................
.............................

10

4.2

S
ENDING US YOUR PUBLI
C KEY OF THE CERTIFI
CATE

................................
................................
................

10

5.

ONRAMP TESTING

................................
................................
................................
................................
................

12

5.1

I
NTRODUCTION TO
O
NRAMP

................................
................................
................................
.......................

12

5.2

M
ESSAGES FROM YOU TO
O
NRAMP

................................
................................
................................
...........

12

5.3

M
ESSAGES FROM
O
NRAMP TO YOU

................................
................................
................................
...........

18

5.4

O
NRAMP EXIT CRITERIA

................................
................................
................................
..............................

19

6.

PILOT AND LIVE PHASE

................................
................................
................................
................................
.....

22

7.

GLOSSARY

................................
................................
................................
................................
.............................

24

8.

DOCUMENT HISTORY

................................
................................
................................
................................
..........

25


Web Services Access Guide

Issue 2.
7



1
7
th

October
2011


Page
4

of
25

Copyright


British Telecommunications plc 20
11

1.

About this handbook

This document provides an overview of the On
-
Ramp Process to help Communications
Providers (CPs).Realistic sample messages are used in this user guid
e 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
.

Please refer to the B
2B and Web Services pages
on the BT Wholesale web site
for further
information

Web Services Access Guide

Issue 2.
7



1
7
th

October
2011


Page
5

of
25

Copyright


British Telecommunications plc 20
11

2.

Introduction

The Web Services Gateway is designed to allow you to manage a variety of
telecommunication services electronically, by linking your support systems and processes
wi
th BT.

This has been 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 Production, the live environ
ment
,

where you should
benefit fully from BT Wholesale’s 21CN WBC Web Services initiative.

2.1

What is BT Wholesale Onramp
intended
for?

The Onramp environment is available to BT Wholesale customers so that they can test:

a)

Connectivity to and from BT Wholesale
Gateway via the Internet and any
proxies and firewalls that may be on the routes involved.

b)

The c
reation, format conversion (if required), and installation of any certificates
that may be used to support the https connections.

c)

and use the environment to p
av
e the way to accessing a host of additional
online services as these become available.

d)

The
Implementation of web services.


Testing of the interface may be done using test stubs but final testing should use

data generated by and integrated with
your

backen
d systems.


For 21CN services, the BT Wholesale Web Services gateway will generate a synchronous
response with the following “Your message is received.” message in the “document”
element confirming to CP published WSDL
below
.


2.2

What is BT Wholesale Onramp n
ot
intended
for?

Onramp does not:


a)

Provide you with a full end
-
to
-
end testing environment

b)

Faithfully re
plicate

the performance in the production

(live)

environment

c)

Exhaustively test possible data values and error conditions sent to or returned
by Openreac
h

d)

Facilitate load or performance testing

e)

Work for live orders

Web Services Access Guide

Issue 2.
7



1
7
th

October
2011


Page
6

of
25

Copyright


British Telecommunications plc 20
11

2.3

How long will you use Onramp for?

The testing phase on Onramp systems depends on the complexity of your management and
development processes. Fundamental connectivity testing can take anything f
rom one day
to over a month and message testing may take days or months. However, in normal
circumstances
,

the set
-
up on the Wholesale side
should
take no more than four working
days from the provision of details.

The main causes of any delays are

due to
:



Incorrectly
-
configured digital and Certificate Authority (CA) certificates on web
servers



Firewall and proxy setup problems



Development and integration with your backend systems




Web Services Access Guide

Issue 2.
7



1
7
th

October
2011


Page
7

of
25

Copyright


British Telecommunications plc 20
11

3.

Setting up the Gateway

The Onramp Customer Support team, known as PEM (Par
tner Enablement
Management)
Team
, can be contacted at

wholesale.pem@bt.com
. T
he interface
-
specific
parameters and requirements are

set out below and the PEM Team
may ask you for
certain
details as part of their tas
k of building up
your

“Client Profile”.

3.1

BT Wholesale side set up

All you need to do is tell us more about your organisation and requirements. The PEM team
will need the following information to set you up:


Name of the your organisation


This will be used

for creating your profile under

the

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
ht
tp://express.dnbsearch.com/advFind.asp.


Look for the option “Search by Data Universal Numbering System (DUNS) Number”, enter
your company’s 9
-
digit number and press “Search” to see the validated result.


Your URL

You can provide an URL with default port

443 to which the BT Wholesale will send the
asynchronous Notification messages. This is only needed during the Live phase and not
required for Onramp testing.



Your IP addresses


Theses are the Internet Facing IP Addresses from which the requests to the
BT Wholesale
Onramp would originate.



Your client certificate

The digital certificate issued from BT Wholesale Northside is required for mutual
authentication. And note that same certificate should be used when you move on to
production (live) Web Service
s Gateway. Complete instructions for applying for this
certificate are detailed later in this document.





Your BT Account Manager

Web Services Access Guide

Issue 2.
7



1
7
th

October
2011


Page
8

of
25

Copyright


British Telecommunications plc 20
11

This is the member of the BT Account Team who confirmed your access to the BT
Wholeasle Web Services Gateway. The PEM team

will liaise with your Account Manager
as necessary.


Your technical contact’s name, email and phone number

This is the person in your organisation whom the PEM team will contact directly to discuss
any technical issues.


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. Howev
er, everyone’s circumstances
are unique and our PEM team will be well placed to discuss a realistic schedule with you.
As long as the lead times are realistic, we will work with you to ensure we begin testing by
the date you have chosen.


You preferred pr
oduction date

As you will see, how long the Onramp tests
last

depends more on what tests you have
chosen to carry out rather than any fixed lead times required by us. If you have a proposed
Production date in mind, please let us know, but note that this is

not a mandatory
requirement
at this stage. Your Production date can be agreed later with the PEM team as
we work together to progress moving on to production gateway.


Your production support contact’s details

As our customers move into the In
-
Life phase
known as “Production”, many prefer to
appoint a different contact to monitor and maintain their systems. Please enter the details of
the person we should contact in case of problems with your Production system.


3.2

Your Onramp setup

Onramp will accept and re
spond synchronously. The response will be a static response
such as "
Your message is received
".


1. BT Wholesale Data Universal Numbering System (DUNS) number: 232510151


2. URL for Diagnostics:

https://www.ws
-
onramp1.wholesale.bt.com:5443/WBC_T2R_116


3. URL for Appointing services:

https://www.ws
-
onramp1.whol
esale.bt.com:5443/WBC_CPCL


4. URL for Order and Fault Tracker Services:

https://www.ws
-
onramp1.wholesale.bt.com:5443/btw/v5/Orderandfaulttracker


It is expected that y
ou will need to arrange firewall access. For access from the Onramp
Gateway:


Web Services Access Guide

Issue 2.
7



1
7
th

October
2011


Page
9

of
25

Copyright


British Telecommunications plc 20
11

217.140.45.139
over port
5443.

Web Services Access Guide

Issue 2.
7



1
7
th

October
2011


Page
10

of
25

Copyright


British Telecommunications plc 20
11

4.

Security & Certificate Information


A number of security measures need to be in place in order to use the BT Wholesale Web
Services

G
ateway, both d
uring the Onramp Test phase and in Production.


Before you can access our online services you need to have an appropriate firewall and
digital certificate.


If you are in any doubt, please feel free to discuss any existing certificates with our Partner
En
ablement Management (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 fr
om
one computer to another as and when required.


You may apply for a client certificate using this link.

https://onsite.trustwise.com/services/BTGroupPlcNort
hsideclient/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
-
mai
l 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 In
ternet 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.

N
ext, choose either binary or base
-
64 .cer or a .p7b (with or without a Certificate of
Authority CA))


Web Services Access Guide

Issue 2.
7



1
7
th

October
2011


Page
11

of
25

Copyright


British Telecommunications plc 20
11

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
T
eam 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.


The reason you will need to export the public part of the certificate (without private key) and
send the file to the PEM
T
eam
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
compa
ny 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 requi
rements (a visit to
www.openssl.org

may prove
helpful
).

4.

You should also move the Certificate Authority to maintain the evidence of trust (by
using the “export all certificates in path” command).


IMPORTANT: We recomme
nd
,

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.


Web Services Access Guide

Issue 2.
7



1
7
th

October
2011


Page
12

of
25

Copyright


British Telecommunications plc 20
11

5.

Onramp testing

5.1

Introduction to Onramp

Communication takes place by

way of a series of requests from your systems and
synchronous responses from BT. You can carry out as many tests as your business
requires. This may depend on the size and complexity of your organisation.


Currently, BT Wholesale Onramp will generate sync
hronous responses for the
corresponding request messages. Your gateway would need to send a Web Service
request over HTTPS to BT Wholesale Web Services gateway.


A clear picture about the transaction process on onramp is explained below:



1.

CP sends Add
TestRequest



BT would send a response

“Your message is received”


2.

CP sends AddSessionKillRequest



BT would send a response “
Your message is received



3.

CP sends AddAppointment



BT would send a response

“Your message is received”




4.

CP send
s AddAppointmentAvailabilityRequest



BT would send a response

“Your message is received”


5.

CP sends
AddOrderDetailsQuery



BT would send a response


BTWholesale OnRamp W/S Gateway has
received your request



6.

CP sends
AddTroubleReportDetailsQuery



B
T would send a response


BTWholesale OnRamp W/S Gateway has
received your request



5.2

Messages from you to Onramp

Messages are sent to Web Services Onramp by an https POST to URL:


Diagnostics:
https://www.ws
-
onramp1.wholesale.bt.com:5443/WBC_T2R_116

Appointing:
https://www.ws
-
onramp1.wholesale.bt.com:5443/WB
C_CPCL


For order and fault tracker services:

https://www.ws
-
onramp1.wholesale.bt.com:5443/btw/v5/Orderandfaulttracker





The message comes as a payload in SOAP body
which you may code explicitly or devolve
to message handling software. Realistic sample messages are used in this User Guide to
illustrate interface usage. Variables are indicated by
bold
italic
text
; used to signify data
parameters at the client level.


Web Services Access Guide

Issue 2.
7



1
7
th

October
2011


Page
13

of
25

Copyright


British Telecommunications plc 20
11

A

few reminders

As we’ve seen, connection to On
-
剡o瀠ps慤攠esi湧=慮⁓pi⁣潮n散瑩o渠nn⁰=r琠
5443
. All SSL connections
require a Digital Certificate on the “server” end. It’s at your discretion whether this certificate is validated by the
process known as “
mutual authentication” which may or may not be available in your software.
=

-
剡o瀠pill⁦畲瑨敲⁲e煵ir攠yo甠u漠or敳e湴n愠a敲eific慴攠ess略d⁴==yo甠uy⁴=攠mbM⁴=慭⸠.桩s⁩s=k湯睮⁡s=
“mutual authentication”, something not specified as part of Netscape's orig
in慬=pp䰠i敳i杮=睨wc栠睡w⁦潲o
䍯湳畭敲⁴漠e畳i湥ss
䌲B)⁣潮n散瑩o湳ⰠI畴=t⁵=c潭m潮⁩渠n畳i湥ss⁴==B畳i湥ss
B㉂)⁣o湮散ti潮s.
=
p敥=
p散ti潮
=
潮o

=
Security & Certificate Information” above for more information


First, some http.

If you are coding at a low

level, please ensure that the http uses DOS style
Character Return
-

Line Feed (
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.


5.2.1


A look at http

The followin
g example is for XML Diagnostics.

POST /
RequestTest

HTTP/1.1

Host: www.
ws
-
onramp1
.wholesale.bt.com

SOAPAction: "RequestTest"

Content
-
Type: type="text/xml";

Content
-
length: 1234

5.2.2


About XML


Now the XML


Additional elements and attributes may or may not be
acceptable. Part of the purpose of
Onramp

is to ensure that your software does not add any extra data, which causes conflicts
with the software used by
Onramp



if it doesn't conflict, feel free to do as you will but
Onramp

is not able
to guarantee that

t
he software

will not conflict at some time in the future.

Few standards are so simple that they can be implemented without potential problems of
interpretation when interacting with other implementations so testing is essential. In other
interfaces even th
e 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

W
holesale

gateway uses XML business payloads that make use of namespaces: use
of namespace aware XML software is strongl
y 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 t
his
is

not guaranteed.



5.2.3

Sample example with SOAP

Here is a SOAP example for XML AddTestRequest


<?xml version='1.0' encoding='UTF
-
8'?>

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">

<soapenv:Body>"

Web Services Access Guide

Issue 2.
7



1
7
th

October
2011


Page
14

of
25

Copyright


British Telecommunications plc 20
11


<open:DiagnosticRequest
xmlns:open="http://www.openuri.org/">

<dial:CPWSPALServiceMessage xmlns:dial="http://www.bt.com/eai/pal/btw/DialogueServices">


<urn:AddTestRequest

xmlns:urn="urn:com.btwholesale.Assurance4
-
v5
-
0">

<dt:Test xsi:schemaLocation="urn:com.btwholesale.Assurance
4
-
v5
-
0
../../Schemas/Application/Assurance4
-
v5
-
0.xsd urn:org.uk.telcob2b/tML/Assurance.DiagnosticTests4
-
v5
-
0 ../../Schemas/Application/DiagnosticTests4
-
v5
-
0.xsd" xmlns:btw="urn:com.btwholesale.Assurance4
-
v5
-
0"

xmlns:dt="urn:org.uk.telcob2b/tML/Assuranc
e.DiagnosticTests4
-
v5
-
0"

xmlns:xsi="http://www.w3.org/2001/XMLSchema
-
instance">

<dt:TestHeader>

<dt:TestDate>2009
-
06
-
26T15:37:53</dt:TestDate>

<dt:TestReference>

<dt:ConductorReference>

<dt:InvokeIdentifier>

<dt:RefNum>ORT1
-
1246026976738</dt:RefNum>

</dt:
InvokeIdentifier>

</dt:ConductorReference>

</dt:TestReference>

<dt:TestParty>

<dt:ConductorParty>

<dt:Party PartyID="227015718" AgencyID="DUNS">

<dt:ListOfIdentifier>

<dt:Identifier>

<dt:Ident>INTERNET_BT_OPENWORLD_SP</dt:Ident>

</dt:Identifier>

</dt:ListO
fIdentifier>

<dt:TestContact>

<dt:Contact>

<dt:ContactName>ORT1</dt:ContactName>

<dt:Telephone>01473609782</dt:Telephone>

</dt:Contact>

</dt:TestContact>

</dt:Party>

</dt:ConductorParty>

<dt:PerformerParty>

<dt:Party PartyID="232510151" AgencyID="DUNS"/>

<
/dt:PerformerParty>

</dt:TestParty>

</dt:TestHeader>

<dt:ListOfTestDetail>

<dt:TestDetail>

<dt:TestCategory>xDSL IP Test</dt:TestCategory>

<dt:ServiceType>21C_WBC_SERVICE</dt:ServiceType>

<dt:ToBeTestedMorts>

<dt:Mort>

<dt:ServiceID>

<dt:Ident>BBEU22168000
6</dt:Ident>

</dt:ServiceID>


<dt:TestFeatures>


<dt:TestInputFeatureSet>


<dt:ListOfTestFeature>


<dt:TestFeature>


<dt:FeatureName>faultOccurredDateAndTime</dt:FeatureName>


<dt:FeatureValue>2009
-
06
-
26T15:37:53</dt:FeatureValue>


</dt:Te
stFeature>


</dt:ListOfTestFeature>

Web Services Access Guide

Issue 2.
7



1
7
th

October
2011


Page
15

of
25

Copyright


British Telecommunications plc 20
11


</dt:TestInputFeatureSet>

</dt:TestFeatures>

</dt:Mort>

</dt:ToBeTestedMorts>

</dt:TestDetail>

</dt:ListOfTestDetail>

</dt:Test>

</urn:AddTestRequest>


</dial:CPWSPALServiceMessage>

</open:DiagnosticRequest>"


</soapen
v:Body>

</soapenv:Envelope>


5.2.4


Curl connectivity


A simple end
-
to
-
end connectivity test can be carried out using curl (you can download an
SSL enabled version
-

available for most platforms
-

from http://curl.haxx.se if you do not
already have it). The comm
and to use will be based on this version which works in Windows
(
please note that
Linux needs extra escaping)
.



curl
-
i
-
k
-
E certname.pem:password
-
x proxy.whatever:8080
--
data
-
binary “@testWS.txt”
-
H "Content
-
Type:

text/xml; charset=
\
"utf
-
8
\
""
https://www.ws
-
onramp1.wholesale.bt.com:5443/WBC_T2R_116



-
E specifies your client certificate required by Wholesale for authentica
tion

-
x specifies your proxy; leave out if you are not using one

-
k turns off server verification

use of quotes and escape characters may be OS dependent so the above is to be treated as a guide only;
refer to curl documentation as a check, and be prepared

to try a different version in case of trouble (that sorted
out problems on more than one occasion)


testWS.txt is a text file containing:



<?xml version="1.0" encoding="UTF
-
8"?>

<soapenv:Envelope mlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">

<soapenv:Body><rul:invokerules xmlns:rul="http://rules.kmtool.bt.com">

<rul:arg0><![CDATA[<
<btw:AddTestRequest
xmlns:btw="urn:com.btwholesale.Assurance4
-
v5
-
0"
xmlns:dt="urn:org.uk.telcob2b/tML/Assurance.DiagnosticTests4
-
v5
-
0"
xmlns:xsi="http://www.w3.org/2
001/XMLSchema
-
instance"
xsi:schemaLocation="urn:com.btwholesale.Assurance4
-
v5
-
0 ../../Schemas/Application/Assurance4
-
v5
-
0.xsd


urn:org.uk.telcob2b/tML/Assurance.DiagnosticTests4
-
v5
-
0
../../Schemas/Application/DiagnosticTests4
-
v5
-
0.xsd">


<dt:Test>

<dt:Te
stHeader>

<dt:ConductorID>CP message ID</dt:ConductorID>

<dt:TestDate>2006
-
06
-
11T12:00:00</dt:TestDate>

<dt:TestReference>

<dt:ConductorReference>

<dt:InvokeIdentifier>

<dt:RefNum>CP Test Reference</dt:RefNum>

</dt:InvokeIdentifier>

</dt:ConductorReference
>

</dt:TestReference>

<dt:TestParty>

Web Services Access Guide

Issue 2.
7



1
7
th

October
2011


Page
16

of
25

Copyright


British Telecommunications plc 20
11

<dt:ConductorParty>

<dt:Party PartyID="987654321" AgencyID="DUNS">


</dt:Party>

</dt:ConductorParty>

<dt:PerformerParty>

<dt:Party PartyID="232510151" AgencyID="DUNS"/>

</dt:PerformerParty>

</dt:TestParty>

</dt:TestHead
er>

<dt:ListOfTestDetail>

<dt:TestDetail>

<dt:TestCategory>AssociationAndDiagnosticTest</dt:TestCategory>

<dt:ServiceType>21C_WBC_SERVICE</dt:ServiceType>

<dt:ToBeTestedMorts>

<dt:Mort>

<dt:ServiceID>

<dt:Ident>BBEU12345678</dt:Ident>

</dt:ServiceID>

<dt:T
estFeatures>

<dt:TestInputFeatureSet>

<dt:ListOfTestFeature>

<dt:TestFeature>

<dt:FeatureName>serviceSimulationUserName</dt:FeatureName>

<dt:FeatureValue>bt_test_user@startup_domain</dt:FeatureValue>

</dt:TestFeature>

<dt:TestFeature>

<dt:FeatureName>servi
ceSimulationPassword</dt:FeatureName>

<dt:FeatureValue>password</dt:FeatureValue>

</dt:TestFeature>

<dt:TestFeature>

<dt:FeatureName>serviceSimulationUrl</dt:FeatureName>

<dt:FeatureValue>www.bt.com</dt:FeatureValue>

</dt:TestFeature>

<dt:TestFeature>

<dt:
FeatureName>serviceSimulationIPAddress</dt:FeatureName>

<dt:FeatureValue>62.239.21.140</dt:FeatureValue>

</dt:TestFeature>

<dt:TestFeature>

<dt:FeatureName>intrusionConsent</dt:FeatureName>

<dt:FeatureValue>Y</dt:FeatureValue>

</dt:TestFeature>

<dt:TestFea
ture>

<dt:FeatureName>faultReportCode</dt:FeatureName>

<dt:FeatureValue>ISP</dt:FeatureValue>

</dt:TestFeature>

<dt:TestFeature>

<dt:FeatureName>FaultTypeOther</dt:FeatureName>

<dt:FeatureValue>Optional description of the fault</dt:FeatureValue>

</dt:TestF
eature>

<dt:TestFeature>

<dt:FeatureName>PPPencapsulation</dt:FeatureName>

<dt:FeatureValue>PPPoE</dt:FeatureValue>

</dt:TestFeature>

<dt:TestFeature>

<dt:FeatureName>alarmLookbackPeriod</dt:FeatureName>

<dt:FeatureValue>String</dt:FeatureValue>

</dt:TestF
eature>

<dt:TestFeature>

<dt:FeatureName>neverWorked</dt:FeatureName>

Web Services Access Guide

Issue 2.
7



1
7
th

October
2011


Page
17

of
25

Copyright


British Telecommunications plc 20
11

<dt:FeatureValue>String</dt:FeatureValue>

</dt:TestFeature>

<dt:TestFeature>

<dt:FeatureName>repeatFaultCount</dt:FeatureName>

<dt:FeatureValue>String</dt:FeatureValue>

</dt:TestFeature>

<dt:TestFeature>

<dt:FeatureName>faultOccurredDateAndTime</dt:FeatureName>

<dt:FeatureValue>String</dt:FeatureValue>

</dt:TestFeature>

<dt:TestFeature>

<dt:FeatureName>lastWorkedDateAndTime</dt:FeatureName>

<dt:FeatureValue>String</dt:FeatureValue>

</dt:T
estFeature>

<dt:TestFeature>

<dt:FeatureName>transactionId</dt:FeatureName>

<dt:FeatureValue>String</dt:FeatureValue>

</dt:TestFeature>

</dt:ListOfTestFeature>

</dt:TestInputFeatureSet>

</dt:TestFeatures>

</dt:Mort>

</dt:ToBeTestedMorts>

</dt:TestDetail>

<
/dt:ListOfTestDetail>

</dt:Test>

</btw:AddTestRequest>
]]></rul:arg0></rul:invokerules>

</soapenv:Body></soapenv:Envelope>



5.2.5

Webservices Transport Web Service definition for

Diagnostics:








5.2.6

Webservices Transport Web Service defin
ition for
Appointing

services:




5.2.7

Webservices Transport Web Service definition for

Order
and Fault Tracker services
:



Web Services Access Guide

Issue 2.
7



1
7
th

October
2011


Page
18

of
25

Copyright


British Telecommunications plc 20
11


5.2.8

What are the services and what XML goe
s with them?


M
entioned

below

are a list of service names and the corresponding root nodes present in
the request XML:


Service Name

Root Node (Request/Response Type)

RequestTest

AddTestRequest

RequestSessionKill

AddSessionKillRequest

RequestAppointmen
t

AddAppointment

RequestAppointmentAvailability

AddAppointmentAvailabilityRequest

QueryOrderDetails

AddOrderDetailsQuery


QueryTroubleReportDetails


AddTroubleReportDetailsQuery




5.3

Messages from Onramp to you

5.3.1


Some more http


HTTP/1.1 415 Unsupported
Media Type

Date: Mon, 07 Aug 2006 16:59:40 GMT

Content
-
Type: text/xml; charset="utf
-
8"

Server: Forum Sentry

Content
-
Length: 794

<soap:Envelope xmlns:soap=”....

...

</soap:Envelope


You should get an http 200 OK response, but there will be occasions when yo
u don't:




You may get a security failure (e.g. 403)



You may get something else (e.g. 500)



You may get an error (e.g. if you specify an incorrect path in the URL.e.g. with your
Data Universal Numbering System (DUNS) instead of BT)



You may get a timeout ex
ception when there is no connectivity.



You may fail to connect at all (like any system, there will be outages
-

normally
scheduled and communicated in advance)


5.3.2


Response business payload

If a valid request reaches Onramp, a response will be sent back sayi
ng
“Your message is
received”

Web Services Access Guide

Issue 2.
7



1
7
th

October
2011


Page
19

of
25

Copyright


British Telecommunications plc 20
11


5.3.3

Exceptions


It is possible that your input will be rejected with an AcceptanceAcknowledgementException
(when the Gateway passes your input to other systems but they either reject it before
processing or fail to return it). Th
is will actually be presented as a SOAP Exception with the
exception string set

to: “BTWHOLESALE HAS EXPERIENCED A PROBLEM”


Indeed, all problems should be returned as SOAP faults. Sometimes, but not always, they
will contain sufficient information for yo
u to understand the cause of the problem:


Security Exception

<?xml version="1.0" encoding="UTF
-
8"?>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">


<soap:Body>


<soap:Fault>


<faultcode>soap:Server</faultcode>


<fault
string>
BTWHOLESALE HAS EXPERIENCED A PROBLEM WITH YOUR REQUEST SEE BELOW
FOR TECHNICAL REASON :
-

Unauthorized request
</faultstring>


<detail>


<fs:Detail


xmlns:fs="http://www.forumsystems.com/2004/04/soap
-
fault
-
detail">


<fs:
SystemName>AP001STY01</fs:SystemName>


<fs:User>987654301D</fs:User>


<fs:Policy>Line Characteristic WSDL Policy</fs:Policy>


<fs:TaskList></fs:TaskList>


<fs:Task></fs:Task>


</fs:Detail>


</detail>


</so
ap:Fault>


</soap:Body>

</soap:Envelope>


PEM will usually be able to see these in logs. Assistance will be given by
suggesting an explanation and where changes may be needed.


NOTE:

WBC_Diagnostics_via_Web_Service_Interface_Design_Issue_v2.0

document
ex
plains
all possible exceptions and error messages. Kindly refer
to
the same.

This document can be
downloaded from the foll
owing link in BT Wholesale site on the B2B pages.


You will need to click on the option
-


XML specification documents for Sentry
Diagn
ostics”

to download the document.


5.4

Onramp exit criteria

These are the set of tests which need to be done on the Onramp systems before moving to
the live environment. Live server set up starts after the Onramp signoff.


Web Services Access Guide

Issue 2.
7



1
7
th

October
2011


Page
20

of
25

Copyright


British Telecommunications plc 20
11

You simply have to fill

in
the
Q
ual
ity
G
ate report (with the details of the Onramp tests
performed) and send this to the PEM
T
eam.

They will then verify the tests performed and provide the signoff from Onramp.


Please Note
: Completing the Quality
G
ates only proves that your system is capabl
e of
handling more than one
,

and also all kinds of
,

request and response messages
simultaneously.

The
Quality Gate does not constitute to complete functional testing.


The following sections describe separate scenarios for XML Diagnostics.

5.4.1


Scenarios for
XML Diagnostics

Scenario 1: Add Test Request


Sender

Message Type

1

CP

AddTestRequest

2

BT

Your message is received


Scenario 2: Add Session Kill Request


Sender

Message Type

1

CP

AddSessionKillRequest

2

BT

Your message is received



5.4.2


Scenario for

Appointing services

Scenario 1: Add Appointment



Sender

Message Type

1

CP

AddAppointment

2

BT

Your message is received


Scenario 2: Add Appointment Availability Request



Sender

Message Type

1

CP

AddAppointmentAvailabilityRequest

2

BT

Your message

is received


5.4.3


Scenario for
Order Tracker

services

Scenario
1
:
Add

Order

Details

Query




Sender

Message Type

1

CP

AddOrderDetailsQuery


2

BT

BTWholesale OnRamp W/S Gateway has received your request


5.4.4


Scenario for
Fault Tracker

services

Scenario
1
:
Add

Trouble

Report

Details

Query


Web Services Access Guide

Issue 2.
7



1
7
th

October
2011


Page
21

of
25

Copyright


British Telecommunications plc 20
11


Sender

Message Type

1

CP

AddTroubleReportDetailsQuery


2

BT

BTWholesale OnRamp W/S Gateway has received your request

Web Services Access Guide

Issue 2.
7



1
7
th

October
2011


Page
22

of
25

Copyright


British Telecommunications plc 20
11

6.

Pilot and live phase

The PEM
T
eam 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.
Y
ou will

then

be given access to the live Production platform.


After this, the PEM
T
eam will confirm any operational changes to your IP address and your
URL.

We will then carry out any final checks on your certificate configuration and send you
an email to tell you when the requested services via the Web Services Gateway will be
approved.


In technical terms, the changes involved
on

your
system
side
of the int
erface
for going live
are the URLs to be used to post the messages:


For 21CN Diagnostics:

https://www.ws.wholesale.bt.com:5443/WBC_T2R_116



For Appointing services:

https://www.ws.wholesale.bt.com:5443/WBC_CPCL



For Order and Fault Tracker services:

http
s://www.ws.wholesale.bt.com:5443/btw/v5/Orderandfaulttracker




You will also need to arrange firewall access. For access from the Live Gateway:



217.140.45.140 is for traffic coming from BT to Communication Partner


217.140.45.137 is for traffic comi
ng from the
Communication Partner
to BT.


The client certificate issued to you during your Onramp tests should be used on
P
roduction
as well. However, asynchronous responses will require the server certificate public key of
BT Wholesale.
Please
contact the

PEM
T
eam to obtain this.


Production is the first time that:




Your organisation will be connecting to real back end systems



You will be able to test specific details of lines, exchanges and so on



You get back the full range of Notifications at times refle
cting 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 (Partner Enableme
nt
Management) team will support you for a two week trial period if you are an existing
customer and for
four (
4
)

weeks if you are a new customer. If you have any issues while
placing orders against the live system please get in touch with the PEM Team at
wholesale.pem@bt.com.


Web Services Access Guide

Issue 2.
7



1
7
th

October
2011


Page
23

of
25

Copyright


British Telecommunications plc 20
11

Within this trial period, you w
ill

need to
:




Fill the Test Plan (that would be provided to you by your CRM) with the details of all
the tests performed and return it to your CRM. Kindly contact the PEM (
T
eam
(wholesale.pem@bt.com) if

you face any issue during this period.



Once you have completed testing for all the services, you will need to inform your
CRM and the PEM
Team
about the completion of tests.



These tests could be similar to those of the Onramp tests you had carried out e
arlier
(in terms of various services and XMLs used).


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.

Web Services Access Guide

Issue 2.
7



1
7
th

October
2011


Page
24

of
25

Copyright


British Telecommunications plc 20
11

7.

Glossary

BT

British Telecommunications plc (not t
o be confused with business transaction)

BTW

BT Wholesale

CA

Certificate Authority

TP

Trading Partner (essentially same as Communications Provider or Service Provider)

CUPID

Communications Provided Identifier (previously known as LOPID) from

Ofcom

(htt
p://www.ofcom.org.uk/telecoms/ioi/numbers/numbers_administered/#cupid)

Data
Universal
Numbering
System
(DUNS)

Data Universal Numbering System, a unique nine
-
digit sequence issued by Dun &
Bradstreet, recognised as the universal standard for identifying an
d keeping track of
over

100 million businesses worldwide

DNS

Domain Naming System

DOS

Disk Operating System

IP

Internet Protocol Address

OTA

Office of the Telecommunications Adjudicator

PI

Processing Instruction (XML terminology)

SOAP

Simple Object
Access Protocol

SSL

S
ecure
S
ockets
L
ayer
, a p
rotocol 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. B
oth 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
.

WS

We
b Services

WSDL

Web Service Definition Language

WBC

Wholesale Broadband Connect

CP

Communications Provider

ServiceId

The service identifier of the end user service. The format is BBEUnnnnnnnn, i.e.
four letters as shown followed by eight digits.



Web Services Access Guide

Issue 2.
7



1
7
th

October
2011


Page
25

of
25

Copyright


British Telecommunications plc 20
11

8.

Do
cument history

Issue

Date

Author

Comments

1.0

12/12/2008

PEM Team

Initial Draft.

2.0

29/06/2009

PEM Team

Added 21C WBC Diagnostic services

2.1

02/07/2009

PEM Team

Updated WSDL for WBC & review
comments from XML Design Team

2.2

05/11/2009

PEM Team

Edit
ed the guide to exclusively cater to
WBC. Removed all KBD references in the
document. Proofread for better readability.

Changed nomenclature of customer from
TP to CP.

2.3

25/02/2010

PEM Team

Updated mail id of PEM Team from


b2b.pem@bt.com

to

wholesale.pem@bt.com

2.4

25/06/2010

PEM Team

Updated to incorporate comments from
Development and Design teams

2.5

04/02.2011

PEM Team

Renamed the document name from ‘21C
WBC Web Servi
ces On
-
Ramp User Guide’
To ‘
21C Web Services Access User Guide


2.6

30/09/2011

BT Wholesale
Team

Updated for “tone of voice” and

to meet

new btw.com guidelines

2.7

17/10/2011

PEM Team

Updated the User Guide to include order
and fault tracker services