Docstoc

Openreach_Web_Services_Gateway_OT_FT_Design_Docv1 6 m

Document Sample
Openreach_Web_Services_Gateway_OT_FT_Design_Docv1 6 m Powered By Docstoc
					Openreach Web Services Gateway OT FT Web Service Interface Design




Openreach Web Services Gateway

OT FT Web Service Interface Design




10th November 2009



                                                     Page 1 of 23
Openreach Web Services Gateway OT FT Web Service Interface Design




Legal notice

BT maintains that all reasonable care and skill has been used in the compilation of this publication.
However, BT shall not be under any liability for loss or damage (including consequential loss)
whatsoever or howsoever arising as a result of the use of this publication by the reader, his
servants, agents or any third party.

The contents of this document shall not be reproduced in whole or in part without the written
consent of Openreach.

Standard terms and conditions apply to the provision of the services described in this document.


British Telecommunications plc
Registered office: 81, Newgate Street, London EC1A 7AJ
Registered in England no. 1800000

Document history

Revision      Author                        Date                    Notes
                                             th
Draft 0.1     Neeraj Kumar Jadaun           9 June 2009
                                             th
1.1           Neeraj Kumar Jadaun           7 July 2009
                                               th
1.2           Neeraj Kumar Jadaun           29 July 2009            Updated the Test documents
                                             th
1.3           Neeraj Kumar Jadaun           4 August 2009           Updated soap-fault and read
                                                                    time out value
                                             th
1.4           Neeraj Kumar Jadaun           5 August 2009
                                              th
1.5           Neeraj Kumar Jadaun           17 August 2009          Removed few un-necessary
                                                                    references
                                              th
1.6           Martin Heath                  10 November 2009        Update of Legal section




                                                     Page 2 of 23
Openreach Web Services Gateway OT FT Web Service Interface Design




Contents                                                            Page



1       Introduction                                                  4
1.1       Intended Audience                                            4


2       Architecture                                                  5
2.1. E2E Diagram for OT FT exposure by Openreach Web Services Gateway 5


3       Web Service Implementation                                    6
3.1 Fault Tracker Web Service Request                                  6
3.2 Order Tracker Web Service Request                                  6
3.3 WSDL                                                               7
3.4 XMLs                                                               7
3.4.1 Fault Tracker                                                    7
3.4.2 Order Tracker                                                    8


4       Web Service Client                                           10
4.1       Web Service Communication                                   10
4.2       HTTPS/SSL                                                   11
4.3       Digital Certificates                                        11


5       Monitoring                                                   12

6       Authorization and Authentication                             13

7       Appendix A - Exception Handling                              14
7.1 Error Types                                                       14
7.2 Message Types                                                     15
7.2.1    Web Service SOAP Fault                                       15
7.3       Timeouts                                                    19


8       Client characteristics                                       20

9       Openreach Web Services Gateway Deliverables 21
9.1 Test Document                                                     21


10      References                                                   22

11      Glossary                                                     23

                                                     Page 3 of 23
Openreach Web Services Gateway OT FT Web Service Interface Design



1      Introduction
This document provides the detailed design of Order Tracker and Fault Tracker Web Service
exposed by Openreach Web Services Gateway. It describes the interaction between CP and
Openreach Web Service Gateway and between Openreach Web Services Gateway and OR Portal.


1.1 Intended Audience


The document is intended for communications provider technical teams responsible for designing
and building clients that will call into the Openreach Web Services Gateway.

Note: In this document the term “CP” is used to represent “Communication Provider”.




                                                     Page 4 of 23
Openreach Web Services Gateway OT FT Web Service Interface Design



2      Architecture
2.1. E2E Diagram for OT FT exposure by Openreach Web Services Gateway




                        SOAP                Openreach Web             SOAP             Openreach
      CP
                        HTTPS               Service Gateway           HTTP               Portal




                                             Figure 1




                                   The Fault Tracker and Order Tracker would be securely
CPs                                exposed to CPs by Openreach Web Service Gateway. This
                                   communication will happen over SSL. CPs need to have the
                                   public certificate of Openreach Web Service Gateway in its
                                   keystore while Openreach Web Service Gateway needs to have
                                   the public certificate of CP in its keystore in order to facilitate
                                   mutual authentication based on PKI infrastructure.

