xGate Getting Started

Introduction

This documentation is designed to give an overview of the xGate system and help guide the reader through implementing calls to place an order on the system. Examples in this document are based around Microsoft .NET C#, but the system can be called by any language that can make SOAP compliant XML calls. We have tested the system with the following languages and operating systems

Windows - Microsoft Active Service Pages (MS Soap toolkit)
Windows - .NET (native .net soap calls, xGate Web interface uses gateway)
Linux/Windows - PHP (Pear Soap library )
Linux - PERL (Soaplite)

Some examples are available on the channel partner web site.

Overview

The xGate web service system is composed of many web services that allow different operations. Each web service has a distinct function. For example,

xGateSecurity service contains a login function, and functions that relate to the user logged in
Order service contains functions to list available products and create orders.

Usage

To use xGate, first you have to login via the xGateSecurity Service.The login method returns a unique Authentication Token for that user at that IP Address.

Once you have the Authentication Token, you can set this in the AuthHeader of the Service you wish to call.

WRxGateSecurity.xGateSecurity objSecurity = new WRxGateSecurity.xGateSecurity();

string AuthToken = new WRxGateSecurity.xGateSecurity().Login(Session["Username"].ToString(), Session["Password"].ToString(), Session["IPAddress"].ToString(), Session["Domain"].ToString());

objSecurity.AuthenticationHeaderValue = new WRxGateSecurity.AuthenticationHeader();

objSecurity.AuthenticationHeaderValue.AuthenticationToken = AuthToken;

Once you have an AuthToken, you can use it on each of the services provided by xGate.

There are various functions provided by xGate, but the most important one is the CreateOrder function in the Order service. This takes in 4 strings of xml (CustomerXML, ProductsXML, PaymentXML and UserXML), validates all of the data provided, and attempts to order the products requested. Once it is done it returns an xGateOrderResponse, that details the success or failure of all of the elements related to the xGate order.

Note: For resellers you can use the CreateOrderWithDefaultUserCustomerAndPaymentDetails function which will create an order with the default customer, payment and user information for the xGate user you logged in as. This function simply takes the Products XML.

The only slightly complicated piece of XML is the Products XML that xGate requires. This is actually the xGateOrderProducts XML, and each of the products specific XML combined.

e.g. If you are ordering an ADSL line, you need to populate the xGateOrderProducts schema, and the ADSLOrder schema. Once the ADSLOrder schema has been created, it can be appended to the ProductsXML node of the xGateOrderProducts XML. See the example XML files for a better idea.

Services

The following services are provided by xGate.

xGateSecurity

Contains functions to login and retrieve information about the logged on user.

Service Locations

The test version is located:

http://xgatetest.thevisp.co.uk/Webservice/Services/xGateSecurity.asmx?wsdl

The live version is located:

https://www.tricommerce.co.uk/xGateWebservice/Services/xGateSecurity.asmx?wsdl

Functions

· Login
Log into the service

· GetLoggedInUsersCustomerInformation
Retrieves Customer information for the user in the AuthToken

· GetLoggedInUsersDefaultPaymentMethod
Retrieves Customer information for the user in the AuthToken

· GetLoggedInUserInformation
Retrieves information about the user relevant to the AuthToken

Customer

Contains functions related to the xGate Customer. e.g. retrieving customer information via a postcode lookup.

Service Locations

The test version is located:

http://xgatetest.thevisp.co.uk/Webservice/Services/Customer.asmx?wsdl

The live version is located:

https://www.tricommerce.co.uk/xGateWebservice/Services/Customer.asmx?wsdl

Functions

· SaveUsersCustomerInformation
Saves details for a customer

· GetCustomerInformationFromPostcodeLookup
Returns a dataset of customer information based on a postcode lookup

· GetCustomerInformationFromAccountCodeLookup
Returns a dataset of customer information from an account code lookup

· GetAddressInformationFromPostcodeLookup
Returns a dataset of address information based on a postcode lookup

· GetEmptyCustomerInformationObject
Returns an empty dataset of customer information.

· GetCustomerInformationFromPreviousOrder
Returns a dataset of customer information from a previous order

Order

Contains functions related to placing orders on xGate.

Service Locations

The test version is located:

http://xgatetest.thevisp.co.uk/Webservice/Services/Order.asmx?wsdl

The live version is located:

https://www.tricommerce.co.uk/xGateWebservice/Services/Order.asmx?wsdl

Functions

· CreateOrder
Create an order on xGate

· GetEmptyVisp2SignupObject
Returns an empty Visp2Signup dataset

· GetListOfProductsByServiceType
Returns a list of available Products for a Service Type.

