ato common message implementation guide.docx

Standard Business ReportingAustralian Taxation Office

Common Message Implementation Guide

Date: 15th September 2016

Status: Final – suitable for use

This document and its attachments are Unclassified.X

For further information or questions, contact the SBR Service Desk at [email protected] or call 1300 488 231. International callers may use +61-2-6216 5577

http://sbr.gov.au/agreement/Gateway/1.0/Push/PKI

STANDARD BUSINESS REPORTING ATO COMMON MESSAGE IMPLEMENTATION GUIDE

VERSION CONTROL

Version Date Description of changes

3.0 15/09/2016 General:

References to Product Message Implementation Guides (MIGs) changed to either ATO Service Registry or Service Suite packages depending on the context of the sentence.

Section 1.3 – Document Context

Figure 1: ATO MIG package updated to remove Message Implementation Guides and add in the ATO Artefact Location sheet and the ATO Site and Document Map sheet.

Section 1.4 – ATO Document Suite

Table updated to reflect the document suite diagram along with descriptions.

Section 3.3 – SBR ebMS3 Supported Service Invocation Types

Tables removed to avoid duplication with the SBR ebMS3 WIG and WIG reference added.

Section 4.1.2 – Supported Attachments Section added to show the supported ebMS3 attachments,

the MIME type and filename extension.

Section 8 – Message structure spreadsheets Updated Table 16 – CST Table Description as follows:

Adds:o XML - XPatho JSON - JSONPath

Modso ‘Min’ to ‘Min Occurs’o ‘Max’ to ‘Max Ocurrs’

Updated Table 17 – MST Table Description as follows:Adds:

o Data Typeo Patterrno Full Enumerationo Min Lengtho Max Lengtho Total Digitso Fractional Digitso XML – Xpatho JSON - JSONPath

Modso ‘Min’ to ‘Min Occurs’o ‘Max’ to ‘Max Ocurrs’o ‘Legal Reference’ movedafter ‘Report Guidance’.

Section 9 – Validation Rules spreadsheets Updated Table 18 – Validation Rule Table Description as

follows:Adds:

o Legacy Ruleo Applies to XBRL Payloadso Applies to XML Payloadso Applies to JSON Payloads

VERSION 3.0 UNCLASSIFIEDPAGE 2 OF 85



Note: Previous Version Control information is located in Section 12 of this document.



ENDORSEMENT

APPROVALChief Solutions ArchitectStandard Business Reporting

Michael Ferris Project ManagerStrategic Web ServicesAustralian Taxation Office

Copyright© Commonwealth of Australia 2016 (see exceptions below). This work is copyright. Use of this Information and Material is subject to the terms and conditions in the “SBR Disclaimer and Conditions of Use” which is available at http://www.sbr.gov.au. You must ensure that you comply with those terms and conditions. In particular, those terms and conditions include disclaimers and limitations on the liability of the Commonwealth and an indemnity from you to the Commonwealth and its personnel, the SBR Agencies and their personnel.

You must include this copyright notice in all copies of this Information and Material which you create. If you modify, adapt or prepare derivative works of the Information and Material, the notice must still be included but you must add your own copyright statement to your modification, adaptation or derivative work which makes clear the nature of your modification, adaptation or derivative work and you must include an acknowledgement that the adaptation, modification or derivative work is based on Commonwealth or SBR Agency owned Information and Material. Copyright in SBR Agency specific aspects of the SBR Reporting Taxonomy is owned by the relevant SBR Agency.


http://www.sbr.gov.au/software-developers/enabling-sbr-in-my-application/sbr-taxonomy/view-taxonomy


Table of contents1 Introduction............................................................................................................................7

1.1 Purpose.........................................................................................................................7

1.2 Audience.......................................................................................................................7

1.3 Document context.........................................................................................................7

1.4 ATO documentation suite..............................................................................................9

1.5 Supporting documentation..........................................................................................10

1.6 Change management..................................................................................................11

1.7 Glossary......................................................................................................................12

2 Business Context.................................................................................................................13

2.1 Prerequisites...............................................................................................................13

2.2 Interactions..................................................................................................................13

3 Standard Business Reporting Platforms..............................................................................15

3.1 SBR ebMS3 Instructions.............................................................................................15

3.2 Supported Data Formats.............................................................................................18

3.3 SBR ebMS3 Supported Service Invocation Types.....................................................18

4 SBR ebMS3 Message Packaging.......................................................................................25

4.1 Overview.....................................................................................................................25

4.2 Single Request............................................................................................................26

4.3 Single Receipt.............................................................................................................28

4.4 Single Pull Request.....................................................................................................28

4.5 Single Response (Non-Collect)...................................................................................29

4.6 Collect Response........................................................................................................31

4.7 Batch/Bulk Request.....................................................................................................33

4.8 ELS Tag Batch Request..............................................................................................36

4.9 Batch/Bulk Receipt......................................................................................................37

4.10 Batch/Bulk Pull Request..............................................................................................37

4.11 Batch/Bulk Response.................................................................................................38

5 SBR ebMS3 Message Structure..........................................................................................41

5.1 Security Header..........................................................................................................41

5.2 ebMS Header..............................................................................................................41

5.3 eb:USERMESSAGE – SBR ebMS3 Profile................................................................41

5.4 eb:SIGNALMESSAGE – ATO Profile.........................................................................48

6 General Instructions............................................................................................................50

6.1 Anonymous Interactions..............................................................................................50

6.2 Authorisation of online (cloud) service providers........................................................50

6.3 Authorisation of intermediaries...................................................................................51



6.4 Declarations................................................................................................................51

6.5 Response messages...................................................................................................54

6.6 Data Formats..............................................................................................................59

6.7 Validation....................................................................................................................59

6.8 Rule Expression..........................................................................................................62

7 ATO structured English.......................................................................................................65

8 Message Structure spreadsheets........................................................................................75

9 Validation Rules spreadsheets............................................................................................78

10 APPENDIX A – Physical end points................................................................................80

10.1 SBR Core Services.....................................................................................................80

10.2 SBR ebMS3................................................................................................................80

11 APPENDIX B – Authorisation Error Messages................................................................82

12 Previous Version Control.................................................................................................84



1 INTRODUCTION1.1 PURPOSEThe purpose of this document is to provide information that will assist software developers in the implementation of calls to the web services offered by the Australian Taxation Office (ATO) through the Standard Business Reporting (SBR) platform.

1.2 AUDIENCEThe audience for this document is any organisation that will be building any ATO SBR services into their products. Typically this will be software application developers.

1.3 DOCUMENT CONTEXTThe ATO Common MIG forms part of the broader suite of documents used by the ATO to describe the way in which software developers must implement messages. In particular, it describes the ATO specific requirements to ensure those messages are both SBR and ATO compliant.

The ATO Service Registry contains service and message configuration data that describes the way in which web services are choreographed to create a composite service for SBR business collaborations for the ATO.

For ATO business collaborations, the Service suite is a package of documents as described in Figure 1 below. Each ATO Service specific package is supported by the ATO Common MIG.

For business collaborations produced prior to 2014, the Service Suite package is a single Message Implementation Guide (MIG) document which includes both the message structure and validation rules artefacts.

ATO SRATO Specific Service Registry

detailing services and platform configuration for ATO Web Services deployed to SBR

ATO MRATO Message Repository

This is the xml representationof the ATO messages for VRs.

CS Test CasesConformance

Test Casesfor a SWD to use in

testing their productand self certify against

CS CNConformance Suite

Cover Notedetailing the changes

from priorimplementations and

known defects

Test InstancesConformance Test Instances

for a SWD to use intesting their product

and self certify against

XBRLXBRL

CS Key StoreConformance Suite

Key Storecontaining AUSkeys for

a SWD to use whentesting their product

AUSAUS

MSTATO Message Structure Table

detailing the message body construct for a

service/obligation

ATO cMIGATO Common MessageImplementation Guide

containing common information for services/

obligations

ATO PCNATO Package Content Note

Package content note detailing artefacts within the

package and their status

Service Suite Zip

Conformance Suite Zip

ATO cBIGATO Common Business

Implementation Guidecontaining common

business informationfor services/obligations

ATO BIGATO Business

Implementation Guidecontaining specific business

Information for a service/obligation

ATO CS Package Contents

Package content note detailing artefacts within the

package and their status

ATO ALATO Artefacts and Location

Contains links to current artefactsand packages

ATO TPDecTaxpayer Declaration Guideprovides guidance regarding

the provision of taxpayer declarations lodged to the ATO

SchematronATO Message Rule

Implementationpertaining to the

service/obligationto be developed

TT

VRsSBR/ATO

Validation Rulespertaining to the

service/obligationto be developed

Contracts and Samples *Used for JSON and XML

ATO SDMAPSATO Site and Document Maps (bonus: Acronyms)Shows the ATO structure of relevant information onsbr.gov.au and SBR Share File, along with the ATO

document map and Acronyms/Initialisms

Service/Message information Test information

Figure 1: ATO Service Suite package.



This ATO Common MIG describes the rules and guidelines for the SBR platform that are common across all ATO business collaborations, including both reporting obligations and business services. Specifically, this document describes the implementation context of the ATO in relation to SBR, and guidelines on interpreting the validation rules and message structures described within each ATO Service Suite package.

This document is to be read in conjunction with the other documents that make up the ATO documentation suite as described in section 1.4 below, including the ATO Service Suite package for the ATO business collaboration(s) being developed.

Where there are variations to the general instructions contained within this document, the ATO Service Registry will identify these variations by exception.

The ATO Common MIG shares many common parts with the SBR Cores Services and SBR ebMS3 web service implementation guides (WIGs), which are commonly referenced in this document. It is recommended that this document and the SBR WIGs are read in conjunction with one another.

1.4 ATO DOCUMENTATION SUITEThe following table lists and describes the artefacts released by the ATO that support the development of software designed to use the SBR channel, including those that form each ATO Service Suite package. Each package (other than the conformance suite) may be accessed from the SBR website at http://www.sbr.gov.au/software-developers/developer-tools/ato

Artefact Scope Description Format(s)

ATO Artefact and Locations

ATO Contains links to current artefacts and packages.

XLSX

ATO Site and Document Maps

ATO Describes the relationship between the artefacts required for delivery of ATO SBR web services and the structure of published content.

XLSX

ATO SBR Service Registry

ATO Registry of all SBR web services delivered by the ATO.

XLSX

ATO Common MIG ATO (This document) Instructions common to many ATO forms, schedules and services.

DOCX

ATO Common Business Implementation Guide (BIG)

ATO Business information common to many ATO forms, schedules and services.

DOCX

ATO Taxpayer Declaration Guide

ATO Provides guidance regarding the provision of taxpayer declarations lodged to the ATO.

DOCX

ATO Message Repository ATO All error and warning messages used in ATO SBR web services.

ZIP of XML

ATO Package Content Note

ATO Provides information on the Service Suite package contents.

DOCX

Product-specific message structure

Product Lists and describes the contexts, data elements, tuples and headings in a particular ATO form, schedule or service. Contains a ‘context structure table’ and a ‘message structure table’.

XLSX


http://www.sbr.gov.au/


Artefact Scope Description Format(s)

Product-specific validation rules

Product Validation rules applicable to an ATO form, schedule or service. Includes ‘common module rules’, ‘domain definitions’ in addition to ‘product-specific rules’.

XLSX

Schematron Product The schematron rules and messages specific to an ATO form, schedule or service.

ZIP of Schematron

Contracts and Samples Product Contains the contract shcemas and samples.

Zip of XML or JSON

Conformance suite Product Test cases in the conformance suite to be executed by software developers as part of the self-certification process for a particular ATO reporting obligation or service. Available on request from the SBR Service Desk.

DOCX

Zip ofXBRL

Table 1: ATO Document Suite

1.5 SUPPORTING DOCUMENTATIONDocument DescriptionThe SBR taxonomy architecture document

http://www.sbr.gov.au/__data/assets/pdf_file/0007/36907/SBR_AU_Taxonomy_Architecture_v14.0-_20120827_.pdf Reference document that describes the structure of the SBR taxonomy, its naming conventions, release management and change control, and how each business interaction fits within the architecture.

It should be noted that even though the SBR taxonomy is expressed using XBRL terminology, it represents a logical data model that may be implemented using non-XBRL data formats (e.g. XML or JSON).

The SBR web service implementation guides

SBR Core Services .

SBR ebMS3.

Technical interface data that is common to all business processes and messages that use the SBR channel. Contains ·web service protocol specifications, standard message header structure, standard error codes, authentication protocol and trust broker.

The SBR software developer kit SBR Core Services

SBR ebMS3

SBR’s suite of implementation support products available to software developers; the technical context and a checklist of the key steps that software developers need to consider during their implementation of SBR.

Table 2: Supporting Documentation

1.6 CHANGE MANAGEMENTIf a material change is required to this MIG the document will be re-released.


http://www.sbr.gov.au/__data/assets/pdf_file/0007/36907/SBR_AU_Taxonomy_Architecture_v14.0-_20120827_.pdf

http://www.sbr.gov.au/__data/assets/pdf_file/0007/36907/SBR_AU_Taxonomy_Architecture_v14.0-_20120827_.pdf


1.7 GLOSSARYThe following table contains terms that are specific to the ATO. More general terms and acronyms in relation to SBR can be found at http://www.sbr.gov.au/software-developers/developer-tools/glossary .

Term Definition

Agent Tax agent or BAS agent. A request by an agent must include a registered agent number.

ATO product Documentation produced in order to support an SBR ATO business collaboration.

Business collaboration

An ATO business collaboration is a reporting obligation or a business service

Business document All the components that make up the design of an electronic message exchange which are organised in a certain hierarchy (structure) and sequence.

Collaboration A version of the reporting taxonomy which defines a particular business interaction comprised of a sequence of interactions between business and government.

Device AUSkey An AUSkey assigned to a device rather than an individual. (Refer to the SBR web service implementation guides).

Financial year The 12 month period between 01 July to 30 June. The period usually covered by Australian tax returns. Where a single year is used to describe a financial year, this represents the end of the period. For example, the 2014 financial year is the period 01 July 2013 to 30 June 2014.

Intermediary A person or organisation which acts as the middleman between clients and the ATO. The three key types of intermediaries are registered tax agents, BAS agents and fund managers.

Obligation Refers to a tax return or other ATO form or service, which may include zero, one or more schedules.

SBR Standard Business Reporting. When used in the context of a channel SBR covers both SBR Core Services and SBR ebMS3.

SBR Core Services The SBR channel that supports Standard Business Document Message (SBDM).

SBR ebMS3 The SBR channel that supports ebMS3.

Sender The entity sending the request message to the ATO via SBR. The entity can be an online (cloud) service provider or an intermediary or be same as the reporting party. The sender must have an AUSkey. (Refer to the SBR WIGs).

Taxpayer The entity to whom the reporting or lodgment obligation pertains.

Web service A web service is a software component that is described via web service description language (WSDL) and is capable of being accessed via standard network protocols such as but not limited to SOAP over HTTP.

Table 3: Glossary


http://sbr.gov.au/agency


2 BUSINESS CONTEXT2.1 PREREQUISITESPrior to performing any SBR interactions with the ATO a sender must:

register as an Australian business and obtain an ABN from the Australian Business Register (ABR)

obtain and install an AUSkey

link the AUSkey to the ATO

register people to gain ‘user’ level SBR credentials to perform tasks using the AUSkey with the ATO

register the required tax types with the ATO through one of the ATO portals (Business Portal, Tax Agent Portal, BAS Agent Portal).

If the sender is an online (cloud) service provider acting on behalf of another entity, then the entity must