Openreach Web Service              Openreach Web Service Gateway receives the Web Service
Gateway                            request over HTTPS various CPs.

                                   Openreach Web Service Gateway does the following
                                   validations:
                                        1. WSDL Validation

                                        2. DunsID Validation

                                   If the above validations are successful, the request is proxied to
                                   Openreach Portal.
                                   Openreach Portal sends the Web Service Response back to
                                   Openreach Web Service Gateway (which in turn to CP) In the
                                   same transaction.

Openreach Portal                   Openreach Portal actually hosts the Fault Tracker and Order
                                   Tracker Web service (exposed by Openreach Web Service
                                   Gateway to the CP). Openreach Portal also provides a DR
                                   solution. It has two sites (one at Derby and another at St.
                                   Just). The Derby site is the primary site while the St. Just
                                   site is passive site. In case Derby site goes down then
                                   Openreach Web Services Gateway has to manually point to
                                   the St. Just Openreach Portal address.




                                                     Page 5 of 23
Openreach Web Services Gateway OT FT Web Service Interface Design



3      Web Service Implementation
The Openreach Web Services Gateway securely exposes the following Web Services.

3.1 Fault Tracker Web Service Request
The Fault Tracker Web Service Request contains one operation:

getFaultsWithNotes Operation
This operation is responsible for returning a single fault and its associated notes displayed in fault
tracker application as a web-service response.



3.2 Order Tracker Web Service Request
The Order Tracker Web Service Request contains one operation:

getOrdersWithNotes Operation
This method is responsible for returning a single order and its associated notes displayed in order
tracker application as a web-service response.



A Web Service Request will be sent and corresponding response will be returned all in the same
communication session.




                                                     Page 6 of 23
Openreach Web Services Gateway OT FT Web Service Interface Design




3.3 WSDL
A WSDL file defines the Web Service call and operation names.
This is much like a schema and all Web Service calls must conform to the corresponding WSDL or it
will be rejected by Openreach Web Services Gateway.

Please find the Fault Tracker and Order Tracker WSDL as exposed by Openreach Portal.




3.4 XMLs
This section defines the structure of message body to be transacted between Openreach Web
Services Gateway and Openreach Portal.

3.4.1 Fault Tracker
3.4.1.1 Fault Tracker getFaultsWithNotes Operation
This operation is responsible for returning a single fault and its associated notes displayed in fault
tracker application as a web-service response.

Request

<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <SOAP-ENV:Body>
    <m:getFaultsWithNotes xmlns:m="services:FaultTrackerServices">
      <m:header>
        <m:dunsId>String</m:dunsId>
        <m:userType>String</m:userType>
      </m:header>
      <m:faultServiceInputParams>
        <m:filterConditions>
          <m:item>
            <m:key>String</m:key>
            <m:value>String</m:value>
          </m:item>
        </m:filterConditions>
        <m:otherParams>
          <m:item>
            <m:key>String</m:key>
            <m:value>String</m:value>
          </m:item>
        </m:otherParams>
        <m:serviceId>-0</m:serviceId>
      </m:faultServiceInputParams>
    </m:getFaultsWithNotes>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The value of dunsId element should be equal to the Duns Id of the CP otherwise the request will
not be authorised by Openreach Web Service Gateways and an error message will be sent to the
CP requesting to send the request with correct Duns Id.

The value of the userType should be CP_USER else the request will be rejected by Openreach
Web Services Gateway and an error message will be sent to the CP requesting to send the request
with correct userType value.

                                                     Page 7 of 23
Openreach Web Services Gateway OT FT Web Service Interface Design




Response




3.4.2 Order Tracker
3.4.2.1 Order Tracker getOrdersWithNotes Operation
This method is responsible for returning associated notes displayed in order tracker application for
given order id as a web-service response.

Request

<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ser="services:OrderTrackerServices">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:getNotes>
         <ser:header>
            <ser:dunsId></ser:dunsId>
            <ser:userType></ser:userType>
         </ser:header>
         <ser:noteServiceInputParams>
            <ser:filterConditions>
               <!--Zero or more repetitions:-->
               <ser:item>
                   <ser:key>orderId</ser:key>
                   <ser:value>1-94752469992</ser:value>
               </ser:item>
               <ser:item>
                   <ser:key>productType</ser:key>
                   <ser:value>WLR</ser:value>
               </ser:item>
            </ser:filterConditions>
            <ser:otherParams>
               <!--Zero or more repetitions:-->
               <ser:item>
                   <ser:key></ser:key>
                   <ser:value></ser:value>
               </ser:item>
            </ser:otherParams>
         </ser:noteServiceInputParams>
      </ser:getNotes>
   </soapenv:Body>
