A Developer Guide to the SOAP Services

Overview

This document provides technical information about Business Gateway. You should use it if you are a:

case management software vendor (CMS)
conveyancer
developer

And wish to integrate with our legacy services using SOAP/XML. To integrate using REST/JSON visit A Developer Guide to the REST Services

System overview

Business Gateway allows CMS vendors to have a direct interface with our e-services. It provides a framework to streamline and improve their business skills.

This provides an electronic XML interface for interoperability between CMS and our existing services.

A mutual SSL connection between the external system and Business Gateway’s web services allows for exchange of information.

Services available on Business Gateway

Prerequisites

Prerequisites for generating a web service client

A valid SSL certificate is required for downloading the WSDL and schema files from HM Land Registry Business Gateway. This certificate is needed for mutual SSL authentication.

A list of URLs for all services provided by Business Gateway to download the respective WSDL and schema files for a given service.

Expiry of Certificates

HM Land Registry Business Gateway certificates expire after 3 years. When this date is approaching you will need to contact your Account Manager who can raise a request to have new Certificates issued.

If your certificate expires you will not be able to access the Business Gateway until the new certificate is installed and your system is configured to use it.

Prerequisites for invoking Business Gateway’s services

To invoke Business Gateway services:

a valid SSL certificate issued by Business Gateway is required. This certificate is used to enable mutual SSL authentication. This certificate is installed once at the CMS client site
a list of URLs is required for all services provided by Business Gateway in order to invoke the required services
an active user account to use Business Gateway. The user ID and the password is the same as for the HM Land Registry portal
an active variable direct debit (VDD)
the request should conform to the request schema
the request must contain Business Gateway User ID and password and locale information as part of the SOAP header
a unique message ID generation mechanism should be followed for every request being sent to Business Gateway (see Note 1)
a mechanism is required to temporarily store the generated message ID. This message ID is used to fetch the response when the end user does not receive the synchronous response from Business Gateway for example when a request is made out of hours or when the message is lost in transit


Note 1

Reliable Messaging:

Message ID is used for the reliable messaging mechanism used in Business
Gateway. The external system is required to generate a unique identifier for
every request that has been sent to Business Gateway

This message ID is used to receive a response from Business Gateway if the
original response is lost due to network issues or other reasons such as
if the original request was submitted out of hours.

Business Gateway uses the following information for determining whether a
given request is a new request

- Message ID.
- Service Type (for example bankruptcy search).
- User ID.

Business Gateway uses the following information for determining whether a
given request is a new request

Development activities

Install SSL certificates issued by HM Land Registry as trusted root.
Install client digital certificate issued by HM Land Registry into client key store
Develop a mechanism to generate and store unique message IDs with respect to the request sent to Business Gateway
Consume the WSDL offered by Business Gateway and develop the following functionality based on the web services exposed
Develop a mechanism to send requests to Business Gateway for each web service that has been exposed
Develop a mechanism to submit Outstanding Request requests to get information about requests where the response is not available synchronously
Develop a mechanism to send polling requests for the requests returned by the Outstanding Request service
Develop a mechanism to process responses
Develop a mechanism to deal with exceptions
For each request sent, the SOAP header must contain the user ID, password and locale information
For each request sent, the HTTPS channel will be mutually authenticated using certificate exchange

Design constraints

Web service requests over HTTP/HTTPS internet protocols are not reliable. This can lead to lost messages between request and response.

To solve this, we use a reliable messaging mechanism (see Note 1). This way responses are not lost between the client CMS software and Business Gateway.

The constraints used to ensure reliable messaging include:

unique message ID
process request only once

Unique message ID

The client sends a SOAP request with a unique message ID and waits for the response. In case the client does not receive a response within a specified period of time, it will send the request with the same message ID once again.

The client ensures that all message requests have a unique message ID. It is the responsibility of Business Gateway to correlate the SOAP request and response with the same message ID.

Process request only once

Business Gateway processes the request for the first time and stores the response in a database. Next time a request arrives as a result of a lost message, with the same message ID for the same service type and from the same user ID then the response is sent from the stored data.

APIs and schema

Information service schema

Application Enquiry
Discharge Activity
Enquiry by property description
Land Charges Bankruptcy Search
Land Charges Full Search
Official Copy Title Known
Official Search of Whole
Official Search of Part
Search of the Index Map
Register Extract Service

eDocument Registration Services

Application to Change Register
Attachment
Correspondence
Early Completion

Verification Services

Online Ownership Verification

Local Land Charges Services

Local land charges search

Utility Services

Outstanding requests

API request and response

Request Type
- Normal Request
  A request is considered to be a normal request when it is sent to Business Gateway during working hours. The original request is stored by Business Gateway along with the response.
