ppsr government to business (g2b) system overview · ppsr government to business (g2b) system...
TRANSCRIPT
PPSR Government to Business (G2B)
System Overview
Author: Ministry of Business, Innovation and Employment
Date: 29 May 2015
Document Version 1.5
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Contents Page 1
Contents
Author: Ministry of Business, Innovation and Employment ........................................................... 1
Date: 29 May 2015 ......................................................................................................................... 1
Document Version 1.5 .................................................................................................................... 1
Contents 1
Preface 1
Changes To This Document ............................................................................... 1
Important Client Information ......................................................................................................... 1
Version 1.5 ...................................................................................................................................... 1
Overview Of G2B For PPSR ................................................................................ 2
Personal Property Securities Register (PPSR) ................................................................................. 2
PPSR Usage ..................................................................................................................................... 2
MBIE Government To Business System .......................................................................................... 2
PPSR G2B Transaction Access ......................................................................................................... 4
Security ........................................................................................................................................... 5
Accessing The Application............................................................................................................... 5
Contact Details ................................................................................................................................ 5
PPSR Glossary ................................................................................................... 6
PPSR And XML................................................................................................... 9
Introduction .................................................................................................................................... 9
Further Information ........................................................................................................................ 9
PPSR Transaction Types .................................................................................. 10
Introduction .................................................................................................................................. 10
PPSR G2B Transaction Type Access .............................................................................................. 11
Testing Your Software ................................................................................................................... 11
PPSR G2B Client Processing ............................................................................ 17
Overview ....................................................................................................................................... 17
1. Getting DTDs ............................................................................................................................ 18
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Contents Page 2
2. Building Your XML Request File ............................................................................................... 19
4. Submitting Your XML Request File ........................................................................................... 22
5. Processing The XML Response Received ................................................................................. 24
Timeouts When Submitting Large Transactions .............................................. 26
Introduction .................................................................................................................................. 26
Further Information ...................................................................................................................... 26
Related Documents......................................................................................... 27
Introduction .................................................................................................................................. 27
Generic G2B Documents ............................................................................................................... 27
PPSR Specific G2B Documents ...................................................................................................... 28
PPSR Transaction Documents ....................................................................................................... 28
Appendix A – Changes To This Document 1
Document Changes ........................................................................................... 1
Introduction .................................................................................................................................... 1
Version 1.0 ...................................................................................................................................... 1
Version 1.1 ...................................................................................................................................... 1
Version 1.2 ...................................................................................................................................... 1
Version 1.3 ...................................................................................................................................... 2
Version 1.4 ...................................................................................................................................... 2
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Page 1
Preface
CHANGES TO THIS DOCUMENT
Important Client Information
General
All examples of the PPSR Test and Production urls have been updated.
Version 1.5
• Updated with Ministry of Business, Innovation and Employment branding.
• Support contact details updated.
This preface is used to:
• denote the latest version of this document and changes that have been made to the document since the last version was released.
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Page 2
OVERVIEW OF G2B FOR PPSR
Personal Property Securities Register (PPSR)
The PPSR is a centralised, electronic register where notice of a security interest or agreement
relating to personal property can be registered. Registration on the PPSR is one way to secure the
priority of your interest over personal property that is subject to a security interest.
More detailed information is available about PPSR at http://www.ppsr.govt.nz.
PPSR Usage
For the majority of people and businesses who wish to connect to the Personal Property Securities
Register, the web site at http://www.ppsr.govt.nz will provide an efficient method of registration
and searching. However, where clients have a high volume of transactions with PPSR, they may
choose to use a Government to Business electronic connection.
MBIE Government To Business System
The Ministry of Business, Innovation and Employment’s G2B (Government to Business) system provides an alternative means for high volume clients to access the Personal Property Securities
Register (PPSR).
General Information About The G2B System
Web browser functions often involve double keying data from the client’s database onto web
pages. The Government to Business system involves raw data being sent from the client’s
computer system directly to the MBIE G2B system in the required format. In turn, raw data
returned from the MBIE G2B system can be formatted and integrated directly into client specific
applications.
This processing occurs in real time and communications are via a secure Internet Secure Socket
Layer (SSL) session. The G2B system is not a batch processing system.
Using the G2B system requires higher levels of technical expertise to initiate and maintain than
the use of a web browser. The MBIE does not support client side G2B software or networks.
Each G2B connection is subject to an individual access agreement that specifies requirements in respect of security, certification, compliance with legislation and distribution of data. A
Connection Agreement will need to be signed before a client can establish a G2B connection. For
the latest information about the PPSR G2B system, refer to the web site at
http://www.g2b.govt.nz.
Functionality
The functionality of the Government to Business system will be similar to that provided by the
internet web access except that a client will develop their own software which will transmit XML
via HTTPS to PPSR and receive XML responses via HTTPS from PPSR.
Note: Unlike the web, the input and output are in XML format.
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Page 3
OVERVIEW OF G2B FOR PPSR, CONTD.
MBIE Government To Business System, contd.
PPSR Functions Not Supported By G2B
The G2B system largely duplicates the web site functionality, however there are some web
features which have not been included in the initial G2B service that will be offered. This means that G2B users will probably conduct their business using a mixture of a web browser and the G2B
system.
Current PPSR functions that are not supported by the G2B system include:
• Subordinations and cancellation of subordinations.
• Lodging of change demands by debtors or interested parties.
• Acceptance of change demands by secured parties.
• Maintaining secured party details.
• Establishing accounts and users.
• Transferring secured party groups.
• Loading Pending Financing Statements into PPSR.
Prerequisites For Using The Government To Business System
To use the Ministry of Business, Innovation and Employment’s Government to Business system, potential users must first comply with the following conditions:
• Be able to support HTTPS connections via SSL using digital client certificates.
• Be a registered user of the Operations Branch Customer Account Billing System (CABS).
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Page 4
OVERVIEW OF G2B FOR PPSR, CONTD.
PPSR G2B Transaction Access
The PPSR G2B application has a number of different transactions. Access to a PPSR transaction is
specified individually for each transaction.
For each transaction, the G2B client is responsible for ensuring that:
• the data passed to and from the transaction operates correctly
• search transactions retrieve the correct information
• update transactions maintain the correct information.
Once the G2B client is satisfied that their software for a particular transaction is working correctly,
they can request MBIE to grant them access to the transaction.
Note: Until access is provided for a specific transaction, any requests submitted by the client to
the G2B production system will be rejected.
Version Certification
Over time, the PPSR G2B software will be modified and new software versions created.
Consequently, new versions of each transaction will also be created. Your software is linked to a
specific version of a transaction type. When a new version of a transaction type is released, your
software will need to be updated before you can use the new version in the production environment.
When you wish to start using a new version of a transaction, access to the new version will
need to be granted (and conversely, access to the old version will need to be revoked).
Development And Testing
While clients are developing and testing their application, they will communicate with our TEST
environment.
When a G2B client is satisfied that their software is complete, they need to contact our G2B
management group to request access to each specific transaction in the production environment.
If the G2B client is updating to a newer version of a transaction already in production use by them,
then both the G2B client and MBIE will need to synchronise their systems to use the new version
of the transaction. MBIE will request a date and time when the G2B client’s modified software will
be activated within their production environment, then the MBIE G2B application will
automatically switch to this newer version of the transaction at that specified date and time.
IMPORTANT NOTE: To grant / revoke access to a particular version of a transaction in the
production system, clients use the G2B web site and manage access themselves. See the G2B Web
Site Administration document for further information.
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Page 5
OVERVIEW OF G2B FOR PPSR, CONTD.
Security
Prevention of unauthorised access to the Ministry of Business, Innovation and Employment’s
Government To Business system is an important issue and appropriate procedures must be
implemented to maintain security for the system.
External users are responsible for all security measures when accessing Ministry of Business,
Innovation and Employment computer systems. Prudent security issues to be addressed will
include, but not be limited to, the following:
• Users should not allow unauthorised access to the system.
• Users should archive or delete users who leave their organisations and change passwords immediately a user leaves.
• Users should not disclose sensitive information including logons, passwords or certificate private keys to any third parties that they may employ to assist with the setup of their
Government to Business connection, or any other day to day running of their computer
system.
• Users should immediately inform the Ministry of Business, Innovation and Employment of any suspected breaches of security.
Accessing The Application
The client site must have the expertise to support HTTPS connections via SSL using digital client
certificates.
It is envisaged that collaboration will be required between the client and our G2B management
group to establish initial communication. This should be planned beforehand so that the necessary
configuration changes at both ends can be made prior to attempting initial HTTPS SSL access.
Using the PPSR G2B system requires use of digital client certificates. The Ministry of Business,
Innovation and Employment (MBIE) is acting as their own certificate authority and issuing digital
certificates to clients. Each user will have to apply for a SSL digital client certificate from MBIE.
Each digital client certificate will be unique. MBIE will supply users with details about their digital
certificate. These digital certificate details must then be supplied by the client each time they
access the G2B system via HTTPS.
Contact Details
For further information about using the MBIE G2B system for PPSR, contact [email protected].
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Page 6
PPSR GLOSSARY
PPSR – Personal Property Securities Register
PPSA – Personal Property Securities Act 1999
Attachment A security interest ‘attaches’ when the secured
party (i.e. the creditor) has given value (e.g.
advances money), the debtor acquires an
interest in the collateral (it does not need to be
an ownership interest) and there is a written security agreement in respect of that collateral.
Attachment is not sufficient to protect the
interest of the creditor. The attached security
interest must then be ‘perfected
Collateral Personal property that is subject to the security
interest. The collateral may be physical (.g. a
motor vehicle, DVD player, or a dairy herd of
cows), or intangible (e.g. a trademark or patent),
a specific item(s) (the DVD player, or the inventory of a shop) or include the future
property of the debtor (e.g. all current and after
acquired property).
Creditor A person or organisation to whom a debt is
owed. In the PPSA and PPSR, the creditor is
always referred to as the secured party.
Debtor A borrower (and can be a person or an
organisation).
Debtor PIN The personal identification number that a debtor
or interested party is require to enter before
lodging an interested party change demand on
the register.
Default Failure to pay or fulfil an obligation; or when an
event occurs that gives the secured party the
right under the security agreement to enforce
the security.
Discharge A release of obligations. On the PPSR, the discharge of a registration means its
cancellation.
Financing Statement Change The information required to be registered to
make an amendment to any information on the
PPSR. This can be used to renew, discharge, or
subordinate a financing statement, or amend
information in the financing statement itself.
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Page 7
PPSR GLOSSARY, CONTD.
Financing Statement The information required to register notice of
a security interest on the PPSR.
Interested Party Change Demand A debtor or person with an interest in the collateral described in the financing
statement may, in certain circumstances,
give a written demand to the secured party
requiring registration of the financing change
statement.
Perfection A status of a security interest under the PPSA
that may enable a secured party to enforce
the security agreement against a third party. Can be achieved by registration of a financing
statement or possession of the collateral.
Register The PPSR.
Registered Security Interests Security interests that have been registered
in accordance with the PPSA. The maximum term of a registration is 5 years, but it can
renewed at any time before the expiry of the
term.
Secured Party A person or organisation that holds a security
interest for their own or another’s benefit
(i.e. the person or organisation generally
lending the money and holding the security
interest). Can include a trustee.
Secured Party Group A combination of one or more secured
parties. It is a secured party group, rather
than a secured party that is assigned to a
financing statement.
Security Agreement A written agreement that creates or provides for a security interest over collateral.
Security Interest An interest by one person in the collateral of
another given to secure the performance of
an obligation or payment. The collateral
does not need to be owned by the person
who is giving the security.
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Page 8
PPSR GLOSSARY, CONTD.
Transitional Period A six month period from the date the PPSA
comes into effect during which all existing
security interests will need to be registered
on the PPSR in order to retain their existing
priority date after the transitional period
ends.
Verification Statement The information that is sent to the registering
party confirming the registration of a
financing statement, and also contains the
financing statement registration number and
the debtor PIN.
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Page 9
PPSR AND XML
Introduction
The Personal Property Securities Register (PPSR) Government to Business functions use XML for
both request (input) and response (output) files.
XML (Extensible Markup Language) allows creation of customised content tags used to define
types of information.
Further Information
For further information about XML and how the MBIE G2B system uses it, see the “Using The
Ministry of Business, Innovation and Employment Government To Business Functions” document.
This document uses examples of various PPSR transactions to illustrate how the MBIE G2B system
works. It also contains other information that will be relevant to PPSR clients using the MBIE G2B
system. These topics include:
• Using Keep-Alive To Improve Response Times.
• G2B Clients Using Java.
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Page 10
PPSR TRANSACTION TYPES
Introduction
The PPSR G2B application has a number of different transaction types defined. The transaction
type indicates to MBIE which PPSR function you wish to perform. Each transaction type is
associated with a specific DTD.
As well, there are several versions of some transactions. Each individual transaction type (and
version) is described in detail in the appropriate document listed below.
Function Name Description Document file Name
B2B_REQUEST_STATUS Request the status of a
previously submitted G2B request
statusqueryver1
PPSR_REFERENCE_QUERY Query specific PPSR
reference tables
referencequeryver1
PPSR_REG_FS Register a financing
statement
registerver1, or egisterver2
PPSR_REG_PRIOR_FS*
Note: *Obsolete from
1/11/02
Load a previously
registered security into PPSR
previous_securityver1, or
previous_securityver2
PPSR_SELECT_FS Request internal details
of an existing registered
PPSR financing statement
selectver1, or selectver2
PPSR_AMEND_FS Amend a registered
financing statement
amendver1, or amendver2,
or amendver3
PPSR_RENEW_FS Renew an existing
registered PPSR financing statement
renewver1, or renewver2
PPSR_DISCHARGE_FS Discharge an existing
registered PPSR financing statement
dischargever1, or
dischargever2
PPSR_SPG_QUERY Query the contents of a
PPSR secured party
group
spgqueryver1
PPSR_SEARCH Perform PPSR search searchver1
PPSR_SEARCH_DETAILS Retrieve PPSR search
details
get_searchdetailsver1, or
get_searchdetailsver2
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Page 11
PPSR TRANSACTION TYPES, CONTD.
PPSR G2B Transaction Type Access
For each specific transaction type, the G2B client is responsible for ensuring that:
• the data passed to and from the transaction operates correctly
• search transactions retrieve the correct information
• update transactions maintain the correct information.
Once the G2B client is satisfied that their software for a particular transaction is working correctly,
they can request MBIE to grant them access to the transaction.
PPSR G2B Transaction Type Access Error
If you submit an XML request for a PPSR G2B transaction type that you do not have access to in production, you will receive an error message back from MBIE and the request submitted to the
G2B production system will be rejected.
Testing Your Software
The following information may be useful when testing your software.
The test url is https://xml.eat.g2b.govt.nz/ppsr-xml/gateway.svt
You need a digital client certificate. At present, you need to contact [email protected]
The following sample code can be used to initiate a G2B connection.
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Page 12
PPSR TRANSACTION TYPES, CONTD.
Testing Your Software, contd.
The following code is an example in perl that can be used to initiate a G2B connection. This code
requires the LWP and SSLEAY crypto perl modules.
#!/usr/local/bin/perl
# Program: b2bpost
# Description: sample program to post to ppsr b2b site
# Parameters: take one parameter of xml file name (optional)
use LWP::UserAgent; use
HTTP::Request::Common; use
strict;
$ENV{HTTPS_CERT_FILE} = "ab.crt";
$ENV{HTTPS_KEY_FILE} =
"abnopass.key";
#$ENV{HTTPS_CA_FILE} = "ppsr.ca";
my $ua = LWP::UserAgent->new;
my $filename = shift || './ppsr_reference_query1.xml';
# Submit request
my $res = $ua->request( POST https://xml.eat.g2b.govt.nz/ppsr-
xml/gateway.svt
Content_Type => 'form-data',
Content => [p_xml_file => [ $filename ]] );
# Check the outcome of the
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Page 13
response if ($res->is_success)
{
print $res-
>content; } else {
print "Bad luck this time\n";
}
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Page 14
PPSR TRANSACTION TYPES, CONTD.
Testing Your Software, contd.
Verification Statement / Confirmation Letter Emails
Introduction
The PPSR system is designed to send out verification statements and confirmation letters by email
for a number of types of PPSR transaction.
Transactions that will return a verification email include:
Creation of a secured party group.
• Register a financing statement (1 or 2 emails are sent depending on circumstances – see
below for further details).
• Amend a financing statement.
• Discharge a financing statement.
• Renew a financing statement.
• Change a financing statement PIN.
• Change a financing statement debtor PIN.
• Change the Secured Party Group password.
• Modify Secured Party Group details.
• Subordinate a financing statement.
• Un-subordinate a financing statement.
• Transfer a financing statement.
• Accept a financing statement change demand.
IMPORTANT NOTE: Some PPSR transaction types are only available via web access, i.e. they are not available using the G2B process. The table on the next page details what verification emails
are sent for each of the transaction types above and also which are available via web access only.
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Page 15
PPSR TRANSACTION TYPES, CONTD.
Testing Your Software, contd.
Verification Statement / Confirmation Letter Emails
Verification Emails for Each Transaction Type
Transaction Type Email information Sent Web
Access
Only
Creation of a secured party
group
Note: In G2B, there is no
separate transaction type
for the creation of a secured
party group. The creation
of a secured party group
could happen as part of the
transaction PPSR_REG_FS –
Register A Financing
Statement when the
request XML file contains
details of a new secured party group
Email contains a confirmation letter
containing secured party ID and password.
No verification statement is sent
No
Register a financing
statement
By default, no email is sent on registration of
the financing statement.
Two optional emails may be sent by setting
the user’s web preferences. The first email
contains a registration confirmation letter
and a verification statement with the debtor
PIN information. The second one contains
the financing statement PIN.
To receive these optional emails:
• Use the “Maintain User Web
Preferences” web function.
• Select the “Email verification for
priors” and /or “Email verification for
new registrations” as appropriate to
receive the registration confirmation and verification statement email.
• Select “Email financing statement
PIN” to receive the financing statement PIN email.
No
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Page 16
PPSR TRANSACTION TYPES, CONTD.
Testing Your Software, contd.
Verification Statement / Confirmation Letter Emails
Verification Emails for Each Transaction Type, contd.
Transaction Type Email information Sent Web
Access
Only
Amend a financing
statement
Email contains a registration confirmation
letter and a verification statement
No
Discharge a financing statement
Email contains a registration confirmation letter and a verification statement
No
Renew a financing statement
Email contains a registration confirmation letter and a verification statement
No
Change Secured Party Group password
Email contains a confirmation letter with the new password
Yes
Maintain Secured Party
Group details
Email contains a confirmation letter with the
new secured party details and a list of financing statements affected
Yes
Change a financing
statement PIN
Email contains a registration confirmation
letter and a verification statement
Yes
Change a financing
statement debtor PIN
Email contains a registration confirmation
letter and a verification statement
Yes
Subordinate a financing
statement
Email contains a registration confirmation
letter and a verification statement
Yes
Un-subordinate a financing
statement
Email contains a registration confirmation
letter and a verification statement
Yes
Transfer a financing
statement
Email contains a registration confirmation
letter and a verification statement
Yes
Accept a financing
statement change demand
Email contains a registration confirmation
letter and a verification statement
Yes
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Page 17
PPSR G2B CLIENT PROCESSING
Overview
Personal Property Security Register (PPSR) Business to Business client processing includes the
following steps. Each step is described in greater detail after this overview.
Step Action
1. Get the DTD for the PPSR transaction type you wish to use.
Note: Specific DTDs are supplied by MBIE for each type of PPSR transaction.
2. Build your XML request file using the appropriate DTD’s structure.
3. Client-Side Parsing
Parse your XML request file against its corresponding DTD. Use a document type
declaration line (<!DOCTYPE …>) to associate the XML request file to its
corresponding DTD during client-side parsing. Resolve any errors.
Note: After client-side parsing, remember to either remove or comment out the
document type declaration line from your XML request file before submitting your
transaction to MBIE.
4. Submit your XML request file to the MBIE PPSR application once it is successfully
parsed and the “Document Type Declaration” line has been removed or commented
out.
5. Process the PPSR XML response.
If Then
the XML response contained no errors • your G2B PPSR transaction has
beedn successfully processed
the XML response contained errors • identify the errors encountered
• resolve the errors
• repeat Steps 3-5
no response was received • initiate followup procedures (see “If You Do Not Receive A
Response”later in this
document).
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Page 18
PPSR G2B CLIENT PROCESSING, CONTD.
1. Getting DTDs
Each XML request and response transaction file has an associated DTD file which you need to use
for client processing.
All G2B specification documents and files and associated DTD and XML files are stored in the
Information Library on the G2B web site. This ensures that the latest version of each document
(and associated DTDs and XML files) is available to all times.
The specifications documents are stored as PDFs. The DTDs and XML files are stored as MS Word documents. If you require these in another format, e.g. PDF or zipped files, please contact
The procedure to access these files is detailed in the G2B Web Site Administration document in the “Accessing G2B Specification Documents And Associated DTD / XML Files”topic.
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Page 19
PPSR G2B CLIENT PROCESSING, CONTD.
2. Building Your XML Request File
Use the appropriate DTD to build your XML request file.
How To Enable Auditing On Your Requests
If you supply your own unique client reference for each XML request that you submit, MBIE will
attach this reference to the transaction in the G2B transaction logs.
The benefit of supplying a client reference is that you can then request information about the
Status of that specific transaction at any time, i.e. you can then audit the processing of the
transaction.
Example
You submit a “ppsr_reg_fs” transaction to MBIE to register a financing statement. However, you do not receive a XML response back. If it was a large transaction, this may have been due to a
“timeout “ occurring while the transaction was being submitted.
In this situation, you are unsure if the financing statement has been registered or not. If it has been registered, you do not want to register it again. See the “Timeouts When Submitting Large
Transactions” topic on page 23 for further information.
In this situation, you SHOULD SUBMIT a “b2b_request_status” transaction to MBIE to find the
status of the original XML request. The response will return a <request> element which has two
attributes “status” and “ status_desc”. These attributes are used to indicate the status of the original XML request. The table below contains a list of the responses you may receive.
IMPORTANT NOTE: In ANY situation where you DO NOT receive a response to your XML request,
you need submit a “b2b_request_status” transaction to check the status of the previously
submitted transaction.
status status_desc
ÄP “Processing – request awaiting parsing”
BE “Error – encountered while initialising request
file”
CE “Error – encountered extracting client details”
CS “Completed – processed successfully”
PE “Error – encountered parsing request”
PP “Processing – request parsed, currently
processing transaction”
RE “Error – encountered parsing response”
SE “Error – encountered while sending response”
TE “Error – encountered while processing
transaction”
X “No B2B request with this client_ref found in
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Page 20
log”
XE Error – encountered extracting B2B transaction
type details”
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Page 21
PPSR G2B CLIENT PROCESSING, CONTD.
2. Building Your XML Request File, contd.
How To Enable Auditing On Your Requests, contd.
Using client references is optional. However, MBIE does suggest that you do so. If you do not,
individual XML requests cannot be tracked in the G2B transaction logs and their status cannot be ascertained by a query type transaction.
IMPORTANT: If you use client references, the reference must be unique for each and every
request submitted, regardless of the PPSR transaction type. The client reference serves as the
unique ID of the transaction being submitted and it must be unique.
Example
If your first submission of a Financing Statement transaction fails, this is one transaction identified by its unique client reference. To resubmit the Financing Statement transaction, in order to track
the resubmission, you need to use a different client reference, even though the Financing
Statement content to be registered in the XML request is the same. In this way every submission is
uniquely traceable, and its status can be retrieved using its unique client reference. See the
“B2B_REQUEST_STATUS” document for further information.
It may be a good idea to institute a two-part client reference with the second part being a sequence number representing resubmissions. For example, ‘ABC_001’ would be the first
submission. If this failed and needs to be resubmitted, then the next client reference would be
‘ABC_002,’ etc.
MBIE will not validate the uniqueness of the client references used.
3. Client–Side Parsing Of Your XML Request File
Before submitting your transaction to the MBIE PPSR application, you must parse your XML request file for both “well formedness” and “structural validity”. The Document Type Declaration
line in the XML request file is used to associate the request file to its corresponding DTD during
client-side parsing.
You must resolve any parsing errors before you send your XML request file to MBIE. If you do not, MBIE will immediately return the XML request file with parsing errors and the transaction will not
be processed further.
Note: The Document Type Declaration line in the XML request file is only used by PPSR B2B during client-side parsing. After client-side parsing, remember to either remove or comment out the
document type declaration line from your XML request file before submitting your transaction to
MBIE.
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Page 22
PPSR G2B CLIENT PROCESSING, CONTD.
4. Submitting Your XML Request File
Your XML Request File should be submitted using HTTPS.
Test url
When certifying your software, ensure that you submit your requests to the following (Test) url.
https://xml.eat.g2b.govt.nz/ppsr-xml/gateway.svt
Production url
Once your software is certified, submit your requests to the following (Production) url.
https://xml.g2b.govt.nz/ppsr-xml/gateway.svt
Improving Response Times
The HTTP option “Connection: Keep-Alive” improves response times when you submit XML files.
Using this facility is optional, but MBIE recommends its use. See the “Using Keep-Alive To Improve Response Times” topic in the “Using The Ministry of Business, Innovation and Employment
Government To Business Functions” document for further information.
XML Request File Upload Procedure
Use the following procedure to upload an XML request file to the MBIE G2B application. This example uses the Test url.
Step Action
1. Establish an HTTPS session with the appropriate Test or Production MBIE G2B system
using your Digital Certificate.
2. Create an HTML form tag and set the enctype attribute to “multipart/form- data”, the action attribute to
https://xml.eat.g2b.govt.nz/ppsr-xml/gateway.svt and the method attribute to
“POST”.
3. Create an HTML INPUT element for the form above and set the type attribute to
“file” and the name attribute to “p_xml_file”.
4. Set the value property of the p_xml_file field to the location of the XML request file that you are submitting.
5. Submit your HTTPS request to MBIE
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Page 23
PPSR G2B CLIENT PROCESSING, CONTD.
4. Submitting Your XML Request File, contd.
XML Request File Upload Procedure, contd.
Sample HTML Form For Submitting XML Request File
During your development cycle you may find the simple HTML form below useful.
Load the HTML page into a web browser and it can be used to upload/submit XML request files to the MBIE G2B application.
<html>
<head>
<title>MBIE G2B Submit XML request file</title>
</head>
<body>
<H2>MBIE B2B Test</H2>
<H3>Submit XML request file</H3>
<FORM enctype="multipart/form-data"
action=https://xml.eat.g2b.govt.nz/ppsr-xml/gateway.svt method="POST">
<p>XML File to submit: <INPUT type="file" name="p_xml_file"><BR>
<p><INPUT type="submit">
</FORM>
</body>
</html>
Post Submission Processing
After your request is uploaded, the following things occur:
• The contents of the file specified within the p_xml_file field is uploaded to the MBIE G2B
application via HTTPS.
• The G2B application will process your request and on completion will return an XML file as a
response.
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Page 24
PPSR G2B CLIENT PROCESSING, CONTD.
5. Processing The XML Response Received
You need to process the XML response file you receive from the G2B application. Check the XML
response for errors, which can occur during the processing of a request. There are two forms of
error:
1. “Non-application” and “G2B initialisation” type errors, which are encountered during the
initial processing of a G2B request, e.g. a G2B client not certified for the submitted
transaction.
2. “Transaction validation” type errors, which are encountered during the processing of the transaction e.g. Invalid expiry date specified.
The <transaction> element within a response will always include a result attribute, which indicates whether the request encountered any “non-application” and/or “G2B initialisation” type
errors. If there were no errors the result attribute will be set to “S”(Successful) otherwise it will be
“E” (Error).
The “transaction validation” type errors can appear throughout the response. There is a separate document describing each G2B transaction type.
Note: The element <nonapplication_error> can only occur directly within the <transaction>
element, whereas the element <application_error> may occur throughout the response.
Possible Error Elements
There are two error type elements:
• <application_error> elements. These are errors encountered in G2B initialisation and transaction validation. An error code and a descriptive message will be returned to you
within each of these elements included in a response. An <application_error> element can
occur anywhere within the response.
• <nonapplication_error> elements. These are operating system type errors encountered during the processing of a G2B request that have no association with the validation of the
transaction itself. An error code and a descriptive message will be returned to you within
each of these elements included in a response. A <nonapplication_error> element, if
encountered, will be the first element that occurs after the <transaction> element.
Note: It is very rare to receive this type of error and if encountered you may need to seek technical assistance to resolve it.
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Page 25
PPSR G2B CLIENT PROCESSING, CONTD.
5. Processing The XML Response Received, contd.
Error Resolution
<application_error>
Correct the indicated error and resubmit the G2B request.
<nonapplication_error>
Determine if you have a communication problem connecting to MBIE. If not, email
If You Do Not Receive A Response
As long as you have used unique client references for your transactions, i.e. enabled transaction
auditing, you can submit a “b2b_request_status” transaction requesting the status of the original
XML request file.
IMPORTANT NOTE: In ANY situation where you DO NOT receive a response to your XML request,
you need submit a “b2b_request_status” transaction to check the status of the previously
submitted transaction.
This issue is particularly important for “Register A Financing Statement - PPSR_REG_FS”
transactions. For example, for large PPSR_REG_FS transactions, a “timeout “ may have occurred
while the transaction was being submitted. Ensure that you always provide a “client_ref” attribute
for the <request> element for large transactions where timeout may occur.
See the “Timeouts When Submitting Large Transactions” topic on page 23 for further information.
Submit the “b2b_request_status” XML request file as you would for any other transaction, i.e. following the process outlined above. Information about this transaction type is detailed in the
“Request Status Query (B2B_REQUEST_STATUS)” document.
Note: If you have not enabled transaction auditing, you cannot submit a “b2b_request_status” transaction as MBIE cannot uniquely identify the specific transaction in the G2B transaction log
files.
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Page 26
TIMEOUTS WHEN SUBMITTING LARGE TRANSACTIONS
Introduction
At present there is a 300 second (5 minute) timeout set on the G2B front end, i.e. the web / https
server.
For large transactions, where the submission time exceeds this limit, the G2B front end will
timeout. The G2B back end application will continue to process the transaction, but you will not
receive a response back due to the timeout.
IMPORTANT: In ANY situation where you DO NOT receive a response to your XML request, you need submit a “b2b_request_status” transaction to check the status of the previously submitted
transaction. This issue is particularly important for “Register A Financing Statement -
PPSR_REG_FS” transactions.
For large transactions, you should do this approximately 10 – 15 minutes later (depending on the size of the original submitted transaction).
Ensure that you always provide a “client_ref” attribute for the <request> element for large transactions where timeout may occur.
Further Information
For detailed information about the “b2b_request_status” transaction, see the
“B2B_REQUEST_STATUS” document.
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Page 27
RELATED DOCUMENTS
Introduction
There are a number of documents that should be read in conjunction with this document, i.e.
“PPSR Government To Business (G2B) System Overview”.
Some of the documents are “generic” for the G2B system and some are specifically related to the
PPSR application. For the PPSR application documents, they are also divided into general PPSR
information documents and PPSR transaction documents.
These documents are listed below.
Note: These documents can be requested by contacting [email protected] or accessed from the Information Library on the G2B web site (http://www.g2b.govt.nz ).
See the “Accessing G2B Specification Documents And Associated DTD / XML Files” topic in the G2B
Web site Administration document for information on how to access these files on the web site.
Generic G2B Documents
Document Name File Name
Using The Ministry of Business, Innovation
and Employment Government To Business Functions
g2boverview
G2B Web Site Administration g2bwebsiteadministration
Customer Details customerdetails
Request Status Query (B2B_REQUEST _STATUS transaction) Ver 1*
Note: Generic G2B transaction, not PPSR
specific
statusqueryver1
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Page 28
RELATED DOCUMENTS, CONTD.
PPSR Specific G2B Documents
General PPSR Information Document
Document Name File Name
Element Characteristics elementcharacteristics
Collateral Types collateraltypes
Common Verification Statement Details commonverification
Enhancements To Improve PPSR G2B
System Response Times
response_enhancements
PPSR G2B Data Validation datavalidation
PPSR Transaction Documents
Version 1 Transactions
Transaction Type Document Name File Name
B2B_REQUEST
_STATUS*
Note: Generic G2B
transaction, not just PPSR specific
Request Status Query
(B2B_REQUEST
_STATUS) Ver 1
statusqueryver1
PPSR_REFERENCE
_QUERY
(PPSR_REFERENCE_
QUERY) Ver 1
referencequeryver1
PPSR_REG_FS Register A Financing
Statement (PPSR_REG_FS)
Ver 1
registerver1
PPSR_REG_PRIOR_FS*
Note: * *Obsolete from
1/11/02
Load A Previously Registered Security Or S196
Prior Security Interest Into
PPSR (PPSR_REG_PRIOR_FS)
Ver 1
previous_securityver1
PPSR_SELECT_FS Request Internal Details Of
An Existing Registered PPSR
Financing Statement (PPSR_SELECT_FS)
Ver 1
selectver1
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Page 29
RELATED DOCUMENTS, CONTD.
PPSR Transaction Documents, contd.
Version 1 Transactions
Transaction Type Document Name File Name
PPSR_AMEND_FS Amend A Financing Statement
(PPSR_AMEND_FS) Ver 1
amendver1
PPSR_RENEW_FS Renew An Existing
Registered PPSR Financing
Statement
(PPSR_DISCHARGE_FS) Ver 1
renewver1
PPSR_DISCHARGE_FS Discharge An Existing
Registered PPSR Financing
Statement
(PPSR_DISCHARGE_FS) Ver 1
dischargever1
PPSR_SPG_QUERY Secured Party Group Query
(PPSR_SPG_QUERY) Ver 1
spgqueryver1
PPSR_SEARCH Search The PPSR
(PPSR_SEARCH) Ver 1
searchver1
PPSR_SEARCH_
DETAILS
Retrieve PPSR Search
Details (PPSR_SEARCH _DETAILS) Ver 1
get_searchdetailsver1
Version 2 Transactions
Transaction Type Document Name File Name
PPSR_AMEND_FS Amend A Financing Statement
(PPSR_AMEND_FS) Ver 2
amendver2
PPSR_SELECT_FS Request Internal Details Of
An Existing Registered PPSR
Financing Statement (PPSR_SELECT_FS)
Ver 2
aelectver2
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Page 30
RELATED DOCUMENTS, CONTD.
PPSR Transaction Documents, contd.
Version 2 Transactions, contd.
Transaction Type Document Name File Name
PPSR_REG_FS Register A Financing
Statement (PPSR_REG_FS)
Ver 2
registerver2
PPSR_REG_PRIOR_FS*
Note: * *Obsolete from
1/11/02
Load A Previously Registered Security Or S196
Prior Security Interest Into
PPSR (PPSR_REG_PRIOR_FS)
Ver 2
previous_securityver2
PPSR_RENEW_FS Renew An Existing
Registered PPSR Financing
Statement
(PPSR_DISCHARGE_FS) Ver 2
renewver2
PPSR_DISCHARGE_FS Discharge An Existing
Registered PPSR Financing
Statement
(PPSR_DISCHARGE_FS) Ver 2
dischargever2
PPSR_SEARCH_
DETAILS
Retrieve PPSR Search
Details (PPSR_SEARCH _DETAILS) Ver 2
get_searchdetailsver2
Version 3 Transactions
Transaction Type Document Name File Name
PPSR_AMEND_FS Amend A Financing Statement
(PPSR_AMEND_FS) Ver 3
amendver3
PPSR_SEARCH_
DETAILS
Retrieve PPSR Search
Details (PPSR_SEARCH _DETAILS) Ver 3
get_searchdetailsver3
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Appendix Page 1
Appendix A – Changes To This Document
DOCUMENT CHANGES
Introduction
This appendix lists changes that have occurred in each version of this document.
Version 1.0
This document contains overview and background information related specifically to the PPSR G2B system.
It replaces the “Using The PPSR Government To Business Functions, Version 3.1” document, which contained generic information about the MBIE G2B system, as well as information that related specifically to the PPSR application.
Added Information
An “Important Note” has been added the end of the “PPSR G2B Transaction Access” topic. See page 3 for further information.
Version 1.1
General
The test url has been updated to https://xml-test.g2b.govt.nz/test/b2btest/ throughout the
document.
Appendix A - Changes To This Document
This appendix has been added. It lists the changes that occurred to each version of this document.
Version 1.2
General
The previous version of the document had an incorrect test url. The test url has been corrected to
https://xml-test.g2b.govt.nz/test/b2btest/DBSB2B.SubmitRequest throughout the document.
PPSR G2B Client Processing
This topic has been updated. See “How To Enable Auditing On Your Requests” on page 17 and “If
You Do Not Receive A Response” on page 22 for further information.
Timeouts When Submitting Large Transactions
This topic has been added. See page 23 for further information.
PPSR Government To Business (G2B) System Overview Doc Ver 1.5 Appendix Page 2
Version 1.3
General
Version 3 of the “Retrieve PPSR Search Details (PPSR_SEARCH_DETAILS)” transaction has been released to Test. To account for this, the “Related Documents” topic has been updated. See page
27 for further information.
IMPORTANT NOTE: See the “Retrieve PPSR Search Details (PPSR_SEARCH_DETAILS) Ver 3” document for detailed information about this transaction.
Version 1.4
This version of the document contains information about functionality that is currently in Test for
the “Retrieve PPSR Search Details (PPSR_SEARCH_DETAILS)” Version 3 transaction and Production for all other transactions.