· GetListOfPreviousServiceProvidersForADSL
Returns a list of known previous service providers for ADSL

· GetListOfAgents
Gets a list of account managers

· GetListOfAdditionalProductsByProductCode
Returns a list of available Additional Products for a Main Product.

· GetProductsXMLSchemaLocation
Returns the location of a products XML Schema.

· GetEmptyADSLOrderObject
Returns an empty ADSLOrder dataset

· CheckTelNoForADSLAvailability_v7
Returns BT ADSL availability details for a phone number

· CheckTelNoForADSLAvailability
Returns BT ADSL availability details for a phone number

· GetListOfADSLProvisioningDomains
Gets a list of available ADSL Provisioning Domains for the logged in user

· GetListOfNavisionResponsibilityCentres
Gets a list of available Navision Responsibility Centres for the logged in user

· GetAvailablePaymentMethods
Gets a list of available payment methods

· GetAvailableCreditCardTypes
Gets a list of available Credit Card Types

· GetEmptyADSLAdditionalOptionsOrderObject
Returns an empty ADSLAdditionalOptionsOrder dataset

· CreateOrderWithDefaultUserCustomerAndPaymentDetails
Create an order on xGate

· GetUniqueBTPSTNReferenceNumber
Gets a list of available Navision Responsibility Centres for the logged in user

· GetListOfAccountManagers
Gets a list of account managers

· GetVisp2SignupObjectfromClientsID
A fully populated Visp2Signup dataset

· RequestMACCodefromCBUKandTelephoneNumber
Returns a MAC Code generated from BT

· CheckPostcodeForSDSLAvailability
Returns BT SDSL availability details for a phone number

· GetListOfPreviousServiceTypesForADSL
Returns a list of BT service types for ADSL

· GetListOfIndustryGroupCodes
Gets a list of account managers

· GetListOfAvailableServiceTypes
Returns a list of available Service Types. E.g. ADSL, VISP II.

· RequestMACCodefromLoginorCBUK
Returns a MAC Code generated from BT

· GetListOfAdditionalProductsByProductCodeAndOrderType
Returns a list of available Additional Products for a Main Product.

xGateSchemas

Contains functions to return dataset and XML string versions of all of the schemas used in xGate.

Service Locations

The test version is located:

http://xgatetest.thevisp.co.uk/Webservice/Services/xGateSchemas.asmx?wsdl

The live version is located:

https://www.tricommerce.co.uk/xGateWebservice/Services/xGateSchemas.asmx?wsdl

Functions

· GetADSLProvisioningDomainsDataset
Returns the ADSL Provisioning Domains DataSet

· GetProductsListDataset
Returns the Products List DataSet

· GetAddressInformationSchema
Returns the Address Information Schema

· GetAgentsListSchema
Returns the Agents List Schema

· GetCustomerInformationSchema
Returns the Customer Information Schema

· GetPaymentTypesListDataset
Returns the Payment Types List DataSet

· GetAdditionalProductsListSchema
Returns the Additional Products List Schema

· GetADSLPreviousServiceTypesDataset
Returns the ADSL Previous Service Types DataSet

· GetPaymentDetailsInformationDataset
Returns the Payment Details Information DataSet

· GetSECPayRequestSchema
Returns the SECPay Request Schema

· GetADSLPreviousServiceTypesSchema
Returns the ADSL Previous Service Types Schema

· GetxGateOrderResponseSchema
Returns the xGate Order Response Schema

· GetServiceTypesListDataset
Returns the Service Types List DataSet

· GetPaymentDetailsInformationSchema
Returns the Payment Details Information Schema

· GetUserInformationDataset
Returns the User Information DataSet

· GetADSLOrderSchema
Returns the ADSL Order Schema

· GetxGateOrderProductsSchema
Returns the xGate Order Products Schema

· GetAccountManagersListSchema
Returns the Account Managers List Schema

· GetUserInformationSchema
Returns the User Information Schema

· GetxGateOrderResponseDataset
Returns the xGate Order Resposne Schema

· GetCreditCardTypesListDataset
Returns the Credit Card Types List DataSet

· GetAddressInformationDataset
Returns the Address Information DataSet

· GetAgentsListDataset
Returns the Agents List DataSet

· GetPaymentTypesListSchema
Returns the Payment Types List Schema

· GetServiceTypesListSchema
Returns the Service Types List Schema

· GetADSLPreviousServiceProvidersDataset
Returns the ADSL Previous Service Providers DataSet

· GetProductsListSchema
Returns the Products List Schema

· GetADSLPreviousServiceProvidersSchema
Returns the ADSL Previous Service Providers Schema

