SAMPLE CODE INSTALLATION
GUIDE
JAVA
USI External Services Sample Code
CONTENTS
INTRODUCTION.................................................................................................................................. 3
PURPOSE ................................................................................................................................................. 3
AUDIENCE ................................................................................................................................................ 3
OVERVIEW ............................................................................................................................................... 3
PREREQUISITES .................................................................................................................................. 4
REGISTRATION .......................................................................................................................................... 4
DIGITAL CERTIFICATE .................................................................................................................................. 4
DEVELOPMENT ENVIRONMENT..................................................................................................................... 4
USING THE SAMPLE CODE .................................................................................................................. 5
ENVIRONMENT.......................................................................................................................................... 5
COMMAND LINE INTERFACE......................................................................................................................... 5
SOURCE FILES ........................................................................................................................................... 5
BASIC FLOW ............................................................................................................................................. 6
REQUIRED CHANGES .................................................................................................................................. 7
Dependencies.................................................................................................................................... 7
UsiServiceChannel.java ..................................................................................................................... 7
USITest.java ...................................................................................................................................... 7
DOCUMENT VERIFICATION .......................................................................................................................... 8
Page 2 of 9
USI External Services Sample Code
INTRODUCTION
PURPOSE
This document details the USI sample code for integrating with the USI external
web service. The sample code is delivered as an Eclipse (Kepler) console
application.
AUDIENCE
Developers and/or system integrators should read this document.
OVERVIEW
The USI Sample Code demonstrates how a Student Management System can
integrate with the USI Agency web services. The web services provide five distinct
functions:
1. Create a USI record for an individual and receive an immediate response;
2. Verify a USI for an individual and receive an immediate response;
3. Submit a batch of USI creation requests, and receive a receipt number;
4. Retrieve the results of a previous batch creation request via the receipt
number; and
5. Perform USI verification for a batch of requests and receive an immediate
response.
Page 3 of 9
USI External Services Sample Code
PREREQUISITES
REGISTRATION
To use the USI web service RTO’s must be registered and current on
Training.Gov.Au (TGA). Other VET related organisations can register with the USI
Taskforce. Registration will provide organisations with an Organisation code which
must be provided when calling the USI web services.
DIGITAL CERTIFICATE
Callers of the USI web services will require an AUSkey device credential matching
the ABN registered with TGA or the USI Taskforce in order to verify their identity.
For ThirdParty environments, the device credential will be issued by VANguard in
the form of an Xml document (usually named KeyStore.xml).
The USI web services are secured using the VANguard Security Token Service
(STS). The STS is a WS-Trust compliant service used to validate the credential
and generate security tokens. These security tokens are then used to secure one
or more messages sent to the USI web services.
The sample code provided demonstrates how to extract the certificate from the
AUSkey keystore and additionally make the VANguard STS call.
DEVELOPMENT ENVIRONM ENT
The sample code has the following dependencies:

Eclipse (Kepler);

Java 7;

AUSKey Development Kit (ADK) version 8.0.0, sourced from the Australian
Taxation Office (NOT included with the sample code);

