User Manual for Pre Qualify Coverage Checker Page 1

KPN Wholesale COBS WMIA / WIA Pre Qualify Coverage Checker Version 9.0, July 2018

Revision History

Version Date Author Description

5.7 June 18, 2001 W.D. Nijdam First version 0.02 June 22, 2001 W.D. Nijdam ASP name in URL. 1.00 June 28, 2001 W.D. Nijdam Update error messages 2.00 August 16,

2001 W.D. Nijdam Update error messages and table with

result texts. 3.00 October 19,

2001 W.D. Nijdam Update PQCC URL and reference to

DekCheck 3.01 December 6,

2002 W.D. Nijdam Updated to PQCC version 2. XML option

added 3.02 June 17, 2003 W.D. Nijdam XML schema added. Postal code format

description added 3.03 February 2,

2004 W.D. Nijdam Most likely delivery dates added

3.04 February 11, 2004

W.D. Nijdam Error result text modified

3.05 August 9, 2004 W.D. Nijdam NetNumber field added 3.06 May 25, 2005 W.D. Nijdam AggrGroupName field added 4.00 August 17,

2005 W.D. Nijdam Update to Web Service version of PQCC

(Version 4.0) 5.00 March 1, 2008 W.D. Nijdam Update to Partnersoap Web Service

version 5.0 op PQCC 5.7 February 27,

2009 W.D. Nijdam New ExistingSituation data element

introduced in PQCC v5.7 6.0 January 2011 W.D. Nijdam Updated to PQCC v6.0 6.1 7.0 7.1 8.0 9.0

March 2011 June 2012 July 2014 July 2015 July 2018

W.D. Nijdam W. Troost Harini .S Raja B Harini S

Added chapter ‘Best practices’ Updated to PQCC v7.0 Updated to PQCC v7.1 Updated to PQCC v8.0 Updated to PQCC v9.0. Authentication added.

The information contained herein is the property of KPN b.v and is supplied without liability for errors or omissions. Written permission must be sought from KPN b.v. before this document can be reproduced, used or disclosed in any way. The copyright and foregoing restriction of

User Manual for Pre Qualify Coverage Checker Page 2

reproductions, use and disclosure extend to all media in which this information may be embodied.

User Manual for Pre Qualify Coverage Checker Page 3

Contents Introduction ..................................................................................................................... 4 1 Accessing PQCC ..................................................................................................... 5

1.1 Accessing PQCC manually ............................................................................... 6 1.2 Accessing PQCC from another application using SOAP ................................... 8

2 Input parameters ..................................................................................................... 9 3 Result fields ........................................................................................................... 11 4 Best practices ........................................................................................................ 18

4.1 Test postcodes ................................................................................................ 18 4.2 Street and City names ..................................................................................... 18 4.3 House number additions ................................................................................. 18 4.4 Validating shared line information ................................................................... 19 4.5 Checking for changes on existing DSL lines .................................................... 19

5 PQCC versioning ................................................................................................... 20 6 Contact information ............................................................................................... 20

User Manual for Pre Qualify Coverage Checker Page 4

Introduction

This document describes how to use the COBS WMIA/WIA pre qualification coverage checker (PQCC). PQCC translates an address to a list of deliverable products. It also returns the street and city name, distance to MDF and SDF, and the telephony netnumber. Most important changes in PQCC version 8.0:

References to BabyXL and WBA-A network types are removed

An Option is provided in PQCC GUI to select PQCC Check type (Coverage / Copper / Fiber)

An option is provided in PQCC GUI to enter the connection point (Isra Specs) details

PQCC Request in SOAP Web Service is modified to accept 2 new parameters PQCCCheckType and ConnectionPoint

ExistingSituation in Response is modified to display either Copper or Fiber information based on type of check performed

Type of Check Response

Coverage Response contains OriginalRequest, Address, CGB and DeliverableProducts sections. ExistingSituation is empty.

Copper Response contains OriginalRequest, Address, CGB and DeliverableProducts and ExistingSituation sections. ExistingSituation contains only ExistingSituationCopper section and ExistingSituationFiber section is empty.

