Australian Government Extensions v1.3

This package contains components and integrations relevant to the Australian Government including a number of basic checksum validation fields and some more advanced dynamic lookups. These include:

  • Basic input fields with checksum validations for Australian Business/Company Number (ABN/ACN), Medicare Number and Tax File Number (TFN).
  • Business lookups against the Australian Business Register (ABR) and Australian Securities and Investments Commission (ASIC) to search and retrieve business information by name, ABN or ACN.
  • Super Fund lookups against the Australian Tax Office (ATO) to search and retrieve Super Fund information by name or ABN.

Note: The APIs provided by the Super Fund Lookup service are unfortunately not well designed, resulting in a fairly limited capability in the UI components provided in this package relating to those APIs.

Process Flow

Below are the process flow diagrams for the Australian Government services which give an insight into the design of the Exchange components.

ABN/ACN Lookup

Australian Business Quick Search

Super Fund ABN Lookup

Super Fund Quick Search

Licensing

There are no license requirements to use the ABR (ABN Lookup) and ATO (Super Fund Lookup) web services. However, each client is required to register with the relevant service provider to obtain their own authentication GUID.

Compatibility

This package has the following compatibility requirements:

ModuleCompatibilityNotes
Transact Manager5.0 or above
Transact Maestro5.1.0 or above

Installation Instructions

To install this package please walk through the following proceedure:

  1. Unzip the package to a directory on your computer
  2. Import each zip archive found in the services folder to Transact Manager under the Services >> All Services menu item.
  3. Review the Help Doc tab for each of the imported services and make any required adjustments to service parameters.
  4. Review the Service Connection requirements under the same Help Doc tab for each of the imported services and make any required configurations to the Service Connection. Service Connections can be configured in Transact Manager under the Services >> Service Connections menu item.
  5. Import each archive found in the libraries folder to Maestro. Importing these into the Organisation level libraries folder is recommended as this will make the components available to all projects, however they can be imported at the Project level if required.

Basic Validation Fields

The following fields can be simply added to forms in Maestro to perform format validation based on the published checksum algorithms:

  • ABN/ACN: validates either Australian Business Number (ABN) or Australian Company Number (ACN) or either (default)
  • Medicare Number: validates an Australian Medicare number
  • TFN: validates an Australian Tax File Number

Australian Business Register Lookups

The components listed below utilise services provided by the Australian Business Register (ABR) to find and retrieve information about a business:

These components allow you to map the following information into fields of your choice:

  • Entity Name
  • Entity Type
  • ABN and ACN (where applicable)
  • ABN Registration Status
  • Address State and Postcode

You can map these fields into your form fields by configuring the Response Field Mappings. With the Australian Business Quick Search component, these mappings are configured on the ABR Quick Search field under the Second DDS Configuration section on the Properties tab. For the ABN/ACN Lookup Button you will find these under the Configuration section on the Properties tab (Note: you will also need to map the input ABN/ACN field against Input Field Mappings).

Note: From 10 February 2020, The ABN and Super Fund Lookup services will remove access to unsecure get/post protocol, HyperText Transfer Protocol (HTTP) and the services will point to the existing HTTPS endpoint only. Any users who attempt to retrieve data using HTTP get/post protocols will receive no data. We've provided the new https endpoint in this version. Please check the service connection Australian Business Register (ABR) for detail.

Super Fund Lookups

These components utilise services provided by the Australian Tax Office (ATO) to find and retrieve information about a Superannuation Fund:

These components allow you to map the following information into fields of your choice:

  • Super Fund Name
  • Fund Type
  • ABN
  • ABN Registration Status
  • Complying Status
  • Full Address (where available)
  • Product Name and USI (available in the Quick Search component only)

You can map these fields into your form fields by configuring the Response Field Mappings. With the Super Fund Quick Search component, these mappings are configured the Super Fund Quick Search field under the Second DDS Configuration section on the Properties tab. For the Super Fund ABN Lookup Button you will find these under the Configuration section on the Properties tab (Note: you will also need to map the input ABN field against Input Field Mappings).

The Super Fund Quick Search component includes a product selection drop-down that is only presented where there are products registered against that fund. Selection of a product will populate the Product Name and USI values.

Note: From 10 February 2020, The ABN and Super Fund Lookup services will remove access to unsecure get/post protocol, HyperText Transfer Protocol (HTTP) and the services will point to the existing HTTPS endpoint only. Any users who attempt to retrieve data using HTTP get/post protocols will receive no data. We've provided the new https endpoint in this version. Please check the service connection ATO - Super Fund Lookup for detail.

