PPSR Government to Business (G2B) System Overview · PPSR Government To Business (G2B) System...

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.


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.


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 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.



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 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 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 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 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 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 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.



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


response if ($res->is_success)

{

print $res-

>content; } else {

print "Bad luck this time\n";

}




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.





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





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



Yes

Change a financing

statement debtor PIN



Yes

Subordinate a financing

statement



Yes

Un-subordinate a financing

statement



Yes

Transfer a financing

statement



Yes

Accept a financing

statement change demand



Yes


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 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

[email protected].

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.



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


log”

XE Error – encountered extracting B2B transaction

type details”



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.



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



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.



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.



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

[email protected]

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.


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.


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


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


PPSR_SELECT_FS Request Internal Details Of

An Existing Registered PPSR

Financing Statement (PPSR_SELECT_FS)

Ver 1

selectver1



PPSR Transaction Documents, contd.



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


Statement


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






amendver2

PPSR_SELECT_FS Request Internal Details Of

An Existing Registered PPSR

Financing Statement (PPSR_SELECT_FS)

Ver 2

aelectver2



PPSR Transaction Documents, contd.

Version 2 Transactions, contd.


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


PPSR_RENEW_FS Renew An Existing


Statement


renewver2

PPSR_DISCHARGE_FS Discharge An Existing


Statement


dischargever2

PPSR_SEARCH_

DETAILS








amendver3

PPSR_SEARCH_

DETAILS




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.

PPSR Government to Business (G2B) System Overview · PPSR Government To Business (G2B) System...

Documents

Transcript of PPSR Government to Business (G2B) System Overview · PPSR Government To Business (G2B) System...