register an online (cloud) service provider – client (entity) relationship with the ATO. Please refer to the Cloud Software Authentication and Authorisation Software Development Information Kit for more information.

If the sender is interacting on behalf of another entity as an intermediary, then the sender (or the entity itself) must:

register an ‘intermediary-reporting party’ relationship with the ATO.

If an online (cloud) service provider (sender) is interacting on behalf of an intermediary then the intermediary must:

register an online (cloud) service provider – client (entity) relationship with the ATO.

register an ‘intermediary-reporting party’ relationship with the ATO.

2.2 INTERACTIONSOnce a business has met the pre-requisites, that business may use SBR enabled software to access the SBR services made available by the ATO, that are supported by that software. As described in the web services implementation guides, this includes the list, prefill, prelodge/validate and lodge/submit web services.

The following business process model describes the process a sender follows when interacting with the ATO through the SBR channel. A sender may be the taxpayer, or a business acting on behalf of a taxpayer as an intermediary (such as a tax agent). This model ignores interactions beyond the scope of SBR such as post lodgment and payment interactions.



ATOSender

Register withABR and ATO

Choose service

Send List request

Sign in withAUSkey

Send Prefillrequest

Send Prelodgerequest

Prelodge?

Send Lodgerequest

Lodgment complete

Receive Listresponse

Receive Prefillresponse

Prepare lodgment

Receive Prelodgeresponse

Receive Lodgeresponse

Ok?

List

PrefillLodge/Prelodge

YES

NO

NOYES

Figure 2: Shows the process a sender follows interacting with the ATO using the SBR channel.



3 STANDARD BUSINESS REPORTING PLATFORMSThe first phase of the SBR program provided a platform that offers a collection of core services that are part of the implementation of the SBR initiative to simplify Business to Government reporting obligations.

Whilst that platform is currently still available for use, the next phase of the SBR program involves building and offering new services that are based upon the ebMS3/AS4 messaging standard.

The new SBR services differ from the previous SBR services mainly in the following ways:

Messaging is based on the ebMS3 standard and AS4 Conformance Profile The addition of support for batch and bulk interactions The addition of support for asynchronous single interactions The addition of support for a wider range of reporting obligations

The terms SBR Core Services and SBR ebMS3 as used in this document are defined as:

SBR Core Services

The current ‘legacy’ Whole of Government platform that:

provides the interface for SBR services for Business to Government reporting; and

routes received requests to the appropriate government agency system.

SBR ebMS3 The strategic Whole of Government platform that:

provides ebMS3 based SBR services for Business to Government reporting; and

routes received requests to the appropriate government agency system.

Table 4: SBR Core Services and SBR ebMS3 Definitions

In this document any statements that refer to “SBR” are to be taken to be refer to either SBR Core Services or SBR ebMS3 or both SBR Core Services and SBR ebMS3.

This document provides guidance for construction of request messages for both SBR Core Services and SBR ebMS3.

Request messages that are targeted for SBR Core Services must be constructed using the Standard Business Document Format in accordance with the instructions below that are specified as being for SBR Core Services.

Request messages that are targeted for SBR ebMS3 must be constructed using the ebMS3 Message Format in accordance with the instructions that are specified as being for SBR ebMS3.

Differences in response message formats coming from SBR Core Services and SBR ebMS3 will be similarly identified.

3.1 SBR ebMS3 INSTRUCTIONSAs defined in SBR ebMS3 Web Services Implementation guide, “Interaction” is the combination of the Service and Action invoked by an (external client) BMS (“BMS Invokable Interaction”). For example: LodgeCTR.001.00, ListAS.001.00, AddClientRole.001.00.



Every SBR ebMS3 Interaction that can be invoked by an (external client) BMS is defined to have certain attributes that indicate how it is supported by the eCommerce Platform. These attributes, known as “Service Attributes” are:

Request Message Type, Response Time Service Level, and Invocation Mode

3.1.1 Request Messages TypesThis section provides a high level overview of the compositions defined by the SBR ebMS3 Message Types.

In this document, a “Logical Record” is defined as the structured business request data that must be submitted for a single invocation of a particular BMS Invokable Interaction. Every Request Message sent to the ATO eCommerce Platform must contain at least one Logical Record.

For more information on the data, structure and order of message components, refer to Section 4 SBR ebMS3 Message Packaging.. The SBR ebMS3 channel accepts three distinct request message types:

3.1.1.1 Single RequestA Single Request Message must contain only one Logical Record for a specific Interaction e.g. ListAS, ValidateFBT, LodgeCTR.

A single request can either be submitted synchronously or asynchronously.

A single request can be sent containing either a “Service Request” (e.g. retrieve a list of accounts), a Standalone Form, or a Base Form with Optional Schedules:

Figure 3: Single Request Message Composition

Additionally, the Single Message Type logically has a sub-type called “Collect” – which is a special type of Single Request Message that is used to collect information or communications made available by an Australian Government Agency such as the ATO.



3.1.1.2 Bulk RequestA Bulk Request Message contains one Logical Record that is a multi-level construct comprised of a Parent (e.g.: Payer) and one or more Children (e.g.: Payees). The “Bulk” information is provided in the Children which are all of the same type and all relate to the Parent. In a Bulk Request Message each Child has a “business link” to the other children in that Request Message which is represented by the “Parent” e.g.: Private health insurance and member contribution statements. Like a batch, these requests can only be submitted in an asynchronous interaction pattern.

Figure 4: Bulk Request Message Composition

3.1.1.3 Batch RequestBatch messages serve as a container for multiple Logical Records. A Batch Request Message may contain multiple Logical Records of the same type (e.g.: Four LodgeCTRs) to be sent in one transmission, thereby facilitating what is effectively multiple invocations of an interaction using the one Request Message. A Batch Request Message can be one of 3 sub-Types:

Batch of Standalone Forms or Service Requests Batch of Base Forms with Optional Schedules Batch of Bulk Requests

Note that the Logical Records in a Batch Request must all be of the same type. All batch requests are asynchronous.



Figure 5: Batch Request Message Composition

3.2 SUPPORTED DATA FORMATSEach Logical Record may be expressed using one of the following data formats:

Data Format Abbreviation Data Format

XBRL Extensible Business Reporting Language

JSON Javascript Object Notation

XML Extensible Markup Language

For information on the data format used for a particular interaction please refer to the ATO Service Registry.

3.3 SBR ebMS3 SUPPORTED SERVICE INVOCATION TYPESATO supports all the invocation types as described in the SBR ebMS3 WIG. The ATO Service Registry describes the relevant invocation types for each ATO service implemented on the SBR ebMS3 platform.



3.3.1 Polling Interval

3.3.1.1 Pull-only PollingThe pull request messages are effectively used for polling for response messages.

For asynchronous requests the BMS shall poll for the response after a specific time interval. This section outlines the polling pattern for various asynchronous exchanges. The purpose for these directives is to police polling intervals via appropriate guidelines to ensure the service is not overloaded by requests. Polling intervals only applies to asynchronous interactions. As for synchronous interactions the BMS will halt the thread and wait for the response.

The time frames given in seconds and hours below are just indicative and not actual time frames.

3.3.1.1.1 Single 1. Initial attempt after 10 seconds.2. Second attempt after 20 seconds. I.e. Add 10 seconds for the second attempt.3. Third attempt after 40 seconds. I.e. double the second attempt.

Continue to double the time frame for each subsequent poll. Final poll at 180 seconds, as there is a timeout after 3 minutes for single

asynchronous requests.NOTE: If the maximum timeframe is reached without receiving the response a timeout would occur and a user message response will be generated and returned stating that there was an unexpected error and if the problem persists, contact the agency support.

3.3.1.1.2 Intermediate Batch1. Initial attempt after 30 seconds + 10 seconds for each document transmission.2. Second attempt after the same time frame as step 1. I.e. if the attempt above is a total

of 50 seconds, then the second poll can be repeated after another 50 seconds.3. For the third attempt, double the time frame of the previous attempt. I.e. Poll after 100

seconds.1. Continue to double the time frame for subsequent attempts.

NOTE: If a validation response is returned, reset the time and start again at step 1. Shouldn’t generally be required to poll after 1 hour since intermediate SLA is capped at 1 hour.

3.3.1.1.3 Delayed Batch/Bulk 1. Initial attempt after 1 hour + [10 seconds for each document in transmission].2. Second attempt after the same time frame as step 1. For example : If there were two

documents in transmission, the the first attempt would have occurred after 1 hour + 20 seconds. Therefore the second poll can be repeated after another 1 hour + 20 seconds.

3. For the third attempt, double the time frame of the previous attempt. I.e. For the above example, poll after 2 hours and 40 seconds. Continue to double the time frame for subsequent attempts until the polling interval

reaches 24 hours, after which doubling can stop and polling can continue on a once per day interval.

NOTE: If a validation response is returned reset the time and start again at step 1.



3.3.1.2 Intermediate Collect (“Push-and-Pull”) PollingCollect Polling differs from the above “Pull-only Polling” in that the “poll” actually uses a two-way/push-and-pull message exchange pattern rather than just a one-way/selective-pull message exchange pattern.

In the case of Collect Polling a BMS must:1. send a Push request for which it should receive a receipt (signal) message. 2. send a Pull request for which it may receive either:

a. an ebMS3 User Message that will contain a business response that may either:

i. contain the item sought to be collected; orii. information advising that the item to be collected is not yet available

for collection or that there are no items to collect. OR b. an ebMS3 Signal Message that is an error indicating that there is no

business response eplaced at all at that point in time.

If the response to the Pull request contains an ebMS3 User Message that does not contain the item sought to be collected then upon delivery of that ebMS3 User Message the two-way/push-and-pull message exchange will be complete and in order to make another “Collect Polling” attempt the BMS must initiate another two-way/push-and-pull message exchange to “poll” for the business response.

If the response to the Pull request is an ebMS3 Signal Message then it will be necessary for the BMS to engage in “Pull-only” polling (as described above) until it receives an ebMS3 User Message in response.

Therefore, it becomes necessary to provide polling interval guidance at two different levels:1) Collect Polling (i.e. how often should a two-way/push-and-pull be initiated in order to collect a specific item*); and2) Pull-only Polling (i.e. once the Push part of Collect Polling has been completed, how often should the Pull part of Collect Polling be attempted).

*This guidance for the timing of Collect Polling shall not preclude polling for two different business responses within a polling interval. For example , if a BMS polls for report A it can also poll for report B within the polling interval if either:

1) report A is of a different type to that of report B;2) report A or report B is an “on-demand”/requested report;

3.3.1.2.1 Collect Polling1. Initial attempt as indicated in the product specific message implementation guide related

to the item to be collected .2. Second attempt after the same time frame as step 1.3. For the third attempt, double the time frame of the previous attempt. 2. Continue to double the time frame for subsequent attempts ongoing.



3.3.1.2.2 Pull-only Polling within Collect Polling1. Initial attempt 5 minutes after receipt of the corresponding Push request ebMS3 receipt

signal message.2. Second attempt after the same time frame as step 1.3. For the third attempt, double the time frame of the previous attempt. 3. Continue to double the time frame for subsequent attempts ongoing.

When polling, the time frame occurrence is once a day. Doubling can stop and polling can continue on a once per day interval.



3.3.2 Submission Guidelines

Note: Software products should not multi-thread requests into SBR, unless each thread is being initiated via a direct end-user request. It is not allowable for software products if they have a stockpile of transactions to automatically within their software to spawn multiple threads to push them all through concurrently into SBR.

Message Type When to Use When not to Use Consequence of Message Type

Example

Single Sync or Single Async

Where single requests are being initiated by end users and a timely response is critical

When requests have been stockpiled by BMS, in this instance this stockpile should be sent as a batch request

If unexpected errors are encountered then the client will be returned a message typically along the lines of unexpected error has occurred please retry and if problem exists contact ATO. This means that the ownership belongs on the client to retry and contact ATO.

BAS agent lodges an Activity Statement (AS) when the client is present and receives an immediate response.

Where single requests are being system initiated and a timely response is critical to the system behaviour

For requests which are large in size, in this instance these requests should be sent as a bulk requests

Batch When single requests for different entities (same product and service action) have been stock piled for ‘end of day processing’

For requests which are large in size, in this instance these requests should be sent as a bulk requests

As long as the push of the message has occurred successfully; because the Batch/Bulk capability has state then if any unexpected errors occur then the ownership of resolving any issues reside with ATO to ensure that the appropriate response is generated so that the pull request will get a business response.Note: The client still has the responsibility to check the response to ensure that there were no validation errors etc.

A Tax Agent, as part of end of day processing, submits multiple Company Tax Return (CTR) with schedules for different clients and will review the result in the next morning.

Bulk When single request with multiple data records belonging to the same entity that is large in size

For requests which are not large in size, in this instance these requests should be sent as a batch requests

Bulk – A supplier submits a Taxable Payments Annual Report (TPAR) for a single client (payer) and will review the result in the next morning.

Batch of bulk – A

VERSION 3.0 UNCLASSIFIED PAGE 20 OF 85


Message Type When to Use When not to Use Consequence of Message Type

Example

supplier as part of end of day processing, submits Taxable Payments Annual Reports (TPAR) for several clients and will review the result in the next day.



4 SBR ebMS3 MESSAGE PACKAGING 4.1 OVERVIEW4.1.1 GeneralAll user messages sent to the ATO MUST conform to the minimum standards User Message structure specification in the SBR ebMS3 WIG.

Document metadata is captured differently between Single and Batch/Bulk messages due to differences in message structure.

Messages to and from SBR MUST be packaged using the SOAP messages with Attachments (SwA) standard. This section outlines the SwA message packaging format for various message exchange patterns supported by SBR.

Request Messages will basically comprised of: a Header; and a Payload.

Payloads are made up of one or more Logical Records.

For details on how this information applies to specific requests, refer to the Product Specific MIGs.

4.1.2 Supported AttachmentsThe table below outlines supported attachment file types and MIME types where an ATO ebMS3 service allows attachments. If a service allows attachments yet only a subset, this will be called in the ATO Service Registry.

MIME Type Filename extension

application/msword doc

application/pdf pdf

application/rtf rtf

application/vnd.ms-excel xls

image/tiff tif

image/jpeg jpg

image/bmp bmp

image/png png

image/gif gif

application/vnd.ms-project mpp

application/vnd.ms-powerpoint ppt

application/vnd.openxmlformats- docx



MIME Type Filename extension

officedocument.wordprocessingml.document

application/vnd.openxmlformats-officedocument.wordprocessingml.template

dotx

application/vnd.openxmlformats-officedocument.spreadsheetml.sheet xlsx

application/vnd.openxmlformats-officedocument.spreadsheetml.template

xltx

application/vnd.openxmlformats-officedocument.presentationml.presentation

pptx

application/vnd.openxmlformats-officedocument.presentationml.template

potx

application/vnd.openxmlformats-officedocument.presentationml.slideshow

ppsx

4.2 SINGLE REQUESTBoth synchronous and asynchronous single requests are requests which contain a Payload of only one Logical Record i.e. a single invocation is being requested for a specific service action e.g. ListAS, ValidateFBT, LodgeCTR and etc.

A Logical Record may however, be comprised of one or more “Logical Documents”.

For a Single Request Paylaod the business management software SHALL create a separate physical document for each Logical Document that forms part of the Single Request Payload.

Each of those physical documents SHALL be packaged as a separate ebMS3 MIME part in the ebMS3 user message.

However, the first MIME part, which must contain the ebMS3 header and the SOAP body SHALL contain an empty SOAP body and an ebMS3 header as per the guidelines in section 5.2.