BatchCreateService.wsdl USI web service definition (included with the
sample code as BatchCreateService_3pt.wsdl)
Page 4 of 9
USI External Services Sample Code
USING THE SAMPLE CODE
ENVIRONMENT
Release 1.1.0.0 of the USI Sample Code is designed to work with the VANguard
ThirdParty environment. The ThirdParty environment provides the following
endpoints:
The endpoint URL for the VANguard STS is:
https://thirdparty.authentication.business.gov.au/R3.0/vanguard/S007v1.2/Servi
ce.svc.
The endpoint URL for the USI web service calls is:
https://3pt.portal.usi.gov.au/Service/BatchCreateService.svc
COMMAND LINE INTERFACE
The sample code comes in the form of a simple console application that calls the
USI service with a request to create a USI, then a request to verify the same USI.
It writes the results of these calls to the console and then exits.
SOURCE FILES
The following table provides an overview of each of the files required for the
USISampleCode solution. Some must be obtained separately:
File
Description
BatchCreateService_3pt.wsdl
The service metadata for the USI service in 3PT.
At the time of writing, it is exactly the same as
found on the published USI service in 3PT.
wsit-client.xml
Configures the Metro library to initialise with the
above WSDL file.
cxf_bindings.config
RegenerateClientJava.bat
Customises the behaviour of the Apache CXF
wsdl2java tool so that it wraps all request
arguments in singular request objects.
Calls wsdl2java with appropriate arguments to
recreate the request/response/client objects
required for application code.
It assumes the install directory of Apache CXF,
Page 5 of 9
USI External Services Sample Code
File
Description
and that it is generating objects for 3PT.
UsiServiceChannel.java
Retrieves your AUSkey from a local store, creates
a USI service client, then sets it up with the
discovered AUSkey and other environmental
settings.
USITest.java
Example application code using the USI service.
SecurityHeader.java
Contains a customisation to the Metro library,
ensuring that the SOAP security header is
ordered correctly (i.e. “Strict” ordering, with the
key-containing EncryptedAssertion appearing
before the Signature).
abrakm.jar
AUSkey ADK component used to access the local
Keystore. This file is not included with the sample
code and must be sourced from the ADK.
auskey-dep-1.1.jar
AUSkey ADK dependency. This file is not included
with the sample code and must be sourced from
the ADK.
webservices-api.jar
Part of the Metro 2.3 library. The metro library is
large to include with the sample code so must be
downloaded separately.
webservices-extra.jar
Part of the Metro 2.3 library. The metro library is
large to include with the sample code so must be
downloaded separately.
webservices-rt.jar
Part of the Metro 2.3 library. The metro library is
large to include with the sample code so must be
downloaded separately.
BASIC FLOW
The following is a basic outline of the processing flow:
1. Extract the certificate from the AUSkey keystore using the ADK;
Page 6 of 9
USI External Services Sample Code
2. Create an endpoint to the USI service.
3. Setup the endpoint, using the AUSkey certificate, and config information
about VANguard STS;
4. Invoke the USI web service, relying on the Metro library to call VANguard STS
for a security token and then secure the USI call with that token.
5. Write the response to the console.
REQUIRED CHANGES
The following customisations are required in the following files before using the
Sample Code:
DEPENDENCIES
The AUSkey ADK will need to be sourced from the Australian Taxation Office and
added to the sample code solution. VANguard does not redistribute the ADK with
the sample code.
Further, the Metro 2.3 library must be downloaded so some of its components can
be included. At the time of writing, Metro 2.3 is at https://metro.java.net/2.3/
The following files must be added to the lib folder within the sample code folder
structure. Once added, Eclipse will resolve the dependencies:

abrakm.jar

auskey-dep-1.1.jar

webservices-api.jar

webservices-extra.jar

webservices-rt.jar
USISERVICECHANNEL.JAVA
The const string AUSKEY_KEYSTORE needs to be changed to refer to the
location on disk of the Keystore.xml file.
The const string AUSKEY_ALIAS needs to be changed to match the credential
identifier as found in the Keystore.xml file. The credential identifier is in the form
of “ABRP:99999999999_99999999”.
The const string AUSKEY_PASSWORD needs to be changed to match the
keystore/credential password.
USITEST.JAVA
The setOrgCode() calls must be changed to match the issued Organisation Code.
By default it is set to “0001”.
Page 7 of 9
USI External Services Sample Code
DOCUMENT VERIFICATION
Document verification in the VANguard Third Party environment uses a mock
service (the DVS service is not called). Valid DVS document types include:

Citizenship;

Registration by Descent;

Drivers License;

Medicare Card;

Passport;

Visa; and

Birth Certificate.
By default the sample code sets the DVSCheckRequired property to true on the
ApplicationType object for each request. As a result, the USI web service will
invoke the mock Document Verification Service to verify the DVS document.
Each document type uses a key value for verification. Note these key values are
only appropriate for the USI web services in the Third Party environment. The
following table outlines the acceptable key values that will result in a pass or
unavailable status for the document check.
Document Type
Key Field
Value
Result
Citizenship
Stock Number
111111
Pass
Citizenship
Stock Number
000000
Unavailable
Registration by Descent
AcquisitionDate
01/01/2013
Pass
Registration by Descent
AcquisitionDate
12/12/2012
Unavailable
Drivers Licence
Licence Number
111111
Pass
Drivers Licence
Licence Number
000000
Unavailable
Medicare Card
Card Number
111111111
1
Pass
Medicare Card
Card Number
000000000
Unavailable
Page 8 of 9
USI External Services Sample Code
Document Type
Key Field
Value
Result
0
Passport
Document Number
X1111111
Pass
Passport
Document Number
X0000000
Unavailable
Visa
Passport Number
111111
Pass
Visa
Passport Number
000000
Unavailable
Birth Certificate
Registration Number
11111111
Pass
Birth Certificate
Registration Number
00000000
Unavailable
Setting the value to any other will result in a failed request.
Please refrain from submitting “Unavailable” values to the BulkUpload operation,
as these will cause the corresponding applications to get stuck in the system
indefinitely.
Page 9 of 9