- Poll Request
  - Collecting Out of Hours applications
    
    When a request is sent to Business Gateway ‘out of hours’ or after the day list is closed, the system calculates a suggested date and time at which the response to the request will be made available. The client can then make a poll request to Business Gateway at the suggested date and time, with the message ID of the original message, to retrieve the stored response.
  - Manual Processed applications
    
    A poll request may be used to collect the result of a Business Gateway application that has been processed manually by LR Staff.
  For optimal usage the system can be written to automatically call the Outstanding Request service, which will provide details of requests that have a new response to be collected. These can then automatically be sent through the corresponding Poll Request services, enabling the response to be collected as early as possible. This is the only way to collect some of the messages sent when using electronic Document Registration Service (eDRS). We recommend following this process every couple of hours.

Request structure

Business Gateway’s SOAP request consists of the following elements: SOAP header must contain (refer to figure 1):

user ID
password
locale information


<!-- SOAP envelope starts -->
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:drs="http://drsv1_0.ws.bg.lr.gov"
xmlns:req="http://www.oscre/ns/eReg-
Final/2012/RequestApplicationToChangeRegisterV1_0">

  <!-- SOAP header starts -->
  <soapenv:Header>
    <wsse:Security xmlns:wsse="http://docs.oasis-
open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
      <wsse:UsernameToken>
        <wsse:Username>userName here</wsse:Username>
        <wsse:Password type="http://docs.oasis-open.org/wss/2004/01/oasis-
200401-wss-username-token-profile-1.0#PasswordText">password
here</wsse:Password>
      </wsse:UsernameToken>
    </wsse:Security>
    <i18n:international xmlns:i18n="http://www.w3.org/2005/09/ws-i18n">
      <i18n:locale>en</i18n:locale>
    </i18n:international>
  </soapenv:Header>
  <!-- SOAP header ends -->

  <!-- SOAP body starts -->
  <soapenv:Body>
    <!-- SOAP body contains web service request -->
  </soapenv:Body>
  <!-- SOAP body ends -->

</soapenv:Envelope>
<!-- SOAP envelope ends -->

Figure 1: SOAP request

The SOAP body contains the web service request as shown in figure 1.

Response types
Business Gateway sends the following types of responses as part of request processing:
- Normal response when the request is processed successfully. This includes the response for a Business Gateway application that has been processed manually.
- Acknowledgment response when the requested service is not available, or the application requires manual processing.
- Error response when one or more business rules failed while processing the request.
- SOAP fault response when some unexpected exception occurred while processing the request. For example, the submitted request does not contain a value in a mandatory element of the request schema corresponding to the requested service. Refer to figure 2 for the structure of this type of response.
```
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:drs="http://drsv1_0.ws.bg.lr.gov/"
xmlns:req="http://www.oscre.org/ns/eReg-
Final/2012/RequestApplicationToChangeRegisterV1_0">
          <soapenv:Fault>
          <faultcode>soapenv:SchemaFault</faultcode>
          <faultstring>Schema Errors have occured</faultstring>
          <detail>
            <drs:SchemaException>cvc-pattern-valid: Value '' is not facet-
            valid with respect to pattern '[A-Z] {0,3} [0-9] {1,6} [ZT]?' for type 
            'TitleType'.</drs:SchemaException>
              <drs:SchemaException>cvc-type.3.1.3: The value '' of element 
              'TitleNumber' is not valid.</drs:SchemaException>
          </detail>
          </soapenv:Fault>
      
```
Figure 2: SOAP fault response

Response structure

Business Gateway’s response structure has the following elements: Response type code indicates the response type in the response structure. In Business Gateway the response type code element can have one of the following values

10 (for Acknowledgement)
20 (for Rejection)
30 (for Success)

Acknowledgement

This element response type contains the following information:

Expected time when the user is supposed to send a poll request to get the response. (this is only provided if the service was not available when the application was submitted).

HMLRReference, this is HM Land Registry’s internal reference for the application (this is only provided when the service was available, but the application requires manual processing).

Unique message ID, the acknowledgment ID, which must be used to get the poll response (refer to figure 3).


<!-- SOAP envelope starts -->
<soapenv:Envolope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">

  <!-- SOAP body starts -->
  <soapenv:Body>
    <ns3:processLCBankruptcySearchRequestResponse
xmlns:ns1="http://www.oscre.org/ns/eReg-
Final/2011/RequestLandChargesBankruptcySearchV2_0"
    xmlns:ns3="http://bankruptcyv2_0.ws.bg.lr.gov/"
    xmlns:ns4="http://www.oscre.org/ns/eReg-