4.2.1 Header – ebMS3 Header ContentebMS3 header content is detailed in Section 5 SBR ebMS3 Message Structure.

NOTE for base forms and schedules: The base form and each schedule should have a corresponding PartInfo Node in the header section. If there are no schedules, only PartInfo Node 1 for the base form should be populated.

4.2.2 Payload – ebMS3 Request MIME Part(s) Content

4.2.2.1 Single Non-Collect RequestIn a Single Non-Collect Request, a “Logical Record” and a “Payload” are equivalent since there is only one Logical Record. The Payload for Single requests can contain any one of the following:



1. a Base ‘Form’ with a number of attached schedules. Each Document within the Logical Record must have a corresponding PartInfo Node in the ebMS3 header of the message. Each schedule should be placed in a subsequent separate MIME Part which is shown as “MIME Part 3” to “MIME Part X” in the figure below.

2. a standalone (Base) Form; or3. a “Service Request” (e.g. a request to retrieve a list of accounts).

Figure 6: Single Non-Collect Request ebMS3 MIME Part Content

4.2.2.2 Collect RequestA Collect Request is a special type of Single Request. MIME Part 2 may contain either:

1) no payload i.e. empty MIME Part;OR

2) one payload/logical record to request to collect one item (e.g. one report) only (note that if there is a Collect Request Payload it must be prefixed by a Delimiter).



Figure 7 – Collect Request

4.3 SINGLE RECEIPTThe SBR ebMS3 WIG provides the specification for the single receipt structure.

4.4 SINGLE PULL REQUESTThe SBR ebMS3 WIG provides the specification for the single pull request structure.

4.5 SINGLE RESPONSE (NON-COLLECT)The ebMS3 message containing the response to a single non-Collect request will be an ebMS user message comprised of multiple MIME parts.

The first MIME part will contain an empty SOAP body and an ebMS header structure as per the guidelines in section 5.3.



The second MIME part will contain an Overall Event Message Block comprising of Processing Steps completed System and Processing Errors

The event structure is further explained in the SBR ebMS3 WIG.

The third MIME part will contain a Business Event Message Block (following the event structure) comprising of either:

Validation Report for the Logical Record in the request message1, or Errors/Warnings combined with Validation Report for the logical record2 in the request

message.

This MIME part is not returned if the request fails prior to reaching the validation stage (e.g. unexpected system error).Please refer to product-specific MIGs to find out the exact contents of this MIME part. The fourth MIME part is optional and may contain a Business Response for the logical record3. Some Request Messages, for example those that are only validated (i.e. most ‘Validate’ service actions) or that are not expected to return any “business data” will not include a Business Response.

1 If the logical record comprises of base form and one or more schedules, a single validation report is returned for the whole logical record.2 If the logical record comprised of base form and one or more schedules, backend errors/warnings are returned for the base form only.3 If the logical record comprised of base form and one or more schedules, the business response is returned for the base form only.



Figure 8: Single response Message packaging



4.6 COLLECT RESPONSE The ebMS3 message containing the response to a Collect request will be an ebMS user message comprising of two MIME parts as shown in the following diagram:

4.6.1 MIME Part 1The first MIME part (MIME Part 1 in the above diagram) shall contain an empty SOAP body and an ebMS3 header structured as per the guidelines in the SBR ebMS3 WIG.



4.6.2 MIME Part 2The first “block” in MIME Part 2 will be an Overall Event Message Block comprising of request level processing information, including:

Processing Steps completed System and Processing Errors


For a Collect response the rest of MIME Part 2 will contain:1. An optional Business Event Message Block (following the event structure) comprising of

either: Validation Report for the Collect Request, or Errors/Warnings combined with Validation Report for the Collect Request.

2. The business response comprised of the document or communication item that is sought to be collected from the ATO. The business response will be preceded by a meta-data record (a.k.a ‘Delimiter’).

In some cases the business response may be split into “Business Response Parts” (in order to improve manageability and scalability) and in such cases each Business Response Part will be prefixed by a Delimiter. These Delimiters will contain the information to allow assembly of the Business Response Parts into the complete Business Response (document or communication item). So for example, a complete list of all of the Superannuation Products and each of their respective details (as held by the ATO at a point in time) might be broken into multiple documents where each document (Business Response Part) contains the details for one Superannuation Product.



4.7 BATCH/BULK REQUEST4.7.1 OverviewFor Batch and Bulk requests the business management system (BMS) shall create an ebMS message comprising of two MIME parts as shown in the following diagram:

Figure 9: Batch/Bulk Request Message Packaging



4.7.2 ebMS3 MIME Part 1 Content

4.7.2.1 ebMS3 HeaderThe first MIME part (MIME Part 1 in the above diagram) shall contain an empty SOAP body and an ebMS3 header as per the guidelines in Section 5 SBR ebMS3 Message Structure.

NOTE: If multiple bulk records are contained within a message, a.k.a ‘a batch of bulks’, document type should be ‘BATCH’.

4.7.2.2 WS-Security HeadersPopulation of these headers should be done in accordance with the SBR ebMS3 Web Services Implementation Guide.

4.7.3 ebMS3 MIME Part 2 ContentAll Batch/Bulk requests (base forms including schedules) are to be placed in a single MIME Part which is shown as “MIME Part 2” in Figure 9: Batch/Bulk Request Message Packaging.MIME Part 2 shall contain all the documents for the Batch/Bulk request. The BMS shall order documents such that the Parent document must appear immediately before its related child documents (see the darker green boxes marked as “Logical Document 1,2,3 etc.” in MIME Part2 in the above diagram). The diagram below shows an example for how the documents should be packaged in Batch and Bulk requests:

- Metadata tagX

Service - CTR LodgeBatch

ParentX

Schedule AX

ParentX

X

ParentX

Schedule B

PAYG LodgeBatch of Bulk

PayerX

X

X

X

X Payer

Payee

Payee

Payee

Figure 10: Payload MIME part for Batch and Bulk Requests

A ‘record delimiter’ (a.k.a. ‘metadata tag’) shall be inserted before each document. The record delimiter contains information similar to the PartProperties sections within the ebMS3 Header. This information is used to correctly identify and process records within a message. Each document must be preceded with a record delimiter. This carriage return must be inserted


between each document and the immediately following separator record. An example record delimiter is provided below:

<Record_Delimiter DocumentID=”234356657659655” DocumentName=”CTR” DocumentType=”BASE” RelatedDocumentID=”” />

The Message specific parts of the Payload Info for each of the documents (the base form and the associated schedules) should be populated as follows:

4.7.3.1 Base/Parent Records

Field Value

For Each Delimiter

Record_Delimiter/@Name=DocumentIDUnique identifier applied to the document

e.g. 234356657659655

Record_Delimiter/@Name=DocumentName {BASE | PARENT PRODUCT NAME}e.g. CTR

Record_Delimiter/@Name =DocumentTypeBASE | PARENT

e.g. BASE

Record_Delimiter/@Name=RelatedDocumentID “”{BLANK}

Table 5: Base/Parent Form Record Delimiter Properties

4.7.3.2 Schedule/Child Records

Field Value

For Each Delimiter

Record_Delimiter/@Name=DocumentIDUnique identifier applied to the document

e.g. 234356657659655

Record_Delimiter/@Name=DocumentName

{SCHEDULE | CHILD PRODUCT NAME}e.g. IEE

Record_Delimiter/@Name =DocumentType

SCHEDULE | CHILD | BINARY

e.g. SCHEDULE

use BINARY when the schedule/child are base 64 encoded

Record_Delimiter/@Name=RelatedDocumentID

The ID of the base or parent form to which the schedule or child record relates:

e.g. 999356657659678

Record_Delimiter/@Name=ContentType

This attribute should be passed only if Record_Delimiter/@Name=DocumentType is set to BINARY.

Content type of the document.

e.g. application/pdf


Field Value

For Each Delimiter

Record_Delimiter/@Name=Filename

This attribute should be passed only if Record_Delimiter/@Name=DocumentType is set to BINARY

Filename for this document along with the extension e.g. Schedule1.pdf

Table 6: Schedule/Child Record Delimiter Properties

4.8 ELS TAG BATCH REQUEST For prior year returns in ELS tag format, the business management system (BMS) shall create an ebMS message comprising of two MIME parts.

The first MIME part shall contain an empty SOAP body and an emMS3 header that shall contain the ELS Approval Number.

The ELS Approval number is 5 digits and shall be provided by the BMS in the payload info section of the ebMS3 header. Any given ELS Approval number must be linked to the Registered Agent Number, which will be associated with the supplied AUSkey. The ELS Approval number is then passed into AS4 path property where the Batch and Bulk Request Processor can construct this as a Batch and Bulk request.

The second MIME part shall contain the ELS request as an attachment for the Batch/Bulk request and conform to the ELS transmission format (zip file with TXID and return files) as per the ELS user guide.

Figure 11: ELS Tag Request and Response Variants



The previous figure shows an example for how ELS Request messages should be packaged in Batch and Bulk requests.

4.9 BATCH/BULK RECEIPT The SBR ebMS3 WIG provides the specification for the batch/bulk receipt structure.

4.10BATCH/BULK PULL REQUESTThe SBR ebMS3 WIG provides the specification for the batch/bulk pull request structure.

4.11 BATCH/BULK RESPONSEThe ebMS3 message containing the response to a Batch/Bulk request will be an ebMS user message comprising of two MIME parts as shown in the following diagram:

Figure 12: Batch/Bulk Response Message Packaging



4.11.1 MIME Part 1The first MIME part (MIME Part 1 in the above diagram) shall contain an empty SOAP body and an ebMS3 header structured as per the guidelines in the SBR ebMS3 WIG.

4.11.2 MIME Part 2The first “block” in MIME Part 2 will be an Overall Event Message Block comprising of request level processing information, including:

Processing Steps completed System and Processing Errors

“Processing Steps completed” contains statistical information that provides an overview of the results of processing of the corresponding request message. Definitions and descriptions of the values returned in this statistical information is provided in the SBR eMS3 WIG.


For Bulk and Batch responses the rest of MIME Part 2 shall contain the individual responses to each of the Logical Records in the request message. Each of those responses are comprised of:

1. A Business Event Message Block (following the event structure) comprising of either: A Validation Report for the corresponding logical record in the request

message4, or Errors/Warnings combined with a Validation Report for the corresponding

logical record5 in the request message.Please refer to product-specific MIGs to find out the exact contents of Business Event Message Block.

2. [Optionally] A Business ResponseThere will be no Business Response for a corresponding Logical Record6 if the Request Messages are only being validated (i.e. most ‘Validate’ service actions) or are not expected to return any business data but instead just a processing result (e.g. some lodgements).

Each response to a Logical Record from the request message (i.e. the Business Event Message Block and the Business Response) within MIME Part 2 is prefixed by a separating metadata record (a.k.a. ‘Delimiter’). These delimiters will contain the information to correlate the Business Event Message Block and the Business Response to a specific Logical Record from the corresponding request message.

4.11.3 Number of Response MessagesA Batch Intermediate request will generate two responses. They are:

Acknowledgement Receipt supplied by SBR (See WIG for further details) Final Response – conforming to the above message packaging. It will contain both

the Business Event Message Blocks and the Business Responses (where applicable).

4 If the logical record comprises of either (a) base form and one or more schedules or (b) Parent and one or more Children, a single validation report is returned for whole logical record. 5 If the logical record comprises of either (a) base form and one or more schedules or (b) Parent and one or more Children, backend errors/warnings are returned for the base form or Parent only.6 If the logical record comprises of either (a) base form and one or more schedules or (b) Parent and one or more Children, the business response is returned for the base form or Parent only.



A Batch/Bulk Delayed request will generate 3 responses. They are: Acknowledgement Receipt supplied by SBR (See WIG for further details). Intermediate Response – conforming to the above message packaging, but does

not include any Business Responses. Also the Business Event Message Blocks will only contain Validation Reports.

Final Response – conforming to the above message packaging. It will contain both the Business Event Message Blocks and the Business Responses (where applicable).



5 SBR ebMS3 MESSAGE STRUCTUREThe message structure presented here details the ATO specifics of the general information provided in the SBR ebMS3 WIG. Only details that differ from that presented in the WIG are detailed here.

5.1 SECURITY HEADERRefer to the SBR ebMS3 WIG for more information.

5.2 ebMS HEADERRefer to the SBR ebMS3 WIG for more information.

5.3 eb:USERMESSAGE – SBR ebMS3 PROFILE5.3.1 OverviewThe following tables outline ATO specific values that are required within the ebMS3 header of a user message for SBR ebMS3 interactions in addition to those defined in the SBR ebMS3 WIG.

The use of double quotes in the specification of values in the following table is for delimiting purposes only and those double quotes do not form part of the value that the field should be set to.

5.3.1.1 eb:PartyInfo/eb:FromThe table below shows the ATO specific children elements require for eb:From, and their use within requests and responses.



Name Description Single Request2 Way Sync1 Way Push

Bulk/Batch1 Way Push

Response2 Way Sync1 Way Pull

Optionality

eb:PartyId String value that identifies a party.

The value of this element must be set to the corresponding party identifier for the party submitting the request message:a) Tax Agent Number (TAN) where the party submitting the request is a tax agent;ORb) Registered Agent Number (RAN) where the party submitting the request is a registered agent;ORc) ABN of the submitting entity, represented as an 11 digit number with no internal separator characters, where the party submitting the request is a Business or a Business Intermediary.

There MUST be one (and only one) “eb:From” eb:PartyId.

Same as single request. Set to ATO’s ABN i.e. “51 824 753 556 “.

Required






Optionality

eb:PartyId@type The type attribute indicates the domain of names to which the string in the content of the PartyId element belongs.

Set to match the corresponding type of the value that eb:PartyId has been set to i.e.:

a) http://ato.gov.au/PartyIdType/TAN where the value is a tax agent number;

or

b) http://ato.gov.au/PartyIdType/RAN where the value is a registered agent number;

orc) http://abr.gov.au/

PartyIdType/ABN where the value is an Australian Business Number.

Same as single request. Set by ATO e.g. when the PartyId is the ATO’s ABN this will be set to: “http://abr.gov.au/PartyIdType/ABN where the value is a unique Australian Buiness Number;”

Required






Optionality

eb:Role Identifies the authorized role of the Party sending the message.

Set to URI representing authorised roles:

a) http://sbr.gov.au/ ato/Role/Registered Agent where the party submitting the request is a registered agent (including tax agent);

orb) http://sbr.gov.au/

ato/Role/Business Intermediary where the party submitting the request is a Business Intermedairy;

orc) http://sbr.gov.au/

ato/Role/Business where the party submitting the request is a Business

Same as single request. Set to URI representing the role of the ATO:http://sbr.gov.au/agency

Required

Table 7: eb:From Structure


http://sbr.gov.au/ato/Role/Business

http://sbr.gov.au/ato/Role/Business

http://www.sbr.gov.au/software-developers/developer-tools/web-services

http://www.sbr.gov.au/software-developers/developer-tools/web-services

http://sbr.gov.au/agreement/Gateway/1.0/SelectivePull/PKI



http://www.sbr.gov.au/software-developers/developer-tools/ato




5.3.1.2 eb:PartyInfo/eb:ToThe table below shows the ATO specific children elements for eb:To, and their use within requests and responses.




Optionality

eb:PartyId String value that identifies a party.

Set to ATO’s ABN i.e. “51824753556 “.There MUST be one (and only one) “eb:To” eb:PartyId.

Same as single request. Copy from PartyInfo.From.Party Id of related Request Message.

Required

