SBR II Software Developer training Presented by Digital
SBR II Software Developer training Presented by Digital Wholesale Services Team November 2017 Australian Taxation Office 1 Unclassified – Software Developer Training - SBR 2
Overview
Who is this targeted at? This training session has been prepared as an introduction for new software developers looking to consume Standard Business Reporting (SBR) services for the delivery of Single touch payroll (STP). Due to this focus the presentations will provide specific references to the ATO e. BMS implementation for STP. The session will be broken into four parts • Introduction – A general overview to the key concepts of SBR and the STP implementation to provide context for later parts of the presentation. Target - All • Analysis – Will provide detail to the documentation and process for creating a message to send to the ATO. Target –Project Managers, Business Analysists, System Analysis. • Development – Concentrates on the technical aspects of the service implementation. Target – System Analysts, Developers • Testing and Implementation – Focuses on the testing aspects that a software developer will need to carry out, including the verification processes to ensure a product is production ready. Target – Testers, Project Managers 3 Unclassified – Software Developer Training - SBR 2
What is SBR “Using SBR-enabled software, businesses will be able to realise the benefits of reporting to government directly from their financial, accounting or payroll system. ” • • • Government created web services to offer a wholesale implementation which integrates the collection of your client’s data to the submission processes that government requires. Incorporates standard terms that are used in government legislation and reporting. These terms are then linked to terms that are in the business/accounting software creating consistency for business and government (taxonomy). Provides consistency in dealing with many government agencies, using the same technical delivery methods and the shared taxonomy to reference terms. 4 Unclassified – Software Developer Training - SBR 2
Taxonomies • Definitional taxonomy (SBR Taxonomy) is based on “whole of government terms” and goes through a process of verification and normalisation before approval through the SBR taxonomy advisory committee (TAC) • Reporting taxonomy – “Instance of the form” values are taken from the definitional taxonomy to make up the values in the form. • Interface is usually defined in the message structure table and associated artefacts provided to describe the implementation of the reporting taxonomy. Definitional Reporting Interface 5 Unclassified – Software Developer Training - SBR 2
How to create an SBR message A STP message is made up of two main components Payload (in XBRL, XML or JSON format) • The content of the message to be sent to the ATO, the main example for STP will be the elements and values of the “Payroll event” message, which will be in XML format Envelope (e. BMS 3/AS 4) • A set of layered extensions to the SOAP protocol, providing security and reliability features enabling e-Commerce transactions. • ATO is using the e. BMS 3 standard with the addition of the AS 4 profile 6 Unclassified – Software Developer Training - SBR 2
What is e. BMS “The prime objective of the eb. XML Messaging Service (eb. MS) is to facilitate the exchange of electronic business messages within an XML framework that leverages common Internet standards, without making any assumption on the integration and consumption model these messages will follow on the back-end” OASIS This gives a consistent approach for creating a message for; • PLS, STP, SR • Superannuation B 2 B • e. Invoicing • Other B 2 B transactions 7 Unclassified – Software Developer Training - SBR 2
8 Unclassified – Software Developer Training - SBR 2
MEPS – Message Exchange Patterns Message Type Invocation Modes Response Time Service Level Service Invocation Type eb. MS 3 MEP Single Synchronous Chatty Single-Sync-Chatty Two-Way/Synchronous Single Asynchronous Chatty Single-Async-Chatty Two-Way/Push-and-Pull Batch Asynchronous Intermediate Batch-Async-Intermediate One-Way/Push One-Way/Selective-Pull Batch Asynchronous Delayed Batch-Async-Delayed One-Way/Push One-Way/Selective-Pull Batch Asynchronous Intermediate or Delayed Bulk-Async – Hybrid * One-Way/Push One-Way/Selective-Pull based on no. logical records. Bulk Asynchronous Intermediate Bulk-Async-Intermediate One-Way/Push One-Way/Selective-Pull Bulk Asynchronous Delayed Bulk-Async-Delayed One-Way/Push One-Way/Selective-Pull Bulk Asynchronous Intermediate or Delayed Bulk-Async – Hybrid * One-Way/Push One-Way/Selective-Pull based on no. logical records. Collect Asynchronous Delayed Collect-Async-Delayed Two-Way/Push-and-Pull * Payevnt. 0003 2018 will use the Hybrid pattern. This will be available in EVTE – 30 th Jan and Production – March 2018. 9 Unclassified – Software Developer Training - SBR 2
Your choices on e. BMS implementation Build, Buy or Partner. • Build • You do not need the full feature set of e. BMS / AS 4 to deliver services for the ATO • Understand the MEP’s needed for each service. • Services delivered for different ATO systems and B 2 B delivery require different e. BMS / AS 4 functionality. • Buy • Consider the value for money proposition of purchasing a product against delivery and maintenance effort. • You may not need to consume a fully featured e. BMS product. • Partner • Value of passing the e. BMS delivery to a 3 rd party or even have them send the data to the ATO • Potential for negotiation on what and how you send data and agreements being made between the parties. 10 Unclassified – Software Developer Training - SBR 2
Message sender Using the AUSkey certificate of the sender as intermediary 11 Unclassified – Software Developer Training - SBR 2
Accessing SBR To register as a SBR developer http: //www. sbr. gov. au/software-developers/what-can-i-expect/registration-form Upon registering to become a SBR software developer to interact with the ATO all software developers will be allocated an account manager from the ATO’s Software Onboarding team. As your account manager, the Onboarding team representatives will represent you as a Digital Service Provider (DSP); • Facilitate the integration of DSP systems to SBR. • Assist with Software and technical related questions for all ATO web service delivery. • Be the professional advocate for DSP within the ATO. • Provide management and technical resolution of on-boarding issues. 12 Unclassified – Software Developer Training - SBR 2
Some basic information on eb. MS 3/AS 4 • The eb. MS 3. 0 standard composes the fundamental Web Services standards SOAP 1. 1 [SOAP 11], SOAP 1. 2 [SOAP 12], SOAP with Attachments [SOAPATTACH], WS-Security ([WSS 10], [WSS 11]), WS-Addressing [WSADDRCORE], and reliable messaging (WS-Reliability 1. 1 [WSR 11] or WSReliable. Messaging - currently at version 1. 2 [WSRM 12]) together with guidance for the packaging of messages and receipts along with definitions of messaging choreographies for orchestrating document exchanges. • As a profile of the eb. MS 3. 0 specification, AS 4 leverages much of messaging services requirements defined in that standard. Message security is governed by the WS-Security specification with support for payload compression. AS 4 supports both document push and pull message exchange choreographies, contains an AS 2 -like business nonrepudiation of receipt, and has the support for reception awareness providing just enough reliable messaging without overspecifying the functionality. Source: http: //docs. oasis-open. org/ebxml-msg/ebms/v 3. 0/profiles/AS 4 -profile/v 1. 0/os/AS 4 -profilev 1. 0 -os. html 13 Unclassified – Software Developer Training - SBR 2
Important Links Software Developer detail on SBR. GOV. AU http: //www. sbr. gov. au/software-developers SBR taxonomy architecture http: //www. sbr. gov. au/software-developers/enabling-sbr-in-my-application/sbr-taxonomy/taxonomyarchitecture SBR e. BMS web service artefacts (WIG, SDK) http: //www. sbr. gov. au/software-developers/developer-tools/new-form-pages/ebms-webservice SBR forms / services for the ATO http: //www. sbr. gov. au/software-developers/developer-tools/ato 14 Unclassified – Software Developer Training - SBR 2
Analysis and ATO documentation
Your path through our document will vary depending on your role. Pathway
Your pathway and what you need to achieving an STP enabled solution 0 1 2 3 4 5 Understanding STP requirements. Develop STP compliant data/XML. Develop an STP service into a whitelisted product. Develop complete STP solution. Develop eb. MS 3 component. Integrator working with employers. Systems integrator deploying COTS products. Pathway Scenario Business information you will need Payroll software developer 1 only using 3 rd party components to enable your solution. • • ATO Technical artefacts you will need • Payroll software developer 1 creating STP XML but using 3 rd party services to create wrapper, conform and send message to ATO 2 Payroll software developer 1 creating Conforming XML and wrapper but using 3 rd party service/ component to send message to ATO 2 Payroll software developer 1 creating Conforming XML and wrapper and building own eb. MS 3 capability to sign and send message to ATO 2 Software developer producing an eb. MS 3 client for use by third parties. STP Business Implementation Guide (BIG) AUSkey and Access Manager • • • STP Business Implementation Guide (BIG) AUSkey and Access Manager • None • STP Program Specific SBR Platform Conformance Testing Support • • SBR Platform Support Operational Framework • Operational Framework if Cloud STP Business Implementation Guide (BIG) • • • STP Program Specific Selected SBR Support • STP Program Specific Selected SBR Conformance Testing Support • • Operational Framework • • Guidance from your Service Providers. • • • Other ATO matters to be considered • CAA – online service provider kit. Other information you will need • Guidance from your Service Providers. 1. 2. STP Business Implementation Guide (BIG) • Guidance from your Service Providers. • • • Includes Commercial Software Developers, Employers who are customising legacy payroll systems. Component could be a Client, “API” or Cloud Service. Unclassified – Software Developer Training - SBR 2 Parties interested in becoming a Gateway. • STP Business Implementation Guide (BIG) AUSkey and Access Manager • STP Business Implementation Guide (BIG) • Expected that COTS vendor will provide guidance to implement their products. 17
The message layers and artefacts Looking at the layers that form a compliant eb. MS 3 message and how each segment is supported our artefacts. Information Sources Business Management System (BMS) STP Business Implementation Guide (BIG) How to develop your payroll system to meet the business rules and populate the XML message XML Message MST and Validation Rules Data and rules forming a valid STP message eb. MS 3 SBR 2 – eb. MS 3 Platform Suite The message patterns and conforming to the eb. MS wrapper and conformance. Signing Secure Token Service - Vanguard Access Manager - ATO 18 Unclassified – Software Developer Training - SBR 2
Your pathway and the ATO Artefacts Map The embedded document contains 4 ‘pathway to artefacts’ maps to help point you to the key documents you need to help you navigate the products we produce. 0 1 2 3 4 5 Understanding STP requirements. Develop STP compliant data/XML. Develop an STP service into a whitelisted product. Develop complete STP solution. Develop eb. MS 3 component. Integrator working with employers. 19 Unclassified – Software Developer Training - SBR 2
ATO Documentation http: //www. sbr. gov. au/software-developers/developer-tools/ato Register for updates! We publish on a Thursday and you should get an email on Friday with a link to the ATO Landing page open the A&L xlsx to find out what has changed. 20 Unclassified – Software Developer Training - SBR 2
Using the service registry • Critical to understand the relationships of the message to services, formats and deployment. • Can be used to link the type of service to the other artefacts – such as MEPs. • The communications sheet is important to see what has changed and impacts on your business. • Security type – tells you what type of authentication we need for the message - Vangard and SAML tokens. • Consumer access – tells you what authorisation model is required. This links you to the message structure as well as ATO’s access manager requirements. • SBR 3 section gives you the technical information as well as what to look for in our other artefacts. 21 Unclassified – Software Developer Training - SBR 2
Message Structure Table A definition of the data contained in the message which is sent/received by the service including: • Elements • Tuples (containers) • Specification for the schemas • Message may be re-used across collaborations. Same Schema used for Payevnt. submit and payevnt. update Message structure table Schema 22 Unclassified – Software Developer Training - SBR 2
Validation Rules • Validations run by the channel before internal processing occurs • Specified using Structured English • Validations document will provide details of that. Validation rules spreadsheet C# snippet Message repository 23 Unclassified – Software Developer Training - SBR 2
ATO Conformance Suite package • The test cases contain sample XML to use as part of your development processes. • If you are building an product that will send messages to the ATO, you will need to use these as part of the self certification testing process. • The test case data does not reflect payroll output. The intention is to provide scenarios to ensure you have covered the relevant aspects of eb. MS 3 development such as error handling, polling, etc. Conformance ATO Conformance Suite of artefacts pertaining to the Service/Obligation CS Key Store Conformance Suite Key Store AUSkeys to be used in EVTE CS CN Conformance Suite Cover Note Details of the changes from prior deployments and known defects CS Test Cases Conformance Test Cases Details of the test cases required for certification Test Instances Available at: standardbusinessreporting. sharefile. com Contact your account manager to get access. Conformance Test Instances XBRL test data that can be used with test cases 24 Unclassified – Software Developer Training - SBR 2
Important Links ATO Page in SBR http: //www. sbr. gov. au/software-developers/developer-tools/ato Subscriber page (system status and document updates) http: //www. sbr. gov. au/bulkmail/forms/subscribe-to-ato-landing-page 25 Unclassified – Software Developer Training - SBR 2
High level description of the ebms 3 SDK, C# Rules, Xml Format and Access Manager
Overview • The following will be covered at a high level • The purpose of the ebms 3 SDK embedded /reference client • Description of C# Rule Usage for SBR. • Description of the Xml Format used by the ATO. • Operation of Access Manager 27 Unclassified – Software Developer Training - SBR 2
Context 28 Unclassified – Software Developer Training - SBR 2
SBR SDK and Reference Client The Reference Client is provided as an example of how to connect to SBR using the ebms 3/AS 4 standards. The reference client is provided in Java, . NET and C. Both 32 Bit and 64 bit versions exist. All implementations rely on Java. 29 Unclassified – Software Developer Training - SBR 2
Reference Client Overview The SBR Reference Client is aimed at giving Software Developers an example of how to connect to the SBR eb. MS 3 platform using the SDK components provided by SBR. It is an example only and is not intended for production use. The reference client shows how to: • Interact with an AUSkey credential store. • Use a credential from the AUSkey store to call Van. Guard. • Package bulk/batch requests. • Submit requests. • Interpret the responses received. 30 Unclassified – Software Developer Training - SBR 2
eb. MS 3 Embeddable client • • • Is an implementation of a client eb. MS 3 Message Service Handler (MSH) that supports the exchanges applicable to SBR. Depends on the Java Runtime Environment (the IBM JRE is supplied). It facilitates communication between your business software and the SBR eb. MS 3 server using the eb. MS 3 protocol. 31 Unclassified – Software Developer Training - SBR 2
Recommendations • • • Use the Reference Client, eb. MS 3 SDK Developer guide and SBR eb. MS 3 Web Services Implementation Guide to familiarise yourself with the technologies and how they are used. Use the ebms 3 embedded client but abstract your business software from the implementation so that you are able to switch out the embedded client. Consider purchasing an eb. MS 3 message handler and adapt its implementation using the abstraction layer created above. 32 Unclassified – Software Developer Training - SBR 2
C# Rules • The ATO provides C# rules for services submitted via SBR • The C# files that the ATO provides for third parties reflects the code that the ATO currently uses at run time for both the eb. MS 3 and SBR 1 platforms. 33 Unclassified – Software Developer Training - SBR 2
C# Overview – How the ATO uses it • • • Each business rule in the Business Rules Spreadsheet has a corresponding implementation in the C# rules are based on an assertion model – so each business rule checks data elements within the incoming message and will return an error message if that assertion fails. These rules are considered to be “boundary layer” rules as no calls are made to back end systems. 34 Unclassified – Software Developer Training - SBR 2
C# Rules – How you can use them The ATO provides C# to software developers as a reference implementation – a very unusual practise for web services. The following are some ways in which the files can be used. • Unit testing of software products – allowing you to test the output reports that your product produces to see if they will pass through ATO boundary validation checks. • Could enable you to create a mock service that may allow you to run tests without hitting the EVTE environment. • You could use third party tools to convert the C# to another programming language. • Provides some additional clarity of what a business rule means at run-time. • Note that it is not recommended to include the provided C# rules in your delivered product. 35 Unclassified – Software Developer Training - SBR 2
C# Rules – What you need to use them • The. NET runtime 4. 5+ is recommended. • If you do not use. NET then either: • Potentially use C# conversion software to allow the C# to be converted to another language. • Or create a web service/mock that allows the rules to be called from your language/run time environment. • Any editor can be used to view/edit the C# files – but visual studio is recommended. 36 Unclassified – Software Developer Training - SBR 2
C# – Generation • • • The ATO has invested heavily over the past two year in enabling code generation for C#. The ATO is currently migrating from manually written code to generated code. Cross form rules are currently not generated. 37 Unclassified – Software Developer Training - SBR 2
Xml Format The ATO is still heavily invested in the SBR taxonomy – however the over the wire format is changing from Xbrl to Xml. • All data elements are still based on the SBR definitional taxonomy. • An algorithm is used to convert the message structure represented by the MST into Xml Schemas that are used by services. • While all data elements are still based upon the SBR taxonomy the algorithm compacts the data element names based on the Object. Classword standard used in SBR data elements. • Object Classes are removed by taking the parent element name into account. • The classwords are cut down in size. • Xml namespaces are not used for versioning – a single namespace is applied on a report by report basis. Versioning is handled by shape (similar to JSON). • More details are available at http: //www. sbr. gov. au/softwaredevelopers/developer-tools/ato 38 Unclassified – Software Developer Training - SBR 2
Access Manager enables an Administrator to assign permissions for Standard AUSkey holders and Device AUSkeys in their business to control access to ATO services. It allows a online service provider to identify their device AUSkey for Cloud authentication and authorisation. 39 Unclassified – Software Developer Training - SBR 2
What Access Manager allows for • Management of access to tax records for businesses, Tax and BAS agents. • Allows a business to specify another business that can act on their behalf. • Allows Tax/BAS Agents or business appointments to restrict access to particular clients or functions. • Allows businesses and agents to select and authorise online service providers who are able to securely submit lodgements from the cloud. PAYEVNT. 0003 2018 only 40 Unclassified – Software Developer Training - SBR 2
Access Management - Future Services • In the future services will be provided to enable management of end user security directly through a third party product. • This will allow users of third party products to stay within their product rather than having to go to the ATO web site to manage permissions. • The level of interest will determine the priority over building of other business value services. • Adding security maintenance features is inherently higher risk that other business services thus requiring a higher level of testing. • The use of device AUSkeys for Online Service Providers also has to be considered in the viability of creating Access Management Services. 41 Unclassified – Software Developer Training - SBR 2
Where to find further information Access Manager information can be accessed from the following links: Link Description https: //www. ato. gov. au/General/Online-services/Indetail/Using-Access-Manager/Access-Managerpermissions-for-ATO-and-ABR-online-services/ Provides a list of permissions and their support for SBR. https: //www. ato. gov. au/General/Online-services/Indetail/Transact-Online/Using-Access-Manager/ Describes what you can do within Access Manager https: //am. ato. gov. au/amsupport/pages/Scenarios. pdf Describes key scenarios for common usage of Access Manager. https: //abr. gov. au/AUSkey/ Reference Information for AUSkey 42 Unclassified – Software Developer Training - SBR 2
Implementation
Business 2 Government & Business 2 Business Super. Stream eb. MS 3 Standards cover each of the transaction below. Not every group will require every aspect of eb. MS 3, but should be able to handle the all features offered by eb. MS 3. B 2 B and B 2 G have mutual and exclusive patterns used, some outside the eb. MS 3/AS 4 standard, B 2 B Super. Stream eb. Ms 3/AS 4 GOVT AGENCY B 2 G G B 2 G ER Y EMPLO TAX PRACTITIONER Unclassified – Software Developer Training - SBR 2 MPC sub channels Bundling Alt Auth of Pull XML encryption security B 2 G B 2 B h G B 2 G SUPER FUND (or administrator) t Au B 2 B L One way Push One way Pull Two way Push/Push Two way Push/pull Two way Pull/Push Username & Password Auth PKI Auth Split/Join Multi Hop endpoint Reception Awareness Reliable Messaging Compression Body Duplicate detection XML Signature Security of Attachments Transport Level Security BANK M SA SUPER FUND (or administrator) Two way Synch Multi Hop Authenticate Pull Selective Pull MPC PAYROLL PROVIDE R 44
Choosing an SBR Implementation Model All parties in the SBR program must choose an implementation feature set. We have suggested three patterns in this presentation. To select a pattern: eb. MS 1. Understand your business model and Transaction volumes. Super 2. Understand SBR, Super. Stream and STP Specifications. 3. Determine what eb. MS 3 feature set and pattern is appropriate to your business. Super eb. MS Super ATO Super eb. MS Super 4. Choose eb. MS 3 Implementation approach. Should I: • Buy • Build or • Partner? Super Other eb. MS Gateways Universal Client Minimal Client
Architecture of the ATO Gateway SBR transactions are handled: 1. Software packages construct SBR payloads and transport via eb. MS. 2. Core services may route transactions to the ATO or any other SBR gateway. 3. Transactions are authenticated and authorised using Aus. Key certificates. 4. Transactions are handled in bulk or single. 5. SBR messages are validated and transformed to target system format. 6. ATO back office systems process transactions.
Testing
Systems Development Process Readiness is continuously assessed throughout the software takeup and deployment cycle Software Developer Take-up Cycle INFORMED ALIGNED COMMITTED PLANNED EXECUTED DEPLOYED OPERATING Expansion of ‘Executed’ and ‘Deployed’ Steps Software Developer SWD BUILD BUSINESS REQUIREMEN TS SERVICE SPECIFICATIO N BUILD INTEGRATION TEST EVTE FUNCTION TEST INTEGRATION TEST ATO BUSINESS ACCEPTANCE CONFORMAN CE TEST DEVELOPMEN T PRODUCTION WHITELIST AND PILOT 48 Unclassified – Software Developer Training - SBR 2
Multi-modal Testing e. Commerce has developed a double V Model for testing with SWD. This is largely used to explain to SWD their expectations and touchpoints with the ATO for testing. This process adapts to SWD with differing methodologies. Behind the e. CSD layer the ‘back-end’ changes can be delivered and tested in their existing practices adapting to the ATO’s multi-modal delivery approach. 49 Unclassified – Software Developer Training - SBR 2
Interoperability Process eb. MS 3/AS 4 Interoperability: Testing to done through an external organisation (such as the Drummond Group) to test for interoperability by simulating authentic transaction. Done by a matrix of test cases with all eb. MS 3/AS 4 enabled products. A certificate should be supplied to provide the product developer with certification there product has been tested against SBR. Similar to the heart foundation tick but applied to eb. MS 3 compliant products. Interoperability Trials Conducted by industry aligned groups to demonstrate interoperability at the business process level. Conformance Testing Conformance testing is used to ensure that defined standards are met. Testing the business message interoperability will be done through the SBR 2 conformance process. 50 Unclassified – Software Developer Training - SBR 2
ATO Production Go-Live Prod SWD Production Deployment EVTE Conformance Testing Level 4 System and Performance Testing EVTE Waterfall EVTE Integrated Product Testing In House Unit and Product Testing e. Commerce Testing ATO Processing Testing Level 1 & 2 Agile / Iterations 51
8. Software Developer On-Boarding • Developer Registration required • through SIPO, SBR Service Desk or existing account manager • Onboarding Team support services • Facilitate the integration of software developer partners systems to STP • Professional advocate for software developer partners within the ATO • Support, management and technical resolution of on boarding issues • Account management services to software developer partners • Testing & production release support • Limitations of the EVTE • Production Verification Test • Whitelisting and Certification • Assisting through the ATO Business process • Certifying the software and promoting via SBR Website UNCLASSIFIED
Production Service A Deploy Service A Go-Live Service C Deploy EVTE Conf Platform Deployment Service B Service C Service A Level 4 Platform Service B Service C Service A Platform Service B Iteration 1 EVTE (IPT) Level 2 Service B Go-Live Service B Deploy Service A Iteration 1 Service C Iteration 1 Service A Iteration 2 Service C Iteration 3 Platform Service B Iteration 1 Service A Iteration 1 Platform Service C Iteration 1 Service A Iteration 2 Service C Iteration 3 53
Questions? UNCLASSIFIED
- Slides: 54