Unique Student Identifier

Technical Service Contract for the Unique Student Identifier Web Service

Comprising the following service operations:

Verify single USI

Verify multiple USIs

Create single USI

Create multiple USIs (processed asynchronously)

Retrievethe result of a request to create multiple USIs

Update Personal Details

Update Contact Details

Get Non DVS Document Types

Contract Version 2.0 –June 2015

Document Details

Security classification / Unclassified
Dissemination limiting marking / None
Author / Department of Industry
Document Status / Approved June 2015

Copyright © 2013-2015 Commonwealth of Australia

Unique Student Identifier TechnicalService Contract

Document Administration

Service Name / USI Web Service
Contract version / 2.0
File Location / USI Document SharePoint
File Name / Document:USI TSC.docx
Diagram masters: USI TSC – feeder.pptx

Revision History

Revision / Date / Author / Details
0.1 / 28 Oct 2012 / Malcolm Young / First Draft
0.2 / 13 Dec 2012 / Malcolm Young / Added WSDL
0.3 / 19 Dec 2012 / Malcolm Young / Review comments inc
1.0 / 19 Dec 2012 / Malcolm Young / Final revision
1.1 / 20 Dec 2012 / Malcolm Young / Updated following additional comments
1.2 / 11 Feb 2013 / Luke Elliott / Fixed syntax errors, remove unnecessary fields, some clarification
1.3 / 26 Feb 2013 / Luke Elliott / Major revision to the WSDL, XSD and various fields
1.4 / 27 Mar 2013 / Luke Elliott, Trent Kerin / UpdatedWSDL and correcteddetails based on review feedback
1.5 / 28 Mar 2013 / Ben Bildstein / Polish
1.6 / 10 Apr 2013 / Luke Elliott, Trent Kerin / Actioning comments from USI Task Force
1.7 / 11 Apr 2013 / Ben Bildstein / Polish
1.8 / 9 May 2013 / Ben Bildstein, David Spencer / Incorporate David Spencer’s changes
1.9 / 24 May 2013 / Ben Bildstein, Luke Elliott / Bulk verify
1.10 / 26 July 2013 / Jason Chase / Updated validation rules for DVS documents
1.11 / 26 July 2013 / Jason Chase / Updated phone number minimum length validations
1.12 / 31 July 2013 / Patrick McNamara / Added production end point addresses.
1.13 / 2 Aug 2013 / Trent Kerin / Added “WSDL with WCF” section
1.14 / 11 Sep 2013 / Jason Chase / Updated Bulk Verify sections
1.15 / 23 Oct 2013 / Ben Bildstein / Updated example requests and responses
1.16 / 8 Nov 2013 / Trent Kerin / Removed Change of Name and Marriage documents.
1.17 / 5 Dec 2013 / Trent Kerin / Updated definition of ErrorType allowable codes. Mentioned that some of the codes in Fault Values appear as regular errors.
1.18 / 12 Dec 2013 / Nick Evans / Updated the Medicare card document type. And Updated the WSDL to match.
1.19 / 29 Jan 2014 / Kurt Marr / Updated to include contact details changes
1.20 / 29 Jan 2014 / Ben Bildstein / Update to contract version 1.1
1.21 / 30 Jan 2014 / David Spencer / Minor wording revisions
1.21 / 18 Mar 2014 / Harold Hotham / Updates for ImmiCard, Error 1002 and new passport number
1.22 / 20 Mar2014 / Harold Hotham / Update for WSDL and preferred contact method
1.23 / 15 Apr2014 / Harold Hotham / Update for unique email address
1.24 / 16 Apr2014 / Harold Hotham / Contract version 1.2, some minor changes to field names and validation rules.
1.25 / 1 May 2014 / Ben Bildstein / Merged David Spencer’s document version 1.21 with Harold Hotham’s document version 1.24.
1.26 / 2 May 2014 / Kurt Marr / Modified UserReference Element
1.27 / 6 May 2014 / Patrick McNamara / Update error code list
1.28 / 12 May 2014 / Trent Kerin / Specify Visa CountryOfIssue as 1-80 chars
1.29 / 22 May 2014 / Trent Kerin / Update WSDL endpoints and SOAP actions to target implementation.
Added brief section about service identifiers.
1.30 / 24 June 2014 / Trent Kerin, Neville Schroder / Removed service identifiers section, in favour of the AppliesTo argument for STS being identical to the USI endpoint URL.
Updated WSDL to reflect latest changes.
Cut out most of Appendix D as the new WSDL now auto-configures everything except client certificate.
Corrections to textual descriptions of DVSCheckRequired and FirstName and FamilyName elements in the Personal Details Type.
1.31 / 2 July 2014 / Trent Kerin / Fixed typo in single name Bulk Verify example.
1.32 / 28 July 2014 / Harold Hotham / Rewrite of birth certificate section to include conditional field info.
1.33 / 12 August 2014 / Patrick McNamara / Updated the validation rules for TownCityOfBirth, SuburbTownCity, Address1, Address2 and InternationalAddress. Removed blank Address2 from the sample requests. WSDL updated to reflected these changes.
1.34 / 22 September 2014 / Harold Hotham / Updated “Endpoints and Operations” section with prod urls.
1.35 / 1 October 2014 / Patrick McNamara / Added GetNonDvsDocumentType, UpdatePersonalDetails and UpdateContactDetails. Replaced wdsl xml in appendix to link to the real wsdl.
1.36 / 2 November 2014 / Harold Hotham / Added Error 3250, this error already existed but did not have a code. Should be very difficult to hit this error. It represents an unexpected error when performing schema validation.
1.37 / 1 December 2014 / Kurt Marr / Added error 3370 for suspended DVS document types
1.38 / 12 December 2014 / Kurt Marr / Fixed Medicare IndividualRefNumber valid values
1.39 / 12 December 14 / Harold Hotham / Updated VerifyUSIResponse to indicate fields are not mandatory
1.40 / 18 Dec. 14 / Harold Hotham / Added Locate USI
1.41 / 3 March 2015 / Kurt Marr / Made preferred contact method optional
1.42 / 17 March 2015 / Patrick McNamara / Added Name Validation rules for Create USI and Update Personal Details web methods.
2.0 / 30 April 2015 / Harold Hotham / Updates for V2 of the services.
  • New endpoint
  • PreferredContact
  • NonDvsDocumentTypeId
  • WSDL Location
  • TownCityOfBirth