eb:PartyId@type The type attribute indicates the domain of names to which the string in the content of the PartyId element belongs.

Set to http://abr.gov.au/PartyIdType/ABN where the value is an Australian Business Number.

Same as single request. Copy from PartyInfo.From.Party Id of related Request Message.

Required

eb:Role Identifies the authorized role of the Party receiving the message.

Set to URI representing the role of the ATO:“http://sbr.gov.au/agency”

Same as single request Copy from PartyInfo.From.Role of related Request Message.

Required

Table 8: eb:To Structure

5.3.2 eb:UserMessage/eb:CollaborationInfoThe table below shows the children elements for eb:CollaborationInfo, and their use within requests and responses.




Optionality

eb: AgreementRef String element that identifies the entity or artefact governing the exchange of messages between the parties

Set by BMS to URI for pMode file that relates to this MEP. pMode URI’s are specified in

Same as single request. Set by agency to the corresponding value in the request.

Required






Optionality

Appendix A.

eb:Service String identifying the service that acts on the message.

Set by BMS to the Service Name defined in the ATO product-specific MIG.

Same as single request. Set by agency to the same value as in request.

Required

eb:Action String element that identifies an operation or an activity within a Service.

Set by BMS to the Service Name defined in the ATO product-specific MIG.


Required

eb:ConversationId String element that identifies the set of related messages that make up a conversation between Parties.

Set to value defined in the SBR ebMS3 WIG.


Required

Table 9: eb:CollaborationInfo Structure

5.3.3 eb:PayloadInfo/eb:PartInfo/eb:PartPropertiesThe table below shows the ATO specific eb:Property elements and associated attribute values to be used.For single requests, a separate eb:PartInfo node is required for the base form and each schedule (e.g. A base form with 3 schedules will have 4 eb:PartInfo nodes)




Optionality

eb:Property@name Property Name Set by BMS to “DocumentName”.

Set by BMS to ”DocumentName”

Set by agency to ”DocumentName”

Required






Optionality

eb:Property DocumentName Set by BMS to the “Business Name” of the type of document contained in the MIME Part.e.g. CTR or NIPSS

Set by BMS to the “Business Name” of the type of document contained in the MIME Part.e.g. CTR or NIPSS

Identifies the type of the document contained in the MIME Parte.g. CTR or NIPSS etc.

Required

eb:Property@name Property Name Set by BMS to “DocumentType”

N/A Set by agency “DocumentType”

Conditionally Mandatory for Single.

Eb:Property DocumentType Indicates the business type of the business document/s. Must be set to one of the following :“BASE”“SCHEDULE”

Must be set to one of the following:“BATCH”“BULK”

Describes the message packaging used to transport the business document/s. Must be set to one of the following:“BATCH”“BULK”“BASE”

Required

eb:Property@name Property Name N/A Set to “ELS Approval Number” for ELS “prior year” request messages.Only applicable for requests that are targeted from ELS.

N/A Conditionally Required

eb:Property ELS Approval Number N/A Set to [ELS Approval Number] “ for ELS “prior year” request messages.Only applicable for requests that are targeted from ELS.

Conditionally Required

Table 10: eb:PartProperties Structure



5.4 eb:SIGNALMESSAGE – ATO PROFILEThe following tables outline ATO specific values that are required to be inserted into the ebMS3 header of a signal message for various ELS2SBR interactions. The use of double quotes in the specification of values in the following table is for delimiting purposes only and those double quotes do not form part of the value that the field should be set to.

5.4.1 eb:SignalMessage/eb:MessageInfoThe table below shows the children elements for eb:MessageInfo, and their use within different types of Signal requests

Name Description Pull Request from BMS Receipt from SBR Error from SBR Optionality

eb:Timestamp Date at which the message header was created

Client MSH to set with DateTimestamp for the date:time that the pull request is sent to SBR ebMS3

SBR ebMS3 to set with DateTimestamp for the date:time that the receipt message is sent to the BMS

SBR ebMS3 to set with DateTimestamp for the date:time that the receipt message is sent to the BMS

Required

eb:MessageId Globally unique identifier conforming to MessageId [RFC2822]

Set by BMS Set by SBR ebMS3 Set by SBR ebMS3 Required

eb:RefToMessageId MessageId value of an ebMS Message to which this message relates, in a way that conforms to the MEP in use.

N/A Copy of MessageInfo.MessageId field from related Request Message

Copy of MessageInfo.MessageId field from related Request Message

Required depending on the type of Signal Message i.e. Error, Pull or Receipt

Table 11: ebMessageInfo Structure



5.4.2 eb:SignalMessage/eb:PullRequest

Name Description Pull Request from BMS Optionality

eb: RefToMessageId Selective pulling criteria as per ebMS3 advanced features, implemented by SBR ebMS3.

Set by BMS to the copy of MessageInfo.MessageId field from related Request Message i.e. the MessageId of the request message that this pull request is trying to pull the (business or validation) response to.

Required

Table 12: eb:PullRequest Structure

5.4.3 ebMS3 Signal-Receipt & Signal-Error Response MessageThere are no ATO specific ebMS3 signal response message field values.



6 GENERAL INSTRUCTIONS6.1 ANONYMOUS INTERACTIONS ATO offers both authenticated and anonymous services. By default all ATO services are authenticated unless specified otherwise. If a service is anonymous this shall be specified in the appropriate interaction section, row “SBR Core Services Security Implementation” in the service specific message implementation guide. Not every service specified in a message implementation guide can be anonymous.

6.2 AUTHORISATION OF ONLINE (CLOUD) SERVICE PROVIDERSFor all SBR cloud request messages, ATO will check against its records that the sender (online (cloud) service provider) can submit the message to SBR on behalf of the entity (Reporting Party or Intermediary).

For these submissions Software ID must be provided otherwise authorisation will fail. If an online(cloud) service provider is lodging for themselves then a Software ID must not be provided.

If authorisation fails, then a response message with the authorisation error will be returned. Please refer to Appendix B for the list of error messages associated with authorisation.

Sections 6.2.1 and 6.2.2 describe the implementation of the Software ID in each message. Please refer to the Cloud Services Authentication and Authorisation Implementation guide for more information.

6.2.1 Software ID for SBR Core Services The request message will incorporate a new element called “softwareSubscriptionId” in the namespace “http://sbr.gov.au/identifier/softwareSubscriptionId”. This element can be added into the message after the message generation process is completed (including signing).

There are 2 options for setting the Software ID in the requests for SBR Core Services;

Using the .NET SBR Core Services Requester (SBR CSR) component – Either “Request Factory” or “Request” may be used.

Using the Java SBR Core Services Requester (SBR CSR) component – Either “SBRCoreServicesRequestFactory” or “RequestInterface”may be used.

Please refer to the SBR Core Servcies SDK developer guide for more information.


http://www.sbr.gov.au/software-developers/developer-tools/glossary


6.2.2 Software ID for SBR ebMS3 A new Message Property called “SoftwareSubscriptionId” should be added. To do that the API of the RequestUserMessage class setMessageProperty (String name, String value) of the embeddable client can be used. The method allows adding a new property with the specified value to the generated message.

The location of the new property is shown in the diagram below. It is located in the eb namespace (http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/).Please refer to the SBR ebMS3 SDK developer guide for more information.

6.3 AUTHORISATION OF INTERMEDIARIESFor all SBR non-cloud request messages, ATO will check against its records that the sender (intermediary) is authorised to perform the requested action for the reporting party.

The checking will also compare the identity in the credential against the identity provided in the business document for the intermediary. If the sender is acting in their role as an agent, then a registered agent number must also be provided otherwise authorisation will fail.

For all SBR cloud request messages, ATO will check against its records that the intermediary is authorised for the following;

The online (cloud) service provider can submit the message to SBR on behalf of the intermediary (See Section 6.1)

The intermediary can perform the requested action on behalf of the reporting party.

If authorisation fails, then a response message with the authorisation error will be returned. Please refer to Appendix B for the list of error messages associated with authorisation.

6.4 DECLARATIONSThe ATO requires, for most business collaborations, a declaration indicating that the information contained in the submission is true and correct. This declaration may be made by


http://sbr.gov.au/identifier/softwareSubscriptionId

the reporting party or by an intermediary – a party acting on behalf of the reporting party, such as a registered tax agent.

To make a declaration, the intermediary or reporting party must be aware of two things:

1. the statement they are making, and

2. that it becomes a declaration by them ‘signing’ it.

As a result, in every case that a declaration is required to accompany a transaction, the intermediary or reporting party must have displayed to them:

a specific statement(s) describing what they are about to declare, and

an acknowledgment that the declaration is made by signing the statement(s) in a particular way.

The intermediary or reporting party signs by actively confirming what constitutes their ‘signature’ by using a tick-box, submit button, or similar mechanism. Their signature must be some information sent with the transaction that enables the sender to be uniquely identified within the business.

The wording of the declaration varies depending on whether the declarer is the reporting party or the intermediary and what type of AUSkey the intermediary or reporting party is using. The tables below describe each scenario and provide the wording for each declaration and suggested wording for the signing statements. In the tables, the placeholder <ATO Product> is to be replaced with the appropriate ATO product as defined in the ATO Service Registry. For those business collaborations that do not permit schedules, the phrase ‘and its related schedule(s)’ is to be omitted.

Where a specific business collaboration requires a different declaration or no declaration, this will be specified in the ATO Service Registry for that product.

Online (cloud) service providers sending a message on behalf of another entity (reporting party or an intermediary) must support case 2 and 4.

Case 1: A reporting party or an intermediary who is not a registered agent, is lodging via SBR using an AUSkey assigned to an individual.

Declaration statement The statement that the the reporting party or intermediary who is not a registered agent is declaring shall be:

“I declare that the information transmitted in this <ATO Product> is true and correct and that I am authorised to make this declaration”.

Signing statement The text describing the way that they are ‘making’ the declaration by ‘signing’ it in a particular way shall include reference to signing with the AUSkey.

For example:

“Tick this box to sign this declaration with the AUSkey you used to log in.”

A statement “Tick this box to sign this declaration” would not be acceptable as it does not state the identity the the reporting party or intermediary who is not a registered agent is using to make the declaration.

Case 2: A reporting party or an intermediary who is not a registered agent, is lodging via SBR using an AUSkey assigned to a device.

Declaration statement The statement that the reporting party or intermediary who is not a registered agentis declaring shall be:

“I declare that the information transmitted in this <ATO Product> is true and correct and that I am authorised to make this declaration.”

Signing statement The text describing the way that they are ‘making’ the declaration by ‘signing’ it in a particular way shall include reference to signing with the AUSkey for the device and the field giving a unique user identifier.

For example:

“Tick this box to sign this declaration with the AUSkey used by this software and your full name inserted above.”

A statement “Tick this box to sign this declaration” would not be acceptable as it does not state the identity the the reporting party or intermediary who is not a registered agent is using to make the declaration.

The user identifier must allow the AUSkey owner or an external auditor to uniquely identify the individual who made the declaration.

The identifier used can be specified by the AUSkey owner providing it allows identification as mentioned above. Examples of suitable identifiers include a user login, a full name, or an email address.

Case 3: An intermediary who is a registered agent is lodging via SBR using an AUSkey assigned to an individual.(For those returns forms that do not permit schedules, the phrase ‘and its related schedule(s)’ is omitted).

Declaration statement The statement that an intermediary who is a registered agent is declaring shall be:

“I declare that:

I have prepared this <ATO Product> and its related schedule(s) in accordance with the information supplied by the entity;

I have received a declaration made by the entity that the information provided to me for the preparation of this return is true and correct; and

I am authorised by the entity to give information in this return to the Commissioner.”

Signing statement The text describing the way that they are ‘making’ the declaration by ‘signing’ it in a particular way shall include reference to signing with the AUSkey.

For example:

“Tick this box to sign this declaration with the AUSkey you used to log in.”

A statement “Tick this box to sign this declaration” would not be acceptable as it does not state the identity an intermediary who is a registered agent is using to make the declaration.

Case 4: An intermediary who is a registered agent is lodging via SBR using an AUSkey assigned to a device.(For those returns forms that do not permit schedules, the phrase ‘and its related schedule(s)’ is omitted).

Declaration statement The statement that an intermediary who is a registered agent is declaring shall be:

“I declare that:

I have prepared this <ATO Product> and its related schedule(s) in accordance with the information supplied by the entity;

I have received a declaration made by the entity that the information provided to me for the preparation of this return is true and correct; and

I am authorised by the entity to give information in this return to the Commissioner.”

Signing statement The text describing the way that they are ‘making’ the declaration by ‘signing’ it in a particular way shall include reference to signing with the AUSkey for the device and the field giving a unique user identifier.

For example:

“Tick this box to sign this declaration with the AUSkey used by this software and your full name inserted above.”

A statement “Tick this box to sign this declaration” would not be acceptable as it does not state the identity an intermediary who is a registered agent is using to make the declaration.

The user identifier must allow the AUSkey owner or an external auditor to uniquely identify the individual who made the declaration.

The identifier used can be specified by the AUSkey owner providing it allows identification as mentioned above. Examples of suitable identifiers include a user login, a full name, or an email address.

6.5 RESPONSE MESSAGES6.5.1 Error messagesBusiness rules that are expected to be implemented by software developers are described in each of the product-specific validation rules spreadsheets. Each rule is associated with a response message code. Where a submission does not comply with a given rule, the associated message code will be returned.

Message codes returned by the ATO have the following format:

{Jurisdiction}.{Agency}.{Function}.{Id} where:

Jurisdiction = CMN (Commonwealth)

Agency = ATO

Function = GEN (General – can apply to many functions/forms); orForm specific, such as FBT, CTR, PTR, AS, SMSFAR, etc.

Id = function specific identifier.

For example: CMN.ATO.CTR.123456


6.5.2 Successful requestsIn the event of a successful request, for most (and all 2015 onwards) services, the following information message shall be returned (in addition to any warning messages):

Message Code Severity Code Short Description

CMN.ATO.GEN.OK Information Message Accepted

Note that a number of older SBR Core services: AS.0001, FBT.0001, FBT.0002 (2011-2014), PS.0001, PS.0002 and TFND.0001, use the following information response message:

Message Code Severity Code Short Description

SBR.GEN.GEN.OK Information Message Received Successfully

6.5.3 Statistical InformationEach response message will contain an Overall Event Message (the structure of the Overall Event Message is defined in the SBR ebMS3 Web Service Implementation Guide).

An overall event message will contain:

a. Statistical Information that provides an overview of the eplace of processing of the corresponding request message; and optionally

b. System and processing errors.

The Statistical Information (when available) will contain:

1) the summary information related to the number of transactions received as part of one transmission;

2) the number of transactions which were authorised and validated successfully or failed; and

3) the number of successes and failures from the processing of the transaction.

More particularly, each of the Statistical Information fields are as follows:



Text that is surrounded by curly braces (i.e “ { }”) is dynamic information.Dynamic Information is inserted as parameter values into the Short.Descriptions below (refer to the SBR ebMS3 Web Services Implementation Guide for details).

Error.Code Short.Description Description RulesSBR.GEN.INFO.1 Request Unsuccessful

ORRequest Successful

Indicates whether or not the related Request Message has been successfully processed.

If SBR.GEN.INFO.5, SBR.GEN.INFO.7, SBR.GEN.INFO.9 or SBR.GEN.INFO.10 have a count that is > 0 (i.e. there are errors during processing)

this is set to ‘Request Unsuccessful’elsethis is set to ‘Request Successful’

SBR.GEN.INFO.2 Total number of transactions in the related Request Message is {number}

Total number of transactions in the related Request Message

Where {number} is the total number of Logical Records in the related Request Message.