</soapenv:Envelope>

The value of dunsId element should be equal to the Duns Id of the CP otherwise the request will
not be authorised by Openreach Web Service Gateways and an error message will be sent to the
CP requesting to send the request with correct Duns Id.

The value of the userType should be CP_USER else the request will be rejected by Openreach
Web Services Gateway and an error message will be sent to the CP requesting to send the request
with correct userType value.




                                                     Page 8 of 23
Openreach Web Services Gateway OT FT Web Service Interface Design




Response




                                                     Page 9 of 23
Openreach Web Services Gateway OT FT Web Service Interface Design



4       Web Service Client
The CP Web Service client will call Openreach Web Services Gateway synchronously.

This means that when the application wishes to call a Web Service it calls the Web Service Client
with the correct Message and the client then makes the Web Service call. It then synchronously
receives the response and sends it back to the application.



4.1 Web Service Communication

As indicated, the communication is synchronous and is made via an HTTPS Post to a URI exposed
by the Openreach Web Service Gateway. The response to this request will be returned in the same
communication session.


                                                                    Fault Tracker,
                                                                    Order Tracker
                                                                       WSDL




                             Synchronous                                    Synchronous
     Communication         Request/Response    Openreach Web Service      Request/Response
                                                                                             Openreach Portal
       Provider                                      Gateway

                               HTTPS                                           HTTP
     CP Keystore                              Openraech Keystore
        CP Keypair                               Openreach Web
     Openreach Web                              Services Gateway
 Services Gateway Public                             Keypair
        Certificate                             CP Public Certificate




Figure 2: Components involved in Web Service call to Openreach Web Services Gateway and
                                then to Openreach Portal.




                                                       Page 10 of 23
Openreach Web Services Gateway OT FT Web Service Interface Design




4.2 HTTPS/SSL

As mentioned above, the protocol between CP and Openreach Web Services Gateway is HTTPS
and this means that the Web Service link (in the red side world i.e. out side of Openreach domain) is
secured by the use of certificates as seen in the figure above.


The connection will be a two way SSL connection which is also known as mutual authentication.
With two-way SSL the Openreach Web Services Gateway verifies that it is CP (registered CP),
which is communicating with, and likewise CP verifies that it is a trusted party (Openreach Web
Services Gateway), which is serving the Web Service call.
  All encryption/decryption should take place at the protocol level so that the application developer
need not be too concerned about this. When making the HTTPS post the client needs to indicate
the location of the digital certificates so the protocol layer can encrypt the request and make the
SSL Handshake. Openreach Web Services Gateway does this with some SSL/Certificate/Policy
configuration.
  The client needs to open a new SSL session for each Web Service call. I.e. one SSL Session per
Web Service Request. Once the Client receives the response the SSL connection should be
terminated.
Supported Cipher Suites for SSL connection:
        TLS_RSA_W ITH_AES_256_CBC_SHA
        TLS_DHE_RSA_W ITH_AES_256_CBC_SHA
        TLS_RSA_W ITH_AES_128_CBC_SHA
        TLS_DHE_RSA_W ITH_AES_128_CBC_SHA
        SSL_RSA_W ITH_3DES_EDE_CBC_SHA
        SSL_DHE_RSA_W ITH_3DES_EDE_CBC_SHA
    
4.3 Digital Certificates

As mentioned in the above section two way SSL is being used and therefore both client and server
certificates are required. Openreach Web Services Gateway is responsible for holding the
Openreach keypair and CPs (registered CP) public key.




                                                    Page 11 of 23
Openreach Web Services Gateway OT FT Web Service Interface Design



5       Monitoring
This section describes the monitoring that takes place on the Openreach Web Services Gateway
platform.


Note - Appendix A describes the exception messages that can be returned to the Web Service
client. It is the responsibility of the client to monitor and evaluate the outcome of each Web Service
call.




The Openreach Web Services Gateway does not actively monitor business rule failures. In these
cases the transaction is deemed to have been correctly processed by Openreach Web Services
Gateway hence it is the CP’s responsibility to verify the Web Service Request.




                                                    Page 12 of 23
Openreach Web Services Gateway OT FT Web Service Interface Design



6      Authorization and Authentication
Openreach Web Services Gateway does the authentication and authorization of the incoming
request from various CPs. The certificate of the CP used in successful SSL handshake is also used
in validating the DunsId of the CP. If the Duns Id validation fails then Openreach Web Services
Gateway sends the Soap-Fault with HTTP 401 response code (Unauthorised request) back to the
CP else it proxies the authorised request to the Openreach portal.




                                                    Page 13 of 23
        Openreach Web Services Gateway OT FT Web Service Interface Design



        7      Appendix A - Exception Handling
        This section is intended to summarise all the exceptions types that can occur whilst interacting with
        the Openreach Web Services Gateway

        7.1 Error Types
        The following types of error can occur.

Error             Description                       Resolving          Resolving       Message       From           To
Type                                                Party              Action          Type

Business          A “business error” is an          CP                 CP will         Web Service   Openreach      CP
Error             event thrown as a result of a                        investigate     SOAP          Web
                  business validation failure but                      and then        Response      Services
                  where the system is still                            resubmit                      Gateway
                  operating within the functional                      message.
                  specification e.g. the CP does
                                                                                                     (actually
                  not own the circuit.                                                               coming from
                                                                                                     Openreach
                                                                                                     Portal)
Invalid Duns      A message confirming that         CP                 CP to send      Web           Openreach      CP
ID                the “Request” has NOT                                request         Service       Web
                  passed Duns ID validation                            with correct    SOAP-Fault    Services
                  and will NOT be forwarded to                         Duns ID         with HTTP     Gateway
                  the Openreach Portal
                                                                                       Error Code
                                                                                       401
Request           A message confirming that         CP                 CP will         Web Service   Openreach      CP
Validation        the “Request” has NOT                                investigate     SOAP Fault    Web
Error             passed initial validation                            and then        With HTTP     Services
                  against the WSDL and will                            resubmit        Error Code    Gateway
                  NOT be forwarded to the BT                           message.        400
                  backend system.
Openreach         A message from Openreach          Openreach          Openreach       Web Service   Openreach      CP
Portal            Portal                            Portal             portal will     SOAP Fault    Web
technical         indicating there is a                                investigate.                  Services
exception         technical problem with the                           CP to                         Gateway
                  Openreach Portal systems                             resubmit                      (Coming from
                  and the message cannot be                            message at                    Openreach
                  processed at this time.                              a later time.
                                                                                                     Portal)
                  e.g. “Internal system
                  unavailable - please retry
                  later. If still unsuccessful
                  please contact the helpdesk”.
Timeout           A timeout has occurred            Openreach          Openreach       Web Service   Openreach      CP
within            whilst Openreach Portal is        and CP             will            SOAP Fault    Web
Openreach         processing a Web Service                             investigate.    with HTTP     Services
                  Request. This will typically                         CP to           500 Error     Gateway
                  happen after 30 seconds                              resubmit        Code
                  (configurable).                                      message at
                                                                       a later time.
CP Web            A timeout has occurred on         CP, Openreach      CP,             None          -              -
Service Client    the Client whilst calling the                        Openreach
Timeout           Openreach Web Service                                to identify
                  Gateway. The timeout                                 point of
                                                                       failure
                  seconds can be set locally                           causing
                  by the client (It should be                          timeout
                  more than 30 seconds).




                                                            Page 14 of 23
Openreach Web Services Gateway OT FT Web Service Interface Design




7.2 Message Types
This section describes the Message Types that can be received by a Web Service Client in an error
condition.



7.2.1   Web Service SOAP Fault

As described in the section above the CP may get back certain types of exceptions in the format of
a Web Service SOAP Fault. Below are examples of possible SOAP faults for the different error
types defined in the table above: -


Error Template

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <soap:Fault>
         <faultcode>soap:Client</faultcode>
         <faultstring xml:lang="en-US"> </faultstring>
         <detail>
            <fs:Detail xmlns:fs="http://www.forumsystems.com/2004/04/soap-fault-detail">
               <fs:SystemName></fs:SystemName>
                  <fs:User></fs:User>
                  <fs:Policy></fs:Policy>
                  <fs:TaskList/>
                  <fs:Task/>
               </fs:Detail>
         </detail>
      </soap:Fault>
   </soap:Body>
</soap:Envelope>


Optional && Specific to Openreach Web Services Gateway

Fault code :: Specific to Openreach Web Services Gateway
fs:SystemName :: Openreach Web Services Gateway System Name
fs:User :: User invoking the Service
fs:Policy :: Specific to Openreach Web Services Gateway
fs:TaskList :: Specific to Openreach Web Services Gateway
fs:Task :: Specific to Openreach Web Services Gateway

Mandatory

Faultstring :: Contains the Error Message
fs:Detail :: Value is specific to Openreach Web Services Gateway




                                                    Page 15 of 23
Openreach Web Services Gateway OT FT Web Service Interface Design



Errors to CP
---------------------------------------------------------

Invalid DUNS ID (Duns Id in the message does not matching Client Certificate)

<soap:Envelope>
 <soap:Body>
   <soap:Fault>
     <faultcode>soap:Server</faultcode>
     <faultstring>Openreach Web Services Gateway (NBK-BNG-925534) has experienced a problem with your
request. Please see below for technical reason:- IDP Rule &apos;Process Error&apos; aborted processing.
Invalid Duns ID or Invalid userType</faultstring>
     <detail>
      <fs:Detail
       xmlns:fs="http://www.forumsystems.com/2004/04/soap-fault-detail">
       <fs:SystemName>NBK-BNG-925534</fs:SystemName>
       <fs:User></fs:User>
       <fs:Policy>OpenreachPortalInvalidDunsIDXMLPolicy</fs:Policy>
       <fs:TaskList>OpenreachPortalInvalidDunsIDTaskList</fs:TaskList>
       <fs:Task>Abort Processing</fs:Task>
      </fs:Detail>
     </detail>
   </soap:Fault>
  </soap:Body>
</soap:Envelope>

Invalid userType (userType not equal to CP_USER )

<soap:Envelope>
 <soap:Body>
   <soap:Fault>
     <faultcode>soap:Server</faultcode>
     <faultstring>Openreach Web Services Gateway (NBK-BNG-925534) has experienced a problem with your
request. Please see below for technical reason:- IDP Rule &apos;Process Error&apos; aborted processing.
Invalid Duns ID or Invalid userType</faultstring>
     <detail>
      <fs:Detail
       xmlns:fs="http://www.forumsystems.com/2004/04/soap-fault-detail">
       <fs:SystemName>NBK-BNG-925534</fs:SystemName>
       <fs:User></fs:User>
       <fs:Policy>OpenreachPortalInvalidDunsIDXMLPolicy</fs:Policy>
       <fs:TaskList>OpenreachPortalInvalidDunsIDTaskList</fs:TaskList>
       <fs:Task>Abort Processing</fs:Task>
      </fs:Detail>
     </detail>
   </soap:Fault>
  </soap:Body>
</soap:Envelope>



Bad URL (CP calling bad URL on Openreach Web Services Gateway)

<soap:Envelope>
<soap:Body>
  <soap:Fault>
   <faultcode>soap:Server</faultcode>
   <faultstring>Openreach Web Services Gateway (NBK-BNG-925534) has experienced a problem with your
request. Please see below for technical reason :- The requested virtual directory was not found</faultstring>
   <detail>
    <fs:Detail
     xmlns:fs="http://www.forumsystems.com/2004/04/soap-fault-detail">
     <fs:SystemName>NBK-BNG-925534</fs:SystemName>
     <fs:User></fs:User>
     <fs:Policy>OpenreachFaultTrackerWSDL-TestHTTPSListener</fs:Policy>
     <fs:TaskList></fs:TaskList>
     <fs:Task></fs:Task>
    </fs:Detail>
   </detail>

                                                            Page 16 of 23
Openreach Web Services Gateway OT FT Web Service Interface Design



   </soap:Fault>
 </soap:Body>
</soap:Envelope>
 </soap:Body>
</soap:Envelope>


Invalid incoming request failed to pass WSDL validation at Openreach Web Services Gateway (one
such example)

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
 <soap:Body>
   <soap:Fault>
    <faultcode>soap:Client</faultcode>
    <faultstring xml:lang="en-US">IDP Rule &apos;Process Error&apos; aborted processing.