Fiber Response contains OriginalRequest, Address, CGB and DeliverableProducts and ExistingSituation sections. ExistingSituation contains only ExistingSituationFiber section and ExistingSituationCopper section is empty.

PQCC is delivered as a SOAP web service: https://pqcc.soap.dslorder.nl/pqcc/v9.0/pqcc.asmx There is a web interface to facilitate manual requests: https://pqcc.soap.dslorder.nl/pqcc/v9.0/pqcc.aspx Both are accessible from any place on the Internet. NOTE: The previous version of Pqcc -> Pqcc8.0 will be available for some more time to facilitate the ISP’s to upgrade.

User Manual for Pre Qualify Coverage Checker Page 5

1 Accessing PQCC

PQCC can be found at https://pqcc.soap.dslorder.nl/pqcc/v9.0/pqcc.asmx The test/training version can be found at https://pqcc-training.soap.dslorder.nl/pqcc/v9.0/pqcc.asmx.

The service is self-documenting. The WSDL definition file can be retrieved by clicking ‘Service Description’. Furthermore the SOAP calling method for the ‘PostcodeCheck’ method and the ‘Test’ method is presented.

User Manual for Pre Qualify Coverage Checker Page 6

1.1 Accessing PQCC manually PQCC can be accessed through a website:

Navigate to https://pqcc.soap.dslorder.nl/pqcc/v9.0/pqcc.aspx

Enter the following details to perform PQCC Check

Field Name Type Mandatory

UserName Text Yes

Password Text Yes

Postal Code Text Yes

House Number Number Yes

House Number Addition

Text No

Phone number to validate

Text No

Show Debug info Check Box No

Check for upgrade / downgrade

Check Box No

User Manual for Pre Qualify Coverage Checker Page 7

PQCC Check Type Option Button Yes

Connection Point Number

Text Box No

Press the ‘’check’ button

A file with the XML result will start downloading

Error code Error Desc (NL) Error Desc (Eng)

89 "Gebruikersnaam of wachtwoord mag niet leeg zijn"

"Username or password can not be empty"

90 "Ongeldige opgegeven legitimatie of gebruiker is uitgeschakeld"

"Invalid credential supplied or user is disabled"

As part of v9.0 COBS has introduced authentication in Pqcc. Username and Password will be mandatory. Please refer to the document attached for more information.

PQCC

9.0Auth_v1.0.docx

User Manual for Pre Qualify Coverage Checker Page 8

1.2 Accessing PQCC from another application using SOAP

SOAP is the preferred access method. Create a SOAP wrapper based on a web reference to the PQCC web service. Use the ‘PostcodeCheck’ method of the wrapper to call PQCC. Recommendation: use https when calling PQCC. The WSDL definition can be found at https://pqcc.soap.dslorder.nl/pqcc/v9.0/pqcc.asmx?WSDL

User Manual for Pre Qualify Coverage Checker Page 9

2 Input parameters

Only PostalCode, HouseNumber and PQCCCheckType are mandatory fields in the PqccRequest object:

Parameter Input Datatype Conversion

Postalcode char 6 Existing Dutch Postal code. Must conform to format '[1-9][0-9][0-9][0-9][A-Z][A-Z]'

HouseNumber Int 5 House numbers between 1 and 99999.

HouseNumberAddition varchar 4 House number addition. This field is mandatory when an adequate view on the existing situation is needed.

ApplicationName varchar 10 ‘PQCC’ is default. Partners can provide Application name of their application.

Reseller varchar 50 Unique key to indicate specific Reseller. Usually the name of the Reseller. Leave empty or use value assigned by KPN Implementation Manager.

Source varchar 2000 Indication of the calling application and end

User Manual for Pre Qualify Coverage Checker Page 10

Parameter Input Datatype Conversion

user IP address.

CheckForUpgradeDownGrade

Boolean Set to true when checking PQCC for upgrade orders (change of existing DSL connections). Even when no stock is available PQCC will still return products.

QueryDate DateTime Fill with current data. Only used for message logging.

SharingPhonenumberToValidate PQCCChekType ConnectionPoint

Varchar(10) Varchar(8) Char(3)