Final/2011/ResponseLandChargesBankruptcySearchV2_0">
      <return>
        <ns4:GatewayResponse>
          <!-- Response type code:10 i.e Acknowledgement -->
          <ns4:TypeCode>10</ns4:TypeCode>
          <ns4:Acknowledgement>
            <ns4:AcknowledgementDetails>
              <!-- Unique message ID taken from request -->
              <ns4:UniqueID>7987dff7666s001</ns4:UniqueID>
              <!-- Expected date and time for the response to be available -->
              <ns4:ExpectedResponseDateTime>
              2011-09-15T06:40:30</ns4:ExpectedResponseDateTime>
              <ns4:MessageDescription>Service is not currently
              available.System has queued your request,please poll
              at specified time.</ns4:MessageDescription>
            </ns4:AcknowledgementDetails>
          </ns4:Acknowledgement>
        </ns4:GatewayResponse>
      </return>
    </ns3:processLCBankruptcySearchRequestResponse>
  </soapenv:Body>
  <!-- SOAP body ends -->

</soapenv:Envelope>
<!-- SOAP envelope ends -->

Figure 3: SOAP acknowledgement response

Rejection

This error response type contains the business rules that have failed while processing the request (refer to figure 4).


  <!-- SOAP Envelope starts -->
  <soapenv:Envelope
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  
    <!-- SOAP Body starts>
    <soapenv:Body>
      <ns3:processLCBankruptcySearchRequestResponse
  xmlns:ns1="http://www.oscre.org/ns/eReg-
  Final/2011/RequestLandChargesBankruptcySearchV2_0"
      xmlns:ns3="http://bankruptcyv2_0.ws.bg.lr.gov/"
      xmlns:ns4="http://www.oscre.org/ns/eReg-
  Final/2011/ResponseLandChargesBankruptcySearchV2_0">
          <return>
            <ns4:GatewayResponse>
              <!-- Response type Code:20 i.e. Rejection -->
                <ns4:TypeCode>20</ns4:TypeCode>
                <ns4:Rejection>
                  <ns4:ExternalReference>
                    <ns4:Reference>Test 1.023</ns4:Reference>
                  </ns4:ExternalReference>
                  <ns4:RejectionResponse>
                    <ns4:Reason>BatchException</ns4:Reason>
                    <ns4:Code>BatchExceptionCode</ns4:Code>
                    <!-- Business Rule failed -->
                      <ns4:ValidationErrors>
                        <!-- Language independent error code -->
                          <ns4:Code>bg.fee.feeMismatch</ns4:Code>
                        <!-- Language dependent description (in this case 'EN') -->
                          <ns4:Description>:Fee Amount provided does not match with 
                          the fee calculated by Land Registry.</ns4:Description>
                      </ns4:ValidationErrors>
                  </ns4:RejectionResponse>
                </ns4:Rejection>
              </ns4:GatewayResponse>
            </return>
      </ns3:processLCBanruptcySearchRequestResponse>
    </soapenv:Body>
    <!-- SOAP Body end -->
  </soapenv:Envelope>
  <!-- SOAP Envelope ends -->

Figure 4: SOAP rejection response

Success

This normal response type contains the success result (refer to figure 5).


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

<!-- Soap Body starts -->
<soapenv:Body>
  <ns3:processLCBankruptcySearchRequestResponse
xmlns:ns1="http://www.oscre.org/ns/eReg-
Final/2011/RequestLandChargesBankruptcySearchV2_0"
  xmlns:ns3="http://bankruptcyv2_0.ws.bg.lr.gov/"
  xmlns:ns4="http://www.oscre.org/ns/eReg-
Final/2011/ResponseLandChargesBankruptcySearchV2_0">
    <return>
      <ns4:GatewayResponse>
        <!-- Response type Code:30 i.e. Success -->
        <ns4:TypeCode>30</ns4:TypeCode>
          <!-- Success Results -->
        <ns4:Results>
          <ns4:ExternalReference>
            <ns4:Reference>abc12345</ns4:Reference>
          </ns4:ExternalReference>
          <ns4:HMLRReference>
            <ns4:Reference>09395D</ns4:Reference>
          </ns4:HMLRReference>
          <ns4:ActualPrice>
            <ns4:GrossPriceAmount>2.00</ns4:GrossPriceAmount>
          </ns4:ActualPrice>
          <ns4:Attachment>
            <ns4:EmbeddedFileBinaryObject ns4:format="PDF">Large byte
array here removed for space</ns4:EmbeddedFileBinaryObject>
          </ns4:Attachment>
          <ns4:ResultTypeCode>10</ns4:ResultTypeCode>
        </ns4:Results>
      </ns4:GatewayResponse>
    </return>
  </ns3:processLCBankruptcySearchRequestResponse>
</soapenv:Body>
<!-- Soap Body ends -->
</soapenv:Envelope>
<!-- Soap Envelope ends -->

Figure 5: SOAP success response

Business Gateway service URLs

WSDL and request/response schema download links

Test Environments: