NZ B2B Guide

Connectivity Guide
VedaXML V2

NZ B2B Guide Connectivity Guide

VedaXML V2

Need additional information?

Web:

www.veda.co.nz

Email:

assistonline.nz@veda.co.nz

Phone:

0800 653 309

Address:

Veda Advantage (NZ) Ltd, PO Box 912012,

Victoria Street West,
Auckland 1142,
New Zealand

Connectivity Guide VedaXML V2

Document Version Number: 1.07
Issue Date: 3 August 2011

Copyright Notice
3 August 2011 Veda Advantage (NZ) Limited
This document is the intellectual property of Veda Advantage (NZ) Limited. The information contained in this document is
confidential and may not be stored, copied, given, lent or in any way transmitted to any other company or person without
the express written consent of Veda Advantage (NZ) Limited.

Revision Control
Product
Version

Document
Version

Date

Description

Author

V2

1.07

22/08/2011

Rebrand from Veda Advantage to Veda

Esm Jack

______
Page 2
Copyright @ 3 August 2011 Veda Advantage (NZ) Limited

NZ B2B Guide Connectivity Guide

VedaXML V2

Contents
Introduction ..................................................................................................................................................................4
Assumptions .............................................................................................................................................................4
Conventions ..............................................................................................................................................................4
Getting Started .........................................................................................................................................................4
Future Enhancements ..............................................................................................................................................5
Connecting to VedaXML ...............................................................................................................................................6
Route ........................................................................................................................................................................6
Security .....................................................................................................................................................................6
Testing the Connection.............................................................................................................................................7
Messaging with VedaXML.............................................................................................................................................8
Building Requests .......................................................................................................................................................10
The Prologue...........................................................................................................................................................10
The Request Envelope ............................................................................................................................................10
The Request Element..............................................................................................................................................12
Identification Details...........................................................................................................................................14
Product ...............................................................................................................................................................14
The Data Elements..................................................................................................................................................14
Testing Requests .....................................................................................................................................................14
Processing Responses .................................................................................................................................................15
The Response Envelope ..........................................................................................................................................15
Normal Product Response ......................................................................................................................................16
Product Error ..........................................................................................................................................................16
VedaXML Error........................................................................................................................................................16
______
Page 3
Copyright @ 3 August 2011 Veda Advantage (NZ) Limited

NZ B2B Guide Connectivity Guide

VedaXML V2

Introduction
This manual discusses the procedures for implementing the Veda business-to-business (B2B) system VedaXML. It covers the
following topics:

Connecting with the VedaXML system.

Writing requests.

Handling responses.

Individual products are discussed in the VedaXML Product Guides.

Veda supplies:
Separate identification, access codes and passwords for testing and production.

VedaXML schemas.

Test and production URLs.

VedaXML Product Guides.

Assumptions
This document assumes the following:

That your organisation is a Veda subscriber.

You have reasonable knowledge of XML schemas and their use.

A good understanding of internet protocols.

Appropriate programming techniques for extracting data from and importing responses into your own system.

Conventions
The following conventions are used in this document:

XML elements appear in a monospace bold font.

XML attributes are identified by placing the attribute name in braces (e.g. {code}). Where necessary, the attribute is
further identified by including its element (e.g. street-type{code}).

Getting Started
The following steps broadly describe the procedures for working with the VedaXML System:

Extract data from your system and build a request.

Validate the request by parsing it through the schema for that product.

Put it in a data envelope, together with the correct authentication information.

______
Page 4
Copyright @ 3 August 2011 Veda Advantage (NZ) Limited

NZ B2B Guide Connectivity Guide

VedaXML V2

Send it to the URL supplied by Veda.

Extract the response from the body of the reply.

Parse and extract the necessary data from the response.

Future Enhancements
The VedaXML system is progressively evolving; your programming strategy should be prepared for changes to your
implementation. Proposed enhancements to the VedaXML System are:

Further products more VedaXML products will be progressively introduced.

Use of XML namespaces as the number of VedaXML products increases, and other XML-based documents become
more numerous, XML namespaces will prevent clashes between identical element names in different documents.
This will result in changes to the schemas.