2.1 / 30 April 2015 / Harold Hotham / Completed changes for v2 of the service
2.11 / 19 May 2015 / Patrick McNamara / Refreshed the Visa Country List to the May 2015 list.

Release notes

3PT Deployment date / 21/10/15
Production deployment date / 29/10/15
Description / Breaking[1]/
Non-breaking[2]
New features and enhancements /
  1. Version 2 of the service at a new endpoint
/ Breaking
  1. PreferredMethod (contact) all references removed.
/ Breaking
  1. NonDvsDocumentTypeId is now mandatory when not specifying a DVS document. (If DVS override is available)
/ Breaking
  1. New WSDL for V2 of the service
/ Breaking
  1. Namespaces and SOAP actions have changed.
/ Breaking
  1. New rule for TownCityOfBirth (when country of birth is Australia)
/ Breaking
Bug fixes / None / -
Known issues / None / -

Approvals

Approved by:

Name:Deborah Morgan

Position:Manager, USI Project

Signed:______

Date:______

Terminology

ABN / Australian Business Number
ATO / Australian Taxation Office
AUSkey / Australian Government issued digital certificate
Credential / Something used to prove their digital identity
Device Key / AUSKey specifically for use with web services
Digital Certificate / Proof of identity data
DVS / Document Verification Service – a service to verify evidence of identity documents.
More information is available from
Identity Token / See Security Token
OASIS / A standards body 'Organization for the Advancement of Structured Information Standards'. See Section 1.3, References and Related Documents.
RTO / Registered Training Organisation. A provider of accredited VET courses and training.
SAML / Secure Assertion Mark-up Language – an OASIS standard
SAML Assertion / A signed XML block asserting identity of a user. The XML conforms to the SAML Core schema.
Security Token / This is an industry term for an assertion about identity that is issued by an Identity Provider. In the context of this contract this is signed SAML assertion.
SMS / Student management system
SMS Vendor / Provider of student management systems to RTOs.
SOAP / Simple Object Access Protocol
Student / A person undertaking VET and who will require a USI from January 2015.
TA / State and Commonwealth authorities that oversee delivery of VET.
TGA / training.gov.au
Token / See Security Token
User / An RTO staff member using an SMS to interact with the USI web services.
USI Registrar / A Registrar will be appointed, subject to legislation,to administer unique student identifiers for the VET sector.
USI Taskforce / Responsible for implementation of the USI Program.
VET / Vocational Education and Training.
WS-Trust / A specification that deals with distribution of security tokens.

Contents

1Introduction

1.1Purpose

1.2Audience

1.3References and Related Documents

2Business View

2.1Version Information

2.1.1About This Version

2.1.2Changes by Contract Version

2.2Overview and Broad Functionality

2.3Service Environments

2.3.1Third Party Testing

2.3.2Production

2.4Digital Certificate (AUSkey)

2.5Web Services Security