· GetADSLOrderDataset
Returns the ADSL Order DataSet

· GetSECPayResponseSchema
Returns the SECPay Response Schema

· GetSECPayRequestDataset
Returns the SECPay Request DataSet

· GetCreditCardTypesListSchema
Returns the Customer Information Schema

· GetAdditionalProductsListDataset
Returns the Additional Products List DataSet

· GetSECPayResponseDataset
Returns the SECPay Response DataSet

· GetADSLProvisioningDomainsSchema
Returns the ADSL Provisioning Domains Schema

· GetxGateOrderProductsDataset
Returns the xGate Order Products Schema

· GetCustomerInformationDataset
Returns the Customer Information DataSet

· GetAccountManagersListDataset
Returns the Account Managers List DataSet

Example Soap Requests and Responses.

xGateSecurity.Login

Request

<?xml version="1.0" encoding="utf-16"?>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<Username>pobox</Username>

</Login>

</soap:Body>

</soap:Envelope>

Returns

<?xml version="1.0" encoding="utf-16"?>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<LoginResult>dbfcdad0-90d0-4d73-9b7d-4a80d011e9c4</LoginResult>

</LoginResponse>

</soap:Body>

</soap:Envelope>

xGateSecurity.GetLoggedInUsersCustomerInformation

Request

<?xml version="1.0" encoding="utf-16"?>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Header>

<AuthenticationToken>dbfcdad0-90d0-4d73-9b7d-4a80d011e9c4</AuthenticationToken>

</AuthenticationHeader>

</soap:Header>

<soap:Body>

</soap:Body>

</soap:Envelope>

Returns

<?xml version="1.0" encoding="utf-16"?>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<xs:schema id="UserInformation" targetNamespace="https://www.tricommerce.co.uk/xGate/UserInformation.xsd" xmlns:mstns="https://www.tricommerce.co.uk/xGate/UserInformation.xsd" xmlns="https://www.tricommerce.co.uk/xGate/UserInformation.xsd" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata" attributeFormDefault="qualified" elementFormDefault="qualified">

<xs:element name="UserInformation" msdata:IsDataSet="true">

<xs:complexType>

<xs:choice maxOccurs="unbounded">

<xs:element name="User">

<xs:complexType>

<xs:sequence>

<xs:element name="Username" type="xs:string" />

<xs:element name="AccountType" type="xs:string" />

<xs:element name="AccountManager" minOccurs="0" maxOccurs="unbounded">

<xs:complexType>

<xs:sequence>

<xs:element name="Name" type="xs:string" />

<xs:element name="InternalName" type="xs:string" />

</xs:sequence>

</xs:complexType>

</xs:element>

<xs:element name="Agent" minOccurs="0" maxOccurs="unbounded">

<xs:complexType>

<xs:sequence>

<xs:element name="Name" type="xs:string" />

<xs:element name="Code" type="xs:string" />

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:choice>

</xs:complexType>

</xs:element>

</xs:schema>

<diffgr:diffgram xmlns:msdata="urn:schemas-microsoft-com:xml-msdata" xmlns:diffgr="urn:schemas-microsoft-com:xml-diffgram-v1">

<Username>pobox</Username>

<AccountType>Reseller</AccountType>

<Name>Nildram</Name>

<InternalName>nildram</InternalName>

</AccountManager>

</Agent>

</User>

</UserInformation>

</diffgr:diffgram>

</GetLoggedInUserInformationResult>

</GetLoggedInUserInformationResponse>

</soap:Body>

</soap:Envelope>

Order.CheckTelNoForADSLAvailability

Request

<?xml version="1.0" encoding="utf-16"?>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Header>

<AuthenticationToken>dbfcdad0-90d0-4d73-9b7d-4a80d011e9c4</AuthenticationToken>

</AuthenticationHeader>

</soap:Header>

<soap:Body>

</CheckTelNoForADSLAvailability>

</soap:Body>

</soap:Envelope>

Returns

<?xml version="1.0" encoding="utf-16"?>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<ExchangeName>AYLESBURY</ExchangeName>

<ExchangeStatus>Enabled.</ExchangeStatus>

<ExchangeStatusCode>ENABLED</ExchangeStatusCode>

<LineSpeed>Initial tests indicated that your line should support 512kbps connection only.</LineSpeed>

<LineSpeedCode>SUPPORT_MIN</LineSpeedCode>

<Error>false</Error>

</CheckTelNoForADSLAvailabilityResult>

</CheckTelNoForADSLAvailabilityResponse>

</soap:Body>

</soap:Envelope>