Phone number to check for use with line sharing. ‘Coverage’ is default. Other possible values are ‘Copper’ and ‘Fiber’. Coverage returns only technical information. Copper returns existing copper line information along with technical information. Fiber returns existing fiber line information along with technical information Default Empty. Possible values are ‘001’ / ‘002’ / ‘003’ etc. This option is used if a location contains multiple isra points and user is interested to see the details about a particular isra point

Hints for evaluating the result:

When a technology is not available, the technology result will not be presented. Presented results are therefore always available.

User Manual for Pre Qualify Coverage Checker Page 11

3 Result fields

PQCC presents the following response branches:

<Address PostalCode="string" HouseNumber="int"

HouseNumberAddition="string" Street="string" City="string">

<PossibleHouseNumberAdditions>

<Addition>string</Addition>

<Addition>string</Addition>

</PossibleHouseNumberAdditions>

</Address>

Address contains information about the requested delivery address location:

Attribute Meaning

Postalcode Reformatted postal code

HouseNumber House number as Integer

HouseNumberAddition Copy of input

Street NEN formatted Street name of delivery address. Presented for cross checking.

City NEN formatted City name of delivery address. Presented for cross checking.

PossibleHouseNumberAdditions List of possible house number additions allowed for the postal code and house number.

The CGB element contains information about the CGB area:

Attribute Meaning

Name Abbreviated name of the central office location

NetNumber Netnumber for phone lines. To be used when VoIP is ordered with a local number

LengthMdf LengthLastDistributor

Distance in meters from the MDF to the customer. Distance in meters from the last street cabinet to the customer.

<Cgb Name="string" LengthLastDistributor="int" NetNumber="string"

LengthMdf="int" />

User Manual for Pre Qualify Coverage Checker Page 12

Each row of DeliverableProducts represents a product that can be ordered.

Attribute Meaning

Network="KpnWbaE or Sni-F" Technology="Adsl1_Pots or Adsl2_Pots or Adsl1_Isdn or Adsl2_Isdn or Vdsl2 or Vdsl2_Pots or Vdsl2_Isdn or EoF or GoF”

Type of network the Intenet access product will be delivered on Used technology on the wire. Determines the kind of modem that will be used. Pots is also known as PSTN Vdsl2 is known as FTTC ”fiber to the curb” Vdsl2_Pots is known as “buitenringen” EoF means “Ethernet over Fiber” GoF stands for “Gigabit over Fiber”

AvailabilityStatus="Orderable or Planned or TempararilySuspended"

Products can only be ordered when status is “Orderable”

AvailabilityPlanDate="date" When Planned the date when ordering is expected

to be possible

ExpectedDownKbps="int" The maximum down speed that can be expected. A value of 0 is returned if the value could not be determined.

ExpectedUpKbps="int" The maximum up speed that can be expected. A value of 0 is returned if the value could not be determined.

OrderableDownKbps="int" The maximum down speed that can be ordered. A value of 0 is returned if the value could not be determined.

OrderableUpKbps="int" The maximum up speed that can be ordered. A value of 0 is returned if the value could not be determined.

Dlm="None or Lc or Sc" Determines dynamic line management option. None when no DLM is used (fixed DSL profiles). Lc

<DeliverableProducts>

<DeliverableProduct Network="string" Technology="string" Dlm="string"

AvailabilityStatus="string" CanShare="string"

NlType="int" ExpectedUpKbps="int"

ExpectedDownKbps="int" AvailabilityPlanDate="date"

OrderableDownKbps="int" DistributionPoint="string"

Tv="boolean" OrderableUpKbps="int" />

</DeliverableProducts>

User Manual for Pre Qualify Coverage Checker Page 13

indicates the use of DLM for low error ratios. SC for medium error ratios (not suited for TV)

Tv="boolean" Indication if this product is usable for TV

DistributionPoint="string" Name of distribution point where the wire is terminated.

NlType="int" Type of delivery for glass fiber.

<DeliverableProducts>

<DeliverableProduct>

<ProductTypes>

<ProductType ProductTypeCode="int" DownSpeed="int"

Sharing="string" />

</ProductTypes>

</DeliverableProduct>

</DeliverableProducts>

If you pass your reseller ID in the OrignalRequest, PQCC will return a list of available product types. This feature is currently in experimental.