Release Notes

Version 1.3 Mar 25, 2020

  • Updated service connection endpoint with https protocol according to vendor's security requirement.

Version 1.2 Jun 12, 2019

  • Added enhancement to retrieve the exact number of active companies when using ABR quick search via a new ABN API
  • Fixed a bug that hid individual entities name from the results of ABR quick search
  • Added enhancement to clear product list field when search text is changed

Version 1.1 Sep 29, 2017

  • Added support for Maestro language translation features.

Version 1.0 Mar 6, 2017

  • Baseline release.

Maestro Assets

ABN/ACN Library: exchange.gov.au Category: Australian Government

Data capture for an ABN (Australian Business Number) or ACN (Australian Company Number) with options to support one or both

Properties

Property Category Description Type Default
Support ABN Configuration

Will allow ABN values (Australian Business Numbers)

boolean true
Support ACN Configuration

Will allow ACN values (Australian Company Numbers)

boolean true
ABN/ACN Lookup Button Library: exchange.gov.au Category: Australian Government

Takes an ABN or ACN number from a field on the form and returns the results of a lookup with the ABR

Service Calls

Rule Templates

You may add your own logic to handle the following rule types triggered by this component:

  • On Success : a script to run on success of the dynamic data call, the parameter info contains the response
  • On Failure : a script to run on failure of the dynamic data call, the parameter info contains the response

Medicare Number Library: exchange.gov.au Category: Australian Government

Supports data entry and validation of Medicare Card Numbers

Super Fund ABN Lookup Library: exchange.gov.au Category: Australian Government

Takes input from an ABN field and performs a lookup against the ATO service to find the matching Superannuation Fund.

Service Calls

Rule Templates

You may add your own logic to handle the following rule types triggered by this component:

  • On Success : a script to run on success of the dynamic data call, the parameter info contains the response
  • On Failure : a script to run on failure of the dynamic data call, the parameter info contains the response

Tax File Number Library: exchange.gov.au Category: Australian Government

Data capture and validation of Australian Tax File Number (TFN) values

Services

ABR - ABN/ACN Search v1
This Dynamic Data service provides real-time searches on the Australian Business Register and can accommodates searches via ABN, ACN or Business Name.

Service Connection

Compatibility

Module Compatibility
Manager 5.0

Service Parameters

Name Description Required Default
missingEntityNameMessage Occasionally there is no legal or organisation name associated with an ABN record. This parameter value will be used as the entity name in this scenario. No Entity name not specified

Inputs

Name Description Required
searchString The ABN (Australian Business Number) or ACN (Australian Company Number) of the target organisation Yes

Outputs

Name Description
entityName The name of the business entity
abn The ABN (Australian Business Number) associated with the organisation
acn The ACN (Australian Company Number) associated with the organisation
registrationStatus The current registration status of the entity
entityTypeCode The short 3 character code identifying the entity type e.g. PRV (see Reference Data for a full list of codes and descriptions)
entityType The descriptive name for the entity type e.g. Australian Private Company
addressState
addressPostcode 		The state and postcode that the entity is registered in
executionStatus The status of the service execution [ SUCCESS | DATA_ERROR | SYSTEM_ERROR ]. Successful execution will be denoted by a SUCCESS value. DATA_ERROR will indicate that there was an issue identified with the input data that may be resolved and potentially retried by the user. SYSTEM_ERROR indicates that there was an unrecoverable system fault and the form should fall-back gracefully to an alternative path.
errorMessage In the event of a DATA_ERROR, this value may contain more information about the error.
ABR - Quick Search v3
This Dynamic Data service allows forms to perform real-time searches for Australian Superannuation Funds by ABN (Australian Business Number), fund name or product name.

Service Connection

Compatibility

Module Compatibility
Manager 5.0

Service Parameters

Name Description Required Default
maxResultSize Default value for maximum number of matching search results returned from the search function (default 10). This value can be overridden as a request parameter if required. Must be between 1 and 20. Yes 10
missingEntityNameMessage Occasionally there is no legal or organisation name associated with an ABN record. This parameter value will be used as the entity name in this scenario. No Entity name not specified

Inputs

