Business Gateway Developer Guide
Information Systems Seaton Court 2 William Prance Road Plymouth Devon PL6 5WS
www.landregistry.gov.uk
Contents 1. Overview
3
1.1 Objective...............................................................................................................................3 1.2 Intended Audience................................................................................................................3
2. Organisation of the Guide 3. System Overview
3 4
3.1 Services exposed via Land Registry Business Gateway......................................................4
4. Prerequisites
5
4.1 Prerequisites for generating a Web Service Client ...............................................................5 4.2 Prerequisites for invoking Land Registry Business Gateway’s services...............................5 4.3 Development Activities .........................................................................................................6
5. Design Constraints
7
5.1 Unique message ID ..............................................................................................................7 5.2 Process request only once ...................................................................................................7
6. APIs and Schema
8
6.1 e-CSF APIs...........................................................................................................................8 6.2 Information Service APIs .....................................................................................................8 6.3 API Request and Response .................................................................................................8 6.4 BPM to Schema Mapping...................................................................................................12
7. OSCRE 8. System Generated Messages 9. Appendix
12 13 13
9.1 WSDL download links.........................................................................................................13 9.2 Upgrade and Change Policy - Vendor Summary................................................................17
Page 2
1. Overview 1.1 Objective The objective of this document is to provide comprehensive technical information about Land Registry Business Gateway for use by third party software vendors.
1.2 Intended Audience CMS vendors and conveyancers.
2. Organisation of the Guide Chapter Name 1. Overview
Chapter contents Gives an insight into the objectives and intended audience of the document.
2. Organisation of the Guide
Gives an overview of organisation of the chapters in this document.
3. System Overview
Gives a brief overview of Land Registry Business Gateway along with the services provided by the Land Registry Business Gateway.
4. Prerequisites
Contains a list of prerequisites for generating web services clients and invoking business gateway’s services.
5. Design Constraints
Gives an insight into the design constraints of the system.
6. APIs and Schema
Gives detailed information of the APIs and the XML structures for input and result parameters. N.B. the API documents are not currently available.
7. OSCRE
Gives information about the OSCRE schemas.
8. System Generated Messages
Provides information about the responses given by the system.
9. Appendix
Provides a list of URL’s for downloading the WSDL schemas and a summary of the Business Gateway Upgrade & Change policy.
Page 3
3. System Overview The Land Registry Business Gateway system allows CMS vendors to have a direct interface with Land Registry e-services. It provides a framework to streamline and improve their business proficiency. The Land Registry Business Gateway provides an electronic XML interface for interoperability between CMS and existing Land Registry services. A mutual SSL connection is established between the external system and Land Registry Business Gateway’s web services for exchange of information.
3.1 Services exposed via Land Registry Business Gateway 3.1.1 e-CSF Create Electronic Charge Standard Form (e-CSF) Create e-CSF poll request Make document effective Make document effective poll request Delete document Delete document poll request Create signatory Create signatory poll request Check document status Check document status poll request Retrieve document Retrieve document poll request
3.1.2 Information Services Official copy title known Official copy title known poll request Official search of whole with priority Official search of whole with priority roll request Enquiry by property description Enquiry by property description poll request Bankruptcy search Bankruptcy search poll request
Page 4
4. Prerequisites 4.1 Prerequisites for generating a Web Service Client A valid certificate is required for downloading the WSDL and schema files from Land Registry Business Gateway. This certificate is used for mutual SSL handshake. A list of URLs for all services provided by Land Registry Business Gateway, to download the respective WSDL and schema files for a given service.
4.2 Prerequisites for invoking Land Registry Business Gateway’s services A valid digital certificate issued by Land Registry 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 Land Registry Business Gateway in order to invoke the required services. An active user account to use Land Registry Business Gateway. The user ID and the password is the same as for Land Registry’s Portal. An active Variable Direct Debit (VDD). The request should conform to the request schema. The request must contain user credentials and locale information as part of the SOAP header. A unique message ID generation mechanism should be followed for every request being sent to Land Registry 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 Land Registry 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 the Land Registry Business Gateway. The external system is required to generate a unique identifier for every request that has been sent to the Land Registry Business Gateway. This message ID is used to receive a response from the Land Registry 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. The Land Registry Business Gateway uses the following information for determining whether a given request is a new request. 1. Message ID 2. Service Type (for example bankruptcy search) 3. User ID If the system determines that the given request is not new then the system will try to find the existing response and return it without processing the request again. Page 5
4.3 Development Activities Install digital certificates issued by Land Registry as trusted root. Install client digital certificates issued by Land Registry into client key store. Develop a mechanism to generate and store unique message IDs with respect to the request sent to Land Registry Business Gateway. Develop a mechanism to prompt the user for their Land Registry user ID and password. Consume the WSDL offered by Land Registry Business Gateway and develop the following functionality based on the web services exposed: - Develop a mechanism to send requests to Land Registry Business Gateway for each web service that has been exposed. - Develop a mechanism to send polling requests for the cases where the response is not available synchronously. - 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.
Page 6
5. Design Constraints Web service requests over http/https Internet protocols are not reliable and lead to lost messages between request and response. Hence, a reliable messaging mechanism is implemented in Land Registry Business Gateway to ensure that the responses are not lost between the client CMS software and Land Registry Business Gateway. The constraints implemented to ensure reliable messaging are as follows: Unique message ID Process request only once.
5.1 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 same message ID once again. The client ensures that all message requests have a unique message ID. It is the responsibility of the Land Registry Business Gateway to correlate the SOAP request and response with the same message ID.
5.2 Process request only once Land Registry 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 and from the same user ID then the response is sent from the stored data.
Page 7
6. APIs and Schema 6.1 e-CSF APIs
Create e-CSF Make document effective Delete document Retrieve document Create signatory Check document status
6.2 Information Service APIs
Official copy title known Official search of whole with priority Enquiry by property description Bankruptcy search
6.3 API Request and Response 6.3.1 Request Type Normal Request A request is considered to be a Normal Request when it is sent to Land Registry Business Gateway during working hours and when the day list is open. The original request is stored by Land Registry Business Gateway along with the response. Poll Request A request is considered to be a Poll Request when it arrives with a unique message ID to retrieve the stored response. For example, when a request is sent to Land Registry 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 request to Land Registry Business Gateway at the suggested date and time, with the unique message ID of the original message, to retrieve the stored response.
6.3.2 Request Structure Land Registry Business Gateway’s SOAP request consists of the following elements: SOAP Header must contain (Refer Figure 1) User ID Password Locale information SOAP Body contains the Web Service Request as shown in Figure 1.
Page 8
Figure 1
6.3.3 Response Types The Land Registry Business Gateway sends the following types of responses as part of request processing. Normal response when the request is processed successfully. Acknowledgment response when the requested service in not available. 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. 6.3.4 Response Structure Land Registry Business Gateway’s response structure has the following elements: Response type code indicates the element being populated in response structure. In Land Registry Business Gateway, this element can have one of the following values: - 10 (for Acknowledgement) - 20 (for Rejection) - 30 (for Success). Acknowledgement This element contains the following information: - Expected time when user is supposed to send poll request to get the response. - Unique message ID, the acknowledgment ID, which must be used to get the poll response (Refer Figure 2).
Page 9
Rejection This element contains the business rules that have failed while processing the request. (Refer Figure 3). Success This element contains success result. (Refer to Figure 4).
Figure 2
Page 10
Figure 3
Page 11
Figure 4
6.4 BPM to Schema Mapping The purpose of this document is to provide a high level overview of the services offered by the Business Gateway. It maps the inputs and outputs of each service to a set of associated PISCES schemas. The document also contains an overview of the process of creating and updating an e-CSF using the Business Gateway services. It can be found from the link on the Business Gateway webpage.
7. OSCRE In November 2009, OSCRE (Open Standards Consortium For Real Estate) was formed by the merger of PISCES (Property Information Systems Common Exchange Standard) Limited and OSCRE Americas. OSCRE is a not-for-profit global consortium maximising value in the real estate industry through open interoperability among real estate information systems. Working closely with Land Registry since October 2008, PISCES has produced eregistration standard now being used in Land Registry Business Gateway to interact with the conveyancers’ CMS. The schemas are available directly from the OSCRE website by using the links on the Developer Pack webpage. Page 12
8. System Generated Messages A list of error and success messages given by Land Registry Business Gateway is detailed in the System Generated Messages document that can be accessed using the link on the Developer Pack webpage.
9. Appendix 9.1 WSDL download links In the URLs listed below, substitute {LR_URL_PLACE_HOLDER} as follows: For testing bgtest.landregistry.gov.uk/b2b/BGStubService For production businessgateway.landregistry.gov.uk/b2b/BGSoapEngine
9.1.1 Create e-CSF https://{LR_URL_PLACE_HOLDER}/CreateEcsfWebService?wsdl https://{LR_URL_PLACE_HOLDER}/CreateEcsfWebService/WEBINF/wsdl/CreateEcsf.xsd https://{LR_URL_PLACE_HOLDER}/CreateEcsfWebService/WEBINF/wsdl/CreateEcsfResponse.xsd
9.1.2 Create e-CSF Poll Request https://{LR_URL_PLACE_HOLDER}/CreateECSFPollRequestWebService?wsdl https://{LR_URL_PLACE_HOLDER}/CreateECSFPollRequestWebService/WEBINF/wsdl/PollRequest.xsd https://{LR_URL_PLACE_HOLDER}/CreateECSFPollRequestWebService/WEBINF/wsdl/CreateEcsfResponse.xsd
9.1.3 Make Document Effective https://{LR_URL_PLACE_HOLDER}/MakeDocumentEffectiveWebService?wsdl https://{LR_URL_PLACE_HOLDER}/MakeDocumentEffectiveWebService/WEBINF/wsdl/MakeDocumentEffective.xsd https://{LR_URL_PLACE_HOLDER}/MakeDocumentEffectiveWebService/WEBINF/wsdl/MakeDocumentEffectiveResponse.xsd
Page 13
9.1.4 Make Document Effective Poll Request https://{LR_URL_PLACE_HOLDER}/MakeDocumentEffectivePollRequestWebServi ce?wsdl https://{LR_URL_PLACE_HOLDER}/MakeDocumentEffectivePollRequestWebServi ce/WEB-INF/wsdl/PollRequest.xsd https://{LR_URL_PLACE_HOLDER}/MakeDocumentEffectivePollRequestWebServi ce/WEB-INF/wsdl/MakeDocumentEffectiveResponse.xsd
9.1.5 Delete Document https://{LR_URL_PLACE_HOLDER}/DeleteDocumentWebService?wsdl https://{LR_URL_PLACE_HOLDER}/DeleteDocumentWebService/WEBINF/wsdl/DeleteDocument.xsd https://{LR_URL_PLACE_HOLDER}/DeleteDocumentWebService/WEBINF/wsdl/DeleteDocumentResponse.xsd
9.1.6 Delete Document Poll Request https://{LR_URL_PLACE_HOLDER}/DeleteDocumentPollRequestWebService?wsdl https://{LR_URL_PLACE_HOLDER}/DeleteDocumentPollRequestWebService/WEB -INF/wsdl/PollRequest.xsd https://{LR_URL_PLACE_HOLDER}/DeleteDocumentPollRequestWebService/WEB -INF/wsdl/DeleteDocumentResponse.xsd
9.1.7 Create Signatory https://{LR_URL_PLACE_HOLDER}/CreateSignatoryWebService?wsdl https://{LR_URL_PLACE_HOLDER}/CreateSignatoryWebService/WEBINF/wsdl/CreateSignatoryForEcsf.xsd https://{LR_URL_PLACE_HOLDER}/CreateSignatoryWebService/WEBINF/wsdl/CreateSignatoryForEcsfResponse.xsd
9.1.8 Create Signatory Poll Request https://{LR_URL_PLACE_HOLDER}/CreateSignatoryPollRequestWebService?wsdl https://{LR_URL_PLACE_HOLDER}/CreateSignatoryPollRequestWebService/WEB -INF/wsdl/PollRequest.xsd https://{LR_URL_PLACE_HOLDER}/CreateSignatoryPollRequestWebService/WEB -INF/wsdl/CreateSignatoryForEcsfResponse.xsd
9.1.9 Check Document Status https://{LR_URL_PLACE_HOLDER}/CheckDocumentStatusWebService?wsdl https://{LR_URL_PLACE_HOLDER}/CheckDocumentStatusWebService/WEBINF/wsdl/CheckDocumentStatus.xsd Page 14
https://{LR_URL_PLACE_HOLDER}/CheckDocumentStatusWebService/WEBINF/wsdl/CheckDocumentStatusResponse.xsd
9.1.10 Check Document Status Poll Request https://{LR_URL_PLACE_HOLDER}/CheckDocumentStatusPollRequestWebServic e?wsdl https://{LR_URL_PLACE_HOLDER}/CheckDocumentStatusPollRequestWebServic e/WEB-INF/wsdl/PollRequest.xsd https://{LR_URL_PLACE_HOLDER}/CheckDocumentStatusPollRequestWebServic e/WEB-INF/wsdl/CheckDocumentStatusResponse.xsd
9.1.11 Official Copy Title Known https://{LR_URL_PLACE_HOLDER}/OfficialCopyTitleKnownWebService?wsdl https://{LR_URL_PLACE_HOLDER}/OfficialCopyTitleKnownWebService/WEBINF/wsdl/RequestTitleKnownOfficialCopy.xsd https://{LR_URL_PLACE_HOLDER}/OfficialCopyTitleKnownWebService/WEBINF/wsdl/TitleKnownOCResponse.xsd
9.1.12 Official Copy Title Known Poll Request https://{LR_URL_PLACE_HOLDER}/OC1TitleKnownPollRequestWebService?wsdl https://{LR_URL_PLACE_HOLDER}/OC1TitleKnownPollRequestWebService/WEBINF/wsdl/PollRequest.xsd https://{LR_URL_PLACE_HOLDER}/OC1TitleKnownPollRequestWebService/WEBINF/wsdl/TitleKnownOCResponse.xsd
9.1.13 Official Search of whole with Priority https://{LR_URL_PLACE_HOLDER}/OfficialSearchWebService?wsdl https://{LR_URL_PLACE_HOLDER}/OfficialSearchWebService/WEBINF/wsdl/RequestOfficialSearchOfWholeWithPriority.xsd https://{LR_URL_PLACE_HOLDER}/OfficialSearchWebService/WEBINF/wsdl/OfficialSearchResponse.xsd
9.1.14 Official Search of whole with Priority Poll Request https://{LR_URL_PLACE_HOLDER}/OfficialSearchPollRequestWebService?wsdl https://{LR_URL_PLACE_HOLDER}/OfficialSearchPollRequestWebService/WEBINF/wsdl/PollRequest.xsd https://{LR_URL_PLACE_HOLDER}/OfficialSearchPollRequestWebService/WEBINF/wsdl/OfficialSearchResponse.xsd
Page 15
9.1.15 Retrieve Document https://{LR_URL_PLACE_HOLDER}/RetrieveDocumentWebService?wsdl https://{LR_URL_PLACE_HOLDER}/RetrieveDocumentWebService/WEBINF/wsdl/RetrieveDocument.xsd https://{LR_URL_PLACE_HOLDER}/RetrieveDocumentWebService/WEBINF/wsdl/RetrieveDocumentResponse.xsd
9.1.16 Retrieve Document Poll Request https://{LR_URL_PLACE_HOLDER}/RetrieveDocumentPollRequestWebService?ws dl https://{LR_URL_PLACE_HOLDER}/RetrieveDocumentPollRequestWebService/W EB-INF/wsdl/PollRequest.xsd https://{LR_URL_PLACE_HOLDER}/RetrieveDocumentPollRequestWebService/W EB-INF/wsdl/RetrieveDocumentResponse.xsd
9.1.17 Enquiry by property description https://{LR_URL_PLACE_HOLDER}/EnquiryByPropertyDescriptionWebService?ws dl https://{LR_URL_PLACE_HOLDER}/EnquiryByPropertyDescriptionWebService/WE B-INF/wsdl/SearchByPropertyDescription.xsd https://{LR_URL_PLACE_HOLDER}/EnquiryByPropertyDescriptionWebService/WE B-INF/wsdl/SearchByPropertyResponse.xsd
9.1.18 Enquiry by Property Description Poll Request https://{LR_URL_PLACE_HOLDER}/EnquiryByPropertyDescriptionPollWebService ?wsdl https://{LR_URL_PLACE_HOLDER}/EnquiryByPropertyDescriptionPollWebService/ WEB-INF/wsdl/PollRequest.xsd https://{LR_URL_PLACE_HOLDER}/EnquiryByPropertyDescriptionPollWebService/ WEB-INF/wsdl/SearchByPropertyResponse.xsd
9.1.19 Bankruptcy Search https://{LR_URL_PLACE_HOLDER}/BankruptcySearchWebService?wsdl https://{LR_URL_PLACE_HOLDER}/BankruptcySearchWebService/WEBINF/wsdl/RequestLandChargesBankruptcySearch.xsd https://{LR_URL_PLACE_HOLDER}/BankruptcySearchWebService/WEBINF/wsdl/BankruptcySearchResponse.xsd
9.1.20 Bankruptcy Search Poll Request https://{LR_URL_PLACE_HOLDER}/BankruptcySearchPollRequestWebService?ws dl Page 16
https://{LR_URL_PLACE_HOLDER}/BankruptcySearchPollRequestWebService/WE B-INF/wsdl/PollRequest.xsd https://{LR_URL_PLACE_HOLDER}/BankruptcySearchPollRequestWebService/WE B-INF/wsdl/BankruptcySearchResponse.xsd
9.1.21 Register Extract Service https://{LR_URL_PLACE_HOLDER}/OfficialCopyWithSummaryWebService?wsdl https://{LR_URL_PLACE_HOLDER}/OfficialCopyWithSummaryWebService/WEBINF/wsdl/RequestOCWithSummary.xsd https://{LR_URL_PLACE_HOLDER}/OfficialCopyWithSummaryWebService/WEBINF/wsdl/OCWithSummaryResponse.xsd
9.1.22 Register Extract Service Poll Request https://{LR_URL_PLACE_HOLDER}/OfficialCopyWithSummaryPollRequestWebSer vice?wsdl https://{LR_URL_PLACE_HOLDER}/OfficialCopyWithSummaryPollRequestWebSer vice/WEB-INF/wsdl/PollRequest.xsd https://{LR_URL_PLACE_HOLDER}/OfficialCopyWithSummaryPollRequestWebSer vice/WEB-INF/wsdl/OCWithSummaryResponse.xsd
9.2 Upgrade and Change Policy - Vendor Summary The general policy for upgrading and changing the Business Gateway is to introduce new web services and deprecate existing web services gracefully wherever possible; this should avoid the need for all applications to perform a hard cutover. Land Registry plan to have two scheduled releases per year. Only where there is a major bug making a web service inoperable, will a web service be replaced with immediate effect.
9.2.1 New web service Notification of the functionality and delivery schedule of a new web service will be through standard Marketing and Sales channels, combined with the new forum created for users of Business Gateway. All technical details will be published in the Business Gateway Developer Pack The OSCRE E-Registration Standard schemas will be kept in line with the WSDL schemas. A vendor test facility will go live at the same time as the web service itself. A new name will be created for an extension of an existing web service.
9.2.2 Web service deprecation Notification of the schedule for deprecation will come from Marketing and Sales, and the Business Gateway Forum. Page 17
The normal ‘sun setting period’ from the date of notification will be six months, but may vary in exceptional circumstances. All users of a service will receive a final reminder one month before the service is discontinued. A history table containing notification will be available in the Pack.
9.2.3 Emergency bug fix (minor version of the web service) Notification of an emergency bug fix will be through the Service Desk. The PISCES E-Registration Standard schemas will be kept in line with the WSDL schemas, possibly retrospectively depending on the urgency. A new version number will be incorporated into an existing web service name that is being replaced, for example Version 1.0 will become Version 1.1. In this emergency example, Version 1.0 will be withdrawn as soon as Version 1.1 becomes live. A new version of the vendor test facility will go live at the same time as the web service itself. Integrated vendors will be notified if and/or when they can test the change before it is put live.
9.2.4 Scheduled upgrade (major version of the web service) Notification of the changes being made in a new version of an existing web service will be from Marketing and Sales, and the Forum. The new version will run simultaneously with the old until the end-of-life date, to avoid the need for all applications to perform a hard cutover. The PISCES E-Registration Standard schemas will be kept in line with the WSDL schemas. A new version number will be incorporated into an existing web service name that is being replaced, for example Version 1.0 (or 1.1) will become Version 2.0. A new version of the vendor test facility (stub) will go live at the same time as the new version of the web service. Change details and release notes will be available in the Pack.
Page 18