cvc-complex-type.2.4.a: Invalid content was found starting with element &apos;ser:keyy&apos;. One of
&apos;{&quot;services:FaultTrackerServices&quot;:key}&apos; is expected.</faultstring>
    <detail>
   <fs:Detail
       xmlns:fs="http://www.forumsystems.com/2004/04/soap-fault-detail">
       <fs:SystemName>xmlevaluation1</fs:SystemName>
       <fs:User>999999999</fs:User>
       <fs:Policy>OR-Portal-FaultTracker-v1.0</fs:Policy>
       <fs:TaskList></fs:TaskList>
       <fs:Task></fs:Task>
      </fs:Detail>
    </detail>
   </soap:Fault>
 </soap:Body>
</soap:Envelope>




Large payload error

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <soap:Fault>
         <faultcode>soap:Client</faultcode>
         <faultstring xml:lang="en-US">IDP Rule 'Large Payload' aborted processing.
         The size of the document including the payload, 93359 bytes, exceeds the maximum payload allowed,
      51,200 bytes.</faultstring>
<detail>
                <fs:Detail xmlns:fs="http://www.forumsystems.com/2004/04/soap-fault-detail">
                     ---------------------------------------
                        ---------------------------------------
                </fs:Detail>
               </detail></soap:Fault>
   </soap:Body>
</soap:Envelope>


The size specified in the error message depends on the value set in Web Services Gateway and the
XML size sent.




                                                    Page 17 of 23
Openreach Web Services Gateway OT FT Web Service Interface Design



Read timeout within Openreach Web Services Gateway Platform:-

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
 <soap:Body>
   <soap:Fault>
    <faultcode>soap:Server</faultcode>
    <faultstring xml:lang="en-US">Read timed out</faultstring>
<detail>
                <fs:Detail xmlns:fs="http://www.forumsystems.com/2004/04/soap-fault-detail">
                    ---------------------------------------
                       ---------------------------------------
                </fs:Detail>
            </detail>
   </soap:Fault>
 </soap:Body>
</soap:Envelope>




Connect Timeout within Openreach Web Services Gateway

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
 <soap:Body>
   <soap:Fault>
    <faultcode>soap:Server</faultcode>
    <faultstring xml:lang="en-US">Connect time out</faultstring>
<detail>
                <fs:Detail xmlns:fs="http://www.forumsystems.com/2004/04/soap-fault-detail">
                    ---------------------------------------
                       ---------------------------------------
                </fs:Detail>
            </detail>
   </soap:Fault>
 </soap:Body>
</soap:Envelope>


Connectivity issue between Openreach Web Services Gateway and Openreach Portal

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
 <soap:Body>
   <soap:Fault>
    <faultcode>soap:Server</faultcode>
    <faultstring xml:lang="en-US">None of the configured servers can be reached</faultstring>
<detail>
                <fs:Detail xmlns:fs="http://www.forumsystems.com/2004/04/soap-fault-detail">
                    ---------------------------------------
                       ---------------------------------------
                </fs:Detail>
            </detail>
   </soap:Fault>
 </soap:Body>
</soap:Envelope>




NOTE: - All SOAP Faults generated by Openreach will have the <faultstring> populated with a description of
the error.




                                                    Page 18 of 23
Openreach Web Services Gateway OT FT Web Service Interface Design




7.3 Timeouts

As described in the above sections there are different kinds of timeouts


1) TCP connection set-up timeout between CP and Openreach Web Services Gateway.
This should be configured at the CP systems for incoming request to Openreach Web Services
Gateway.


2) TCP connection set-up timeout between Openreach Web Services Gateway and Openreach
Portal
This is configured at Openreach Web Services Gateway with the value 10 seconds. If the TCP
handshake fails to complete within 10 seconds then a timeout error will occur and Openreach Web
Services Gateway will send SOAP Fault with fault string “Connect time out” to CP systems.


3) Read time out between Openreach Web Services Gateway and Openreach Portal
If the initial TCP connection has succeeded but no response message is return within 30 seconds
(configurable) then a timeout error will occur at Openreach Web Services Gateway. Openreach Web
Services Gateway will send SOAP-FAULT with fault string as “Read timeout” to CP systems.