3Web Service Policy

4The Service Provider Interface

4.1Conditions of Use

4.1.1Pre-Conditions

4.1.2Service Call Process

4.1.3Post Conditions

4.2Endpoints and Operations

4.2.1Third Party Testing

4.2.2Production

4.3Message Structure

4.3.1Create Single USI

4.3.2Create Multiple USIs (BulkUpload)

4.3.3Retrieve create multiple USIs result (BulkUploadRetrieve)

4.3.4Verify a single USI

4.3.5Bulk Verify multiple USIs

4.3.6Get Non DVS Document Types

4.3.7Update Personal Details for USI

4.3.8Update Contact Details for USI

4.3.9Locate USI

4.3.10Shared Data Types

4.4Fault Messages

4.4.1Sample Fault

4.4.2Fault Values

5Addressing Policy

6Security Policy

7Appendix A – WSDL Schema

8Appendix B – USI Country List

9Appendix C – Visa Country List

10Appendix D – WSDL with a WCF Application

1Introduction

1.1Purpose

The purpose of this document is to inform student management system (SMS) vendors, and RTO in house system developers about the USI webservices available for their consumption.

This interface description is called a 'Technical Service Contract' (TSC).

1.2Audience

This document is intended to be read by organisations and agencies intending to use the web services and covers both technical and business aspects of the services.

Executive readers and business analysts should readSection 2 to gain an understanding of the business need that these services address.

Technical staffimplementing systems that consume the USI Web Services should read the whole document.

1.3References and Related Documents

Common Elements: Common Elements for Vanguard Services – Document Revision V1.16

STS: VANguard Security Token Service Technical Service Contract v1.2

SAMLCore: Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V1.1. OASIS Standard, August 2003.

WSSAML: Web Services Security: SAML Token Profile 1.1

SOAPSOAP Version 1.2 Part 1: Messaging Framework (Second Edition)

WSP: Web Services Policy Framework (WSPolicy) v1.2

WSECP: WS-SecurityPolicy 1.2

WSEC: Web Services Security: SOAP Message Security 1.1

WSA: Web Services Addressing 1.0 – Core

2Business View

2.1Version Information

2.1.1About This Version

This document describes version 2.0 of the USIWeb Services.

Since this document may change without impacting the service definition, i.e. non-technical changes, this document includes the date it was published (June 2015) separate to the contract version number.

2.1.2Changes byContract Version

Important changes made in each version of the contract are listed below.

2.1.2.1Version 1.1

The following changes may cause problems for implementations based on previous versions of this document:

  • The Change of Name document type is no longer supported.
  • The Marriage Certificate document type is no longer supported.
  • If part of a postal address is specified, the complete postal address must now be specified.

The following additions have also been made:

  • Service for verifying multiple USIs.
2.1.2.2Version 1.2

The following changes may cause problems for implementations based on previous versions of this document:

  • The EmailAddress in Contact Details Typemust now be unique in the USI Register for active USIs.
2.1.2.3Version 1.3

The following changes may cause problems for implementations based on previous versions of this document:

  • AppliesTo argument for STS being identical to the USI endpoint URL
2.1.2.4Version 2.0

This version represents a new endpoint and a number of associated changes to the USI Service.

  • There is a new endpoint
  • The namespace has changed
  • The PreferredMethod has been removed
  • NonDvsDocument type now mandatory in some scenarios
  • New WSDL location
  • New requirements for TownCityOfBirth (when country of birth is Australia)

2.2Overview and Broad Functionality

This document describes the system to system functions provided by the USI web services.The services discussed in this document allow an authorised consumer to perform the following actions:

  • Create a USI record for an individual and receive an immediate response
  • Submit a batch of USI creation requests for processing and (BulkUpload)
  • Retrieve the results of a previously submitted batch request (BulkUploadRetrieve)
  • Verify a USI for an individual and receive an immediate response
  • Verify a batch of USIs and receive an immediate response. Added in version 1.1.

2.3Service Environments

TheUSI web services will be deployed in two distinct environmentsas detailed below.

2.3.1Third Party Testing

Third party testing is intended to allow software developers to integrate and test their software with a non-live implementation of the USI web services that is guaranteed to behave the same as the live system. This environment is configured to use only test AUSkey certificates, org codes and mock version of the document verification system. Any USIs generated by the test environment are not valid in the live environment.

2.3.1.1Testing Registration

Developers wishing to access the third party testing environmentmust complete the enrolment process available from the USI Website. Once completed, participants will be issued with appropriate certificates, orgcodes and connection instructions.

2.3.2Production

Production is the live version of the USI Web Services once the scheme goes live.

2.3.2.1Registration