SBR.GEN.INFO.3 Processing completion indicator is {indicator}

Where {indicator} is TRUE or FALSE

Channel Processing completion indicator

Where {indicator} is set to TRUE this indicates channel processing has completed and where it is set to FALSE then channel processing has failed.

Applicable only for the service/actions which do not require backend processing. For other transactions, this field will not be available.

SBR.GEN.INFO.4 Number of transactions passed authorisation check is {number}

Number of transactions (logical records) passed authorisation check

Where {indicator} is the total number of Logical Records that have successfully passed authorisation.

SBR.GEN.INFO.5 Number of transactions failed authorisation check is {number}

Number of transactions (logical records) failed authorisation check

Where {indicator} is the total number of transactions (logical records) that have failed authorisation.

SBR.GEN.INFO.6 Number of transactions passed channel validation check is {number}

Number of transactions (logical records) passed channel validation

Where {indicator}’ is the total number of Logical Records that have successfully passed channel validation.

Channel validation here refers to the form validation as discussed in section 6.5



Error.Code Short.Description Description RulesNote. In a Bulk scenario the successful validation means that Parent and all associated Child records successfully passed their corresponding validations. The count corresponds to the number of parent level records.

SBR.GEN.INFO.7 Number of transactions failed channel validation check is {number}

Number of transactions (logical records) failed channel validation

Where {indicator}’ is the total number of Logical Records that have failed channel validation. The count corresponds to the number of Parent level records.

Channel validation here refers to the form validation as discussed in section 6.5.

Note. In a Bulk scenario the failed validation means that Parent or any of the associated Child records failed their corresponding validations.

SBR.GEN.INFO.8 Number of transactions successfully processed by the backend {number}

Number of transactions (logical records) successfully processed by the backend

This field will keep a count of the number of Logical Records that were successfully processed in the backend for interactive* forms/services. It will not be present for Service Actions involving non-interactive* forms/services.The count corresponds to the number of parent level records.

SBR.GEN.INFO.9 Number of transactions failed the backend processing {number}

Number of transactions (logical records) failed the backend processing

This field will keep a count of the number of Logical Records that failed backend processing for interactive* forms/services. It will not be present for non-interactive* forms/services.The count corresponds to the number of parent level records.

SBR.GEN.INFO.10 Number of unexpected errors is {number}

Number of transactions (logical records) incurred unexpected errors

This field is used to keep a count of unexpected errors that occurred whilst attempting to process the logical records in the related Request Message (which means that the processing result of some records can’t be defined as success or failure). The errors will be tracked at a logical record level.

The “unexpected errors” category comprises of all errors other than authorisation, validation and backend system errors. These are the ATO eCommerce Platform’s technical system errors e.g. database failure.

The count for this statistical field will be set to X, where X is the number of logical records that fail due to a technical system error in the eCommerce platform.



SBR.GEN.INFO.4-9 return separate “pass” and “fail” event counts for authorization, validation and backend processing because for Batch transactions all logical records in a batch may not all pass and some may fail these events. The pass counts are used to communicate number of logical records in a batch that have passed these events and the fail counts are used to communicate the number of logical records that have failed these events. For ‘singleton’ transactions there is only a single logical record in the request message so the count will be 1 for either the pass or the fail event depending on whether the logical record has passed the corresponding (validation/authorization/backend processing) event.

In case if any transmission level error occurs then it will be reported via additional last item in the overall message event block.

In case if this error occurred and record processing hasn’t completed then items SBR.GEN.INFO2, 4-10 might not be reported.

* interactive means that SBR services will get response from the backend system while non-interactive is fire and forget.



6.6 DATA FORMATS6.6.1 XBRL Instances

6.6.1.1 Monetary UnitsThe XBRL 2.1 specification requires that the Qnames used in unit definitions for monetary values MUST use ISO4217 currency designations for the local part, and MUST use a namespace of “http://www.xbrl.org/2003/iso4217”. Unit definitions for monetary currencies in XBRL instances within SBR MUST conform to these requirements. In particular, amounts representing Australian dollars MUST be associated with a unit definition that uses a currency designation of “AUD”.

Unless otherwise stated in the MST, all monetary amounts in XBRL instances must be expressed in Australian dollars.

6.6.1.2 Non Monetary UnitsUnless otherwise stated in the product-specific MST, all non monetary numeric values requiring units in XBRL instances must be expressed as xbrli:pure.

6.6.1.3 Measurement AccuracyThe XBRL 2.1 specification requires that each numeric item (apart from those whose value is a fraction) carry either a precision or decimals attribute allowing the creator of an XBRL instance to provide a statement of the accuracy of the provided value.

Unless otherwise stated in the relevant product-specific MST, when producing XBRL instances within SBR

1. non-financial numeric values, such as counts, SHOULD be provided with a value of ”0” for the decimals attribute.

2. financial amounts accurate to the dollar SHOULD be provided with a value of “0” for the decimals attribute.

3. financial amounts accurate to the cent SHOULD be provided with a value of “2” for the decimals attribute.

When consuming XBRL instances within SBR1. any digits considered to be insignificant SHOULD be replaced with zeros.

6.7 VALIDATION6.7.1 Payload validationEach Payload received by SBR undergoes validation will undergo validation that is specific to the data format of the Payload and the service action that is sought to be invoked for that Payload.

6.7.1.1 XBRL validationFor requests that contain a Payload that is in XBRL format the payload validation checks that the request message is valid XBRL that conforms to the SBR reporting taxonomy and definitional taxonomy. These checks are applied prior to the checks specified in the Validation Rules spreadsheet.



The table below lists the error messages that may be returned from XBRL payload validation and included in the response message. In most cases, more specific information about the error will be included in the detailed description.

SBR message code Short description

CMN.ATO.GEN.XBRL01 The message did not pass XBRL validation. Please contact your software provider.

CMN.ATO.GEN.XBRL02 The message was rejected due to a system error. Please contact your software provider.

CMN.ATO.GEN.XBRL03 A field contains invalid data (such as letters in numeric or date field).

CMN.ATO.GEN.XBRL04 A mandatory field has not been completed.

CMN.ATO.GEN.XBRL05 Invalid start or end datetime for duration period.

CMN.ATO.GEN.XBRL06 End date is earlier than start date.

CMN.ATO.GEN.XBRL07 Invalid value for end datetime of duration period or end datetime earlier than start datetime.

CMN.ATO.GEN.XBRL08 Invalid value for start datetime of duration period.

CMN.ATO.GEN.XBRL09 Invalid value for instant period datetime.

Table 13: XBRL Validation Error Messages

6.7.1.2 JSON ValidationFor requests that contain a Payload that is in JSON format the payload validation checks that the request message is valid JSON that conforms to the SBR reporting taxonomy and definitional taxonomy. These checks are applied prior to the checks specified in the Validation Rules spreadsheet.

The table below lists the error messages that may be returned by JSON validation and included in the response message. In most cases, more specific information about the error will be included in the detailed description.



SBR message code Short description

CMN.ATO.GEN.JSON01 The message did not pass JSON validation. Please contact your software provider.

CMN.ATO.GEN.JSON02 The message was rejected due to a system error. Please contact your software provider.

CMN.ATO.GEN.JSON03 A field contains invalid data (such as letters in numeric or date field).

CMN.ATO.GEN.JSON04 A mandatory field has not been completed.

CMN.ATO.GEN.JSON05 Invalid start or end datetime for duration period.

CMN.ATO.GEN.JSON06 End date is earlier than start date.

CMN.ATO.GEN.JSON07 Invalid value for end datetime of duration period or end datetime earlier than start datetime.

CMN.ATO.GEN.JSON08 Invalid value for start datetime of duration period.

CMN.ATO.GEN.JSON09 Invalid value for instant period datetime.

Table 14: JSON Validation Error Messages

6.7.2 SBR Core Services Validation PhasingValidation, as defined in the Validation rules spreadsheet, is applied in phases for ATO web services in the SBR Core Services platform such that validation will not progress to the next phase until the current phase is completely passed.

Following successful authentication, authorisation, and payload validation, the phases based on rule type are as follows:

1. Message Header checks

2. Payload validation (as described above)

3. XBRL contexts, formats, data types, lengths and enumerations

4. presence of mandatory fields (elements)

5. cross-field rules, calculations, comparisons, common module rules

6. cross-form (cross product) rules

7. warnings (for data that may be incorrect or incomplete).

As an example, if a company tax return (CTR) business document contained correct header information and passed the XBRL validator, but has one or more instances of incorrect XBRL context, the submission would result in a fail response message that would contain details of the invalid XBRL contexts, plus any format errors, incorrect data types, etc. No checks for missing mandatory fields, cross-field or cross-form errors will have been performed (other than those performed by the XBRL validator).

If any warnings occur, the business document will still be accepted and processed by the ATO. To correct these warnings, an amendment to the return may be submitted (for those business documents that allow for amendments via SBR).



6.8 RULE EXPRESSION6.8.1 ATO structured EnglishThe validation rules are written in ATO structured English. This is a type of pseudo-code used to ensure clarity in rule expression. Section 7, below explains each of the terms used in ATO structured English.

NOTE: Although ATO structured English refers to XBRL terminology, the validation rules they have equivalent application to payloads that are in implemented using the JSON/XML data format.

6.8.2 Form prefix labelsForm prefix labels may be used in validation rules to identify the business document of a given fact. These are used primarily where an interaction may involve more than one business document, such as those tax returns that include schedules. CTR for example, is a primary form (parent) with multiple associated schedules (child forms), such as IEE, CGT, IDS, etc.

For example:

CTR:RP:pyid.xx.xx:Identifiers.AustralianBusinessNumber.Identifier

refers to the ABN field in the CTR business document.

6.8.3 Context instance labelsContext instance labels describe the context and link a fact to a context. These labels appear in validation rule as a prefix to each fact.

For example:

RP.TOFA:bafpr1.xx.xx:Income.FinancialArrangementsUnrealisedGains.Amount

refers to the fact being reported in the context ‘RP.TOFA’, where the dimension ReportPartyType is set to “ReportingParty” and the dimension FinancialArrangementType is set to ‘TOFA’.

6.8.4 Absent form or context labelsWhere no form or context prefix (as described above) is provided for a fact within a rule, the rule applies regardless of form or context, for the form(s) in which the rule is specified. This allows a given rule to be specified once and re-used across multiple forms or contexts.

6.8.5 Use of xx.xx in fact namesIn the validation rules the version of an element may not be provided within the namespace prefix and instead be replaced with ‘xx.xx’. In an actual business document an XBRL fact must always include the namespace prefix including the correct version of the element. The correct version can be derived from the discoverable taxonomy set available on the SBR website (refer http://www.sbr.gov.au/software-developers/enabling-sbr-in-my-application/sbr-taxonomy/view-taxonomy).

For example, a validation rule may include:

bafpr1.xx.xx:Income.FinancialArrangementsUnrealisedGains.Amount

where ‘xx.xx’ refers to the version of the element consumed in the reporting taxonomy:

bafpr1.02.02:Income.FinancialArrangementsUnrealisedGains.Amount.

6.8.6 Use of aliasesIn order to make the validation rules more readable aliases have been used in some rules as a shorthand identifier for each fact. An alias used in a rule is enclosed in square brackets, for example, [CTR123]. The definition for each alias is defined in the Message structure spreadsheet..


http://sbr.gov.au/ato/Role/Business%20Intermediary

http://sbr.gov.au/ato/Role/Business%20Intermediary

6.8.7 Interpretation of NULLWhere a rule involves a calculation or a comparison with a number, NULL XBRL facts (xsi:nil=true or fact is absent) are treated as zero for the purposes of the calculation or comparison.

6.8.8 Boolean checksWhere a validation rule includes a check of a form or taxonomy element that has a Boolean data type, it is assumed that the element is not NULL and if the element is NULL then the check does not occur. For example, the expression

([X] <> TRUE) where X is an element with Boolean data type, should be interpreted as equivalent to

([X] = NULL OR [X] <> TRUE).Other interpretations such as “([X] <> NULL AND [X] <> TRUE)” are not correct, unless explicitly specified in the rule.

6.8.9 Use of domain in rulesWhere a rule compares an XBRL fact to a range of values, this range may be defined as a ‘domain’. In this case the values of the domain will be as specified in the product-specific Validation Rules spreadsheet.

6.8.10 Case sensitivityValidation rules that involve comparisons with string values are case insensitive. The case used in these rules often reflects the most common usage, however the case is not used in the comparison.

For example:

IF <a> = ‘Australia’ would be true if <a> was ‘australia’, ‘AUSTRALIA’, ‘Australia’ or ‘AuStRaLiA’.

However, for enumerations that are in the SBR taxonomy, values must match the case of the enumeration code. This is a requirement of XML. Enumerations that are not defined in the taxonomy (for example: suffix codes) are not case sensitive.

6.8.11Tuples and contextIn most SBR ATO interactions, all facts reported within a tuple instance (including nested tuples) use the same context. In some rare exceptions, there are facts within the same tuple that use different contexts.

6.8.12 Common modulesThe common modules worksheets within each product-specific Validation Rules spreadsheet list a set of rules that apply to certain common modules that may be present within the product. With some rare exceptions, these same rules consistently apply regardless of the ATO product.

The following list contains examples of the common modules currently used within ATO business collaborations:

addressdetails2.xx.xx:AddressDetails

declaration2.xx.xx:Declaration

electroniccontactelectronicmail1.xx.xx:ElectronicContactElectronicMail

electroniccontacttelephone1.xx.xx:ElectronicContactTelephone

financialinstitutionaccount1.xx.xx:FinancialInstitutionAccount

organisationname1.xx.xx:OrganisationNameDetails

organisationname2.xx.xx:OrganisationNameDetails

perioddetails1.xx.xx.PeriodDetails


personstructuredname3.xx.xx:PersonNameDetails

personunstructuredname1.xx.xx:PersonUnstructuredName.

For example, for each incidence of an ‘addressdetails2.xx.xx:addressdetails‘ tuple within a message, the ‘addressdetails2’ set of common module rules will apply. Further ‘product-specific’ rules may also apply to that same tuple.


7 ATO STRUCTURED ENGLISHThe validation rules are expressed in ATO structured English. The following table defines terms and characters used throughout these rules. Where that table refers to XBRL concepts, and a Logical Record is specified as being in JSON/XML format the corresponding equivalent JSON/XML concepts should be read in place of those XBRL concepts.

Structured English term

Intended interpretation Examples

- (as in <a> - )

Minus. <a> - Means value of ‘a’ minus the value of ‘b’.

- (as in SET(0-9)

Specifies a range of numeric or alphabetic values within a ‘SET’ construct.

= SET(0-3)Means is equal to 0, 1, 2 or 3.

= SET(a-z)Means is equal to a, b, c, d …(etc.)… or z.

DOES NOT CONTAIN SET(a-z)Means the field does not include any incidence of a lower case alphabetic character between a and z.

& Concatenate. Joins the value of a field to a literal or other field.

[TRT1]&”-06-30”Where [TRT1] is 2010, means 2010-06-30.

+/- In numerical calculations, allows for an allowable deviation.

<a> <> +/- 1Means (<a> > + 1) OR (<a> < - 1)

<a> = +/- 1Means (<a> >= - 1 ) AND (<a> <= + 1).

<> Not equal to. IF <a> <> Means if the value of ‘a’ is not equal to the value of ‘b’.

{x} A named (x) set.

The use of a named set is required when representing context definitions that contain segment(s) that can have more than one possible value.

RP.{ForeignCountry}

‘{ForeignCountry}’ represents the set of possible context segment values defined by the ‘ForeignCountry’ dimension. This dimension can be either an explicit or typed dimension.

When a reference to a specific instance of a set member is being made, the set name is used without curly braces, as in:

FOR EACH ForeignCountry IN SET (RP.{ForeignCountry})

Note: Where a list of explicit context definitions is defined, the notation “SET(RP.x,RP.y,RP.z)” is used.

{x=y} A specific value (y) in a named set (x)

Usage example:

RP.{ForeignCountry = ‘us’}

Refers to the context definitions where the foreign country context segment value = ‘us’.

ALGORITHM (with <Idtype> prefix)

Defines a test against a standard algorithm – as indicated by the <Idtype> prefix.<Idtype> can be ABN, TFN, TAN, ARBN or ACN.

IF TFNALGORITHM(<a>) = FALSEMeans if the TFN field <a> fails the TFN algorithm.

IF ABNALGORITHM(<a>) = FALSEMeans the ABN field <a> fails the ABN algorithm.

ALL OCCURRENCES OF

All instances of a given field or defined set of multiple fields, where the field/s are from a repeatable tuple or context.

(For testing values or sets of values in repeating tuples/contexts)

Usage examples:

EXAMPLE 1: SUM of multiple fields

IF SUM(ALL OCCURRENCES OF(<a> - )) <> <c>.

Means if the sum of every instance of <a>, minus the sum of every instance of is not equal to the value of <c> (where <a> and are from the same repeatable tuple/context).

EXAMPLE 2: Single field condition

IF ALL OCCURRENCES OF(<a>) > 10

Means if all instances of <a> are greater than 10 (where <a> is from a repeatable tuple/context).

EXAMPLE 3: Single field with multiple conditions

IF ALL OCCURRENCES OF(<a>) = SET(NULL,0)

Means if all instances of <a> are NULL or 0 (where <a> is from a repeatable tuple/context).

EXAMPLE 4: Multiple field conditions

IF ALL OCCURRENCES OF(<c>) = (<c> WHERE (<a> = NULL AND <> NULL))

Means if all instances of <a> is NULL and is not NULL in the same defined set (where both <a> and are from the same repeatable tuple/context <c>).

AND Logical AND.

ANY CHARACTER OF

Any character within a field.

(<context set>):ANY ELEMENT

Any element belonging to a context or set of contexts.

1) RP:ANY ELEMENT

Means the set of all elements belonging to the RP context

2) SET(RP,INT):ANY ELEMENT