Name Description Required
searchString The search string may be an ABN, an ACN or an entity name. A minimum of 3 characters is expected. Yes
activeOnly Optionally specify a [ true (default) | false ] flag used to control whether inactive entities are included in search results. No
maxResultSize Optionally specify a numeric maximum result list size to override the default: 10. Cannot be less than 1 or greater than 20. No

Outputs

Name Description
[] The results are provided as a JSON array of objects with the following attributes:
*.label The label to display in the result list, will be entityName.
*.entityName The name of the business entity
*.abn The ABN of the matching entity
*.registrationStatus The current registration status of the entity
Super Fund Lookup - ABN Search v1
This Dynamic Data service allows forms to perform real-time lookups for Australian Superannuation Funds by ABN (Australian Business Number).

Service Connection

Compatibility

Module Compatibility
Manager 5.0

Inputs

Name Description Required
abn The ABN (Australian Business Number) of the Superannuation Fund to lookup Yes

Outputs

Name Description
superFundName The name of the Superannuation Fund
abn The ABN (Australian Business Number) associated with the Superannuation Fund
registrationStatus The current registration status of the Superannuation Fund
fundTypeCode The short 3 character code identifying the fund type e.g. ADF (see Reference Data for a full list of codes and descriptions)
fundType The descriptive name for the fund type
addressLine1
addressLine2
addressSuburb
addressState
addressPostcode 		The registered address of the Superannuation Fund
complyingStatusCode The short code identifying the complying status of the Superannuation Fund (see Reference Data for a full list of codes and descriptions)
complyingStatus The description of the complying status
productList If the super fund has products associated with it a product list will be included in the result. This list can then be used in a data driven drop down.
executionStatus The status of the service execution [ SUCCESS | DATA_ERROR | SYSTEM_ERROR ]. Successful execution will be denoted by a SUCCESS value. DATA_ERROR will indicate that there was an issue identified with the input data that may be resolved and potentially retried by the user. SYSTEM_ERROR indicates that there was an unrecoverable system fault and the form should fall-back gracefully to an alternative path.
errorMessage In the event of a DATA_ERROR, this value may contain more information about the error.
Super Fund Lookup - Quick Search v1
This Dynamic Data service allows forms to perform real-time searches for Australian Superannuation Funds by ABN (Australian Business Number), fund name or product name.

Service Connection

Compatibility

Module Compatibility
Manager 5.0

Service Parameters

Name Description Required Default
maxResultSize Default value for maximum number of matching search results returned from the search function (default 10). This value can be overridden as a request parameter if required. Must be between 1 and 20. Yes 10

Inputs

Name Description Required
searchString The search string may be an ABN, Superannuation fund name or product name. A minimum of 3 characters is expected. Yes
activeOnly Optionally specify a [ true (default) | false ] flag used to control whether inactive funds are included in search results No
searchProductsFlag Optionally specify a [ true | false (default) ] flag to instruct the service to search product names instead of fund names. If no value is provided the service will default to fund name searching. Note, if the search string provided is a valid ABN, an ABN search is performed returning at most 1 result, otherwise a name search is performed returning a list. No
maxResultSize Optionally specify a numeric maximum result list size to override the default: 10. Cannot be less than 1 or greater than 20. No

Outputs

Name Description
[] The results are provided as a JSON array of objects with the following attributes:
*.label The label to display in the result list, will be superFundName unless a product search is performed where it will be productName.
*.superFundName The name of the Superannuation Fund
*.abn The ABN (Australian Business Number) of the matching Superannuation Fund
*.productName The name of the matching Superannuation Product (only returned for product searches)
*.usi The USI (Universal Superannuation Identifier) of the matching product (only returned for product searches)

Service Connections

The following service connections are used by this package.

Australian Business Register (ABR)
Property Name Description Required
Type HTTP Endpoint Yes
Endpoint Should point to the ABN Lookup REST API at: https://abr.business.gov.au/abrxmlsearch/AbrXmlSearch.asmx Yes
Auth Key Should contain the GUID value for the client organisation. Each client must complete the free registration process in order to access the ABN Lookup web service. Yes
ATO - Super Fund Lookup
Property Name Description Required
Type HTTP Endpoint Yes
Endpoint Should point to the Super Fund Lookup REST API at: https://www.superfundlookup.gov.au/xmlsearch/SflXmlSearch.asmx Yes
Auth Key Should contain the GUID value for the client organisation. Each client must complete the free registration process in order to access the Super Fund Lookup service. Yes