Attribute Meaning Sharing="None or PSTN"

Sharing type. If you pass a SharingPhonenumberToValidate, PQCC will return shared products. Otherwise it will return dedicated products.

DownSpeed="int"

The download limit speed set for the product type.

ProductTypeCode="int" The type of the product. The code that is accepted by the DslOrder web service. A full list of codes can be downloaded from https://www.dslorder.nl, menu Reports, then “DSL Producttype”.

User Manual for Pre Qualify Coverage Checker Page 14

User Manual for Pre Qualify Coverage Checker Page 15

The ExistingSituation element can contain the following values:

ExistingSituationCopper

ExistingSitauationFiber

Remarks ExistingSituationCopper element contain the elements as described in below picture

Element Type Description

1-ExistingSituationCopper XML Element

PhoneLineType string Type of phone line that can be used to share with

SharedLine string Whether line is shared or not (true / false)

PhoneNumber string Existing phone number on the customer’s address that is capable to support line sharing. Due to legal issues first 7 digits of phonenumber is replaced with ‘*’

ExistingDSLServiceId string KPN service-id of an existing DSL connection

carrierStatus string

carrierVendorId string

2-connectionpointinfo XML Element

cgb-name String

isra-specs String

number-of-nl1-lines Number

number-of-nl2-lines Number

3-copperconnection XML Element

current-typeofconnection String

current-mdf-access-serviceid

String

current-phonenumber String

future-typeofconnection String

future-mdf-access-serviceid

String

future-phonenumber String

User Manual for Pre Qualify Coverage Checker Page 16

ExistingsitutaionFiber element contain the elements as described in below picture

Element Type Description

1-ExistingSituationFiber XML Element

areaPOP string

ExistingODFServiceId string

FtuType string

carrierStatus string

carrierVendorId string

2-fiber-connectionpointinfo

XML Element

Fiber-terminationpoint-id String

Ftu-type String

3-copperconnection XML Element

current-typeofconnection String

current-odf-connection-id String

current-phonenumber String

future-typeofconnection String

current-odf-connection-id String

Remark code 9058 with explanation “No Service exists” means there is no DSL; the end user can still have Fiber. Each row of Errors represents an error that occurred. There can be multiple errors in a single call. The EnumName attribute can contain the following values. Note that new errors may be added without releasing a new PQCC version.

<Errors>

<Error Number="int" EnumName="string" DescriptionNed="string"

DescriptionEng="string" />

</Errors>

User Manual for Pre Qualify Coverage Checker Page 17

Error Description

PostalCodeFormat Postal code in wrong format. Must be '[1-9][0-9][0-9][0-9][ABCDEGHJKLMNPRSTVWXZ][ABCDEGHJKLMNPRSTVWXZ]

HouseNumberMissing House number is needed HouseNumberFormat House number is nog in right format UnknownResellerId Reseller code is unknown InvalidLanguage Invalid language selected ColoNotFound No related Colo found ColoAmbiguous More than one possible colo found StreetUnknown No related street found StreetAmbiguous Street ambiguous. CityUnknown City unknown AvailabilityUnknown Coverage unknown PlanUnknown No plan date available. PostalCodeHouseNumberMismatch Postal code in combination with house number

invalid. PostalCodeUnknown Postal code is unknown PostalBox The postal code refers to a postal box Glassfiber Probable glass fiber in access network. KnownProblemArea Delivery is nog posible due to long wires or other

known problmes WbaToolsUnavailable KPN WBA coverage check did not respond in time. WbaBroadbandCheckUnavailable Broadbandchecker did not respond in time. Results

in missing ExistingSituation element in the response. PhoneNumberFormat The given phone number to validate is not a valid

phone number PhoneNumberMismatch The given phone number to validate does not match

the number that is used for traditional telephony at the customer’s location.

Some hints in case errors are returned:

If the postal code doesn’t exist (PostalCodeUnknown), we suggest using an external source to validate the postal code. A good source is http://www.postcode.nl/. The PQCC database contains the official PTT Post postal code not older than two months.

If the postal code in combination with the house number is not found (PostalCodeHouseNumberMismatch) a combination with the house number appendix might be needed. For example: use “Weezenhof 7101” in stead of “Weezenhof 71 –01”