Means the set of all elements belonging to either the RP or INT contexts.

3) IF COUNT(RP:ANY ELEMENT <> NULL ) = 0 RETURN VALIDATION MESSAGE ENDIF

Means if all elements in the RP context are null then return error.

ANY OCCURRENCE OF

Any instances of a given field or defined set of multiple field conditions, where the field/s are from a repeatable tuple or context. (For testing values or sets of values in repeating tuples/context).

Usage examples:EXAMPLE 1: Single field conditionIF ANY OCCURRENCE OF(<a>) > 10.

Means if any instance of <a> is greater than 10 (where <a> is from a repeatable tuple/context).

EXAMPLE 2: Single field with multiple conditionsIF ANY OCCURRENCE OF(<a>) = SET(NULL,0)Means if any instance of <a> is NULL or 0 (where <a> is from a repeatable tuple/context).EXAMPLE 3: Multiple field conditionsIF ANY OCCURRENCE OF(<c>) = (<c> WHERE (<a> = NULL AND <> NULL))Means if any instance of <a> is NULL and is not NULL in the same defined set (where both <a> and are from the repeatable tuple/context <c>).

ANY OTHER OCCURRENCE OF

For testing a value in one occurrence against other occurrences.

For elements, used to check if any given value for a particular element is repeated in the same element, where the element is part of a repeatable tuple or repeatable context instance.

For contexts, used to ensure context instances are unique where contexts with the same dimension segments are repeatable.

IF <a> = ANY OTHER OCCURRENCE OF <a>.

Means if the value of element <a> from one instance of a tuple or repeatable context, is equal to the value of another instance of the tuple/context.

IF CONTEXT(RP.{ForeignCountry}.{ActivityCode}) = ANY OTHER OCCURRENCE OF CONTEXT (RP.{ForeignCountry}.{ActivityCode}).

Means if context instance RP.{ForeignCountry}.{ActivityCode}, is equal to any other context instance with the same dimension segment ForeignCountry and ActivityCode values.

CONTAINS A string search for text within a field.

Usage: <a> CONTAINS .

IF <a> CONTAINS “UNKNOWN”.

Means if <a> contains or equals the word ‘unknown’.

CONTAINS MORE THAN ONE

A text field contains more than one incidence of a given string with the field.

IF pyde.xx.xx:ElectronicContact.ElectronicMail.Address.Text CONTAINS MORE THAN ONE “@”.

Means if there is more than one ‘@’ symbol within the email address.

CONTEXT Used to refer to a context instance.

Usage: CONTEXT(<A>)

where <A> is a context instance abbreviation e.g. RP.GST.CC

WHERE CONTEXT = “RPI.Closing”.

Means in instances where the context instance is ‘RPI.Closing’.

CONVERT_TO_DATE

Combines separate day, month and year fields into a single date.

Usage:

CONVERT_TO_DATE(<day>, <month>, <year>)

IF CONVERT_TO_DATE(<A>, , <C>) <> VALID DATE

Where: <A> = the element capturing the day of the month, = the element capturing the month, and represents the element capturing a year.

Means: if the values provided for <A>, and <C> when concatenated, are not equal to a valid date.

COUNT A count of the number of occurrences of a field or context instance.

IF COUNT(RPI) > 1

Means if the number of occurrences of the RPI context is more than 1.