SOAP-compliant envelope SOAP is an XML-based protocol for exchanging information in a decentralised,

distributed environment. It comprises: an envelope that defines a framework for describing what is in a message
and how to process it, a set of encoding rules for expressing instances of application-defined data types, and a
convention for representing remote procedure calls and responses.

______
Page 5
Copyright @ 3 August 2011 Veda Advantage (NZ) Limited

NZ B2B Guide Connectivity Guide

VedaXML V2

Connecting to VedaXML
This chapter discusses the procedures for setting up your connection to the VedaXML system.

Route
VedaXML access is most commonly conducted over the Internet, shown simply in Figure 1. VedaXML utilises SSL 3.0 over
HTTP 1.1.
Figure 1

VedaXML Routing

Your
Server

B2Bay
Server
SSL Layer
Authentication Layer
HTTP Layer

IDC

Security
All transactions are handled in a secure environment, using standard Internet authentication and encryption methods. These
include HTTP credentials checks (as per HTTP 1.1) and registration of certificates in the application key store.
When programming the method to establish an SSL connection for the transport of VedaXML messages, note that the digital
certificates held by Veda will update from time to time. Ideally the connection method retrieves the public key automatically
thereby obtaining new public keys whenever they occur. However if the manual retrieval of the public certificate is part of
the system design (as is sometimes the case with Java development) then note that this process will be required whenever
certificates get updated.
Veda identification codes and passwords ensure that operators can access only those products for which they are authorised.

Under the terms of privacy legislation, access to consumer credit files is strictly
regulated, and severe penalties exist for breach of privacy. If you have any concerns
about using these files, please contact your Veda representative.
Important!

______
Page 6
Copyright @ 3 August 2011 Veda Advantage (NZ) Limited

NZ B2B Guide Connectivity Guide

VedaXML V2

Testing the Connection

To ensure that you have established a correct connection to the VedaXML IP address, post a ping document, as shown in
Figure 2. The asterisks represent codes supplied by Veda.
Figure 2

A Ping Request
<BCAmessage type="REQUEST">
<BCAaccess>
<BCAaccess-code>********</BCAaccess-code>
<BCAaccess-pwd>********</BCAaccess-pwd>
</BCAaccess>
<BCAservice>
<BCAservice-code>PING</BCAservice-code>
<BCAservice-code-version>V00</BCAservice-code-version>
<BCAservice-client-ref>123456789</BCAservice-client-ref>
<BCAservice-data>
</BCAservice-data>
</BCAservice>
</BCAmessage>

If your system is correctly connected to the VedaXML system, you should receive the response shown in Figure 3.
Figure 3

A Ping Response
<BCAmessage type="RESPONSE" service-request-id="00000000056">
<BCAservices>
<BCAservice>
<BCAservice-code>PING</BCAservice-code>
<BCAservice-code-version>V00</BCAservice-code-version>
<BCAservice-client-ref>123456789</BCAservice-client-ref>
<BCAservice-data>
</BCAservice-data>
</BCAservice>
</BCAservices>
</BCAmessage>

______
Page 7
Copyright @ 3 August 2011 Veda Advantage (NZ) Limited

NZ B2B Guide Connectivity Guide

VedaXML V2

Messaging with VedaXML

This chapter discusses the procedures for sending your requests to, and receiving your responses from, Veda. Figure 4 shows
the basic transmission model.
Figure 4

The Transmission Model

Client
System

B2Bay
Server

HTTPS
POST
Receive

Wait

Process

Respond
Read
Response
To ensure Veda maintains a high level of service to all subscribers, please limit your concurrent sessions to three.
If you wish to use VedaXML for batch-style, high-volume use, please contact your Veda representative.
Figure 5 shows sample Java code for transmitting your envelope to Veda. The HTTPS posting protocol is used. Note that the
code assumes that the public key has already been retrieved from the VedaXML URL.
Each product has a specific time out, ranging from 1 minute to 10 minutes; contact your Veda representative for details. The
web server time out is set to 12 minutes.

