Upload
others
View
13
Download
0
Embed Size (px)
Citation preview
Quick Start Integration Guide
Version 3.5
Table of ContentsQuick Start Integration Guide ................................................................................................................. 1!
Introduction .......................................................................................................................................... 4!Getting Started ...................................................................................................................................... 5!
Requirements.........................................................................................................................................5!Test Environment .................................................................................................................................. 5!Live Environment................................................................................................................................... 5!
Getting Started with .NET .......................................................................................................................5!Getting Started with PHP5.......................................................................................................................7!Getting Started with Perl.........................................................................................................................8!Getting Started with Java........................................................................................................................9!
Integrating with the Portal.................................................................................................................... 10!Single Sign On ..................................................................................................................................... 10!White Labelling .................................................................................................................................... 10!Linking directly to workflows ................................................................................................................. 10!
Transfer...............................................................................................................................................10!New Provide.........................................................................................................................................11!
Summary of all available direct link to workflows .................................................................................... 12!Provides...............................................................................................................................................12!Transfers .............................................................................................................................................12!Conversions .........................................................................................................................................12!Modifies ...............................................................................................................................................13!Assurance (faults).................................................................................................................................13!Dialogue services..................................................................................................................................13!
Creating Customers .............................................................................................................................. 13!Creating a Customer from .NET .............................................................................................................14!Creating a Customer from PHP ..............................................................................................................14!Creating a Customer from Perl...............................................................................................................14!Creating a Customer from Java..............................................................................................................15!
Integrating with the Backend ................................................................................................................ 17!Status Update Feeds............................................................................................................................. 17!
Calling the Order Status Update API from .NET.......................................................................................17!Calling the Order Status Update API from PHP5 ......................................................................................18!Calling the Order Status Update API from Perl ........................................................................................18!Calling the Order Status Update API from Java .......................................................................................18!
Dialogue Services ................................................................................................................................. 19!Calling Obtain Installation Details from .NET...........................................................................................19!Calling Obtain Installation Details from PHP5 ..........................................................................................20!Calling Obtain Installation Details from Perl ............................................................................................20!Calling Obtain Installation Details from Java ...........................................................................................21!
Provisioning ......................................................................................................................................... 21!Like for Like Transfer ............................................................................................................................21!
Like for Like Transfer from .NET............................................................................................................ 21!Like for Like Transfer from PHP5........................................................................................................... 22!Like for Like Transfer from Perl ............................................................................................................. 22!Like for Like Transfer from Java ............................................................................................................ 23!
Assurance............................................................................................................................................ 23!Do Line Test.........................................................................................................................................23!
Doing a Line Test from .NET ................................................................................................................. 24!Do Line Test from PHP5 ....................................................................................................................... 24!Do Line Test from Perl.......................................................................................................................... 24!Do Line Test from Java......................................................................................................................... 25!
New Provide example ........................................................................................................................... 26!Address search..................................................................................................................................... 26!Get details of Lines at installation site .................................................................................................... 26!Get available appointments ................................................................................................................... 26!
Reserve appointments .......................................................................................................................... 27!Number Selection ................................................................................................................................. 27!Reserve Selected Number ..................................................................................................................... 28!Provide................................................................................................................................................ 28!
Get changed orders example ................................................................................................................ 30!Appendixes.......................................................................................................................................... 31!
The RetailerContext.............................................................................................................................. 31!Technologies........................................................................................................................................ 31!WSDL URLs.......................................................................................................................................... 31!
Test Environment .................................................................................................................................31!Live Environment..................................................................................................................................32!
Further Reading ................................................................................................................................... 32!Glossary .............................................................................................................................................. 32!
Introduction Integrating with the Evo21 Portal and API provides a number of advantages: Minimise double entry Maintain data integrity Incremental integration Reduce impact of Openreach change Seamless handover Reuse existing infrastructure As such, this guide is a walkthrough of how to get up and running with the Portal and API with a view to achieving this integration as quickly and easily as possible while getting maximum benefit.
Getting Started This section describes what you need to make your first call to the Evo21 Web Services API including what you need from us, how to test your connectivity and how to access the API using various programming languages.
Requirements In order to connect to the Evo21 Web Services, you will need a language and library that can communicate with the Web Services Basic Profile (WS-I Basic Profile 1.0). See the Technologies Appendix for information about which languages and libraries we have tested with. Before you start, you'll need to request a SOAP username and hashed password and a Portal username and password for the test and live environments. Note: We'll only be able to give you your live usernames and passwords when you enter live verification. In order to test connectivity to the two environments, try the following URLs in your browser of choice:
Test Environment Portal http://test.wlr3.net/empportal/
Web Services http://test.wlr3.net/empws/
Live Environment Portal https://wlr3.imperatives.co.uk/empportal/
Web Services https://wlr3.imperatives.co.uk/empws/
Getting Started with .NET Connecting to the Evo21 Web Services API using .NET uses the standard Web Services libraries that come with the .NET framework. The first step in connecting with the Evo21 Web Services API is to create a Web Reference. In your .NET project Solution Explorer, right click on your project and select “Add Web Reference...”. This should bring up a screen that looks as follows:
Paste the following URL into the URL box: http://test.wlr3.net/empws/services/WLR3SecurityServices?wsdl
and Press “Go”. When the Dialogue box returns, it should look something like this: When the Dialogue box returns, type in “SecurityServices” as the Web Reference name and click “Add Reference”. Use the following code to call the Single Sign On Web Service: C#.NET String token = securityServices.getToken(operatorId, soapUsername, soapHashedPassword, 60000);
VB.NET Dim token = securityServices.getToken(operatorId, soapUsername, soapHashedPassword, 60000)
Where the parameters to getToken are: Parameter Name Description
operatorId The user that requires a token (e.g. the Portal username we sent you)
soapUsername The SOAP username we sent you
soapHashedPassword The SOAP hashed password we sent you At this stage it is also worth creating the following method which we'll use in further examples as it is passed into many other method calls: C#.NET protected RetailerContext GetRetailerContext(String operatorName, String soapUsername, String soapHashedPassword) { RetailerContext retailerContext = new RetailerContext(); retailerContext.passwordHash = soapHashedPassword; retailerContext.username = soapUsername; retailerContext.identities = new CorrespondentIdentity[1]; retailerContext.identities[0] = new CorrespondentIdentity(); retailerContext.identities[0].type = CorrespondentType.OPERATOR; retailerContext.identities[0].@ref = operatorName; retailerContext.identities[0].typeSpecified = true; return retailerContext; }
VB.NET Protected Function GetRetailerContext(ByVal operatorName As String, ByVal soapUsername As String, ByVal soapHashedPassword As String) As RetailerContext Dim retailerContext = New RetailerContext retailerContext.passwordHash = soapHashedPassword retailerContext.username = soapUsername retailerContext.identities = New CorrespondentIdentity(0) {} retailerContext.identities(0) = New CorrespondentIdentity() retailerContext.identities(0).type = CorrespondentType.OPERATOR retailerContext.identities(0).ref = operatorName retailerContext.identities(0).typeSpecified = True Return retailerContext End Function
For more information about the RetailerContext object, see the Appendix about RetailerContext's.
Getting Started with PHP5 Connecting to the Evo21 Web Services API using PHP5 uses the standard Web Services libraries that come with PHP5.
In addition, we have created a library and set of examples to get you up and running. These are located at the Strategic Imperatives download site: http://www.imperatives.co.uk/documentation/ in a zip file called evo21-php-examples.zip.
Open up the zip file and copy the evo21.php file into your project. To try out the single sign on functionality create the following PHP code:
<?php require_once 'evo21.php'; $ss = new SecurityServices("http://test.wlr3.net", soapUsername, soapHashedPassword);
$ss->connect(); $getTokenResult = $ss->getToken(operatorId, 60000); ?>
Where the parameters to the SecurityServices constructor and getToken are: Parameter Name Description
operatorId The user that requires a token (the Portal username we sent you)
soapUsername The SOAP username we sent you
soapHashedPassword The SOAP hashed password we sent you
Getting Started with Perl The SOAP::Lite library can be used to to the Evo21 Web Services API using Perl. In addition, we have created a number of libraries and set of examples to get you up and running. These are located at the Strategic Imperatives download site: http://www.imperatives.co.uk/documentation/ in a zip file called evo21-perl-examples.zip. Open up the zip file and copy the SecurityServices.pm file into your project. To try out the single sign on functionality create the following Perl code: use SecurityServices; $fs = new SecurityServices( "http://test.wlr3.net", soapUsername, soapHashedPassword); $fs->connect(); $result = $fs->getToken(operatorId, 60000);
Where the parameters to the SecurityServices constructor and getToken are: Parameter Name Description
operatorId The user that requires a token (e.g. the Portal username we sent you)
soapUsername The SOAP username we sent you
soapHashedPassword The SOAP hashed password we sent you
Getting Started with Java The apache AXIS library may be used to access the EVO21 web services using Java. We have also tested using the Xfire SOAP library but for the purposes of this document I will show only the Axis solution.
Firstly please generate the Java stub, skeletons, etc using the WSDL2Java utility, e.g.:
java org.apache.axis.wsdl.WSDL2Java http://test.wlr3.net/empws/services/WLR3SecurityServices?wsdl
This will generate a number of Java classes that should be compiled and included into your classpath.
Here is an example of calling the getToken operation using the generated classes.
String token = null; try { String endpoint = "http://test.wlr3.net/empws/services/WLR3SecurityServices"; URL url = new URL(endpoint); WLR3SecurityServicesLocator factory = new WLR3SecurityServicesLocator(); WLR3SecurityServicesPortType service = factory.getWLR3SecurityServicesHttpPort(url); token = service.getToken(operatorId, soapUsername, soapPasswordHash, 1000); log.info("Got token '" + token + "'"); } catch (Exception e) { log.error(e,e); }
Integrating with the Portal The Evo21 Portal is designed to slot into your current set of applications as seamlessly as possible. Single Sign On means your users don't need to log in a second time when they get redirected to the Evo21 Portal for provisioning. White labelling means that your branding is consistent across your applications. Linking directly to workflows reduces double entry. Creating customers through the API means there are never unmatched customer records in the Evo21 Platform.
Single Sign On If you followed the “Getting Started” section you will have already done most of the work for Single Sign On. All that is left is to take the Single Sign On token that returns from the getToken API call, appending it to a URL and redirecting your user to the URL. To recap, the Single Sign On getToken API call is available from the following WSDLs Test http://test.wlr3.net/empws/services/WLR3SecurityServices?wsdl
Live https://wlr3.imperatives.co.uk/empws/services/WLR3SecurityServices?wsdl The URLs to redirect to are Test http://test.wlr3.net/empportal/si_security_check?si_token=SI_TOKEN
Live https://wlr3.imperatives.co.uk/empportal/si_security_check?si_token=SI_TOKEN Substitute SI_TOKEN with the token returned from the getToken API call.
White Labelling The Evo21 Portal can easily be branded using your own logo and URL (or those of your resellers if you have them). Please get in touch with us if you would like the Portal white labelled.
Linking directly to workflows By linking directly to workflows with the right data provided in the URL parameters, your users will be able to skip a number of screen in the Portal as well as have information defaulted so as to reduce double entry of data. Used alongside Single Sign On, linking to workflows lets users transfer or add new lines to customers with a minimum of effort while still using much of the Evo21 Portal user interface and workflow. The following examples show how to do the direct linking to workflow:
Transfer In order to link directly into the transfer process, after you've created a Single Sign On token, redirect to the following URL: http://test.wlr3.net/empportal/si_security_check?si_token=SI_TOKEN&process=transfer&postcode=POST_CODE&telephoneNumber=TELEPHONE_NUMBER&owner=LINE_OWNER_NAME&owner_ref=OWNER_REF&return_url=RETURN_URL
Where the parameters are: Parameter Name Description
SI_TOKEN The Single Sign On token (see the Single Sign On section for how to request this token)
POST_CODE The postcode for the line that is to be transferred
TELEPHONE_NUMBER The telephone number to be transferred
LINE_OWNER_NAME The name of the end customer
LINE_OWNER_REFERENCE Your internal reference this this customer e.g. the customer account number
RETURN_URL A url to return to when the workflow is complete. When the URL returns it will have a parameter called openreachOrderReference added to the URL which is our internal reference for this order. This may also include parameters but please separate them with the ‘pipe’ character not an ampersand or question mark. For example: return_url=http://news.bbc.co.uk/weather/forecast/2076|search=_bath|region=uk This will redirect to something like: http://news.bbc.co.uk/weather/forecast/2076?search=_bath&region=uk&orderReference=OR0000000500939
New Provide In order to link directly into the new provide process, after you've created a Single Sign On token, redirect to the following URL: http://test.wlr3.net/empportal/si_security_check?si_token=SI_TOKEN&process=provide&postcode=POST_CODE&owner=LINE_OWNER_NAME&owner_ref=OWNER_REF&return_url=RETURN_URL
Where the parameters are: Parameter Name Description
SI_TOKEN The Single Sign On token (see the Single Sign On section for how to request this token)
POST_CODE The postcode for the line that is to be transferred
LINE_OWNER_NAME The name of the end customer
LINE_OWNER_REFERENCE Your internal reference this this customer e.g. the customer account number
RETURN_URL A url to return to when the workflow is complete. When the URL returns it will have a parameter called openreachOrderReference added to the URL which is our internal reference for this order. This may also include parameters but please separate them with the ‘pipe’ character not an ampersand or question mark. For example: return_url=http://news.bbc.co.uk/weather/forecast/2076|search=_bath|region=uk This will redirect to something like: http://news.bbc.co.uk/weather/forecast/2076?search=_bath&region=uk&orderReference=OR0000000500939
Summary of all available direct link to workflows Here is a list of all workflows that you can have a direct link.
Provides
Process Parameters
provide si_token, postcode, owner, owner_ref, return_url
provideBundled si_token, postcode, owner, owner_ref, return_url
provideIsdn2 si_token, postcode, owner, owner_ref, return_url
provideIsdn30 si_token, postcode, owner, owner_ref, return_url
provideCallerRedirect si_token, owner, owner_ref, return_url
provideRcf si_token, owner, owner_ref, return_url
Transfers
Process Parameters
transfer si_token, postcode, telephoneNumber, owner, owner_ref, return_url
likeForLikeTransfer si_token, postcode, telephoneNumber, owner, owner_ref, return_url
transferAndChangeOfAddress si_token, postcode, telephoneNumber, owner, owner_ref, return_url
transferAndConversion si_token, postcode, telephoneNumber, owner, owner_ref, return_url
Conversions
Process Parameters
basicSingleToIsdn2StandardConversion si_token, installationId, return_url
basicSingleToIsdn2SystemConversion si_token, installationId, return_url
basicSingleToIsdn30eConversion si_token, installationId, return_url
basicSingleToMultilineConversion si_token, installationId, return_url
basicSingleToPremiumSingleConversion si_token, installationId, return_url
isdn2StandardToIsdn2SystemConversion si_token, installationId, return_url
isdn2SystemToIsdn2StandardConversion si_token, installationId, return_url
isdn2standardToBasicingleConversion si_token, installationId, return_url
isdn2standardToMultilineConversion si_token, installationId, return_url
isdn2standardToPremiumSingleConversion si_token, installationId, return_url
isdn2systemToBasicingleConversion si_token, installationId, return_url
isdn2systemToMultilineConversion si_token, installationId, return_url
isdn2systemToPremiumSingleConversion si_token, installationId, return_url
multilineToBasicSingleConversion si_token, installationId, return_url
multilineToIsdn2StandardConversion si_token, installationId, return_url
multilineToIsdn2SystemConversion si_token, installationId, return_url
multilineToIsdn30eConversion si_token, installationId, return_url
multilineToPremiumSingleConversion si_token, installationId, return_url
premiumSingleToBasicSingleConversion si_token, installationId, return_url
premiumSingleToIsdn2StandardConversion si_token, installationId, return_url
premiumSingleToIsdn2SystemConversion si_token, installationId, return_url
premiumSingleToIsdn30eConversion si_token, installationId, return_url
premiumSingleToMultilineConversion si_token, installationId, return_url
Modifies
Process Parameters
modifyCareLevel si_token, installationId, return_url
renumber si_token, installationId, return_url
modifyCnfs si_token, installationId, return_url
modifyLineConfig si_token, installationId, return_url
restrictService si_token, workItemReference (optional), installationId, return_url
cease si_token, installationId, return_url
Assurance (faults)
Process Parameters
newFault si_token, workItemReference (optional), telephoneNumber, installationId, return_url
Dialogue services
Process Parameters
oid si_token, postcode, telephoneNumber, owner, owner_ref, return_url
lineAvail si_token, postcode, telephoneNumber, owner, owner_ref, return_url
Note that “installationId” can be returned by making a call the “getInstallation” method in Inventory Services.
Creating Customers The Evo21 Portal has the option of disabling the creation of new customers so that the only way they can be added is through the API. This allows you to control how new customers are created in the Portal and provides a mechanism to ensure that the only customers (or line owners) that exist in the portal are customers that your systems know about. This makes reduces significantly any reconciliation issues because lines are then always associated with customers from your systems. Creating customers from the API is as simple as calling the createLineOwner API call. The createLineOwner is available from the following URLs Test http://test.wlr3.net/empws/services/WLR3InventoryServices?wsdl
Live https://wlr3.imperatives.co.uk/empws/services/WLR3InventoryServices?wsdl To remove or update the customer the deleteLineOwner and updateLineOwner methods can be used.
Creating a Customer from .NET Add a Web Reference to http://test.wlr3.net/empws/services/WLR3InventoryServices?wsdl and name the Web Service Reference “InventoryServices” and use the following code to create the Customer or Line Owner: C#.Net WLR3InventoryServices inventoryServices = new WLR3InventoryServices(); CreateLineOwnerRequest request = new CreateLineOwnerRequest(); request.lineOwnerName = lineOwnerName; request.lineOwnerReference = lineOwnerReference; inventoryServices.createLineOwner(retailerContext, request);
VB.NET Dim inventoryServices = new WLR3InventoryServices Dim request = new CreateLineOwnerRequest request.lineOwnerName = lineOwnerName request.lineOwnerReference = lineOwnerReference inventoryServices.createLineOwner(retailerContext, request)
Where the following parameters are significant: Parameter Name Description
retailerContext Use the GetRetailerContext method described in the “Getting Started with .NET” section
lineOwnerName A name for this customer. Useful when displaying information about the customer or searching for them by name
lineOwnerReference Your reference for this customer e.g. their customer account id
Creating a Customer from PHP The InventoryServices object in the evo21.php library contains a method “createLineOwner” which you can use to create a new customer as per the following code: <?php require_once 'evo21.php'; $is = new InventoryServices("http://test.wlr3.net", soapUsername, soapHashedPassword); $is->connect(); $createLineOwnerResult = $is->createLineOwner(operatorId,lineOwnerName,lineOwnerReference); ?>
Where the following parameters are significant: Parameter Name Description
operatorId The user that requires a token (the Portal username we sent you)
soapUsername The SOAP username we sent you
soapHashedPassword The SOAP hashed password we sent you
lineOwnerName A name for this customer. Useful when displaying information about the customer or searching for them by name
lineOwnerReference Your reference for this customer e.g. their customer account id
Creating a Customer from Perl The InventoryServices object in the InventoryServices library contains a method “createLineOwner” which you can use to create a new customer as per the following code:
use InventoryServices; $fs = new InventoryServices( "http://test.wlr3.net", soapUsername, soapHashedPassword ); $fs->connect(); $result = $fs->createLineOwner(operatorId, lineOwnerName, lineOwnerReference);
Where the following parameters are significant: Parameter Name Description
operatorId The user that requires a token (e.g. the Portal username we sent you)
soapUsername The SOAP username we sent you
soapHashedPassword The SOAP hashed password we sent you
lineOwnerName A name for this customer. Useful when displaying information about the customer or searching for them by name
lineOwnerReference Your reference for this customer e.g. their customer account id
Creating a Customer from Java Once again if you use the WSDL2Java tool to generate the Java stub and skeleton code from the WSDL. try { URL url = new URL("http://test.wlr3.net/empws/services/WLR3InventoryServices"); WLR3InventoryServicesLocator factory = new WLR3InventoryServicesLocator(); WLR3InventoryServicesPortType service = factory.getWLR3InventoryServicesHttpPort(url); CorrespondentIdentity operator = new CorrespondentIdentity(); operator.setRef(operatorRef); operator.setType(CorrespondentType.OPERATOR); RetailerContext retailerContext = new RetailerContext(); retailerContext.setIdentities(new CorrespondentIdentity[] { operator }); retailerContext.setPasswordHash(soapPasswordHash); retailerContext.setUsername(soapUsername); CreateLineOwnerRequest request = new CreateLineOwnerRequest(); request.setLineOwnerName("bob smith"); request.setLineOwnerReference("ABC12345"); CreateLineOwnerResponse resp = service.createLineOwner(retailerContext, request); ... } catch (Exception e) { log.error(e,e); }
Integrating with the Backend The Evo21 Platform provides an extensive API to allow you to automate any part of the provisioning or fault management process.
While everything you see in the Evo21 Portal is available through the Evo21 API, this document will highlight some of the calls that should provide maximum benefit for the least amount of development effort.
Status Update Feeds Whenever an order or fault changes status, a status update is generated by the Evo21 Platform. By using the getChangedOrders or getChangedTroubleReports API calls, your systems can query for these status updates. The Status Update feeds are very useful as they provide a way to find out how orders or faults are doing as we as letting you trigger any billing or additional workflow steps when orders or faults reach a certain status. Here are some examples of what you could do with these API calls: Create the appropriate charges in your billing system when a line goes live (note, we already integrate with many of the popular billing systems, so this might already be being done for you) Send an SMS or email to an end user when a Fault is cleared or the day before an engineering visit Automate sending of Welcoming or Advice of Transfer letters to customers Update the cases or notes in your CRM system To get the latest status updates, you'll need to periodically call the status update API calls with a from and to date. The response will then contain all of the status updates between the two dates. In order to avoid getting data repeatedly, it is worth storing the last date and time you called the API. We recommend calling the status update APIs approximately every hour. See the next sections for how to call the getChangedOrders API from your own development environment. For a detailed view of all of the information available in the response to this calls and information about the getChangedTroubleReports API call see the link to the Reference Guide in the “Further Reading” Appendix.
Calling the Order Status Update API from .NET Add a Web Reference to http://test.wlr3.net/empws/services/WLR3InventoryOrderServices?wsdl and name the Web Service Reference “InventoryOrderServices” and use the following code to get the changed orders: C#.NET WLR3InventoryOrderServices inventoryOrderServices = new WLR3InventoryOrderServices(); GetChangedOrdersRequest request = new GetChangedOrdersRequest(); request.from = new DateTime().Subtract(new TimeSpan(1, 0, 0)); request.to = new DateTime(); inventoryOrderServices.getChangedOrders(RetailerContext, request);
VB.NET Dim inventoryOrderServices = new WLR3InventoryOrderServices Dim request = new GetChangedOrdersRequest request.from = new DateTime().Subtract(new TimeSpan(1, 0, 0)) request.to = new DateTime inventoryOrderServices.getChangedOrders(RetailerContext, request)
Where the following parameters are significant: Parameter Name Description
retailerContext Use the GetRetailerContext method described in the “Getting Started with .NET” section
from The date and time to query from (one hour ago in the example)
To The date and time to query to (the current date and time in the example)
Calling the Order Status Update API from PHP5 The InventoryServices object in the evo21.php library contains a method “getChangedOrders” which you can use to get the order status updates as per the following code: <?php require_once 'evo21.php'; $ios = new InventoryOrderServices("http://test.wlr3.net", soapUsername, soapHashedPassword); $ios->connect(); $getChangedOrdersResult = $ios->getChangedOrders(operatorId, fromDateTime, toDateTime); ?>
Where the following parameters are significant: Parameter Name Description
operatorId The user that requires a token (the Portal username we sent you)
soapUsername The SOAP username we sent you
soapHashedPassword The SOAP hashed password we sent you
from The from date and time, this is just a string formatted as follows: "2007-09-10T23:59:59"
to The to date and time, this is just a string formatted as follows: "2007-09-10T23:59:59"
Calling the Order Status Update API from Perl The InventoryOrderServices object in the InventoryOrderServices library contains a method “getChangedOrders” which you can use to get the status update feed as per the following code: use InventoryOrderServices; $ios = new InventoryOrderServices("http://test.wlr3.net", soapUsername, soapHashedPassword); $ios->connect(); $result = $ios->getChangedOrders(operatorId, fromDateTime, toDateTime);
Where the following parameters are significant: Parameter Name Description
operatorId The user that requires a token (e.g. the Portal username we sent you)
soapUsername The SOAP username we sent you
soapHashedPassword The SOAP hashed password we sent you
fromDateTime The from date and time, this is just a string formatted as follows: "2007-09-10T23:59:59"
toDateTime The to date and time, this is just a string formatted as follows: "2007-09-10T23:59:59"
Calling the Order Status Update API from Java First generate the Java stubs and skeleton code from the WSDL using the WSDL2Java tool. try { URL url = new URL("http://test.wlr3.net/empws/services/WLR3InventoryOrderServices"); WLR3InventoryOrderServicesLocator factory = new WLR3InventoryOrderServicesLocator(); WLR3InventoryOrderServicesPortType service = factory.getWLR3InventoryOrderServicesHttpPort(url);
CorrespondentIdentity operator = new CorrespondentIdentity(); operator.setRef(operatorRef); operator.setType(CorrespondentType.OPERATOR); RetailerContext retailerContext = new RetailerContext(); retailerContext.setIdentities(new CorrespondentIdentity[] { operator }); retailerContext.setPasswordHash(soapPasswordHash); retailerContext.setUsername(soapUsername); GetChangedOrdersRequest request = new GetChangedOrdersRequest(); Calendar oneWeekAgo = Calendar.getInstance(); oneWeekAgo.add(Calendar.DAY_OF_YEAR, -7); request.setFrom(oneWeekAgo); GetOrdersResponse resp = service.getChangedOrders(retailerContext, request); ... } catch (Exception e) { log.error(e,e); }
Dialogue Services Dialogue Services are informational services provided by Openreach through WLR3. They include the ability to search for an address, query an address to see if it has capacity and find out what the properties of a particular line are. Many of the Dialogue Services are only useful as part of an order workflow or when raising fault. A number are also useful on their own, for example, the Sales team could use “Manage Line Availability” to find out whether there is capacity at an address when they're speaking to a customer to let them know how long it will take Openreach to provide a service to them. The following are dialogue services that are useful on their own: Dialogue Service API call Description
Obtain Installation Details getInstallationDetails Takes in a telephone number and postcode and provides information about what the properties of the line are e.g. the line type, calling and network features etc.
Find Address addressSearch Takes in a postcode and returns all of the addresses that Openreach and the Post Office know about at that postcode
Manage Line Availability getManagedLineDetails Takes in an address key and returns capacity information about the address including how many spare pairs there are and whether there are working or stopped lines
See the Dialogue Services section of the Reference Guide mentioned in the “Further Reading” Appendix for a list of all the Dialogue Services as well as their request and response parameters.
Calling Obtain Installation Details from .NET Add a Web Reference to http://test.wlr3.net/empws/services/WLR3DialogueServices?wsdl and name the Web Service Reference “DialogueServices” and use the following code to obtain the installation details for a particular telephone number and postcode combination: C#.NET WLR3DialogueServices dialogueServices = new WLR3DialogueServices(); GetInstallationDetailsRequest request = new GetInstallationDetailsRequest(); request.telephoneNumber = telephoneNumber; request.postcode = postcode; GetInstallationDetailsResponse response = dialogueServices.getInstallationDetails(retailerContext, request);
VB.NET Dim dialogueServices = new WLR3DialogueServices
Dim request = new GetInstallationDetailsRequest request.telephoneNumber = telephoneNumber request.postcode = postcode Dim response = dialogueServices.getInstallationDetails(retailerContext, request)
Where the following parameters are significant: Parameter Name Description
retailerContext Use the GetRetailerContext method described in the “Getting Started with .NET” section
telephoneNumber The telephone number that you would like to query
postcode The postcode associated with the telephone number
Calling Obtain Installation Details from PHP5 The DialogueServices object in the evo21.php library contains a method “oid” which you can use to get the order status updates as per the following code: <?php require_once 'evo21.php'; $ds = new DialogueServices("http://test.wlr3.net", soapUsername, soapHashedPassword); $ds->connect(); $oidResult = $ds->oid(operatorId, telephoneNumber, postcode); ?>
Where the following parameters are significant: Parameter Name Description
operatorId The user that requires a token (the Portal username we sent you)
soapUsername The SOAP username we sent you
soapHashedPassword The SOAP hashed password we sent you
telephoneNumber The telephone number that you would like to query
postcode The postcode associated with the telephone number
Calling Obtain Installation Details from Perl The DialogueServices object in the DialogueServices library contains a method “oid” which you can use to obtain installation details for a telephone number as per the following code: use DialogueServices; $fs = new DialogueServices( "http://test.wlr3.net", soapUsername, soapHashedPassword); $fs->connect(); $result = $fs->oid(operatorId, telephoneNumber, postcode); Where the following parameters are significant: Parameter Name Description
operatorId The user that requires a token (e.g. the Portal username we sent you)
soapUsername The SOAP username we sent you
soapHashedPassword The SOAP hashed password we sent you
telephoneNumber The telephone number that you would like to query
postcode The postcode associated with the telephone number
Calling Obtain Installation Details from Java After generating the Java Stub and Skeleton classes using the WSDL2JAVA tool. try { URL url = new URL("http://test.wlr3.net/empws/services/WLR3DialogueServices"); WLR3DialogueServicesLocator factory = new WLR3DialogueServicesLocator(); WLR3DialogueServicesPortType service = factory.getWLR3DialogueServicesHttpPort(url); CorrespondentIdentity operator = new CorrespondentIdentity(); operator.setRef(operatorRef); operator.setType(CorrespondentType.OPERATOR); RetailerContext retailerContext = new RetailerContext(); retailerContext.setIdentities(new CorrespondentIdentity[] { operator }); retailerContext.setPasswordHash(soapPasswordHash); retailerContext.setUsername(soapUsername); GetInstallationDetailsRequest request = new GetInstallationDetailsRequest(); request.setPostcode("IP10 0DE"); request.setTelephoneNumber("01142702745"); GetInstallationDetailsResponse resp = service.getInstallationDetails( retailerContext, request); ... } catch (Exception e) { log.error(e,e); }
Provisioning All of the WLR3 order types are supported through the Evo21 API. Many of the order types require some user interaction prior to the order being placed and this interaction ranges from the relatively simple (e.g. Transfers) to the relatively complex (e.g. Change of Address). The Like for Like Transfer process requires no user interaction and is typically a high volume activity in most CPs. As a result, it is an ideal candidate for early integration.
Like for Like Transfer The Like for Like Transfer order takes as its request parameters some line owner details, a telephone number and a postcode. When called, it transfers a customer from their current Communication Provider to yourselves, typically in approximately 10 working days. The following sections describe how to call Like for Like Transfer from various programming languages
Like for Like Transfer from .NET Add a Web Reference to http://test.wlr3.net/empws/services/WLR3FulfilmentServices?wsdl and name the Web Service Reference “FulfilmentServices” and use the following code to do a Like for Like Transfer: C#.NET WLR3FulfillmentServices fulfilmentServices = new WLR3FulfillmentServices(); LikeForLikeTransferRequest request = new LikeForLikeTransferRequest(); request.lineOwnerReference = lineOwnerReference; request.lineOwnerName = lineOwnerName; request.telephoneNumber = telephoneNumber; request.postcode = postcode; request.endUserNameFor999 = endUserNameFor999; LikeForLikeTransferResponse response = fulfilmentServices.likeForLikeTransfer( retailerContext, request);
VB.NET Dim fulfilmentServices = new WLR3FulfillmentServices Dim request = new LikeForLikeTransferRequest request.lineOwnerReference = lineOwnerReference request.lineOwnerName = lineOwnerName request.telephoneNumber = telephoneNumber
request.postcode = postcode request.endUserNameFor999 = endUserNameFor999 Dim response = fulfilmentServices.likeForLikeTransfer(retailerContext, request)
Where the following parameters are significant: Parameter Name Description
retailerContext Use the GetRetailerContext method described in the “Getting Started with .NET” section
lineOwnerReference A unique reference for the owner of this line e.g. your customer account id. This could be a new line owner or an existing one.
lineOwnerName The name of the owner of this line
telephoneNumber The telephone number to transfer
postcode The postcode associated with the telephone number. If the telephone number and postcode don't match in Openreach records, the order will be rejected.
endUserNameFor999 A name to associate with this line for 999 calls. This can be the company name.
Like for Like Transfer from PHP5 The FulfilmentServices object in the evo21.php library contains a method “likeForLikeTransfer” which you can use to do a like for like transfer for a particular number: <?php require_once 'evo21.php'; $fs = new FulfilmentServices("http://test.wlr3.net", soapUsername, soapHashedPassword); $fs->connect(); $likeForLikeTransferResult = $fs->likeForLikeTransfer( operatorId, lineOwnerName, lineOwnerReference, telephoneNumber, postcode, endUserNameFor999); ?>
Where the following parameters are significant: Parameter Name Description
operatorId The user that requires a token (the Portal username we sent you)
soapUsername The SOAP username we sent you
soapHashedPassword The SOAP hashed password we sent you
lineOwnerReference A unique reference for the owner of this line e.g. your customer account id. This could be a new line owner or an existing one.
lineOwnerName The name of the owner of this line
telephoneNumber The telephone number to transfer
postcode The postcode associated with the telephone number. If the telephone number and postcode don't match in Openreach records, the order will be rejected.
endUserNameFor999 A name to associate with this line for 999 calls. This can be the company name.
Like for Like Transfer from Perl The FulfilmentServices object in the FulfilmentServices library contains a method “likeForLikeTransfer” which you can use to do a like for like transfer for a particular number: use FulfilmentServices;
$fs = new FulfilmentServices( "http://test.wlr3.net", soapUsername, soapHashedPassword); $fs->connect(); $result = $fs->likeForLikeTransfer( operatorId, lineOwnerName, lineOwnerReference, telephoneNumber, postcode, endUserNameFor999);
Where the following parameters are significant: Parameter Name Description
operatorId The user that requires a token (the Portal username we sent you)
soapUsername The SOAP username we sent you
soapHashedPassword The SOAP hashed password we sent you
lineOwnerReference A unique reference for the owner of this line e.g. your customer account id. This could be a new line owner or an existing one.
lineOwnerName The name of the owner of this line
telephoneNumber The telephone number to transfer
postcode The postcode associated with the telephone number. If the telephone number and postcode don't match in Openreach records, the order will be rejected.
endUserNameFor999 A name to associate with this line for 999 calls. This can be the company name.
Like for Like Transfer from Java After generating the stubs and skeleton code using WSDL2Java: try { URL url = new URL("http://test.wlr3.net/empws/services/WLR3FulfillmentServices"); WLR3FulfillmentServicesLocator factory = new WLR3FulfillmentServicesLocator(); WLR3FulfillmentServicesPortType service = factory.getWLR3FulfillmentServicesHttpPort(url); CorrespondentIdentity operator = new CorrespondentIdentity(); operator.setRef(operatorRef); operator.setType(CorrespondentType.OPERATOR); RetailerContext retailerContext = new RetailerContext(); retailerContext.setIdentities(new CorrespondentIdentity[] { operator }); retailerContext.setPasswordHash(soapPasswordHash); retailerContext.setUsername(soapUsername); LikeForLikeTransferRequest request = new LikeForLikeTransferRequest(); request.setEndUserNameFor999("mr jones"); request.setLineOwnerName("bob jones"); request.setLineOwnerReference("ABC1234"); request.setPostcode("IP10 0DE"); request.setTelephoneNumber("01142702745"); LikeForLikeTransferResponse resp = service.likeForLikeTransfer( retailerContext, request); log.debug(resp.getOpenreachOrderReference()); ... } catch (Exception e) { log.error(e,e); }
Assurance WLR3 provides an opportunity to automate testing of lines and raising faults for the first time. These calls are exposed by the Evo21 API. The getChangedTroubleReports API provides a way to keep track of the progress of faults through status updates.
Do Line Test Use the Line Test Dialogue Service to find out if automated testing can discover whether a line has a fault. See the following sections for how to do a line test with various programming languages.
Doing a Line Test from .NET Add a Web Reference to http://test.wlr3.net/empws/services/WLR3AssuranceServices?wsdl and name the Web Service Reference “AssuranceServices” and use the following code to do a Like for Like Transfer: C#.NET WLR3AssuranceServices assuranceServices = new WLR3AssuranceServices(); DoLineTestRequest request = new DoLineTestRequest(); request.telephoneNumber = telephoneNumber; request.faultCode = faultCode; DoLineTestResponse response = fulfilmentServices.doLineTest(retailerContext, request);
VB.NET Dim assuranceServices = new WLR3AssuranceServices Dim request = new DoLineTestRequest request.telephoneNumber = telephoneNumber request.faultCode = faultCode Dim response = fulfilmentServices.doLineTest(retailerContext, request)
Where the following parameters are significant: Parameter Name Description
retailerContext Use the GetRetailerContext method described in the “Getting Started with .NET” section
telephoneNumber The telephone number to test. This number must be in the Evo21 inventory (you can use Add Installation to add WLR2 lines to the inventory)
faultCode The fault code e.g. NDT for No Dial Tone
Do Line Test from PHP5 The AssuranceServices object in the evo21.php library contains a method “lineTest” which you can use to test a particular number: <?php require_once 'evo21.php'; $as = new AssuranceServices("http://test.wlr3.net", soapUsername, soapHashedPassword); $as->connect(); $lineTestResult = $as->lineTest(operatorId, telephoneNumber, faultCode); ?>
Where the following parameters are significant: Parameter Name Description
operatorId The user that requires a token (the Portal username we sent you)
soapUsername The SOAP username we sent you
soapHashedPassword The SOAP hashed password we sent you
telephoneNumber The telephone number to test. This number must be in the Evo21 inventory (you can use Add Installation to add WLR2 lines to the inventory)
faultCode The fault code e.g. NDT for No Dial Tone
Do Line Test from Perl The AssuranceServices object in the AssuranceServices library contains a method “lineTest” which you can use to do a like for like transfer for a particular number:
use AssuranceServices; $fs = new AssuranceServices( "http://test.wlr3.net", soapUsername, soapHashedPassword); $fs->connect(); $result = $fs->lineTest(operatorId, telephoneNumber, faultCode);
Where the following parameters are significant: Parameter Name Description
operatorId The user that requires a token (the Portal username we sent you)
soapUsername The SOAP username we sent you
soapHashedPassword The SOAP hashed password we sent you
telephoneNumber The telephone number to test. This number must be in the Evo21 inventory (you can use Add Installation to add WLR2 lines to the inventory)
faultCode The fault code e.g. NDT for No Dial Tone
Do Line Test from Java After generating the stubs and skeleton code using the WSDL2JAVA tool: try { URL url = new URL("http://test.wlr3.net/empws/services/WLR3AssuranceServices"); WLR3AssuranceServicesLocator factory = new WLR3AssuranceServicesLocator(); WLR3AssuranceServicesPortType service = factory.getWLR3AssuranceServicesHttpPort(url); CorrespondentIdentity operator = new CorrespondentIdentity(); operator.setRef(operatorRef); operator.setType(CorrespondentType.OPERATOR); RetailerContext retailerContext = new RetailerContext(); retailerContext.setIdentities(new CorrespondentIdentity[] { operator }); retailerContext.setPasswordHash(soapPasswordHash); retailerContext.setUsername(soapUsername); DoLineTestRequest request = new DoLineTestRequest(); request.setDisruptiveTestsAllowed(true); request.setTelephoneNumber("01142702745"); request.setFaultCode("NDT"); DoLineTestResponse resp = service.doLineTest(retailerContext, request); ... } catch (Exception e) { log.error(e,e); }
New Provide example Providing a new line in WLR3 is done by making a number of dialogue service calls, consulting and involving the customer about various decisions such as appointment date/times, and then placing the order with Openreach. Please see the API usage interaction diagrams on Provide for an depth explanation of the calls to make and decisions to take prior to placing the order.
Address search Typically new provide order would start with attempting to identify the site of the installation. Openreach provides a synchronous dialogue service to allow addresses to be searched for. The results are either classes as Gold (in Openreach Db), Silver (not in Openreach Db but in Post Office Db), or Bronze (not known at all).
To search for an address using just a postcode (other search fields are available):
VB.NET Dim ws = New WLR3DialogueServices Dim rc = GetRetailerContext( helper.operatorRef, helper.soapUsername, helper.soapPasswordHash) Dim addrSearchReq = New AddressSearchRequest addrSearchReq.postcode = postcode Dim addrSearchResp = ws.addressSearch(rc, addrSearchReq) If addrSearchResp.messages.Length > 0 Then 'An error has occurred … Else For i = 0 To addrSearchResp.addresses.Length - 1 Dim adr = addrSearchResp.addresses(i) … Next End If
Get details of Lines at installation site If you select a gold address then it is possible to ask Openreach to give the details of the existing line plant that is at an installation. This will then allow you to make decisions about what type of provide to offer the customer.
VB.NET Dim rc = GetRetailerContext( helper.operatorRef, helper.soapUsername, helper.soapPasswordHash) Dim ws = New WLR3DialogueServices Dim lineDetailsReq = New GetManagedLineDetailsRequest lineDetailsReq.addressReference = selectedAddressReference lineDetailsReq.cssDatabaseCode = selectedCssDatabaseCode Dim lineDetailsResp = ws.getManagedLineDetails(rc, lineDetailsReq) If lineDetailsResp.availabilityDetails Is Nothing Then 'An error has occurred … Else Dim msg = "The type of the installation is " + lineDetailsResp.availabilityDetails.installationType.ToString + " and there are " + lineDetailsResp.availabilityDetails.dpSparePairs.ToString + " spare pairs" … End If
Get available appointments Once again if the customer has chosen a gold address then Openreach can give you a list of appointments that the Openreach engineers can attend the site. Note: prior to making this call the system would typically ask the customer to choose the type of line, service type, etc.
VB.NET
Dim getAppointReq = New GetAppointmentAvailabilityRequest getAppointReq.addressReference = addressReference getAppointReq.cssDatabaseCode = cssDatabaseCode getAppointReq.serviceType = AppointmentServiceType.WLR_SINGLE_LINE getAppointReq.serviceTypeSpecified = True getAppointReq.action = AppointmentAction.PROVIDE getAppointReq.actionSpecified = True getAppointReq.lineType = FulfilmentServices.LineType.BASIC getAppointReq.lineTypeSpecified = True getAppointReq.appointmentType = AppointmentType.STANDARD getAppointReq.appointmentTypeSpecified = True getAppointReq.quantity = 1 getAppointReq.quantitySpecified = True Dim getAppointResp = ws.getAppointmentAvailability(rc, getAppointReq) If getAppointResp.appointments Is Nothing Then 'An error has occurred … Else For i = 0 To getAppointResp.appointments.Length - 1 Dim appoint = getAppointResp.appointments(i) … Next End If
Reserve appointments Having selected an appropriate appointment date and timeslot Openreach can now be called to reserve this appointment. This reservation results in a reservation reference that is valid for 4 hours and will be included in the provide call later.
VB.NET Dim addAppReq = New AddAppointmentRequest addAppReq.addressReference = addressReference addAppReq.cssDatabaseCode = cssDatabaseCode addAppReq.appointment = New Appointment addAppReq.appointment.appointmentDate = appDate addAppReq.appointment.appointmentDateSpecified = True addAppReq.appointment.action = AppointmentAction.PROVIDE addAppReq.appointment.actionSpecified = True addAppReq.appointment.lineType = DialogueServices.LineType.BASIC addAppReq.appointment.lineTypeSpecified = True addAppReq.appointment.serviceType = AppointmentServiceType.WLR_SINGLE_LINE addAppReq.appointment.serviceTypeSpecified = True addAppReq.appointment.quantity = 1 addAppReq.appointment.quantitySpecified = True If (appTimeslot.ToUpper().Equals("AM")) Then addAppReq.appointment.appointmentTimeslot = DialogueServices.AppointmentTimeslot.AM Else addAppReq.appointment.appointmentTimeslot = DialogueServices.AppointmentTimeslot.PM End If addAppReq.appointment.appointmentTimeslotSpecified = True Dim addAppRes = ws.addAppointment(rc, addAppReq) If addAppRes.appointmentReference Is Nothing Then 'An error has occurred … Else appointmentReference.Value = addAppRes.appointmentReference … End If
Number Selection With a gold address key Openreach can provide a list of available numbers that may be selected at a given address. There is an alternative to this where by the we request that Openreach just reserve the next available number and don't select a number.
VB.NET
Dim findNumsReq = New FindNumbersAtAddressRequest findNumsReq.addressReference = addressReference findNumsReq.cssDatabaseCode = cssDatabaseCode findNumsReq.listType = ListType.STANDARD findNumsReq.listTypeSpecified = True Dim findNumsResp = ws.findNumbersAtAddress(rc, findNumsReq) If findNumsResp.numberAvailability Is Nothing Then 'An error has occurred … Else For i = 0 To findNumsResp.numberAvailability.availableTelephoneNumbers.Length - 1 Dim num = findNumsResp.numberAvailability.availableTelephoneNumbers(i) … Next End If
Reserve Selected Number
Having selected a telephone number with the customer this can be reserved so other users of Openreach do not have an opportunity to reserve it themselves. The number reservation key will be later included in the add order provide call.
VB.NET Dim reserveReq = New DialogueServices.ReserveNumberRequest reserveReq.telephoneNumber = Numbers.SelectedValue reserveReq.serviceType = DialogueServices.ServiceType.PSTN_SINGLE_LINE reserveReq.serviceTypeSpecified = True Dim reserveRes = ws.reserveNumber(rc, reserveReq) If reserveRes.numberReservation Is Nothing Then 'An error has occurred … Else … End If
Provide Having performed all these dialogue service calls we have gathered some information about that new line to be installed. There is obviously more information that needs to be collected. Things such as site contact details when the engineer arrives for the appointment, directory information to be included in the phone book, line types, etc. Once all this information is gathered up then a new provide order can be placed with the API.
VB.NET Dim provideReq = New ProvidePstnWithGoldenRequest provideReq.addressReference = addressReference provideReq.cssExchangeCode = cssDatabaseCode provideReq.careLevel = FulfilmentServices.CareLevel.MED provideReq.careLevelSpecified = True provideReq.appointmentReference = appointmentReference.Value provideReq.appointment = New FulfilmentServices.SiteAppointmentVisit provideReq.appointment.appointmentDate = appDate provideReq.appointment.appointmentDateSpecified = True If (appTimeslot.ToUpper().Equals("AM")) Then provideReq.appointment.appointmentTimeslot = DialogueServices.AppointmentTimeslot.AM Else provideReq.appointment.appointmentTimeslot = DialogueServices.AppointmentTimeslot.PM End If provideReq.appointment.appointmentTimeslotSpecified = True provideReq.appointment.contactName = "Larry Small" provideReq.appointment.contactTelephone = "01752813910" provideReq.ecChargeBand = ECChargeBand.UNLIMITED provideReq.ecChargeBandSpecified = True provideReq.trChargeBand = TRChargeBand.UNLIMITED_TRC provideReq.trChargeBandSpecified = True provideReq.terminationType = FulfilmentServices.TerminationType.LINE_BOX provideReq.terminationTypeSpecified = True
provideReq.trChargeBandSpecified = True provideReq.numberReservationReference = numResKey provideReq.postcode = txtPostcode.Text provideReq.installationType = FulfilmentServices.InstallationType.STANDARD provideReq.installationTypeSpecified = True provideReq.lineOwnerName = lineOwnerName.Text provideReq.lineOwnerReference = lineOwnerReference.Text provideReq.lineType = FulfilmentServices.LineType.BASIC provideReq.lineTypeSpecified = True provideReq.serviceType = FulfilmentServices.ServiceType.PSTN_SINGLE_LINE provideReq.serviceTypeSpecified = True provideReq.lineCardSettings = New FulfilmentServices.EULineCardSettings provideReq.lineCardSettings.calling = CallingType.EARTH provideReq.lineCardSettings.callingSpecified = True provideReq.lineCardSettings.clearDisconnectTime = 10 provideReq.lineCardSettings.clearDisconnectTimeSpecified = True provideReq.linePlantType = LinePlantType.SPARE_PAIR provideReq.linePlantTypeSpecified = True provideReq.mainLineDirectory = New FulfilmentServices.Directory provideReq.mainLineDirectory.endUserNameFor999 = "jim smith" provideReq.mainLineDirectory.type = FulfilmentServices.DirectoryType.ORDINARY provideReq.mainLineDirectory.typeSpecified = True provideReq.mainLineDirectory.locationOption = FulfilmentServices.LocationOption.RESIDENTIAL provideReq.mainLineDirectory.locationOptionSpecified = True provideReq.mainLineDirectory.surname = "smith" provideReq.mainLineDirectory.initial = "j" Dim provideResp = ws.providePstnWithGolden(rc, provideReq) If provideResp.openreachOrderReference Is Nothing Then 'An error has occurred … Else Dim successMsg = "Order created with reference " + provideResp.openreachOrderReference End If
That was an example of a provide using a gold address. There is another operation to place a provide with a non-gold address. With non-gold addresses Openreach have to go out and survey the site to try and find it. As such you cannot book appointments, choose numbers, etc. ISDN30 and ISDN2 provides are also available.
At the end of the provide after a few seconds the process will return an order reference number. This can now be used to query the state of the order as it receives update messages from Openreach.
Get changed orders example Orders can be queried using the order reference but often you do not want to have to keep track of all the orders you've placed. As such we provide an operation to return all 'changed' orders (that is orders having received an update or some sort) between two points in time. Typically client's will make this call and then record what time the call was last made. Subsequent calls being made from then until now each time.
VB.NET Dim chgedOrdersReq = New GetChangedOrdersRequest chgedOrdersReq.from = fromD chgedOrdersReq.fromSpecified = Not (fromDate.Text Is Nothing) chgedOrdersReq.to = toD chgedOrdersReq.toSpecified = Not (toDate.Text Is Nothing) Dim chgedOrderResp = ws.getChangedOrders(rc, chgedOrdersReq) If chgedOrderResp.orders Is Nothing Then If chgedOrderResp.messages Is Nothing Then 'No orders found … Else 'An error has occurred … End If Else For i = 0 To chgedOrderResp.orders.Length - 1 Dim order = chgedOrderResp.orders(i) … Next End If
Appendixes
The RetailerContext Security is enforced at the web service level using the Retailer Context, and is a mandatory parameter on every web service method. The Retailer Context object contains: Identities an array of Correspondent Identity objects. These being a tuple of Correspondent Type
(Wholesaler, CP, Retailer, Dealership and Operator) and their unique id. The unique id may be the DUNS in the case of a CP, the RID in the case of a Retailer, etc.
Username name of the user performing the operation.
Password Hash a hash of the password of the user performing the operation. This will be provided by Strategic Imperatives to the client.
There are two security mechanisms used the in the web service API. The username and password inside the Retailer Context are used to authenticate access to the web services. Typically a single soap username will be created which has security access to the web services, at the highest applicable level in the correspondent hierarchy, in the cases below, this is the clientadmin user. This user would then be username in all web service calls. Then different identifies will be provided to specify the operator on whose behalf the call will be performed, this is typically the username of the operator logged onto the external CRM or Billing system. The Identities collection will always contain at least one item - the name of the Operator who is performing an action. There may also be other identities but often this is not necessary as they can be derived. In the case of an Operator who is associated with a Retailer (e.g. Bob in the example above) then there is no need to pass any other information. The CP and Wholesaler can be determined from just the Retailer. If the Operator is associated with a Wholesaler (e.g. Jean in the example above) then they will need to pass the CP and Retailer identity should they wish to do certain operations, e.g. A provide of new services.
Technologies Language Suggested Library
Java XFire
.NET Built in Web Services Library
PHP5 Built in Web Services Library
Perl SOAP::Lite
WSDL URLs
Test Environment http://test.wlr3.net/empws/services/WLR3AssuranceServices?wsdl http://test.wlr3.net/empws/services/WLR3BillingServices?wsdl http://test.wlr3.net/empws/services/WLR3DialogueServices?wsdl http://test.wlr3.net/empws/services/WLR3FulfillmentServices?wsdl http://test.wlr3.net/empws/services/WLR3InventoryOrderServices?wsdl http://test.wlr3.net/empws/services/WLR3InventoryServices?wsdl http://test.wlr3.net/empws/services/WLR3InventoryTroubleReportServices?wsdl
http://test.wlr3.net/empws/services/WLR3SecurityServices?wsdl
Live Environment https://wlr3.imperatives.co.uk/empws/services/WLR3AssuranceServices?wsdl https://wlr3.imperatives.co.uk/empws/services/WLR3BillingServices?wsdl https://wlr3.imperatives.co.uk/empws/services/WLR3DialogueServices?wsdl https://wlr3.imperatives.co.uk/empws/services/WLR3FulfillmentServices?wsdl https://wlr3.imperatives.co.uk/empws/services/WLR3InventoryOrderServices?wsdl https://wlr3.imperatives.co.uk/empws/services/WLR3InventoryServices?wsdl https://wlr3.imperatives.co.uk/empws/services/WLR3InventoryTroubleReportServices?wsdl https://wlr3.imperatives.co.uk/empws/services/WLR3SecurityServices?wsdl
Further Reading Portal User Manual https://wlr3.imperatives.co.uk/empportal/manual/index.html
Web Services Reference https://wlr3.imperatives.co.uk/empws/
Error Codes http://www.openreach.co.uk/orpg/products/wlr/wlr3/downloads/EMP_Response_Code_List_Issue_10.0.zip
Glossary Term Meaning
C&NFs Calling and Network Features
CLI Caller Line Identity (Telephone Number)
CP Communications Provider
CPS Carrier Pre Select
CRM Customer Relationship Management
DUNS Dun and Bradstreet Universal Numbering System
EDR End of Day Report
IDA Indirect Access
L4L Like for Like
LFR Letter Facilitation Report
SI Strategic Imperatives
SOAP Simple Object Access Protocol
SPG Service Provider Gateway (The BT Portal for provisioning WLR2 Lines)
SSO Single Sign On
WLR Wholesale Line Rental
WSDL Web Service Description Language