IF COUNT([FRM1] > 1

Means if the number of occurrences of the element [FRM1] is more than 1.

IF COUNT(ForeignCountry) IN SET (RP.{ForeignCountry}.{ActivityCode}, RP.{ForeignCountry}) >3RETURN VALIDATION MESSAGEENDIF.

Means the count of distinct Foreign Country segment values across all context instances matching ‘RP.{ForeignCountry}.{ActivityCode}’ or ‘RP.{ForeignCountry}’.

COUNT(SCHEDULE)

Return the number of occurrences of a schedule that is attached to a parent return.

Usage: COUNT(SCHEDULE = <A>).

Where <A> is a schedule abbreviation e.g. DIS, IEE.

IF COUNT(SCHEDULE = “IEE”) > 50.

Means if the number of occurrence of an IEE schedule in the business document is greater than 50.

COUNT(SCHEDULE = IEE) = 0.

Means that there are no IEE schedules attached to the form being validated.

CURRENT FINANCIAL YEAR

The year that 30 June next occurs relative to the current system date.

IF <a> > CURRENT FINANCIAL YEAR.

If current system date is 01/08/2013, for example, means IF <a> is after 2014.

DATE(TODAY) Compares a date against the current date.

IF <a> > DATE(TODAY).

Means if <a> is a date in the future.

DIMENSION Test against a specific set of metadata for a particular context.

IF (RprtPyType.xx.xx:ReportingPartyTypeDimension = “RprtPyType.xx.xx:Intermediary”)Means if the Reporting Party Type context is ‘Intermediary’.

DOES NOT CONTAIN

An element has no instance of the stated value or set of values.

DOES NOT CONTAIN SET(“a-z”, “A-Z”, “0-9”).

Means that the field has no instance of an alphabetical character (excepting special characters), nor a numeric character.

DOMAIN A globally defined set of values.

Usage:

<a> = SET(DOMAIN()).

<a> is one of the values defined in .

SET (DOMAIN(COUNTRY CODES)

Means the complete set of country codes. Each set of domain values is defined in the Standard enumerations section within this document.

ENDSWITH A string searches for text at the end of a field

Usage:

<a> ENDSWITH .

IF <a> ENDSWITH “ T/A”.

Means the condition is true if field <a> contains a value that ends with the text string ‘ T/A’.

FOR ANY OCCURRENCE OF <object>

An instruction to process each instance of a repeating object, one at a time.

FOR ANY OCCURRENCE OF CONTEXT (RP) <test condition>

Means for every occurrence of context RP, apply the <test condition>.

FOR EACH <object> IN SET(…)

An instruction to process each object in a set/collection of objects, one at a time.

FOR EACH ForeignCountry IN SET (RP.{ForeignCountry})<test condition>.

Means for each unique ‘ForeignCountry’ segment value, apply the <test condition>.

FOUND A string search for text within a field performing a variation of the SET, CONTAINS, STARTSWITH and ENDSWITH functions.

Includes the following tests:

exact match,

match with a space on each side of the variable,

match with a space after the variable, and

match with a space before the variable.

Where multiple strings have been provided, a check for each string is performed.

Usage:

<A> = FOUND(,<C>).

IF <a> = FOUND(“The trustee”,”The Exec”).

Means if <a>:

equals ‘The trustee’ or ‘The Exec’ (exact match), or

contains ‘ The trustee ’ or ‘ The Exec ’ (a space on each side of either string), or

starts with ‘The trustee ’ or ‘The Exec ’ (with a space after either string), or

ends with ‘ The trustee’ or ‘ The Exec’ (with a space before either string).

IN TUPLE Restricts a test to the value of a field within a particular tuple (where the field may exist in more than one tuple).

(Refer also: ‘WHERE IN TUPLE’).

(1) IF <a> IN TUPLE().

Means if the value of <a> within the tuple . (Where <a> may also exist outside tuple ).

(2) IF ( IN TUPLE(<A>)) = NULLORBLANK

Means if tuple <A> does not exist or if in <A> is null or blank.

(3) IF COUNT( IN TUPLE(<A>)) > 1.

Means if the occurrence of in <A> is more than one.

(4) IN TUPLE(<A>) IF = NULLORBLANK

Means if in the tuple <A> is null or blank. In this example the rule will only trigger if <A> exists.

LENGTH Used to define the constraints on the length of a field.

(Refer also: TEXT).

IF LENGTH(<a>) < 6.

Means if the value of <a> does not contain at least 6 characters.

MONETARY() Defines a monetary field pattern where a true response is given when a value passes all conditions.

As in: MONETARY(<a>,,<c>)

Where:<a> = S or U to indicate if field can be signed or not. = Maximum number of digits (including decimal places).<c> = Maximum number of decimal places.

For <a> an S indicates a field can be prefixed with a ‘+’ or ‘-‘ sign, but may be omitted.

Where <a> is U, the field must not be prefixed with a sign.

The value of does not include a decimal point or sign in the total character limit.

<a> <> MONETARY(U,11,0).

Means <a> is not equal to a number in the range 0 to 99999999999, or includes a character other than 0 to 9.

<a> <> MONETARY(S,11,0).

Means <a> is not equal to a number in the range -99999999999 to 99999999999, or includes a character other than 0 to 9, or ‘+’ or ‘–‘ as the first (left-most) character.

<a> <> MONETARY(U,13,2).

Means <a> is not equal to a number in the range 0.00 and 99999999999.99, or includes a character other than 0 to 9 or a decimal point. (Decimal point may be omitted).

NOT Reverses the value of a eplace i.e. turns TRUE to FALSE and vice versa.

NULL Fact is not there, or has been specified to be null with xsi:nil indicator or is a null non-textual value.

IF <a> = NULL.

Means if a (non-textual) value for <a> is blank or if <a> does not exist.

NULLORBLANK Fact is not there, is null with xsi:nil = true or is a null string.(Applied to Text, Code, Description, and Identifier facts).

IF <a> = NULLORBLANK.

Means if a (textual) value for <a> is blank or if <a> does not exist.

NUMBER Defines a valid numeric field pattern where a true response is given when a value passes all conditions.

Usage: NUMBER(<a>,,<c>)

Where:<a> = S or U to indicate if field can be signed or not. = Maximum number of digits (including decimal places).<c> = Maximum number of decimal places.

For <a> an S indicates a field can be prefixed with a ‘+’ or ‘-‘ sign, but may be omitted.

Where <a> is U, the field must not be prefixed with a sign.

The value of does not include a decimal point or sign in the total character limit.

<a> <> NUMBER(U,11,0).

Means <a> is not equal to a number in the range 0 to 99999999999, or includes a character other than 0 to 9.

<a> <> NUMBER(S,11,0).

Means <a> is not equal to a number in the range -99999999999 to 99999999999, or includes a character other than 0 to 9, or ‘+’ or ‘–‘ as the first (left-most) character.

<a> <> NUMBER(U,13,2).

Means <a> is not equal to a number in the range 0.00 and 99999999999.99, or includes a character other than 0 to 9 or a decimal point. (Decimal point may be omitted).

NUMERIC Contains only digits, 0..9

OR Logical OR

PARENT RETURN Used on schedules to refer to the main ‘parent’ return associated with the schedule.

IF <a> <> PARENT RETURN(<a>).

Means if the value of <a> on the schedule is not equal to the value of <a> on the main form.

WHERE PARENT RETURN EXISTS.

Means apply the test if the business document includes a schedule associated with the main form.

POS The POS function is used to return ZERO for negative numbers, and the actual value for positive numbers.When value is NULL, function will return ZERO.Usage: POS(<a>)

Examples:POS([IITR321]) where;

[IITR321] = -52, result is 0

[IITR321] = 0, result is 0

[IITR321] = <NULL>, result is 0

[IITR321] = 1001, result is 1001

[IITR321] = 99.50, result is 99.50

ROUNDDOWN Round a number down to the nearest specified increment.

Usage: ROUNDDOWN(<A>,)

Where

<A> is the configurable increment to round down to

 is the value that is to be rounded down.

ROUNDDOWN(0.05,[CTR120])

Means round the value of CTR120 to the .05.

In this example, if [CTR120] = 99.93, the amount to be supplied for CTR120 is 99.90.

SCHEDULE Used on a main ‘parent’ form to refer to a schedule that could be attached to the parent return.

In terms of SBR, a schedule refers to a business document submitted within the same standard business document body structure as a business document for a main tax return form.

Usage: SCHEDULE = <A>.

IF COUNT(SCHEDULE = “S25A”) = 0.

Means if there is no instance of a Schedule 25A included in the business document body.

IF COUNT(SCHEDULE = “RSPT”) > 50.

Means if there are more than 50 occurrences of a Rental schedule in the business document body.

SET Defines an explicit set of values, where if one value meets the criteria for comparison, a true response is given.

IF <a> <> SET(“a”,”b”,”c”).

Means if <a> does not equal a or b or c.

IF <a> = SET(“a”,”b”,”c”)

Means if <a> is equal to a or b or c.

IF <a> = SET(0-3).

Means if <a> is equal to 0 or 1 or 2 or 3

STARTSWITH A string searches for text at the start of a field.

Usage: <a> STARTSWITH 

IF <a> STARTSWITH “T/A”.

Means the condition is true if field <a> contains a value that starts with the text string ‘T/A’

SUM The sum of all instances of an element.

Usage: SUM(<A>),

where <A> is an element that appears in a repeating tuple or is a repeating element.

SUM(<a>)

Means the total value of all instances of <a>, when each <a> is added up.

TEXT() Used to define the maximum length of a textual field.

Definition of a valid text field pattern where a true response is given when a value passes all conditions.

Usage: TEXT(<a>)

Where <a> = Maximum number of characters

TRUE if the tested field is less than or equal to length <a>

(Refer also: LENGTH)

<a> <> TEXT(150).

Means the maximum number of characters allowable within field <a> is 150.

TUPLE Used to signify that the element (in brackets) is a tuple – a ‘container’ that may contain a group of two or more related data elements.

TUPLE(addressdetails2.xx.xx:AddressDetails)Means the fields that have been defined as belonging to the ‘addressdetails2.xx.xx:AddressDetails’ module.

VALID DATE A date that conforms to the xbrli:dateItemType datatype.

IF CONVERT_TO_DATE <> VALID DATE

Means if the converted date is not a valid date.

WHERE (tuple/context/set)

Indicates that the rule execution is dependent on the tuple, context or set existence.

Refer WHERE IN CONTEXT, WHERE IN TUPLE and WHERE…IN SET.

WHERE IN CONTEXT

Used to validate data elements which are logically grouped within a context.

Rule is executed within the bounds of each occurrence of a particular context.

Usage:

WHERE IN CONTEXT(<A>) IF ….

WHERE IN CONTEXT(RP) IF = NULLORBLANK

(Where is a fact in the RP context).

Means if the value of within the RP context is null or blank. In this example the rule will only trigger if the RP context exists and if (in the RP context) is null or blank.

WHERE …IN SET Used to validate data elements which are logically grouped within a set.

Rule is executed within the bounds of each occurrence of a set.

Usage:

WHERE <A> IN SET().

Refer also: {x}.

WHERE ForeignCountry = ’us’ IN SET (RP{ForeignCountry})

Means execute the rule if the ForeignCountry dimension value is ‘us’ in the ForeignCountry dimension within the RP context.

WHERE…. IN TUPLE(element definition)

The WHERE and IN TUPLE keywords are used when tuple element explicits are required.

The element including the tuple definition is to be considered as a whole.

(RP:pyde.xx.xx:AddressDetails.Line1.Text WHERE(TUPLE ELEMENT Address Usage = “BUS”) IN TUPLE(address2)) = NULLORBLANK.

Means Line 1 of the business address of the Reporting Party is not present.

Rule will trigger if:

RP context is not present, or

address2 tuple is not present, or

address2 tuple with Address Usage = ‘BUS’ is not present, or

Line1.Text in the address2 tuple with Address Usage = ‘BUS’ is not present.

WHERE IN TUPLE Used to validate data elements which are logically grouped within a tuple.

Rule is executed within the bounds of each occurrence of a tuple.

Usage:

WHERE IN TUPLE (<A>) IF ….

(Refer also IN TUPLE. The ‘WHERE’ keyword is optional).

WHERE IN TUPLE(<A>) IF = NULLORBLANK

(Where is a fact in tuple <A>)

Means if the value of within the tuple <A> is nullorblank. In this example the rule will only trigger if tuple <A> exists and if (in <A>) is null or blank.

Xbrli (\element definition)

‘xbrli’ is used to denote the reporting taxonomy root. Indicates a given tuple or element is not nested within another tuple.

This is used to differentiate elements that are repeated at different levels of the reporting taxonomy within a given business collaboration.

IN TUPLE (xbrli\organisationname2.xx.xx:OrganisationNameDetails).

Means in the tuple ‘organisationname2.xx.xx:OrganisationNameDetails’ that is not within another tuple.

In this example, the implication is that the ‘organisationname2.xx.xx:OrganisationNameDetails’ tuple also exists under another tuple within the product.

Table 15: ATO Structured English Guide


8 MESSAGE STRUCTURE SPREADSHEETSThe ATO supplies a separate Excel spreadsheet for each ATO product describing the message structure. These contain

one worksheet containing the Context structure table (CST);

one worksheet containing the Message structure table (MST); and

zero, one or more containing domain definitions.

The CST, MST and (where applicable) domain definitions together define the context, structure and attributes of the data elements.

The Message Structure Spreadsheets refer to XBRL concepts but may be used to describe message structures that are to be implemented in JSON/XML data formats. Where those spreadsheets refer to an XBRL concept, and payloads are specified as being in JSON/XML format, the equivalent JSON/XML concept should be read in place of that XBRL concept.

The following table describes each column in the context structure tables.

Column label DescriptionSeq Num Sequence number that provides a logical order to the context instances and

allows sorting of the table.Label For a heading shows the logical grouping of a context or context instance.

For a context instance, shows the abbreviated name of the context instance as used in the MST.

Start/Instant Date The start date or instant date expected for the context instance.End Date The end date expected for the context instance.Description Describes the context instance.Period Type Indicates whether the context instance is in relation to a ‘Duration’ or an

‘Instant’.Min Occurs The minimum number of occurrences the context instance must appear within

a valid business document.Max Occurs The maximum number of occurrences of a context instance that may appear

within a valid business document.Identifier Scheme The entity identifier scheme for the context instance.Identifier Value The value required to describe the entity as defined by the identifier scheme.Dimension #:Namespace Prefix

The namespace prefix of each dimension in the context instance.

Dimension #: Name The dimension name of each dimension in the context instance.Dimension #: Type Indicates whether the dimension is ‘Explicit’ or ‘Typed’.Dimension #: Value The value required for each dimension in the context instance.

Where a typed dimension is a container, each contained element and their respective values will be described. For dimensions or elements which require explicit values, the applicable physical values will be defined.

Dimension #: Element1

For ‘Typed’ dimensions. The name of the container element. The namespace prefix for this element is the same as the dimension namespace prefix

Dimension #: Alias1 The Alias (from the MST) where an element of type ‘context’ in the Message Structure table refers to a dimension value.

XML - XPath For XML based messages, will contain the full XPath expression describing where the element(s) using this context will be located.

JSON - JSONPath For JSON based messages, will contain the full JSONPath expression describing where the element(s) using this context will be located.

Table 16: CST Table Description

1 Important: These columns are being introduced as part of 2016 changes. These columns may not appear in MST artefacts first published prior to 2016 (i.e. if the MST filename contains year less than 2016).



The following table describes each column in the MSTs.

Column label DescriptionSeq Num Sequence number that provides a logical order to the facts within the

business document and allows sorting of the tableParent Seq Num The sequence number of the parent item under which the current item is

nested. This is used to represent physical and logical nesting of facts and tuples under headings and tuples.For example, a group of elements with a ParentSeqNum of 15 is nested under the item (heading or tuple) with the SeqNum of 15.

Alias The abbreviated identifier for a given fact. The alias may be used within validation rules (within square brackets) to describe that fact.

Element Type This indicates if the row refers to a fact, a tuple name, a heading, or context element (e.g. period dates and entity identifiers).A heading is an arbitrary name given to group facts and tuples in order to assist understanding but do not exist within the SBR reporting taxonomy.A context element is information that is contained within the context instance which includes entity identifiers, period dates and dimensions values.

Label The label of the fact, tuple, label or context element.For facts, these are the Report Labels in the SBR reporting taxonomy.

ELS Tag Where present, these show the ELS tag identifier for a given fact. This aims to assist software developers familiar with ELS software specifications.2

Min Occurs Indicates the minimum number of occurrences a fact or tuple must appear within a context instance or enclosing tuple. Where a tuple is optional and a fact within that tuple is mandatory, the fact is only mandatory if the tuple is present within the business document.

Max Occurs Indicates the maximum number of occurrences a fact or tuple may appear within a context instance or enclosing tuple.

TREF ID A number allocated by the SBR program to uniquely identify a data element.

Namespace Prefix The abbreviated name for the class, including its version number, for the definitional taxonomy element.

Element Name The name of the definitional taxonomy element.

Context The context instance for a given fact or tuple. For facts within a tuple, this includes the values for any qualifiers. For example, each of the facts for an AddressDetails tuple will include values for the usage code and currency code, such as: ‘RP.[AddressDetails.Usage.Code=’BUS’].[AddressDetails.Currency.Code=’C’]’.

Period Type Indicates whether the fact has a period type of ‘Duration’ or ‘Instant’.

Balance Type3 Indicates whether the monetary item is a debit or credit.

Business DefinitionError! Bookmark not

defined.

The broad business definition of the data element from a ‘whole of government’ perspective.

Business Guidance Guidance provided when additional information is required to complement the business definition.

Report Guidance Provides specific guidance in regards to the use of the given fact within the report (e.g. element properties such as codes).

Legal Reference Where present, these show the legal references for a given fact.

Data Type The SBR taxonomy data type or the base data typePattern Defines the exact sequence of characters that are acceptable (e.g. regular

expression)

2 Important: The SBR data maps identify certain relationships that exist from paper forms, to ELS (Electronic Lodgment Services), and to SBR forms. They are provided as supplementary material to help you better understand the SBR requirements and SBR forms. However, the SBR data maps do not directly correspond to the paper forms or ELS tagged format. In some instances the SBR taxonomy maps a 'one to many' relationship of a label, or a label may not be required in SBR but is available on the paper form. Similarly there are some SBR requirements that may not be present on the paper form.3 Important: These columns are being introduced as part of 2016 changes. These columns may not appear in MST artefacts first published prior to 2016 (i.e. if the MST filename contains year less than 2016).



Column label DescriptionFull Enumeration Defines a list of acceptable values. List of valid values, separated by a “|”

characterMin Length Specifies the minimum number of characters or list items allowed. Must be

equal to or greater than zeroMax Length Specifies the maximum number of characters or list items allowed. Must be

equal to or greater than zeroTotal Digits Specifies the exact number of digits allowed. Must be greater than zero

Note: Used for defining a very small number of SBR AU Taxonomy data elements

Fractional Digits Specifies the maximum number of decimal places allowed. Must be equal to or greater than zero

Note: Used for defining a very small number of SBR AU Taxonomy data elements

XML - XPath For XML based messages, will contain the full XPath expression describing the element name and location.

JSON - JSONPath For JSON based messages, will contain the full JSONPath expression describing the element name and location.

Table 17: MST Table Description



9 VALIDATION RULES SPREADSHEETSThe ATO supplies the validation rules (VRs) within Excel spreadsheets. For each ATO product there is one or more spreadsheet(s) covering the rules for that product. This may include several worksheets:

one containing rules specific to the product;

zero, one or more describing the common module rules that apply to the product; and

zero, one or more containing the domain definitions.

All rules are applied by the ATO, so that if a business message does not comply with a validation rule (other than a warning), the message will be rejected.

Where common module rules are included, these apply for every instance of the common module (tuple) within the product.

Rules implemented via XBRL report design are generally not specified within the Validation rules spreadsheets.

If an error message is returned as a result of the validation rule, the element against which the rule is specified will be referenced in the location path of the response message.

Where a given validation rule involves more than one element (such as with cross-field and cross-form rules) the rule is specified only once against the element to which a location path will be returned.

The following table describes each column in the Validation rules spreadsheets.

Column label DescriptionSeq Num This is the sequence number of the fact, heading or tuple as defined in

the MST.Alias The abbreviated identifier for the fact as defined in the MST.Label The label of the fact, heading, tuple or context information as defined in

the MST.Context instance The context instance for a given fact or tuple.Element Name The name of the definitional taxonomy element, including namespace

prefix.English Business Rule A non-technical explanation of the rule.Legacy Rule Used for transition during the 2016/17 financial year.

Specifies the validation rule using Structured English.

Please refer to section 3.4 for details on the new Technical Business Rule format and Transition Plan

Technical Business Rule

For new services and those being transitioned during the 2016/17 financial year onwards, specifies the validation rule using the new Technical Business Rule format

For existing service specifications, this column specifies the validation rule using Structured English.

Please refer to section 3.4 for details on the new Technical Business Rule format and Transition Plan

Applies to XBRL Payloads Identifies if the validation rule applies to XBRL payloads. Valid values are: ‘Y’, ‘N’ or ‘n/a’

Y - rule is applied to a XBRL payloadN - rule is not applied to a XBRL payloadn/a - service does not use XBRL payloads

Applies to XML Payloads Identifies if the validation rule applies to XML payloads. Valid values



Column label Descriptionare: ‘Y’, ‘N’ or ‘n/a’

Y - rule is applied to a XML payloadN - rule is not applied to a XML payloadn/a - service does not use XML payloads

Applies to JSON Payloads Identifies if the validation rule applies to JSON payloads. Valid values are: ‘Y’, ‘N’ or ‘n/a’

Y - rule is applied to a JSON payloadN - rule is not applied to a JSON payloadn/a - service does not use JSON payloads

Rule Type Indicates the type of rule – Context, Format, Enumeration, Mandatory, Calculation, CrossForm, or CrossField. These, in part, determine the validation phase, as described above in section 3.4.2.

Schematron ID The Schematron ID for the rule.Message Code The response message code (identifier) returned when a request

message does not comply with the rule.The messages returned by the ATO are published in the ATO response messages XML file on the SBR website.

Message – Short Description

The response message short description corresponding to the Message Code. An additional detailed description may be available for the message code which is available in the ATO Response message repository.

Last Updated The date the rule was added or last changed since the prior version or prior business collaboration (where applicable).

Table 18: Validation Rule Table Description



10 APPENDIX A – PHYSICAL END POINTS

10.1 SBR CORE SERVICESPhysical end points for SBR Core Services can be found in Section 6.1.1 Service End Points in the SBR Core Services WIG.

10.2SBR EBMS3 10.2.1 EVTE

Logical Endpoint* Physical EndpointService Invocation Type Supported

Single Synchronous

https://test.ato.sbr.gov.au/services/Single-sync Single-Sync-Chatty

Single Asynchronous

https://test.ato.sbr.gov.au/services/Single-async-push-pull

Single-Async-Chatty

Bulk and Batch Push

https://test.ato.sbr.gov.au/services/BulkBatch-async-push

Batch-Async-IntermediateBatch-Async-DelayedBulk-Async-Delayed

Bulk and Batch Pull

https://test.ato.sbr.gov.au/services/BulkBatch-async-pull


Collect https://test.ato.sbr.gov.au/services/Collect-async

Collect-Async-Intermediate

Table 19: Physical Endpoints – EVTE

10.2.2 Production

Logical Endpoint* Physical EndpointService Invocation Type Supported

Single Synchronous https://ato.sbr.gov.au/services/Single-sync Single-Sync-Chatty

Single Push https://ato.sbr.gov.au/services/Single-async-push

Single-Async-Chatty

Single Pull https://ato.sbr.gov.au/services/Single-async-pull

Single-Async-Chatty

Bulk and Batch Push

https://ato.sbr.gov.au/services/BulkBatch-async-push


Bulk and Batch Pull https://ato.sbr.gov.au/services/BulkBatch-async-pull


Collect https://ato.sbr.gov.au/services/Collect-async

Collect-Async-Intermediate


https://ato.sbr.gov.au/services/Collect-async

https://ato.sbr.gov.au/services/Collect-async

https://ato.sbr.gov.au/services/BulkBatch-async-pull

https://ato.sbr.gov.au/services/BulkBatch-async-pull

https://test.ato.sbr.gov.au/services/Collect-async

https://test.ato.sbr.gov.au/services/Collect-async




Table 20: Physical Endpoints – PROD

10.2.3 pMode URI’s Production

Logical Endpoint Service Invocation Type Supported pMode URI

Single Synchronous Single-Sync-Chatty http://sbr.gov.au/agreement/Gateway/1.0/TwoWaySync/PKI

Single Asynchronous

Single-Async-Chatty http://sbr.gov.au/agreement/Gateway/1.0/TwoWayPushAndPull/PKI

Bulk and Batch Push Batch-Async-Intermediate

Batch-Async-Delayed

Bulk-Async-Delayed

http://sbr.gov.au/agreement/Gateway/1.0/Push/PKI

Bulk and Batch Pull Batch-Async-Intermediate

Batch-Async-Delayed

Bulk-Async-Delayed


Collect Collect-Async-Delayed http://sbr.gov.au/agreement/Gateway/1.0/TwoWayPushAndPull/PKI


http://sbr.gov.au/agreement/Gateway/1.0/TwoWayPushAndPull/PKI



http://www.sbr.gov.au/software-developers/developer-tools/common-components%20

http://www.sbr.gov.au/software-developers/developer-tools/common-components%20

http://sbr.gov.au/ato/Role/Registered%20Agent

http://sbr.gov.au/ato/Role/Registered%20Agent




http://sbr.gov.au/agreement/Gateway/1.0/TwoWaySync/PKI

http://sbr.gov.au/agreement/Gateway/1.0/TwoWaySync/PKI


11 APPENDIX B – AUTHORISATION ERROR MESSAGES

Error Code Short Description Long DescriptionSBR.GEN.AUTH.001 Mandatory information missing from

transmission. Contact your software provider.

Inform your software provider that the following element/attribute {AttributeName}1 was not found in the transmission.

SBR.GEN.AUTH.002 Mandatory information provided in the transmission is invalid. Contact your software provider.

Inform your software provider that the PartyId, PartyId Type and/or Role supplied in the transmission is not valid.

SBR.GEN.AUTH.003 Reporting party identifier information is missing from the lodgment.

SBR.GEN.AUTH.004 Check AUSkey details match the details of the user submitting the information.

Confirm the correct AUSkey has been selected to submit this lodgment.

SBR.GEN.AUTH.005 Misalignment of identifying information. Contact your software provider.

Inform your software provider that the eb:PartyInfo/From/PartyID details does not match the entity details for this submission.

SBR.GEN.AUTH.006 The software provider has not been nominated to secure your online (cloud) transmissions.

You have not nominated this software provider to secure transmissions made through online (cloud based) software.To resolve, please log on to Access Manager (AUSkey required) and select ‘my nominated software provider’ and follow the instructions to nominate a provider, or call the ATO.You will need provide the following details:Software provider name and/or their ABN and Software ID

SBR.GEN.AUTH.007 The software provider has not been accredited as an Online (cloud) Software Provider.

The software provider has not been accredited as an Online (cloud) Software Provider. Contact your software provider to resolve this issue.

SBR.GEN.AUTH.008 Your nomination with the online (cloud) software provider does not contain the correct Software ID.

Your nomination with the software provider does not contain the correct Software ID in Access Manager.To resolve, please log on to Access Manager (AUSkey required), select ‘my nominated software provider’ and update the nomination, or call the ATO.You will need provide the following details:Software provider name and/or their ABN and Software ID

SBR.GEN.AUTH.010 Your transaction failed due to a problem with the online (cloud) software provider’s system.

The AUSkey used by the software provider for securing online (cloud) transmissions made by the business is not enabled for these services. To resolve, please contact your software provider.

SBR.GEN.AUTH.011 The software provider has disabled your nomination.

The software provider has disabled your nomination.To resolve, please contact your software provider.

1 Parameter.Identifier = Attribute Name, Parameter.Text = “eb:PartyId/@Type”,”eb:PartyId”, “eb:Role”



Error Code Short Description Long DescriptionSBR.GEN.AUTH.012 Intermediary identifier information is

missing from the lodgment.SBR.GEN.AUTH.013 The ABN of the business being acted

on behalf of is required.SBR.GEN.AUTH.014 A client’s ABN, TFN, WPN or ARN is

required for this request.SBR.GEN.AUTH.015 You are not authorised to submit this

request. Review permissions in Access Manager and try again.

CMN.ATO.AUTH.001 Your registered agent number is not linked to this ABN.

Your registered agent number is not linked to the ABN of the selected AUSkey. Confirm the correct AUSkey has been selected to submit this lodgment. Or contact the ATO to resolve any issues with the registered agent number to ABN relationship.

CMN.ATO.AUTH.002 You are not authorised to lodge on behalf of this client.

You are not authorised to submit this lodgement on behalf of the client. Link this client to your registered agent number to create a client-to-agent relationship or see your AUSkey Administrator. If the client relationship exists, your AUSkey may not have access to this client.

CMN.ATO.AUTH.0042 No ATO reports currently available. Please try again later.

CMN.ATO.AUTH.005 Your AUSkey is not linked to this registered agent number in Access manager.

Contact your AUSkey administrator to authorise your AUSkey for this registered agent number and set up your permissions in Access manager.

CMN.ATO.AUTH.006 The requested report belongs to another intermediary. Review request details and try again.

CMN.ATO.AUTH.007 You do not have the correct permission to submit this request or retrieve this file.

Review your permissions in Access manager or contact your AUSkey Administrator.

CMN.ATO.AUTH.008 You are not authorised to lodge on behalf of this client.

You are not authorised to submit this lodgement on behalf of the client. Link this client to your eplacedn business number to create a business appointment or see your AUSkey Administrator. If the business appointment exists, your AUSkey may not have access to this client.

CMN.ATO.AUTH.009 Length of the Software ID must be 10 characters.

Length of the Software ID must be 10 characters. Contact your software provider to resolve this issue.

2 Message Severity Code for CMN.ATO.AUTH.0004 is “Information”



12PREVIOUS VERSION CONTROL


2.4 19/05/2016 Section 3 Standard Business Reporting Platforms

3.3 SBR ebMS3 Supported Service Invocation Types

3.3.2 Submission Guidelines - the following note was added for clarity:

Note: Software products should not multi-thread requests into SBR, unless each thread is being initiated via a direct end-user request. It is not allowable for software products if they have a stockpile of transactions to automatically within their software to spawn multiple threads to push them all through concurrently into SBR.

Section 12 Previous Version Control - section added and previous Version Control information moved due to size.

2.3 03/03/2016 Section 1.3 – Document Context

Figure 1: ATO MIG package updated to remove Release Note and include Package Content Note and Business Implementation Guides.

Section 3.2 – Supported Data Formats Added “XML” as one of the new data formats.

Added new section 3.3.2 – Submission GuidelinesAdded new section 6.1 – Anonymous servicesSections 6.8.1 – ATO Structured English and Section 7 – ATO Structured English

Updated to include “XML” as supported data format.

Section 8 – Message structure spreadsheets Updated the first paragraph to include domain definition

worksheet and XML message format. Added rows to Table 18 for 2 new CST columns:

o Dimension #: Elemento Dimension #: Alias

Added rows for Table 19 for 4 new MST columns:o Balance Typeo Business Definitiono Business Guidanceo Report Guidance

Added footnote for new entries to describe phased introduction of the new columns

2.2 19/11/2015 Appendix B – Authorisation errors Updated detailed error message descriptions for error codes

SBR.GEN.AUTH.006 and SBR.GEN.AUTH.008. Removed redundant error codes SBR.GEN.AUTH.009

and CMN.ATO.AUTH.003

2.1 15/10/2015 Appendix B – Authorisation errors Updated error message descriptions for existing

authorisation error codes. Updated to include new authorisation error codes and error

message descriptions.

2.0 23/07/2015 Section 1 Introduction

1.5 Supporting Documentation Sentence ‘It should be noted that even though the SBR

taxonomy is expressed using XBRL terminology, it represents a logical data model that may be implemented



Version Date Description of changesusing non-XBRL data formats (e.g. JSON).’ Added to the Description for The SBR taxonomy architecture document.

Section 3 Standard Business Reporting Platforms3.2 Supported Data Formats section and table added. Further sections renumbered.3.3 SBR ebMS3 Supported Service Invocation Types

Table 6: Logical Endpoints updated to include ‘Bulk-Async-Intermediate’ for ‘Bulk and Batch Push’

Section 4 SBR ebMS3 Message Packaging4.2.2.1 Single Non-Collect Request

XBRL removed on point 1.4.5 Single Response (non-collect)

Figure 8: Single Response Message Packaging updated to include JSON and clarification box for optional MIME parts.

4.6.2 MIME Part 2 Reference to XBRL deleted from the second paragraph in

point 2.4.732 ebMS3 MIME Part 2 Content

Reference to XBRL deleted.4.7.3.2 Schedule/Child Records

Reference to BINARY added for field Record_Delimiter/@Name =DocumentType

Fields Record_Delimiter/@Name=ContentType and Record_Delimiter/@Name=Filename added

Section 5 SBR ebMS3 Message Structure5.3.1.1 eb:PartyInfo/eb:From

‘Single Request 2 Way Sync 1 Way Push’ descriptions updated to provide clarity on which values are to be provided.

Section 6 General Instructions6.4.3 Statistical InformationError code table has been updated for clarification as follows:

SBR.GEN.INFO.1: Short description – ‘Transmission’ changed to ‘Request’. Description – changed from ‘Transmission Outcome’ to

‘Indicates whether or not the related Request Message has been successfully processed.’.

Rules – ‘Transmission’ changed to ‘Request’.SBR.GEN.INFO.2: Short description and Description – ‘Transmission’ changed

to ‘related Request Message’. Rules – ‘request message’ changed to ‘related Request

Message’.SBR.GEN.INFO.4: Description – reference to ‘logical records’ added.

SBR.GEN.INFO.5: Description – reference to ‘logical records’ added. Rules – sentence ‘Same as SBR.GEN.INFO.4, but this field

is used to keep a count of the total number of logical records that have failed authorisation deleted and the sentence ‘Where {indicator} is the total number of transactions (logical records) that have failed authorisation.’ Added.

SBR.GEN.INFO.6: Description – reference to ‘logical records’ added. Rules – re-worded for clarity.

SBR.GEN.INFO.7, 8 and 9: Description – reference to ‘logical records’ added. Rules – re-worded for clarity.

SBR.GEN.INFO.10: Description – reference to ‘logical records incurred

unexpected errors’ added. Rules – re-worded for clarity.

.Following added:



Version Date Description of changesIn case if any transmission level error occurs then it will be reported via additional last item in the overall message event block.In case if this error occurred and record processing hasn’t completed then items SBR.GEN.INFO2, 4-10 might not be reported.

* interactive means that SBR services will get response from the backend system while non-interactive – it is fire and forget.

6.6.1.2 JSON Validation section added along with error code table (figure 16)6.6.2 SBR Core Services Validation Phasing

Reference to ‘XBRL’ changed to now read ‘Payload’:6.7.1 ATO Structured English

New paragraph of ‘NOTE: Although ATO structured English refers to XBRL terminology, the validation rules they have equivalent application to payloads that are in implemented using the JSON data format.’ Added.

Section 7 Structured EnglishNew paragraph of ‘Where that table refers to XBRL concepts, and a Logical Record is specified (in the corresponding MIG) as being in JSON format the corresponding equivalent JSON concepts should be read in place of those XBRL concepts.’ Added.

Section 8 Message Structure SpreadsheetsNew paragraph of ‘The Message Structure Spreadsheets refer to XBRL concepts but may be used to describe message structures that are to be implemented in the JSON data format. Where those spreadsheets refer to an XBRL concept, and payloads are specified as being in JSON format the equivalent JSON concept should be read in place of that XBRL concept.’ Added.

1.9 18/06/2015 Updates to the ATO Common MIG to include “Cloud Software Authentication and Authorisation” solution.Section 1.7 – Glossary- Updated definition of “Sender”Section 2.1 – Prerequisites- Included prerequsites for Online (cloud) Service ProvidersSection 6.2 – Authorisation of intermediaries- Updated section to be specific about intermediary as a senderSection 6.3 – Declarations- -Updated references to “Sender” to be specific to reporting party

and intermediary.

Introduced new sections: Section 6.1 – Authorisation of online (cloud) service provider Section 6.1.1 – Software ID for SBR Core messages Section 6.1.2 – Software ID for SBR ebMS3 messages Appendix B – Authorisation errors

1.8 21/05/2015 Section 4.5- Added scenario when the Business event message mime part is not returned in a single non-collect responseSection 6.3.3- Updated the description of statistical information returned in overall event message blockSection 10.2.3- Updated the Collect pMode URI to be the same as Single-Async-Chatty

1.7 26/02/2015 Section 5.3.1.1Table 9: eb:From- Returned previously removed eb:Role.Section 5.3.1.2Table 10: eb:To- Returned previously removed eb:Role.



Version Date Description of changes1.6 24/02/2015 Section 6.3.2

- Updated to incorporate adjustments to successful messages for FBT and AS.

1.5 05/02/2015 Section 5.3.1.1Table 9: eb:From- Updated row eb:PartyId in ‘Single Request 2 Way Sync 1 Way

Push’ from Tax Agent Identifer to Tax Agent Number.- Updated row eb:PartyId@type ‘Single Request 2 Way Sync 1

Way Push’; removed and eplaced USI information.- Deleted row eb:Role.Section 5.3.1.2Table 10: eb:To- Updated row eb:PartyId@type ‘Single Request 2 Way Sync 1

Way Push’; removed and eplaced URN information and updated URL.

- Deleted row eb:Role.Section 8Table 19: MST Table Description- Added row ‘Legal Reference’ and description

1.4 17/12/2014 Changes:- Separated out collect response message to remove

inconsistency between text and diagram.- Amended polling interval specification for Collect pattern.- Fixed Batch/Bulk Request Message Diagram to add in Bulk

specification.- Added Key to various diagrams to indicate which “blocks” are

delimeters.- Added statistical reporting guidance information. – Section 6.3.3- Minor corrections to Delayed batch/Bulk Polling interval in

section 3.2.1.1.31.3 20/11/2014 Changes:

- Specification of Collect message type functionality- Corrections and additions relating to use of Logical Record

terminology.- Miscellaneous other corrections.- Appendix A named and split between SBR Core Services and

ebMS3.1.2.2 14/11/2014 Structured English Dictionary:

Modified ALL OCCURRENCES OF() function

1.2.1 03/11/2014 Merged v1.1.8 with v1.2 of the ATO Common MIGStructured English Dictionary:

Added POS() function Modified ANY OCCURRENCE OF() and ALL

OCCURRENCES OF() functionsXBRL Instance information: Added sections on Units and Measurement Accuracy.

1.2 17/04/2014 Section 5 – Updates to “Context Structure Table” column headings and descriptions.

1.1.8 11/08/2014 Aligned section 5.3 with sample messages in SDK developer guide.Updated Section 3 to introduce the concept of Logical Record.Updated Section 4.10 to differentiate between number of response messages for a Batch/Bulk Intermediate vs Batch/Bulk delayed.Updated Appendix A with the pmode URI’sUpdated Response Message Diagrams to remove X.509 Certificate and the WSSE Security headerUpdated Section 4.5 to reflect the Message Structure diagram in Figure 7.Aligned SRP and BBRP Response Structure with the platform implementation

1.1.7 04/06/2014 Minor changes for table definitions and document structure.

1.1.6 04/04/2014 Updated Single Async Chatty MEP to use ‘Two Way/Push and Pull. Updated Message Type description to provide more detailed examples.

1.1.5 04/03/2014 Aligned SBR ebMS3 channel information with latest ATO Common




MIG V1.1, applied minor formatting changes and other minor updates.

1.1.4 25/02/2014 Updates to ebMS3 header elements. Added single request message structure. Aligned with SWS Published MIG v1.1. Added description of parent child vs. base schedule. Moved Message Packaging from WIG. Added physical endpoints, added invocation types.

1.1.3 03/02/2014 Minor changes following Platform review.

1.1.2 17/12/2013 Minor changes following SBR review.

1.1.1 06/12/2013 Minor changes to cover SBR Core Services and SBR ebMS3 channels.

1.1 30/01/2014 Fixed minor typographical and formatting errors. Added ‘Dimension Type’ to Message Structure spreadsheets section. Updated status to ‘Production release’.

1.0 21/11/2013 Minor changes following ATO review and endorsement from Treasury.

0.1 15/10/2013 Initial draft. (Largely derived from ATO 2013 product-specific MIGs – using information common to most products).