______
Page 8
Copyright @ 3 August 2011 Veda Advantage (NZ) Limited

NZ B2B Guide Connectivity Guide

VedaXML V2

Figure 5

Sample Java Connection Code

URL url = new URL( "https://services.vedaadvantage.com.au/VedaXML" );
Reader requestReader = new FileReader( "request.xml" );
Writer responseWriter = new FileWriter( "response.xml" );
// configure local proxy settings
String proxyAddress="proxyName";
int proxyPort = 8080;
System.setProperty( "https.proxyHost", proxyAddress );
System.setProperty( "https.proxyPort", proxyPort );
// configure local keystore properties
// note: Java version 1.4 has JSSE included
// note: use Java 'keytool' tool to manage the keystore
System.setProperty( "javax.net.ssl.trustStore", ".keystore" );
// set an Authenticator to generate username/password
Authenticator auth = new Authenticator() {
protected PasswordAuthentication getPasswordAuthentication()
{
String username = "username";
String password = "password";
return new PasswordAuthentication( username, password.toCharArray() );
}
};
Authenticator.setDefault( auth );
// prepare and open an HTTP connection
HttpURLConnection connection
= (HttpURLConnection) url.openConnection();
connection.setRequestMethod( "POST" );
connection.setDoOutput( true );
connection.setRequestProperty( "Content-Type", "text/xml" );
connection.connect();
// POST the request
Writer connWriter
= new OutputStreamWriter(
connection.getOutputStream() );
while ( (c = requestReader.read()) != -1 )
connWriter.write( c );
connWriter.flush();
connection.getOutputStream().close();
// get the response
java.lang.Object response = connection.getContent();
Reader connReader
= new InputStreamReader(
(InputStream) response );
while ( (c = connReader.read()) != -1 )
responseWriter.write( c );
responseWriter.flush();

______
Page 9
Copyright @ 3 August 2011 Veda Advantage (NZ) Limited

NZ B2B Guide Connectivity Guide

VedaXML V2

Building Requests
This chapter describes the procedures for building a request. Each request is written as a standard XML tagged document.
XML elements are logically grouped into parent elements. Parent elements may contain other parent elements.
For a request to be successfully processed, it must pass the validation process:

First, the schema for the request parses the tagged text. This process ensures that the request contains all the
required elements, and carries out some preliminary content validation. However, be aware that the schema cannot
completely validate your request.

After receiving a request, Veda validates the input before processing. If any information is found to be invalid, then
the request is rejected.

Therefore, to prevent the system rejecting your requests, you must be aware of Vedas validation requirements. These
requirements are given in each element description in the VedaXML Product Guides.

The Prologue
Requests begin with a two-line prologue. The first line is mandatory and identifies that the request is an XML document.
Requests are set to XML version 1 and the encoding method of choice, for example:
<?xml version="1.0" encoding="UTF-8"?>
Encoding options are:

Windows-1252 or ISO-8859-1 that allow the XML to be viewed using Internet Explorer 5.

UTF-8 or UTF-16 that do not allow the XML to be viewed using Internet Explorer 5.

The second prologue line, the DOCTYPE declaration, is optional. You may want to include this line for internal reference to
schema files.

The Request Envelope

Your request is placed in a request envelope. Figure 6 shows the hierarchy of the Request Envelope elements.

______
Page 10
Copyright @ 3 August 2011 Veda Advantage (NZ) Limited

NZ B2B Guide Connectivity Guide

VedaXML V2

Figure 6

Request Envelope Element Hierarchy

BCAmessage
{type}

BCAaccess

BCAaccess-code

BCAaccess-pwd

BCAservice

BCAservice-code

BCAservice-code-version

BCAservice-client-ref

BCAservice-data

(All request elements)

BCAmessage{type} describes the type of message being transmitted, in this case a request.
BCAaccess contains VedaXML access code and password information.
BCAservice contains further access and client identification data, and the request itself.

BCAservice-code identifies the VedaXML service you are using.

BCAservice-code-version specifies the version of the VedaXML service.

BCAservice-client-ref is an optional element that you can use to identify the request. In the example below, a simple
number has been included.