To use the USI web services in the production environment, RTOs must firstbe listed and current on Training.Gov.au (TGA). Other VET related organisations wishing to use web services or the web portal must register themselves with the USI Registrar.

Registration will give organisations an OrgCode, from either TGA or the USI Registrar. The OrgCode must be supplied as a part of all web service calls.

In the case where an ABN is associated with multiple registered organisations, it is the responsibility of the web service user to provide the appropriate OrgCode for each service call.

Each organisation wishing to use the USI web services will also need to complete an additional enrolment process, agreeing to the terms and conditions of use, with the Registrar, before they can access the services in the production environment.

2.4Digital Certificate (AUSkey)

Consumers of the USI web services will require an AUSkey, and more specifically an AUSkey device credential, to verify their identity while interacting with the USI web services.These certificates can be obtained free of charge from the Australian Business Register by all ABN holders.

Each organisation, RTO, VAB etc. will require their own AUSkey device credential and matching OrgCode before they can use the USI web services.

2.5Web Services Security

The USI Web Servicesare secured using the VANguard Security Token Service (STS). The STS is a WS-Trust compliant service used to validate digital credentials and generate security tokens which can then be used to create secure web service channels. A typical interaction is as follows:

  1. The end user creates arequest for security token message which is signed using their digital credential. This message is sent to the VANguard STS.
  2. The STS validates the signature over the message and the digital credential used to sign it and returns a SAML security token.
  3. This token is used to secure one or more messages sent to the USI Web Services.

Figure 1: Interaction overview

This document only describes the interaction between the client and the USI Web Services. Technical specifications for the VANguard STS are contained in the VANguard Security Token Service Technical Service Contract.

3Web Service Policy

All the USI services conform to the following standards:

  • SOAP v1.2 [SOAP]
  • WS-Policy v1.2 [WSP]
  • WS-SecurityPolicy v1.2 [WSECP]
  • WS-Security 1.1 [WSEC]
  • WS-Addressing v1.0 [WSA]
  • SAML Token Profile for WS-Security

Detailed policy for all services is described in the WSDL for each service.

4The Service Provider Interface

4.1Conditions of Use

4.1.1Pre-Conditions

In order to invoke any USI web service operation, the following conditions must be met depending on the environment the user wishes to access.

4.1.1.1Third Party Testing

Completing the third party testing enrolment process will result in participants being issued with the following required data:

•A set of organisation codes that can be used to test the web services with different organisation types (RTO, VAB etc).

•AUSkeys specifically for the third party testing environment.

4.1.1.2Production
  • RTOs must be listed and current on Training.Gov.au (TGA). Other VET related organisations must be registered with the USI Taskforce.
  • The organisation will need to complete the web services enrolment process, agreeing to the web services terms and conditions of use, as specified by the Registrar.
  • The organisation must hold a valid device AUSkey matching the ABN registered with TGA or the USI Taskforce.

4.1.2Service Call Process

Each call made to the USI web services must complete the following steps:

  1. Obtaina valid and current SAML security token for the organisation from the VANguard Security Token Service (STS). This token can be used for multiple web service calls within the same session, until it expires.
  2. Call the required USI web service attaching the SAML security token.

4.1.3Post Conditions

All service requests will be recorded for audit purposes. This audit log will not include any sensitive or personal information.

A clear response will be provided to the client indicating success or failure. In the event of a failure to process or authenticate the request, a SOAP fault will be returned to indicate the nature of the problem.

4.2Endpoints and Operations

4.2.1Third Party Testing

Paths for the third party testing environment will be made available to participants after they have completed the enrolment process available from the USI website.

4.2.2Production

The endpoint URL for the USI Web Services is:

The WSDL for the USI Web Services:

The SOAP action for bulk create USIupload operation is:

The SOAP action for bulk create USIretrieve operation is:

The SOAP action for bulk verify USI retrieve operation is:

/2015/ws/BulkVerifyUSI

The SOAP action for the create USI operation is:

The SOAP action for the verify USI operation is:

The SOAP action for the get non-DVS document types operation is:

The SOAP action for the update USI personal details operation is:

The SOAP action for the update USI contact details operation is:

4.3Message Structure

This section details the message structures for each of the USI Web Services interfaces.

The schema for all service calls is provided in Appendix A. Sample messages shown below include only the SOAP body for clarity.

4.3.1Create Single USI

The Create USI service allows a caller to submit a single application to create a USI in a synchronous manner.

4.3.1.1Request Message
4.3.1.1.1Special Conditions

It is important to note that when creating USIs, using both single and multiple create, the combination of RequestId and OrgCode must be unique for all calls to both these services and can never be reused irrespective of the outcome of the current request.