In case ambiguous results are found (ColoAmbiguous) different results exists within the postal code area. Providing a house number in combination with the postal code will give better results.

The error ‘WBAToolsavailable’ means that the WBA-A coverage checker is temporarily not available. In that case no DeliverableProducts are returned.

User Manual for Pre Qualify Coverage Checker Page 18

4 Best practices

4.1 Test postcodes A few selected test postcodes are embedded in PQCC. These cases span the various technology types (from Adsl1 to GoF.) There are also corner-case city names like 1E EXLOERMOND and street names like Laan 1940-'45. Current test postcodes are: 1234AB 1-A, 2, 3, 4 and 6. For the test postcodes, PQCC returns a static result, which can be used for assertions in a test scenario. The list of test postcodes can be found in the StubData.xml document: https://pqcc.soap.dslorder.nl/pqcc/v7.0/StubData.xml

4.2 Street and City names Based on the postal code and house number, PQCC determines the street name and city name in the NEN format. Use these names to:

Let the user validate the entered postal code and house number. In the web dialog ask for the postal code and house number and present the names to the user. Our experience shows that users type the wrong postal code in about 7% of the cases. So let the user validate the street and city names to prevent ordering on wrong addresses.

Use the exact names in the orders to COBS, or leave the street and city blank when ordering in COBS. If a street or city name is provided they must exactly match the string as returned by PQCC.

4.3 House number additions

When using a house number addition like in 1111AA 1-bis, the house number must exactly match an addition that is known in the KPN database. PQCC returns a list of possible house numbers in the following cases:

1. An address was provided without house number extension

2. An address was provided with an unknown house number extension. In this case also error ‘PostalCodeHouseNumberMismatch’ is raised.

3. In case a known house number addition was provided, PQCC could return a list with just the given value and not show other house number additions.

The best approach for entering house number additions:

User Manual for Pre Qualify Coverage Checker Page 19

1. Ask the user to enter postal code, house number and addition.

2. Call PQCC

3. If PQCC does not return the entered addition (including empty string) in the list of possible additions, go back to the user and let the user make a selection from the additions provided by PQCC.

4.4 Validating shared line information

It is possible to use a single copper wire pair for traditional telephony and ADSL at the same time. Telephony will use the low frequencies and ADSL the higher frequencies. This technique is called ‘line sharing’ (sharing the same copper wire for more services). The chance of successful ADSL delivery is higher with line sharing. Therefore ISP’s should prefer line sharing where possible. Sharing is only possible with a traditional phone line delivered by KPN. It is not possible to do ADSL sharing with a VoIP line like “InternetPlusBellen”. PQCC returns information about an existing traditional phone line at the customers address. The ExistingSituation/@PhoneLineType attribute indicates the type of traditional phone line that is present at the customer’s location. It is also possible to validate the phone number for line sharing. For privacy reasons, PQCC does not provide the line sharing number but it can validate a given number. Ask the customer for the number. Send it to pqcc in the field ‘SharingPhonenumberToValidate’. PQCC will raise the ‘PhoneNumberMismatch’ error only when there is traditional telephony at the customer’s location but with a different number. No exception is raised when there is no traditional telephony present at the customer’s location. In the case the customer has ISDN2 he might have multiple phone numbers. In that case the main number must be used.

4.5 Checking for changes on existing DSL lines Existing DSL connections may be changed in speed or altered to other technologies. When using PQCC in these cases call it with parameter CheckForUpgradDownGrade set to ‘true’. In that case PQCC might include deliverable products that might not be available for new DSL connections. This could be important when specific type of networks have been closed for new orders, or are temporarily out of stock.

User Manual for Pre Qualify Coverage Checker Page 20

5 PQCC versioning

This manual is in line with PQCC version 7.1. Small changes may be performed on an existing version. For PQCC, a small change includes the following:

Addition of a new element or attribute

New possible values in existing fields like TechnologyType, CanShare or Dlm

Adding a new SOAP function Please ensure that applications that call PQCC can cope with these changes. The current version is displayed in the result of the ‘Test’ method:

6 Contact information

For questions or remarks please contact the TSD: dsl-order@kpn.com