However the CP Client can terminate the session before this time if they do not wish to tie up their
application connections and threads for up to 30 seconds. This will then just throw a timeout
exception locally in the Client code and close the HTTP session to Openreach Web Services Gateway.
It is important to note that in doing this the transaction may continue to run on the Openreach stack.




                                                    Page 19 of 23
Openreach Web Services Gateway OT FT Web Service Interface Design



8      Client characteristics
For maximum flexibility clients should be built to be configurable for the following settings:


    1. Time-outs
             a. Connection time-out (low level TCP timeout for connection)
             b. Response read time-out


    2. Number of maximum concurrent connections


Clients should also be able to control the throughput of traffic they will send to Openreach Web
Services Gateway.


It is the client’s responsibility to design their Web Service Client to prevent scenarios leading to
thread starvation. This occurs when a client opens threads at a rate faster than they are closed
down until all available threads are used up.




It is therefore advisable to implement some form of connection manager on the client side to control
the number of connections with the Openreach Web Services Gateway.


Currently there is an upper limit being imposed on the number of requests that can be made by the
CPs. This value is configured at 2 requests per second. So if CPs send request more than this rate
they will get a SOAP-FAULT.




                                                    Page 20 of 23
Openreach Web Services Gateway OT FT Web Service Interface Design



9      Openreach Web Services Gateway Deliverables
9.1 Test Document




                                                    Page 21 of 23
Openreach Web Services Gateway OT FT Web Service Interface Design



10     References


 Ref                      Title                      Version            Author          Date
 No
 01       Interface document for exposing               0.6         Openreach Portal   30-June-
          Tracker Functionality                                      Team, Virtuasa      2009
                                                                         corp




                                                    Page 22 of 23
Openreach Web Services Gateway OT FT Web Service Interface Design



11     Glossary

B2B                     Business to business - B2B is a term usually reserved for businesses
                        trading with each other using electronic means
CP                      Communications Provider (Openreach Communication Providers)
HTTP                    HyperText Transfer Protocol - The protocol for moving hypertext files across
                        the internet and designed for the World Wide Web (WWW). Provides
                        packaging of information that can contain instruction headers and other data
                        about the content. Requires a HTTP client program on one end, and an
                        HTTP server program on the other end. HTTP is the most important
                        protocol used in the WWW
                        http://www.w3.org/Protocols/rfc2616/rfc2616.html
HTTPS                   Secure HTTP - The secure version of HTTP (HyperText Transfer Protocol)
                        using certificates that can uniquely identify the server and client, and
                        encrypt all communication between them.
DS                      Dialogue Service
21 C                    21 Century
OSS                     Operational Support System - These are the components that a company –
                        normally a Telco, so far as the standard definition goes – uses to run its
                        network and business. (Although it's now more usual to talk in terms of
                        Communications Service Providers [CSPs] to ensure that we consider ISPs,
                        MVNOs and the like, as well as traditional Telcos). Typical types of activities
                        that would count as part of OSS are taking a customer’s order, configuring
                        network components, creating a bill and managing faults.
SOAP                    Simple Object Access Protocol http://www.w3.org/TR/soap/
SSL                     Secure Socket Layer - A protocol designed by Netscape Communications to
                        enable encrypted, authenticated communications across the internet. SSL
                        used mostly (but not exclusively) in communications between web browsers
                        and web servers. URL's that begin with 'https' indicate that an SSL
                        connection will be used. SSL provides three important things; privacy,
                        authentication, and message integrity. In an SSL Connection each side of
                        the connection must have a security certificate, which each side's software
                        sends to the other. Each side then encrypts what it sends using information
                        from both its own and the other side's certificate, ensuring that only the
                        intended recipient can de-crypt it, and that the other side can be sure the
                        data came from the place that it claims to have come from, and that the
                        message has not been tampered with.
WS                      Web Service
WSDL                    Web Services Definition Language http://www.w3.org/TR/wsdl
XML                     EXtensible Markup Language - A universal format that uses meta tags on
                        content for presentation on the Web. Unlike HTML, XML only uses the tags
                        to de-limit pieces of data, so that the interpretation is left to the application
                        that reads it - http://www.w3.org/XML/




                                                    Page 23 of 23

				
DOCUMENT INFO
Shared By:
Categories:
Tags:
Stats:
views:6
posted:9/9/2011
language:English
pages:23