Standard Business Reporting
Australian Taxation Office
Common MessageImplementation Guide
Date: 04March 2014
Status: Draft
Error! Unknown document property name. / PAGE1 OF 31Error! Unknown document property name. / SBR ATO COMMON MESSAGE IMPLEMENTATION GUIDE
This document and its attachments are Unclassified.
For further information or questions, contact the SBR Service Desk at or call 1300 488 231.
International callers may use +61-2-6216 5577
Error! Unknown document property name. / PAGE1 OF 31Standard business reporting ATO COmmon MIG
VERSION CONTROL
Version / Date / Description of changes0.1 / 15/10/2013 / Initial draft. (Largely derived from ATO 2013 product-specific MIGs – using information common to most products).
1.0 / 21/11/2013 / Minor changes following SWS review and endorsement from Treasury.
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.1.1 / 06/12/2013 / ELS2SBR: Minor changes to cover SBR1 and SBR2 channels.
1.1.2 / 17/12/2013 / ELS2SBR: Minor changes following SBR review.
1.1.3 / 03/02/2014 / ELS2SBR: Minor changes following Platform review.
1.1.4 / 25/02/2014 / ELS2SBR: 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.5 / 04/03/2014 / ELS2SBR: Aligned SBR2 channel information with latest ATO Common MIG V1.1, applied minor formatting changes and other minor updates.
ENDORSEMENT
APPROVAL
Chief Solutions Architect
Standard Business Reporting
Michael FerrisProject Manager
Strategic Web Services
Australian Taxation Office
Copyright
© Commonwealth of Australia 2014(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 . 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 Commonwealthor 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 1.1UnclassifiedPAGE1 OF 66
Standard business reporting ATO COmmon MIG
Table of contents
1Introduction
1.1Purpose
1.2Audience
1.3Document context
1.4ATO documentation suite
1.5Supporting documentation
1.6Change management
1.7Glossary
2Business Context
2.1Prerequisites
2.2Interactions
3Standard Business Reporting Platforms
3.1SBR2 Instructions
3.1.1Request Messages Types
3.2SBR2 Service Versioning
3.3SBR2 Supported Service Invocation Types
3.3.1Single – Sync – Chatty
3.3.2Single – Async – Chatty
3.3.3Batch – Async – Intermediate, Batch – Async – Delayed and Bulk – Async – Delayed
3.3.4Polling Interval
4SBR2 Message Packaging
4.1Overview
4.2Single Request
4.2.1Header – ebMS3 header content
4.2.2ebMS3 Request MIME Part Content
4.3Single Receipt
4.4SINGLE Pull Request
4.5Single Response
4.6Batch/Bulk Request
4.6.1Overview
4.6.2ebMS3 MIME Part 1 Content
4.6.3ebMS3 MIME Part 2 Content
4.7ELS Tag Batch Request
4.8Batch/Bulk Receipt
4.9Batch/Bulk Pull Request
4.10Batch/Bulk Response
5SBR2 Message Structure
5.1Security Header
5.2EBMS Header
5.3EB:USERMESSAGE – SBR2 Profile
5.3.1Overview
5.3.2eb:UserMessage/eb:MessageInfo
5.3.3eb:UserMessage/eb:PartyInfo
5.3.4eb:UserMessage/eb:CollaborationInfo
5.3.5eb:UserMessage/eb:MessageProperties
5.3.6eb:PayloadInfo/eb:PartInfo
5.3.7eb:PayloadInfo/eb:PartInfo/eb:PartProperties
5.4EB:SIGNALMESSAGE – ATO Profile
5.4.1eb:SignalMessage/eb:MessageInfo
5.4.2eb:SignalMessage/eb:PullRequest
5.4.3ebMS3 Signal-Receipt & Signal-Error Response Message
6General Instructions
6.1Authorisation of intermediaries
6.2Declarations
6.3Response messages
6.3.1Error messages
6.3.2Successful requests
6.4Validation
6.4.1XBRL validation
6.4.2Phases of validation
6.5Rule expression
6.5.1ATO structured English
6.5.2Form prefix labels
6.5.3Context instance labels
6.5.4Absent form or context labels
6.5.5Use of xx.xx in fact names
6.5.6Use of aliases
6.5.7Interpretation of NULL
6.5.8Boolean checks
6.5.9Use of domain in rules
6.5.10Case sensitivity
6.5.11Tuples and context
6.5.12Common modules
7ATO structured English
8Message Structure spreadsheets
9Validation Rules spreadsheets
10APPENDIX A – Physical Endpoints
10.1EVTE
10.2Production
1Introduction
1.1Purpose
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.2Audience
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.3Document context
The Common MIG forms part of the broader suite of documents used by agencies to describe the way in which software developers must implement messages. In particular, it describes the agency specific requirements to ensure those messages are both SBR and agency 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.
Rather than a single MIG document, since 2014, the ATO has produced a ‘MIG package’ for each ATO business collaboration. Each MIG package contains the documents as described in Figure 1 below. Each package is supported by this ‘ATO common MIG’.
Figure 1: ATO MIG package.
This ATO common MIG describes the rules and guidelines for the SBR platform that are common across all ATO business collaborations. (An ATO business collaboration is a reporting obligation or a business service). Specifically, this document describes the business 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 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 WIG, which is commonly referenced in this document. It recommended that this document and the SBR WIG are read in conjunction with one another.
1.4ATO 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
Artefact / Scope / Description / Format(s)ATO common MIG / ATO / (This document) Instructions common to many ATO forms, schedules and services. / PDF
ATO response messages / ATO / All error and warning messagesused in ATO SBR web services. / XML
Product-specific MIG / Product / Instructions specific to an ATO obligation (form, schedule or service). / PDF
Product-specific message structure / Product / Lists and describes the contexts, data elements, tuples and headings in a particular ATO form, schedule or service. Contains a ‘context structure table’ and a ‘message structure table’. / Excel
Product-specific validation rules / Product / Validation rules applicable to an ATO form, schedule or service. Includes ‘common module rules’, ‘domain definitions’ in addition to ‘product-specific rules’. / Excel
Conformance suite / Product / Test cases in the conformance suite to be executed by software developers as part of the self-certification process for a particular ATO form, schedule or service. Available on request from the SBR Service Desk. / PDF
XBRL
Schematron / Product / The schematron rules and messages specific to an ATO form, schedule or service. / Schematron
Table 1: ATO Document Suite
1.5Supporting documentation
Document / DescriptionThe SBR taxonomy architecture 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.
The SBR web service implementation guide / SBR1 -
SBR2 –TBA
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 / SBR1 -
SBR2 – TBA
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.6Change management
If a material change is required to this message implementation guide (MIG) the document will be re-released. The Taxonomy Approval Committee must approve any change.
1.7Glossary
The following table contains terms that are specific to the ATO. More general terms and acronyms in relation to SBR can be found at .
Term / DefinitionAgent / Tax agent or BAS service provider. A request by an agent must include a registered agent number.
ATO product / Documentation produced in order to support an SBR ATO business collaboration.
BPMN / Business Process Model and Notation is a standard for business process modelling.
Business collaboration / See 'Collaboration'.
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. (Referto the SBR web service implementation guide’).
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, which may include zero, one or more schedules.
SBR / Standard Business Reporting. When used in the context of a channel SBR covers both SBR1 and SBR2.
SBR1 / The SBR channel that supports Standard Business Document Message (SBDM).
SBR2 / The SBR channel that supports ebMS3.
Sender / The entity sending the request message to the ATO via SBR. The entity can be same as the reporting party or be an intermediary. The sender must have an AUSkey. (Referto the SBR web service implementation guide’).
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
2Business Context
2.1Prerequisites
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 interacting on behalf of another entity (that is, as an intermediary), then the sender (or the entity itself) must:
register an ‘intermediary-reporting party’ relationship with the ATO through one of the ATO portals.
2.2Interactions
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 guide, this includes the list, prefill, prelodge and lodge web services. The full list of ATO products that make use of SBR can be found at Each product-specific MIG describes which web services are available for that business collaboration.
The following business process model (using BPMN) 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.
Figure 2:Shows the process a sender follows interacting with the ATO using the SBR channel.
3Standard Business Reporting Platforms
The first phase of the SBR program provided aplatform 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 SBR1 and SBR2 as used in this document are defined as:
SBR1 / 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.
SBR2 / 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: SBR1 and SBR2 Definitions
In this document any statements that refer to "SBR" are to be taken to be refer to either SBR1 or SBR2 or both SBR1 and SBR2.
This document provides guidance for construction of request messages for both SBR1 and SBR2.
Request messages that are targeted for SBR1 must be constructed using the Standard Business Document Format in accordance with the instructions below that are specified as being for SBR1.
Request messages that are targeted for SBR2 must be constructed using the ebMS3 Message Format in accordance with the instructions that are specified as being for SBR2.
Differences in response message formats coming from SBR1 and SBR2 will be similarly identified.
3.1SBR2 Instructions
3.1.1Request Messages Types
SBR2 accepts three distinct request message types:
1)Single: Business payload contains a single transaction (interaction instance) requested for a specific service-action e.g. ListAS, ValidateFBT, LodgeCTR. A single request can either be submitted synchronously or asynchronously.
2)Batch: Business payload contains multiple transactions (interaction instances) of the same type (e.g.: Lodge CTR) to be sent in a single transmission. Batch messages may contain multiple bulk messages. Batch requests can only be submitted in an asynchronous interaction pattern.
3)Bulk: Business payload contains a Parent (e.g.: Payer) and child (e.g.: Payee) multi-level construct. The bulk message contains information that relates to more than one tax payer. This information is provided in child forms that are the same type, each containing info of a different tax payer where there could be greater than a million records e.g.: Private health insurance and member contribution statements. Like a batch, these requests can only be submitted in an asynchronous interaction pattern.
3.2SBR2 Service Versioning
Versioning will be performed at the action level. In the case of service versioning at the action level each action will have a version associated with it i.e. Action.VVV.vv. Where VVV is the major version and vv is the minor version e.g. List.001.00, List.002.00, List.002.01
3.3SBR2 Supported Service Invocation Types
SBR2 supports the following combinations of service attributes for invocation of its services:
Message Type / Invocation Modes / Response TimeService Level / Service Invocation Type
Single / Synchronous / Chatty / Single-Sync-Chatty
Single / Asynchronous / Chatty / Single-Async-Chatty
Batch / Asynchronous / Intermediate / Batch-Async-Intermediate
Batch / Asynchronous / Delayed / Batch-Async-Delayed
Bulk / Asynchronous / Delayed / Bulk-Async-Delayed
Table 5: Supported Invocation Types
Invocation of an SBR2 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 SBR2 endpoints that BMS Systems must send these requests to are as follows:
Logical Endpoint* / Service Invocation Type Supported / DescriptionSingle Synchronous / Single-Sync-Chatty / Accepts single-sync-chatty requests
Single Push / Single-Async-Chatty / Accepts single-async-chatty requests. The invocation for this endpoint should be followed by invocation(s) for the single pull.
Single Pull / Single-Async-Chatty / Accepts one way pull request to retrieve the response for the corresponding push request.
Bulk and Batch Push / Batch-Async-Intermediate
Batch-Async-Delayed
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.
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
Table 6: Logical Endpoints
*The physical endpoint specification that corresponds to each of the logical endpoints in this table can be found in Appendix A.