ATO Common Message Implementation Guide
advertisement
Standard
Business
Reporting
Australian Taxation Office
Common Message Implementation
Guide
Date: 19 November 2015
Status: Final – suitable for use
This document and its attachments are
Unclassified.
For further information or questions, contact the
SBR Service Desk at SBRServiceDesk@sbr.gov.au
or call 1300 488 231.
International callers may use +61-2-6216 5577
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
VERSION CONTROL
Version
Date
2.2
19/11/2015
Description of changes
Appendix B – Authorisation errors
Updated detailed error message descriptions for error
codes SBR.GEN.AUTH.006 and SBR.GEN.AUTH.008.
2.1
15/10/2015
Removed redundant error codes SBR.GEN.AUTH.009
and CMN.ATO.AUTH.003
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 using nonXBRL data formats (e.g. JSON).’ added to the Description for
The SBR taxonomy architecture document.
Section 3 Standard Business Reporting Platforms
3.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-AsyncIntermediate’ for ‘Bulk and Batch Push’
Section 4 SBR ebMS3 Message Packaging
4.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 Structure
5.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 Instructions
6.4.3 Statistical Information
Error 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
VERSION 2.2
UNCLASSIFIED
PAGE 2 OF 81
STANDARD BUSINESS REPORTING
Version
Date
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
Description of changes
‘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:
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 – 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 English
New 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 Spreadsheets
New 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
-
VERSION 2.2
Included prerequsites for Online (cloud) Service Providers
UNCLASSIFIED
PAGE 3 OF 81
STANDARD BUSINESS REPORTING
Version
Date
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
Description of changes
Section 6.2 - Authorisation of intermediaries
-
Updated section to be specific about intermediary as a
sender
Section 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 response
Section 6.3.3
Updated the description of statistical information
returned in overall event message block
Section 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.1
Table 9: eb:From
-
Returned previously removed eb:Role.
Section 5.3.1.2
Table 10: eb:To
1.6
24/02/2015
Section 6.3.2
-
1.5
05/02/2015
Returned previously removed eb:Role.
Updated to incorporate adjustments to successful
messages for FBT and AS.
Section 5.3.1.1
Table 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 repalced USI information.
-
Deleted row eb:Role.
Section 5.3.1.2
Table 10: eb:To
VERSION 2.2
-
Updated row eb:PartyId@type 'Single Request 2 Way Sync
1 Way Push'; removed and repalced URN information and
updated URL.
-
Deleted row eb:Role.
UNCLASSIFIED
PAGE 4 OF 81
STANDARD BUSINESS REPORTING
Version
Date
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
Description of changes
Section 8
Table 19: MST Table Description
-
1.4
1.3
1.2.2
17/12/2014
20/11/2014
14/11/2014
Added row ‘Legal Reference’ and description
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.3
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.
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 MIG
Structured English Dictionary:
Added POS() function
Modified ANY OCCURRENCE OF() and ALL
OCCURRENCES OF() functions
XBRL 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
VERSION 2.2
UNCLASSIFIED
PAGE 5 OF 81
STANDARD BUSINESS REPORTING
Version
Date
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
Description of changes
response messages for a Batch/Bulk Intermediate vs
Batch/Bulk delayed.
Updated Appendix A with the pmode URI’s
Updated Response Message Diagrams to remove X.509
Certificate and the WSSE Security header
Updated 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).
VERSION 2.2
UNCLASSIFIED
PAGE 6 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
ENDORSEMENT
APPROVAL
Chief Solutions Architect
Standard Business Reporting
Michael Ferris
Project Manager
Strategic Web Services
Australian Taxation Office
Copyright
© Commonwealth of Australia 2015 (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.
VERSION 2.2
UNCLASSIFIED
PAGE 7 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
Table of contents
1
2
3
4
5
6
Introduction .......................................................................................................................10
1.1
Purpose ....................................................................................................................10
1.2
Audience...................................................................................................................10
1.3
Document context .....................................................................................................10
1.4
ATO documentation suite .........................................................................................11
1.5
Supporting documentation ........................................................................................12
1.6
Change management ...............................................................................................12
1.7
Glossary ...................................................................................................................13
Business Context ..............................................................................................................14
2.1
Prerequisites .............................................................................................................14
2.2
Interactions ...............................................................................................................14
Standard Business Reporting Platforms ............................................................................16
3.1
SBR ebMS3 Instructions ...........................................................................................16
3.2
Supported Data Formats ...........................................................................................19
3.3
SBR ebMS3 Supported Service Invocation Types ....................................................19
SBR ebMS3 Message Packaging .....................................................................................24
4.1
Overview...................................................................................................................24
4.2
Single Request .........................................................................................................24
4.3
Single Receipt...........................................................................................................26
4.4
Single Pull Request ..................................................................................................26
4.5
Single Response (Non-Collect) .................................................................................27
4.6
Collect Response......................................................................................................29
4.7
Batch/Bulk Request ..................................................................................................31
4.8
ELS Tag Batch Request ...........................................................................................34
4.9
Batch/Bulk Receipt ...................................................................................................35
4.10
Batch/Bulk Pull Request ...........................................................................................35
4.11
Batch/Bulk Response...............................................................................................36
SBR ebMS3 Message Structure........................................................................................39
5.1
Security Header ........................................................................................................39
5.2
ebMS Header ...........................................................................................................39
5.3
eb:USERMESSAGE – SBR ebMS3 Profile ...............................................................39
5.4
eb:SIGNALMESSAGE – ATO Profile ........................................................................46
General Instructions ..........................................................................................................48
6.1
Authorisation of online (cloud) service providers .......................................................48
6.2
Authorisation of intermediaries ..................................................................................49
6.3
Declarations ..............................................................................................................49
6.4
Response messages ................................................................................................52
VERSION 2.2
UNCLASSIFIED
PAGE 8 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
6.5
Data Formats ............................................................................................................57
6.6
Validation ..................................................................................................................57
6.7
Rule Expression........................................................................................................60
7
ATO structured English .....................................................................................................63
8
Message Structure spreadsheets ......................................................................................75
9
Validation Rules spreadsheets ..........................................................................................77
10
11
APPENDIX A – Physical end points...............................................................................78
10.1
SBR Core Services ...................................................................................................78
10.2
SBR ebMS3 ..............................................................................................................78
APPENDIX B – Authorisation Error Messages...............................................................80
VERSION 2.2
UNCLASSIFIED
PAGE 9 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
1 INTRODUCTION
1.1 PURPOSE
The 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 AUDIENCE
The 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 CONTEXT
The 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.
A message implementation guide (MIG) 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 MIG is a package of documents as described in in Figure
1 below. Each ATO product-specific MIG package is supported by the ATO Common MIG.
For business collaborations produced prior to 2014, the MIG package is a single MIG document
which includes the both the Message structure and Validation rules artefacts.
Figure 1: ATO MIG package.
VERSION 2.2
UNCLASSIFIED
PAGE 10 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
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 MIG 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 MIG package for the
ATO business collaboration(s) being developed.
Where there are variations to the general instructions contained within this document, the
relevant ATO product-specific MIG 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 SUITE
The 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
MIG package. Each MIG (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)
High Level ATO Artefact
Map
ATO
Describes the relationship between the
artefacts required for delivery of ATO SBR
web services.
PDF
ATO SBR Service Registry ATO
Registry of all SBR web services delivered
by the ATO and their related artefacts.
XLSX
ATO Common MIG
ATO
(This document) Instructions common to
many ATO forms, schedules and services.
DOCX
ATO Message Repository
ATO
All error and warning messages used in ATO ZIP of XML
SBR web services.
Product-specific MIG
Product
Instructions specific to an ATO obligation
(form, schedule or service).
Product-specific message
structure
Product
Lists and describes the contexts, data
XLSX
elements, tuples and headings in a particular
ATO form, schedule or service. Contains a
‘context structure table’ and a ‘message
structure table’.
Product-specific validation
rules
Product
Validation rules applicable to an ATO form,
XLSX
schedule or service. Includes ‘common
module rules’, ‘domain definitions’ in addition
to ‘product-specific rules’.
Product-specific release
note
Product
Defines the list of changes between different
versions of business collaborations
DOCX
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
DOCX
VERSION 2.2
UNCLASSIFIED
DOCX
Zip of
PAGE 11 OF 81
STANDARD BUSINESS REPORTING
Artefact
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
Scope
Description
Format(s)
ATO reporting obligation or service. Available XBRL
on request from the SBR Service Desk.
Schematron
Product
The schematron rules and messages specific ZIP of
to an ATO form, schedule or service.
Schematron
Table 1: ATO Document Suite
1.5 SUPPORTING DOCUMENTATION
Document
Description
The SBR taxonomy architecture http://www.sbr.gov.au/software-developers/developertools/common-components
document
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. JSON).
The SBR web service
implementation guides
SBR Core Services - http://www.sbr.gov.au/softwaredevelopers/developer-tools/web-services
SBR ebMS3 – Available on request from the SBR Service Desk.
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 - http://www.sbr.gov.au/softwaredevelopers/developer-tools
SBR ebMS3 – Available on request from the SBR Service Desk.
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 MANAGEMENT
If a material change is required to this MIG the document will be re-released. The Taxonomy
Approval Committee must approve any change.
VERSION 2.2
UNCLASSIFIED
PAGE 12 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
1.7 GLOSSARY
The 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/softwaredevelopers/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
VERSION 2.2
UNCLASSIFIED
PAGE 13 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
2 BUSINESS CONTEXT
2.1 PREREQUISITES
Prior 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 INTERACTIONS
Once 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 full list of ATO products that make use of
SBR can be found at http://www.sbr.gov.au/software-developers/developer-tools/ato/.
Each product-specific MIG describes which web services are available for that business
collaboration.
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.
VERSION 2.2
UNCLASSIFIED
PAGE 14 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
Sender
ATO
Register with
ABR and ATO
Sign in with
AUSkey
Choose service
List
Lodge/Prelodge
Prefill
Send List request
Receive List
response
Send Prefill
request
Receive Prefill
response
Prepare lodgment
Prelodge?
YES
Lodgment complete
Send Prelodge
request
NO
Receive Prelodge
response
YES
Send Lodge
request
Ok?
NO
Receive Lodge
response
Figure 2: Shows the process a sender follows interacting with the ATO using the SBR
channel.
VERSION 2.2
UNCLASSIFIED
PAGE 15 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
3 STANDARD BUSINESS REPORTING PLATFORMS
The 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
SBR ebMS3
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.
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 INSTRUCTIONS
As 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.
VERSION 2.2
UNCLASSIFIED
PAGE 16 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
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 Types
This 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 Request
A 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.
VERSION 2.2
UNCLASSIFIED
PAGE 17 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
3.1.1.2 Bulk Request
A 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 Request
Batch 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.
VERSION 2.2
UNCLASSIFIED
PAGE 18 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
Figure 5: Batch Request Message Composition
3.2 SUPPORTED DATA FORMATS
Each 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
For information on the data format used for a particular interaction please refer to the
corresponding service specific MIG.
3.3 SBR ebMS3 SUPPORTED SERVICE INVOCATION TYPES
ATO supports the following combinations of service attributes for invocation of its SBR ebMS3
services:
Message Type
Invocation Modes
Response
TimeService Level
Service Invocation
Type
Single
Synchronous
Chatty
Single-Sync-Chatty
Single
Asynchronous
Chatty
Single-Async-Chatty
VERSION 2.2
UNCLASSIFIED
PAGE 19 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
Message Type
Invocation Modes
Response
TimeService Level
Service Invocation
Type
Batch
Asynchronous
Intermediate
Batch-AsyncIntermediate
Batch
Asynchronous
Delayed
Batch-Async-Delayed
Bulk
Asynchronous
Delayed
Bulk-Async-Delayed
Collect
Aysnchronous
Intermediate
Collect-AsyncIntermediate
Table 5: Supported Invocation Types
Invocation of an SBR ebMS3 service using a particular service invocation type involves sending
an appropriately formatted request to the appropriate endpoint and, in the case of
asynchronous invocations, sending a pull request to the appropriate endpoint to retrieve the
corresponding response message. The corresponding SBR ebMS3 endpoints that BMS
Systems must send these requests to are as follows:
Logical Endpoint*
Service Invocation Type
Supported
Description
Single Synchronous
Single-Sync-Chatty
Accepts single-sync-chatty requests
Single Asynchronous
Single-Async-Chatty
Accepts the following pair of
associated requests:
1) single-async-chatty push request
followed by
2) single-async-chatty pull request.
Bulk and Batch Push
Batch-Async-Intermediate
Batch-Async-Delayed
Bulk-Async-Intermediate
Bulk-Async-Delayed
Accepts one way bulk/batch
requests.[The invocation for this
endpoint should be followed by
invocation(s) for the bulk/batch
asynchronous pull – see Bulk and
Batch Pull Logical Endpoint]
Bulk and Batch Pull
Batch-Async-Intermediate
Batch-Async-Delayed
Bulk-Async-Delayed
Accepts one way pull request to
retrieve the response for the
corresponding push request.
Collect Asynchronous
Collect-Async-Intermediate
Accepts the following pair of
associated requests:
1) collect-async-intermediate push
request
followed by
2) collect-async-intermediate pull
request.
Table 6: Logical Endpoints
VERSION 2.2
UNCLASSIFIED
PAGE 20 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
* The physical endpoint specification that corresponds to each of the logical
endpoints in this table can be found in Appendix A.
3.3.1 Polling Interval
3.3.1.1 Pull-only Polling
The 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.
Where a service requires different polling intervals, this will be specified in the ATO productspecific MIG.
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 Batch
1. 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.
VERSION 2.2
UNCLASSIFIED
PAGE 21 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
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”) Polling
Collect Polling differs from the above “Pull-only Polling” in that the “poll” actually uses a twoway/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; or
ii. 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 availabe 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 twoway/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*); and
2) 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;
VERSION 2.2
UNCLASSIFIED
PAGE 22 OF 81
STANDARD BUSINESS REPORTING
3.3.1.2.1
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
Collect Polling
1. 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
1.
Pull-only Polling within Collect Polling
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.
VERSION 2.2
UNCLASSIFIED
PAGE 23 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
4 SBR ebMS3 MESSAGE PACKAGING
4.1 OVERVIEW
4.1.1 General
All 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.2 SINGLE REQUEST
Both 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 Content
ebMS3 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.
VERSION 2.2
UNCLASSIFIED
PAGE 24 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
4.2.2 Payload - ebMS3 Request MIME Part(s) Content
4.2.2.1 Single Non-Collect Request
In 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; or
3. a “Service Request” (e.g. a request to retrieve a list of accounts).
Single Request (Non-Collect)
AS4 ebMS3 User Message
SwA MIME Multi-Part Message
MIME Part 1
SOAP Header
ebMS3 Header
Collaboration Info includes
-Service
-Action (includes version)
Payload Info for MIME Part 2
Payload Info for MIME Part 3
Payload Info for MIME Part 4
.
Payload Info for
. MIME Part X
WS-Security Header
AUSKey – Public X.509
SAML Token
SOAP BODY
MIME Part 2
Logical Document 1
- Base Form
- Service Request
- Standalone Form
MIME Part 3
Logical Document 2
– Schedule 1 to Base Form
- Supporting Document 1 for Service Request
Logical
Record
MIME Part 4
Logical Document 3
XBRL
Document 2
- Schedule 2 to Base
Form
- Supporting Document 2 for Service Request
…..
...
MIME Part X
Logical Document X
- Schedule X to Base Form
- Supporting Document X for Service Request
Figure 6: Single Non-Collect Request ebMS3 MIME Part Content
VERSION 2.2
UNCLASSIFIED
PAGE 25 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
4.2.2.2 Collect Request
A 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).
Collect Request
AS4 ebMS3 User Message
SwA MIME Multi-Part Message
MIME Part 1
SOAP Header
ebMS3 Header
Collaboration Info includes
-Service
-Action (includes version)
Payload Info for MIME Part 2
WS-Security Header .
.
AUSKey – Public X.509
SAML Token
SOAP BODY
MIME Part 2
Logical
Record
Optional* Payload
Info for Collect
Request
Optional* Collect Request
Payload
KEY
Delimeter
Figure 7 - Collect Request
4.3
SINGLE RECEIPT
The SBR ebMS3 WIG provides the specification for the single receipt structure.
4.4 SINGLE PULL REQUEST
The SBR ebMS3 WIG provides the specification for the single pull request structure.
VERSION 2.2
UNCLASSIFIED
PAGE 26 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
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.
VERSION 2.2
UNCLASSIFIED
PAGE 27 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
Single Response
AS4 ebMS3 User Message
SwA MIME Multi-Part Message
MIME Part 1
SOAP Header
ebMS3 Header
RefToMessageId
Collaboration Info includes
-Service
-Action (includes version)
Payload Info for MIME Part 2
Payload Info for MIME Part 3
. MIME Part 4
Payload Info for
.
SOAP BODY
MIME Part 2
Overall Event Message
Contains Request Level processing steps
completed, processing errors and system errors
MIME Part 3
Event Message
MIME Part 4*
XBRL or JSON or XML
Document – Business Response
* indicates optional MIME
Part – i.e. Event Message
MIME Part may not
necessarily be associated
with a Business Response
MIME Part
- in particular, validation
only responses may only
have Event Message MIME
Parts
Figure 8: Single response Message packaging
VERSION 2.2
UNCLASSIFIED
PAGE 28 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
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:
Collect Response
AS4 ebMS3 User Message
SwA MIME Multi-Part Message
MIME Part 1
SOAP Header
KEY
ebMS3 Header
Collaboration Info includes
RefToMessageId
Delimeter
Payload Info for MIME Part 2
Dashed border
lines indicate this
delimeter is only
present if the
corresponding
Business Event
Message Block or
Business
Response Part is
present.
SOAP BODY
Dashed border lines
indicate this Business
Event Message Block
or Business
Response Part is
optional
*
MIME Part 2
Overall Event Message Block
Payload Info for
Business Event
Message Block 1
Business Event Message Block 1*
Payload Info for
Business
Response Part 1
Business Response Part 1
Payload Info for
Business
Response Part 2
Business Response Part 2**
**
…..
Payload Info for
Business
Response Part X
indicates optional
Payload Part – i.e.
Business Response may
not necessarily have an
associated Business Event
Message Block – for
example where the collect
request had no business
payload.
Business Response Part X**
Indicates optional
Business Response Part.
Although an item being
collected may logically be
one Business Response
(e.g. a single report or
publication), that Business
Response may be broken
up into multiple “Parts” for
manageability and
scalability reasons (e.g. 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 XBRL
documents where each
XBRL document (Business
Response Part) contains
the details for one
Superannuation Product).
Business Responses may
be either XBRL, XML or a
“Custom Format” chosen
for the Business Response
(e.g. csv)
4.6.1 MIME Part 1
The 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.
VERSION 2.2
UNCLASSIFIED
PAGE 29 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
4.6.2 MIME Part 2
The 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
The event structure is further explained in the SBR ebMS3 WIG.
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.
Please refer to product-specific MIGs to find out the exact contents of Business Event
Message Block.
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.
VERSION 2.2
UNCLASSIFIED
PAGE 30 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
4.7 BATCH/BULK REQUEST
4.7.1 Overview
For 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:
Batch or Bulk Request
AS4 ebMS3 User Message
SwA MIME Multi-Part Message
MIME Part 1
SOAP Header
ebMS3 Header
Collaboration Info includes
-Service
-Action (includes version)
Payload Info for MIME Part 2
WS-Security Header .
.
AUSKey – Public X.509
SAML Token
KEY
Delimeter
Logical
Document
SOAP BODY
MIME Part 2
Logical
Record
Payload Info for
Logical Document 1
Logical Document 1
-Base Form 1 OR
-Standalone Form OR
-Service Request OR
- Parent 1
Payload Info for
Logical Document 2
Logical Document 2
-Schedule 1 to Base Form 1 OR
-Child 1 to Parent 1
Payload Info for
Logical Document 3
Logical Document 3
- Schedule 2 to Base Form 1 OR
- Child 2 to Parent 1
Payload Info for
Logical Document 4
Logical Document 4
-Base Form 2 OR
-Standalone Form OR
-Service Request OR
- Parent 2
Payload Info for
Logical Document 5
Logical Document 5
-Schedule 1 to Base Form 2 OR
-Child 1 to Parent 2
Payload Info for
Logical Document 6
Logical Document 6
-Schedule 2 to Base Form 2 OR
-Child 2 to Parent 2
Payload Info for
Logical Document 7
Logical Document 7
-Schedule 3 to Base Form 2 OR
-Child 3 to Parent 2
Dashed border
lines indicate this
delimeter is only
present if the
corresponding
Logical Document
is present.
Dashed border lines
indicate this Logical
Document is optional,
i.e. some Base Forms
may not have
schedules being
submitted with them.
…..
Logical
Record
…..
Logical Document X
Payload Info for
-Base Form X OR
Logical Document X -Standalone Form OR
Logical
Record
-Service Request OR
- Parent X
Logical Document X +1
Payload Info for Logical
-Schedule 1 to Base Form X OR
Document X+1
-Child 1 to Parent X
Figure 9: Batch/Bulk Request Message Packaging
VERSION 2.2
UNCLASSIFIED
PAGE 31 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
4.7.2 ebMS3 MIME Part 1 Content
4.7.2.1 ebMS3 Header
The 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 Headers
Population of these headers should be done in accordance with the SBR ebMS3 Web Services
Implementation Guide.
4.7.3 ebMS3 MIME Part 2 Content
All 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:
Batch
Batch of Bulk
PAYG Lodge
Service - CTR Lodge
X Parent
X Payer
X Schedule A
X Payee
X Schedule B
X Payee
X Parent
X Payer
X Parent
X Payee
X - Metadata tag
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
VERSION 2.2
UNCLASSIFIED
PAGE 32 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
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
Unique identifier applied to the document
Record_Delimiter/@Name=DocumentID
e.g. 234356657659655
{BASE | PARENT PRODUCT NAME}
e.g. CTR
Record_Delimiter/@Name=DocumentName
BASE | PARENT
Record_Delimiter/@Name =DocumentType
e.g. BASE
Record_Delimiter/@Name=RelatedDocumentID
“”{BLANK}
Table 7: Base/Parent Form Record Delimiter Properties
4.7.3.2
Schedule/Child Records
Field
Value
For Each Delimiter
Record_Delimiter/@Name=DocumentID
Record_Delimiter/@Name=DocumentNa
me
Unique identifier applied to the document
e.g. 234356657659655
{SCHEDULE | CHILD PRODUCT NAME}
e.g. IEE
SCHEDULE | CHILD | BINARY
Record_Delimiter/@Name
=DocumentType
Record_Delimiter/@Name=RelatedDocu
mentID
Record_Delimiter/@Name=ContentType
e.g. SCHEDULE
use BINARY when the schedule/child are base 64
encoded
The ID of the base or parent form to which the schedule
or child record relates:
e.g. 999356657659678
This attribute should be passed only if
Record_Delimiter/@Name=DocumentType is set to
BINARY.
Content type of the document.
e.g. application/pdf
VERSION 2.2
UNCLASSIFIED
PAGE 33 OF 81
STANDARD BUSINESS REPORTING
Field
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
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 8: 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.
ELS Tag Batch Request
ELS Tag Batch Response
AS4 ebMS3 User Message
SwA MIME Multi-Part Message
AS4 ebMS3 User Message
SwA MIME Multi-Part Message
MIME Part 1
MIME Part 1
SOAP Header
ebMS3 Header
Collaboration Info includes
-Service
-Action (includes version)
SOAP Header
ebMS3 Header
Collaboration Info includes
RefToMessageId
Payload Info for MIME Part 2
Payload Info for MIME Part 2
ELS Approval Number
Payload Info for MIME Part 3
WS-Security Header .
.
AUSKey – Public X.509
SAML Token
SOAP BODY
SOAP BODY
MIME Part 2
MIME Part 2
Overall Event Message Block
ELS Request
MIME Part 3
ELS Response
Figure 11: ELS Tag Request and Response Variants
VERSION 2.2
UNCLASSIFIED
PAGE 34 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
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.10 BATCH/BULK PULL REQUEST
The SBR ebMS3 WIG provides the specification for the batch/bulk pull request structure.
VERSION 2.2
UNCLASSIFIED
PAGE 35 OF 81
STANDARD BUSINESS REPORTING
4.11
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
BATCH/BULK RESPONSE
The 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:
SBR Batch or Bulk Response
KEY
AS4 ebMS3 User Message
SwA MIME Multi-Part Message
MIME Part 1
SOAP Header
ebMS3 Header
Collaboration Info includes
RefToMessageId
DELIMETER
Dashed border lines
indicate this delimeter
is only present if the
corresponding
Business Event
Message Block or
Business Response is
present.
Payload Info for MIME Part 2
Dashed border lines
indicate this Event
Message Block or
Business Response is
optional
SOAP BODY
MIME Part 2
Overall Event Message Block
Payload Info for
Business Event
Message Block 1
Business Event Message Block 1
Payload Info for
Business
Response 1
Business Response 1*
Payload Info for
Business Event
Message Block 2
Business Event Message Block 2
Payload Info for
Business
Response 2
Business Response 2*
*
…..
Payload Info for
Business Event
Message Block X
Business Event Message Block X
Payload Info for
Business
Response X
Business Response X*
indicates optional
Payload Part – i.e. a
Business Event Message
Block may not necessarily
have an associated
Business Response
- in particular, validation
only responses may only
have Business Event
Message Blocks.
Business Responses may
be either XBRL, XML or a
“Custom Format” chosen
for the Business Response
(e.g. csv)
Figure 12: Batch/Bulk Response Message Packaging
4.11.1 MIME Part 1
The 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.
VERSION 2.2
UNCLASSIFIED
PAGE 36 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
4.11.2 MIME Part 2
The 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.
The event structure is further explained in the SBR ebMS3 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 Response
There 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
meta- data 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 Messages
A 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.
VERSION 2.2
UNCLASSIFIED
PAGE 37 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
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).
VERSION 2.2
UNCLASSIFIED
PAGE 38 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
5 SBR ebMS3 MESSAGE STRUCTURE
The 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 HEADER
Refer to the SBR ebMS3 WIG for more information.
5.2 ebMS HEADER
Refer to the SBR ebMS3 WIG for more information.
5.3 eb:USERMESSAGE – SBR ebMS3 PROFILE
5.3.1 Overview
The 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:From
The table below shows the ATO specific children elements require for eb:From, and their use within requests and responses.
VERSION 2.2
UNCLASSIFIED
PAGE 39 OF 81
STANDARD BUSINESS REPORTING
Name
eb:PartyId
Description
String value that identifies a
party.
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
Single Request
Bulk/Batch
Response
2 Way Sync
1 Way Push
2 Way Sync
1 Way Push
1 Way Pull
The value of this element must
Same as single request.
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;
OR
b) Registered Agent Number
(RAN) where the party
submitting the request is a
registered agent;
OR
c) 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.
Set to ATO's ABN i.e.
"51 824 753 556 ".
Optionality
Required
There MUST be one (and only
one) “eb:From” eb:PartyId.
VERSION 2.2
UNCLASSIFIED
PAGE 40 OF 81
STANDARD BUSINESS REPORTING
Name
Description
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
Single Request
Bulk/Batch
Response
2 Way Sync
1 Way Push
2 Way Sync
1 Way Push
eb:PartyId@type
The type attribute indicates the
domain of names to which the
string in the content of the
PartyId element belongs.
Optionality
1 Way Pull
Set to match the corresponding
type of the value that eb:PartyId
has been set to i.e.:
a) http://ato.gov.au/Party
IdType/TAN where the
value is a tax agent
number;
or
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/PartyI
dType/ABN where the
value is a unique
Australian Buiness
Number;”
Required
b) http://ato.gov.au/Party
IdType/RAN where the
value is a registered
agent number;
or
c) http://abr.gov.au/Party
IdType/ABN where the
value is an Australian
Business Number.
VERSION 2.2
UNCLASSIFIED
PAGE 41 OF 81
STANDARD BUSINESS REPORTING
Name
Description
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
Single Request
Bulk/Batch
Response
2 Way Sync
1 Way Push
2 Way Sync
1 Way Push
eb:Role
Identifies the authorized role of
the Party sending the message.
Optionality
1 Way Pull
Set to URI representing
authorised roles:
a) http://sbr.gov.au/ato/R
ole/Registered Agent
where the party
submitting the request
is a registered agent
(including tax agent);
or
b) http://sbr.gov.au/ato/R
ole/Business
Intermediary where the
party submitting the
request is a Business
Intermedairy;
Same as single request.
Set to URI representing
the role of the ATO:
http://sbr.gov.au/agen
cy
Required
or
c) http://sbr.gov.au/ato/R
ole/Business where
the party submitting the
request is a Business
Table 9: eb:From Structure
VERSION 2.2
UNCLASSIFIED
PAGE 42 OF 81
STANDARD BUSINESS REPORTING
5.3.1.2
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
eb:PartyInfo/eb:To
The table below shows the ATO specific children elements for eb:To, and their use within requests and responses.
Name
Description
Single Request
Bulk/Batch
Response
2 Way Sync
1 Way Push
2 Way Sync
1 Way Push
Optionality
1 Way Pull
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/A
BN 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
Set to URI representing the role
Identifies the authorized role of
the Party receiving the message. of the ATO:
"http://sbr.gov.au/agency"
Same as single request
Copy from
PartyInfo.From.Role of
related Request
Message.
Required
Table 10: eb:To Structure
5.3.2 eb:UserMessage/eb:CollaborationInfo
The table below shows the children elements for eb:CollaborationInfo, and their use within requests and responses.
Name
eb: AgreementRef
VERSION 2.2
Description
String element that identifies the
entity or artefact governing the
exchange of messages between
the parties
Single Request
Bulk/Batch
Response
2 Way Sync
1 Way Push
2 Way Sync
1 Way Push
1 Way Pull
Set by BMS to URI for
Same as single request.
pMode file that relates to
this MEP. pMode URI’s
are specified in
Appendix A.
Set by agency to the
corresponding value in
the request.
UNCLASSIFIED
Optionality
Required
PAGE 43 OF 81
STANDARD BUSINESS REPORTING
Name
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
Description
Single Request
Bulk/Batch
Response
2 Way Sync
1 Way Push
2 Way Sync
1 Way Push
1 Way Pull
Optionality
eb:Service
String identifying the service that
acts on the message.
Set by BMS to the
Same as single request.
Service Name defined in
the ATO product-specific
MIG.
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
Same as single request.
Service Name defined in
the ATO product-specific
MIG.
Set by agency to the
same value as in
request.
Required
eb:ConversationId
String element that identifies the Set to value defined in
set of related messages that
the SBR ebMS3 WIG.
make up a conversation between
Parties.
Set by agency to the
same value as in
request.
Required
Same as single request.
Table 11: eb:CollaborationInfo Structure
5.3.3 eb:PayloadInfo/eb:PartInfo/eb:PartProperties
The 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)
Name
Description
Single Request
Bulk/Batch
Response
2 Way Sync
1 Way Push
2 Way Sync
1 Way Push
eb:Property@name
VERSION 2.2
Property Name
Optionality
1 Way Pull
Set by BMS to
“DocumentName”.
UNCLASSIFIED
Set by BMS
to ”DocumentName”
Set by agency
to ”DocumentName”
Required
PAGE 44 OF 81
STANDARD BUSINESS REPORTING
Name
Description
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
Single Request
Bulk/Batch
Response
2 Way Sync
1 Way Push
2 Way Sync
1 Way Push
Optionality
1 Way Pull
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 Part
e.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 12: eb:PartProperties Structure
VERSION 2.2
UNCLASSIFIED
PAGE 45 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
5.4 eb:SIGNALMESSAGE – ATO PROFILE
The 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:MessageInfo
The table below shows the children elements for eb:MessageInfo, and their use within different types of Signal requests
Name
Description
eb:Timestamp
Pull Request from BMS
Receipt from SBR
Error from SBR
Optionality
Date at which the message Client MSH to set with
header was created
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
Required
DateTimestamp for the
date:time that the receipt
message is sent to the BMS
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 13: ebMessageInfo Structure
VERSION 2.2
UNCLASSIFIED
PAGE 46 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
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 14: eb:PullRequest Structure
5.4.3 ebMS3 Signal-Receipt & Signal-Error Response Message
There are no ATO specific ebMS3 signal response message field values.
VERSION 2.2
UNCLASSIFIED
PAGE 47 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
6 GENERAL INSTRUCTIONS
6.1 AUTHORISATION OF ONLINE (CLOUD) SERVICE PROVIDERS
For 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.1.1 and 6.1.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.1.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.
soap:Envelope
soap:Header
wsse:Security
saml2:EncryptedAssertion
wsse:BinarySecurityToken
ds:Signature
ds:Signature
ssid:softwareSubscriptionId
...
6.1.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
VERSION 2.2
UNCLASSIFIED
PAGE 48 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
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.
soap:Envelope
soap:Header
eb:Messaging
eb:UserMessage
eb:MessageInfo
eb:PartyInfo
eb:CollaborationInfo
eb:MessageProperties
eb:Property name=”SoftwareSubscriptionId”
eb:PayloadInfo
...
6.2 AUTHORISATION OF INTERMEDIARIES
For 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.3 DECLARATIONS
The 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
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.
VERSION 2.2
the statement they are making, and
UNCLASSIFIED
PAGE 49 OF 81
STANDARD BUSINESS REPORTING
2.
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
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 product-specific MIG. 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 MIG 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
VERSION 2.2
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
UNCLASSIFIED
PAGE 50 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
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.
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.
VERSION 2.2
UNCLASSIFIED
PAGE 51 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
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.4 RESPONSE MESSAGES
6.4.1 Error messages
Business 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); or
Form specific, such as FBT, CTR, PTR, AS, SMSFAR, etc.
Id
= function specific identifier.
For example: CMN.ATO.CTR.123456
VERSION 2.2
UNCLASSIFIED
PAGE 52 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
6.4.2 Successful requests
In 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.4.3 Statistical Information
Each 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 resutls 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:
VERSION 2.2
UNCLASSIFIED
PAGE 53 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
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
Rules
SBR.GEN.INFO.1
Request Unsuccessful
OR
Request 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’
else
this 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}
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.
Where {indicator} is TRUE or
FALSE
SBR.GEN.INFO.4
SBR.GEN.INFO.5
SBR.GEN.INFO.6
VERSION 2.2
Number of transactions passed
authorisation check is {number}
Number of transactions failed
authorisation check is {number}
Number of transactions passed
channel validation check is
{number}
Applicable only for the service/actions which do not require backend
processing. For other transactions, this field will not be available.
Number of
transactions (logical
records) passed
authorisation check
Number of
transactions (logical
records) failed
authorisation check
Number of
transactions (logical
records) passed
channel validation
Where {indicator} is the total number of Logical Records that have
successfully passed authorisation.
Where {indicator} is the total number of transactions (logical records) that
have failed authorisation.
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
UNCLASSIFIED
PAGE 54 OF 81
STANDARD BUSINESS REPORTING
Error.Code
Short.Description
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
Description
Rules
Note. 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
Where {indicator}’ is the total number of Logical Records that have failed
channel validation. The count corresponds to the number of Parent level
records.
Number of transactions failed
channel validation check is
{number}
Number of
transactions (logical
records) failed channel
validation
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}
SBR.GEN.INFO.9
Number of transactions failed
the backend processing
{number}
SBR.GEN.INFO.10
Number of unexpected errors is
{number}
Number of
transactions (logical
records) successfully
processed by the
backend
Number of
transactions (logical
records) failed the
backend processing
Number of
transactions (logical
records) incurred
unexpected errors
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.
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.
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.
VERSION 2.2
UNCLASSIFIED
PAGE 55 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
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 – it is fire and forget.
VERSION 2.2
UNCLASSIFIED
PAGE 56 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
6.5 DATA FORMATS
6.5.1 XBRL Instances
6.5.1.1
Monetary Units
The 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 product-specific MIG, all monetary amounts in XBRL instances
must be expressed in Australian dollars.
6.5.1.2
Non Monetary Units
Unless otherwise stated in the product-specific MIG, all non monetary numeric values requiring
units in XBRL instances must be expressed as xbrli:pure.
6.5.1.3
Measurement Accuracy
The 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 MIG, 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 SBR
1.
any digits considered to be insignificant SHOULD be replaced with zeros.
6.6
VALIDATION
6.6.1 Payload validation
Each 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.6.1.1
XBRL validation
For 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
VERSION 2.2
UNCLASSIFIED
PAGE 57 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
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 15: XBRL Validation Error Messages
6.6.1.2 JSON Validation
For 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.
VERSION 2.2
UNCLASSIFIED
PAGE 58 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
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 16: JSON Validation Error Messages
6.6.2 SBR Core Services Validation Phasing
Validation, 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).
VERSION 2.2
UNCLASSIFIED
PAGE 59 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
6.7 RULE EXPRESSION
6.7.1 ATO structured English
The validation rules in the ATO MIGs 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 data format.
6.7.2 Form prefix labels
Form 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.7.3 Context instance labels
Context 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.7.4 Absent form or context labels
Where 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.7.5 Use of xx.xx in fact names
In 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/sbrtaxonomy/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.7.6 Use of aliases
In 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
VERSION 2.2
UNCLASSIFIED
PAGE 60 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
example, [CTR123]. The definition for each alias is defined in the Message structure
spreadsheet..
6.7.7 Interpretation of NULL
Where 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.7.8 Boolean checks
Where 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.7.9 Use of domain in rules
Where 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.7.10 Case sensitivity
Validation 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.7.11 Tuples and context
In 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.7.12 Common modules
The 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
VERSION 2.2
UNCLASSIFIED
PAGE 61 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
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 ‘productspecific’ rules may also apply to that same tuple.
VERSION 2.2
UNCLASSIFIED
PAGE 62 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
7 ATO STRUCTURED ENGLISH
The 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 (in the corresponding MIG) as being in JSON format the
corresponding equivalent JSON concepts should be read in place of those XBRL concepts.
Structured English
term
Intended interpretation
Examples
(as in <a> - <b>)
Minus.
<a> - <b>
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> <> <b> +/- 1
Means (<a> > <b> + 1) OR (<a> < <b> - 1)
<>
Not equal to.
IF <a> <> <b>
Means if the value of ‘a’ is not equal to the value
of ‘b’.
{x}
A named (x) set.
RP.{ForeignCountry}
The use of a named set is
required when
representing context
definitions that contain
segment(s) that can have
more than one possible
value.
'{ForeignCountry}' represents the set of possible
context segment values defined by the
'ForeignCountry' dimension. This dimension can
be either an explicit or typed dimension.
<a> = <b> +/- 1
Means (<a> >= <b> - 1 ) AND (<a> <= <b> + 1).
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’.
VERSION 2.2
UNCLASSIFIED
PAGE 63 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
Structured English
term
Intended interpretation
Examples
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>) = FALSE
Means if the TFN field <a> fails the TFN algorithm.
All instances of a given
field or defined set of
multiple fields, where the
field/s are from a
repeatable tuple or
context.
Usage examples:
ALL
OCCURRENCES
OF
(For testing values or sets
of values in repeating
tuples/contexts)
IF ABNALGORITHM(<a>) = FALSE
Means the ABN field <a> fails the ABN algorithm.
EXAMPLE 1: SUM of multiple fields
IF SUM(ALL OCCURRENCES OF(<a> - <b>)) <>
<c>.
Means if the sum of every instance of <a>, minus
the sum of every instance of <b> is not equal to
the value of <c> (where <a> and <b> 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 <b> <> NULL))
Means if all instances of <a> is NULL and <b> is
not NULL in the same defined set (where both <a>
and <b> 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.
VERSION 2.2
UNCLASSIFIED
PAGE 64 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
Structured English
term
Intended interpretation
Examples
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 condition
IF ANY OCCURRENCE OF(<a>) > 10.
For testing a value in one
occurrence against other
occurrences.
IF <a> = ANY OTHER OCCURRENCE OF <a>.
ANY OTHER
OCCURRENCE OF
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.
CONTAINS
A string search for text
within a field.
EXAMPLE 2: Single field with multiple conditions
IF 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 conditions
IF ANY OCCURRENCE OF(<c>) = (<c> WHERE
(<a> = NULL AND <b> <> NULL))
Means if any instance of <a> is NULL and <b> is
not NULL in the same defined set (where both <a>
and <b> are from the repeatable tuple/context
<c>).
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.
IF <a> CONTAINS "UNKNOWN".
Usage: <a> CONTAINS
<B>.
CONTAINS MORE
THAN ONE
Means if any instance of <a> is greater than 10
(where <a> is from a repeatable tuple/context).
A text field contains more
than one incidence of a
given string with the field.
Means if <a> contains or equals the word
‘unknown’.
IF
pyde.xx.xx:ElectronicContact.ElectronicMail.Addre
ss.Text CONTAINS MORE THAN ONE "@".
Means if there is more than one ‘@’ symbol within
the email address.
VERSION 2.2
UNCLASSIFIED
PAGE 65 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
Structured English
term
Intended interpretation
Examples
CONTEXT
Used to refer to a context
instance.
WHERE CONTEXT = “RPI.Closing”.
Usage: CONTEXT(<A>)
Means in instances where the context instance is
‘RPI.Closing’.
where <A> is a context
instance abbreviation e.g.
RP.GST.CC
CONVERT_TO_DA
TE
Combines separate day,
month and year fields into
a single date.
Usage:
CONVERT_TO_DATE(<d
ay>, <month>, <year>)
IF CONVERT_TO_DATE(<A>, <B>, <C>) <>
VALID DATE
Where: <A> = the element capturing the day of
the month, <B> = the element capturing the
month, and <B> represents the element capturing
a year.
Means: if the values provided for <A>, <B> 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}) >3
RETURN VALIDATION MESSAGE
ENDIF.
Means the count of distinct Foreign Country
segment values across all context instances
matching ‘RP.{ForeignCountry}.{ActivityCode}’ or
‘RP.{ForeignCountry}’.
COUNT(SCHEDUL
E)
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.
DATE(TODAY)
Compares a date against
the current date.
IF <a> > DATE(TODAY).
VERSION 2.2
If current system date is 01/08/2013, for example,
means IF <a> is after 2014.
Means if <a> is a date in the future.
UNCLASSIFIED
PAGE 66 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
Structured English
term
Intended interpretation
Examples
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").
DOMAIN
A globally defined set of
values.
SET (DOMAIN(COUNTRY CODES)
Means that the field has no instance of an
alphabetical character (excepting special
characters), nor a numeric character.
Usage:
<a> =
SET(DOMAIN(<B>)).
Means the complete set of country codes. Each
set of domain values is defined in the Standard
enumerations section within this document.
<a> is one of the values
defined in <B>.
ENDSWITH
A string searches for text
at the end of a field
Usage:
IF <a> ENDSWITH " T/A".
Means the condition is true if field <a> contains a
value that ends with the text string ‘ T/A’.
<a> ENDSWITH <B>.
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>
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>.
VERSION 2.2
Means for every occurrence of context RP, apply
the <test condition>.
Means for each unique ‘ForeignCountry’ segment
value, apply the <test condition>.
UNCLASSIFIED
PAGE 67 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
Structured English
term
Intended interpretation
Examples
FOUND
A string search for text
within a field performing a
variation of the SET,
CONTAINS,
STARTSWITH and
ENDSWITH functions.
IF <a> = FOUND("The trustee","The Exec").
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.
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).
Where multiple strings
have been provided, a
check for each string is
performed.
Usage:
<A> =
FOUND(<B>,<C>).
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).
(1) IF <a> IN TUPLE(<b>).
(Refer also: ‘WHERE IN
TUPLE’).
Means if tuple <A> does not exist or if <B> in <A>
is null or blank.
Means if the value of <a> within the tuple <b>.
(Where <a> may also exist outside tuple <b>).
(2) IF (<B> IN TUPLE(<A>)) = NULLORBLANK
(3) IF COUNT(<B> IN TUPLE(<A>)) > 1.
Means if the occurrence of <B> in <A> is more
than one.
(4) IN TUPLE(<A>)
IF <B> = NULLORBLANK
Means if <B> 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.
IF LENGTH(<a>) < 6.
Means if the value of <a> does not contain at least
6 characters.
(Refer also: TEXT).
VERSION 2.2
UNCLASSIFIED
PAGE 68 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
Structured English
term
Intended interpretation
Examples
MONETARY()
Defines a monetary field
pattern where a true
response is given when a
value passes all
conditions.
<a> <> MONETARY(U,11,0).
As in:
MONETARY(<a>,<b>,<c>)
Where:
<a> = S or U to indicate if
field can be signed or not.
<b> = Maximum number of
digits (including decimal
places).
<c> = Maximum number of
decimal places.
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).
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 <b> does not
include a decimal point or
sign in the total character
limit.
NOT
Reverses the value of a
boolean 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.
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.
NULLORBLANK
VERSION 2.2
Means if a (non-textual) value for <a> is blank or if
<a> does not exist.
Means if a (textual) value for <a> is blank or if <a>
does not exist.
UNCLASSIFIED
PAGE 69 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
Structured English
term
Intended interpretation
Examples
NUMBER
Defines a valid numeric
field pattern where a true
response is given when a
value passes all
conditions.
<a> <> NUMBER(U,11,0).
Usage:
NUMBER(<a>,<b>,<c>)
Where:
<a> = S or U to indicate if
field can be signed or not.
<b> = Maximum number of
digits (including decimal
places).
<c> = Maximum number of
decimal places.
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).
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 <b> does not
include a decimal point or
sign in the total character
limit.
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
VERSION 2.2
UNCLASSIFIED
PAGE 70 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
Structured English
term
Intended interpretation
Examples
ROUNDDOWN
Round a number down to
the nearest specified
increment.
ROUNDDOWN(0.05,[CTR120])
Usage:
ROUNDDOWN(<A>,<B>)
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.
Where
<A> is the configurable
increment to round down
to
<B> is the value that is to
be rounded down.
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.
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.
Usage: SCHEDULE =
<A>.
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
<B>
SUM
The sum of all instances of
an element.
Usage: SUM(<A>),
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(<a>)
Means the total value of all instances of <a>,
when each <a> is added up.
where <A> is an element
that appears in a repeating
tuple or is a repeating
element.
VERSION 2.2
UNCLASSIFIED
PAGE 71 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
Structured English
term
Intended interpretation
Examples
TEXT()
Used to define the
maximum length of a
textual field.
<a> <> TEXT(150).
Means the maximum number of characters
allowable within field <a> is 150.
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)
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
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.
WHERE IN CONTEXT(RP)
IF <B> = NULLORBLANK
Rule is executed within the
bounds of each
occurrence of a particular
context.
Means if the converted date is not a valid date.
(Where <B> is a fact in the RP context).
Means if the value of <B> within the RP context is
null or blank. In this example the rule will only
trigger if the RP context exists and if <B> (in the
RP context) is null or blank.
Usage:
WHERE IN
CONTEXT(<A>)
IF <B>….
VERSION 2.2
UNCLASSIFIED
PAGE 72 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
Structured English
term
Intended interpretation
Examples
WHERE …IN SET
Used to validate data
elements which are
logically grouped within a
set.
WHERE ForeignCountry = ’us’ IN SET
(RP{ForeignCountry})
Rule is executed within the
bounds of each
occurrence of a set.
Means execute the rule if the ForeignCountry
dimension value is ‘us’ in the ForeignCountry
dimension within the RP context.
Usage:
WHERE <A> IN
SET(<B>).
Refer also: {x}.
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.
WHERE IN TUPLE
(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.
Used to validate data
elements which are
logically grouped within a
tuple.
Rule is executed within the
bounds of each
occurrence of a tuple.
WHERE IN TUPLE(<A>)
IF <B> = NULLORBLANK
(Where <B> is a fact in tuple <A>)
Means if the value of <B> within the tuple <A> is
nullorblank. In this example the rule will only
trigger if tuple <A> exists and if <B> (in <A>) is
null or blank.
Usage:
WHERE IN TUPLE (<A>)
IF <B>….
(Refer also IN TUPLE. The
‘WHERE’ keyword is
optional).
VERSION 2.2
UNCLASSIFIED
PAGE 73 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
Structured English
term
Intended interpretation
Examples
xbrli (\element
definition)
‘xbrli’ is used to denote the
reporting taxonomy root.
Indicates a given tuple or
element is not nested
within another tuple.
IN TUPLE
(xbrli\organisationname2.xx.xx:OrganisationName
Details).
This is used to differentiate
elements that are repeated
at different levels of the
reporting taxonomy within
a given business
collaboration.
Means in the tuple
‘organisationname2.xx.xx:OrganisationNameDetai
ls’ that is not within another tuple.
In this example, the implication is that the
‘organisationname2.xx.xx:OrganisationNameDetai
ls’ tuple also exists under another tuple within the
product.
Table 17: ATO Structured English Guide
VERSION 2.2
UNCLASSIFIED
PAGE 74 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
8 MESSAGE STRUCTURE SPREADSHEETS
The ATO supplies a separate Excel spreadsheet for each ATO product describing the message
structure. These contain two worksheets, a Context structure table, and a message structure
table (MST), which 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 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.
The following table describes each column in the context structure tables.
Column label
Seq Num
Label
Start/Instant Date
End Date
Description
Period Type
Min
Max
Identifier Scheme
Identifier Value
Dimension
#:Namespace Prefix
Dimension #: Name
Dimension #: Type
Dimension #: Value
Description
Sequence number that provides a logical order to the context instances and
allows sorting of the table.
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.
The start date or instant date expected for the context instance.
The end date expected for the context instance.
Describes the context instance.
Indicates whether the context instance is in relation to a ‘Duration’ or an
‘Instant’.
The minimum number of occurrences the context instance must appear within
a valid business document.
The maximum number of occurrences of a context instance that may appear
within a valid business document.
The entity identifier scheme for the context instance.
The value required to describe the entity as defined by the identifier scheme.
The namespace prefix of each dimension in the context instance.
The dimension name of each dimension in the context instance.
Indicates whether the dimension is ‘Explicit’ or ‘Typed’.
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.
Table 18: ATO Structured English Guide
The following table describes each column in the MSTs.
Column label
Seq Num
Parent Seq Num
Alias
Element Type
Label
VERSION 2.2
Description
Sequence number that provides a logical order to the facts within the business
document and allows sorting of the table
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.
The abbreviated identifier for a given fact. The alias may be used within
validation rules (within square brackets) to describe that fact.
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.
The label of the fact, tuple, label or context element.
For facts, these are the Report Labels in the SBR reporting taxonomy.
UNCLASSIFIED
PAGE 75 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
Column label
Description
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. 1
Where present, these show the legal references for a given fact.
Legal Reference
Min
Max
TREF ID
Namespace Prefix
Element Name
Context
Period Type
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.
Indicates the maximum number of occurrences a fact or tuple may appear
within a context instance or enclosing tuple.
A number allocated by the SBR program to uniquely identify a data element.
The abbreviated name for the class, including its version number, for the
definitional taxonomy element.
The name of the definitional taxonomy element.
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']’.
Indicates whether the fact has a period type of ‘Duration’ or ‘Instant’.
Table 19: MST Table Description
1
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.
VERSION 2.2
UNCLASSIFIED
PAGE 76 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
9 VALIDATION RULES SPREADSHEETS
The 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
Seq Num
Alias
Label
Context instance
Element Name
English Business Rule
Technical Business Rule
Rule Type
Schematron ID
Message Code
Message – Short
Description
Last Updated
Description
This is the sequence number of the fact, heading or tuple as defined in the
MST.
The abbreviated identifier for the fact as defined in the MST.
The label of the fact, heading, tuple or context information as defined in
the MST.
The context instance for a given fact or tuple.
The name of the definitional taxonomy element, including namespace
prefix.
A non-technical explanation of the rule.
Specifies the validation rule using Structured English (as described in
Section 4 above).
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.
The Schematron ID for the rule.
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.
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.
The date the rule was added or last changed since the prior version or
prior business collaboration (where applicable).
Table 20: Validation Rule Table Description
VERSION 2.2
UNCLASSIFIED
PAGE 77 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
10 APPENDIX A – PHYSICAL END POINTS
10.1 SBR CORE SERVICES
Physical end points for SBR Core Services can be found in Section 6.1.1 Service End Points in
the SBR Core Services WIG.
10.2 SBR ebMS3
10.2.1 EVTE
Logical Endpoint*
Single Synchronous
Single Asynchronous
Bulk and Batch Push
Physical Endpoint
https://test.ato.sbr.gov.au/services/Singlesync
https://test.ato.sbr.gov.au/services/Singleasync-push-pull
https://test.ato.sbr.gov.au/services/BulkBatchasync-push
Bulk and Batch Pull
https://test.ato.sbr.gov.au/services/BulkBatchasync-pull
Collect
https://test.ato.sbr.gov.au/services/Collectasync
Table 21: Physical Endpoints - EVTE
Service
Invocation
Type
Supported
Single-SyncChatty
Single-AsyncChatty
Batch-AsyncIntermediate
Batch-AsyncDelayed
Bulk-AsyncDelayed
Batch-AsyncIntermediate
Batch-AsyncDelayed
Bulk-AsyncDelayed
Collect-AsyncIntermediate
10.2.2 Production
Logical Endpoint*
Physical Endpoint
Single Synchronous
https://ato.sbr.gov.au/services/Single-sync
Single Push
https://ato.sbr.gov.au/services/Single-asyncpush
https://ato.sbr.gov.au/services/Single-asyncpull
https://ato.sbr.gov.au/services/BulkBatchasync-push
Single Pull
Bulk and Batch
Push
Bulk and Batch Pull
VERSION 2.2
https://ato.sbr.gov.au/services/BulkBatchasync-pull
UNCLASSIFIED
Service
Invocation Type
Supported
Single-SyncChatty
Single-AsyncChatty
Single-AsyncChatty
Batch-AsyncIntermediate
Batch-AsyncDelayed
Bulk-AsyncDelayed
Batch-AsyncIntermediate
Batch-AsyncDelayed
Bulk-AsyncDelayed
PAGE 78 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
Logical Endpoint*
Collect
Physical Endpoint
https://ato.sbr.gov.au/services/Collect-async
Service
Invocation Type
Supported
Collect-AsyncIntermediate
Table 22: 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
http://sbr.gov.au/agreement/Gateway
/1.0/Push/PKI
Batch-Async-Delayed
Bulk-Async-Delayed
Bulk and Batch Pull
Batch-Async-Intermediate
Batch-Async-Delayed
http://sbr.gov.au/agreement/Gateway
/1.0/SelectivePull/PKI
Bulk-Async-Delayed
Collect
VERSION 2.2
Collect-Async-Delayed
UNCLASSIFIED
http://sbr.gov.au/agreement/Gateway
/1.0/TwoWayPushAndPull/PKI
PAGE 79 OF 81
STANDARD BUSINESS REPORTING
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
11 APPENDIX B – AUTHORISATION ERROR
MESSAGES
Error Code
Short Description
Long Description
SBR.GEN.AUTH.001
Mandatory information missing from
transmission. Contact your software
provider.
Inform your software provider that the
following element/attribute {AttributeName}7
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.
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.004
SBR.GEN.AUTH.005
Misalignment of identifying information.
Contact your software provider.
SBR.GEN.AUTH.006
The software provider has not been
nominated to secure your online (cloud)
transmissions.
SBR.GEN.AUTH.007
The software provider has not been
accredited as an Online (cloud) Software
Provider.
SBR.GEN.AUTH.008
Your nomination with the online (cloud)
software provider does not contain the
correct Software ID.
SBR.GEN.AUTH.010
Your transaction failed due to a problem
with the online (cloud) software provider’s
system.
SBR.GEN.AUTH.011
The software provider has disabled your
nomination.
SBR.GEN.AUTH.012
Intermediary identifier information is missing
from the lodgment.
Inform your software provider that the
eb:PartyInfo/From/PartyID details does not
match the entity details for this submission.
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
The software provider has not been
accredited as an Online (cloud) Software
Provider. Contact your software provider to
resolve this issue.
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
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.
The software provider has disabled your
nomination.To resolve, please contact your
software provider.
7
Parameter.Identifier = Attribute Name,
Parameter.Text = “eb:PartyId/@Type”,”eb:PartyId”, “eb:Role”
VERSION 2.2
UNCLASSIFIED
PAGE 80 OF 81
STANDARD BUSINESS REPORTING
SBR.GEN.AUTH.013
SBR.GEN.AUTH.014
SBR.GEN.AUTH.015
CMN.ATO.AUTH.001
ATO COMMON MESSAGE IMPLEMENTATION GUIDE
The ABN of the business being acted on
behalf of is required.
A client’s ABN, TFN, WPN or ARN is
required for this request.
You are not authorised to submit this
request. Review permissions in Access
Manager and try again.
Your registered agent number is not linked
to this ABN.
CMN.ATO.AUTH.002
You are not authorised to lodge on behalf of
this client.
CMN.ATO.AUTH.0048
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.
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.
CMN.ATO.AUTH.008
You are not authorised to lodge on behalf of
this client.
CMN.ATO.AUTH.009
Length of the Software ID must be 10
characters.
8
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.
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.
Contact your AUSkey administrator to
authorise your AUSkey for this registered
agent number and set up your permissions
in Access manager.
Review your permissions in Access
manager or contact your AUSkey
Administrator.
You are not authorised to submit this
lodgement on behalf of the client. Link this
client to your australian 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.
Length of the Software ID must be 10
characters. Contact your software provider
to resolve this issue.
Message Severity Code for CMN.ATO.AUTH.0004 is “Information”
VERSION 2.2
UNCLASSIFIED
PAGE 81 OF 81