Error! Reference source not found. lists the BCAservice-codes and versions currently available.
Service Code

Version

Description

BCA001

V00

Business Information Services Australia.

BCA003

V00

Business Information Services Australia (Scoring

Products).

BCA011

V00

Business Information Services New Zealand.

PING

V00

Ping Service.

VSS001

V00

The Verification Suite Service (VSS).

DUMMY

V00

Dummy Service.

The following example shows a standard request envelope (note that the asterisks represent codes supplied by Veda):

______
Page 11
Copyright @ 3 August 2011 Veda Advantage (NZ) Limited

NZ B2B Guide Connectivity Guide

VedaXML V2

<?xml version="1.0" encoding="UTF-8"?>

<BCAmessage type="REQUEST">
<BCAaccess>
<BCAaccess-code>********</BCAaccess-code>
<BCAaccess-pwd>********</BCAaccess-pwd>
</BCAaccess>
<BCAservice>
<BCAservice-code>BCA001</BCAservice-code>
<BCAservice-code-version>V00</BCAservice-code-version>
<BCAservice-client-ref>123456789</BCAservice-client-ref>
<BCAservice-data>
<request version="1.0" mode='test' transactionreference='AX5841000'>
.
. [all request data]
.
</request>
</BCAservice-data>
</BCAservice>
</BCAmessage>

The Request Element

The request element contains all the information transmitted to Veda. It consists of:

Subscriber details.

The Veda product requested.

One or more elements containing data specific to the request.

The structure of a request differs slightly between New Zealand and Australian products. Figure 7 shows an example of a
New Zealand request and Figure 8 shows an example of an Australian request.

______
Page 12
Copyright @ 3 August 2011 Veda Advantage (NZ) Limited

NZ B2B Guide Connectivity Guide

VedaXML V2

Figure 7

New Zealand Request

<request version=2.0 mode=test transaction-reference=2002-06-02:1355>
<client-details>
<client-identifier>******</client-identifier>
<password>******</password>
</client-details>
<product name=consumer-enquiry-nz/>
<individual>
.
.
</individual>
<enquiry>
.
.
</enquiry>
</request>

Figure 8

Australian Request
<request version=1.0 mode=test transaction-reference=2002-06-02:1355>
<subscriber-details>
<subscriber-identifier>********</subscriber-identifier>
<security>**</security>
</subscriber-details>
<product name=consumer-enquiry/>
<individual>
.
.
</individual>
<enquiry>
.
.
</enquiry>
</request>

The request element has three attributes:

{version} is a fixed attribute that specifies the version of the schema in use.

{mode} is a required attribute that specifies whether you wish to access the Test or Production database.

{transaction-reference} is an optional attribute that you can use to identify the request. In the example above, a
simple date-time stamp has been included.

______
Page 13
Copyright @ 3 August 2011 Veda Advantage (NZ) Limited

NZ B2B Guide Connectivity Guide

VedaXML V2

Identification Details
client-details (NZ) and subscriber-details (AUS) identify your organisations access, and groups or individuals within your
organisation, to Veda. It contains the following elements:

client-identifier/subscriber-identifier is a specific code for your organisation.

password/security is a security code for your organisation.

Veda supplies all codes and passwords.

Product
Some schemas supplied by Veda are designed to accommodate a range of related products; that is, products that rely on
similar or identical information in the request.
Set product{name} to specify the product you want. The available products are always listed in the schema.

The Data Elements

The data elements consist of one or more elements for the information needed by the product requested. These elements
are listed in the request element in the schema. For example, an Individual Enquiry request requires two such elements,
individual or bureau-reference and enquiry.
Lower-level elements may be mandatory or optional. Wherever possible, mandatory and optional elements are flagged in
the schema.
Some elements are required for some products but not for others. How you use these elements is described in the chapters
on specific products and the element descriptions in the VedaXML Product Programming Guides.
If you enter data elements that are not required by a particular product, either these elements are ignored or your request is
rejected. Rejection often occurs when that input could violate rules set down in privacy act legislation.

Testing Requests
Your request should be thoroughly tested before being used in a production environment. Veda has a database set up
exclusively for testing. Use of this database is free of charge.
To use the test database:

Set request{mode} to test.

Set client-identifier/subscriber-identifier to a test code provided by Veda.

Should you require any test data or further information about testing requests, contact your Veda representative.

______
Page 14
Copyright @ 3 August 2011 Veda Advantage (NZ) Limited

NZ B2B Guide Connectivity Guide

VedaXML V2

Processing Responses
This chapter describes the types of response. Each response is written as a standard XML tagged file.

The Response Envelope

Figure 9 shows the hierarchy of the response envelope.
Figure 9

The Response Envelope Hierarchy

BCAmessage
{service-request-id}
{type}

BCAservices

BCAservice

BCAservice-code

BCAservice-code-version

BCAservice-client-ref

BCAservice-data

(All response elements)

BCAmessage{service-request-id} is a unique identifier that is used by Veda to log the message.

BCAmessage{type} describes the type of message being transmitted, in this case a response.
BCAservice-code, BCAservice-code-version and BCAclient-ref reflect data in the corresponding request document.
BCAservice-data contains all of the response data.

The following code shows a standard response envelope:

______
Page 15
Copyright @ 3 August 2011 Veda Advantage (NZ) Limited

NZ B2B Guide Connectivity Guide

VedaXML V2

<?xml version="1.0" ?>

<BCAmessage type="RESPONSE" service-request-id="00000006328">
<BCAservices>
<BCAservice>
<BCAservice-code>BCA001</BCAservice-code>
<BCAservice-code-version>V00</BCAservice-code-version>
<BCAservice-client-ref>123456789</BCAservice-client-ref>
<BCAservice-data>
<response>
.
. [all response data]
.
</response>
</BCAservice-data>
</BCAservice>
</BCAservices>
</BCAmessage>

Normal Product Response

The response contains the data resulting from your request. Product responses are discussed within the individual product
chapters in the VedaXML Product Programming Guides.

Product Error
The response contains information about an exception found in that part of the Veda system that processes your request.
Typically, this is either an error within the input data or non-availability of the system. Product errors are further discussed in
the VedaXML Product Programming Guides.

VedaXML Error
A VedaXML error indicates that a problem has been detected at server level within the Veda system. Figure 10 shows the
elements in a VedaXML error message; note that the figures after each item indicate its length.
Figure 10

VedaXML Error Hierarchy

BCAerror
{type} ................................................................
20

BCAerror-code ........................................................
8

BCAerror-description ................................
200

BCAerror{type} provides the type of error.

______
Page 16
Copyright @ 3 August 2011 Veda Advantage (NZ) Limited

NZ B2B Guide Connectivity Guide

VedaXML V2

BCAerror-code returns an internal Veda error code.

BCAerror-description provides a brief description of the error, or type of error detected.
Table 1 summarises the types of error that may be returned, and the actions you should take to remedy the problem.
Table 1

VedaXML Error Types

Error Type

Description

Action

Authentication

The VedaXML Access Code

or Access Password is
incorrect.

Check that all VedaXML access

codes are correct, then resubmit
your request.

Validation

The Veda system has found

the envelope or the format
of the request to be invalid.

Check your request against the

schema, then resubmit your
request.

Availability

The Veda system is not

currently available.

Resubmit your request after a

suitable wait time, such as one
minute.

The following XML code shows examples of VedaXML error messages> The following message indicates that the request has
been submitted with inaccurate access code and/or password information.
<BCAerror type="AUTHENTICATION">
<BCAerror-code>ERR1005</BCAerror-code>
<BCAerror-description>The Request Manager was unable to authenticate the VedaXML access code and
password supplied</BCAerror-description>
</BCAerror>

This message suggests that the content of the request envelope is incorrect.
<BCAerror type="VALIDATION">
<BCAerror-code>ERR4002</BCAerror-code>
<BCAerror-description>The Service Provider detected an error in the Message Envelope</BCAerrordescription>
</BCAerror>

______
Page 17
Copyright @ 3 August 2011 Veda Advantage (NZ) Limited