Do Not Use

Revenue Online Services Pre-populated Download Web Service Specification

Revenue Online Services

Web Service Specification Pre-populated Download

Last Updated 13/01/11 Document Version 1.0

of 7 Revenue Online Services Pre-populated Download Web Service Specification CONTENTS Contents...... 2 0 Document Information...... 3 0.1 Synopsis...... 3 0.2 Change History...... 3 1 Web Service Overview...... 4 2 Calling the Service...... 5 2.1 WSDL File...... 5 2.2 Web Service Schemas...... 5 2.3 Namespaces, Schemas and Locations...... 5 2.4 Operation Headers...... 5 2.4.1 PrepopulatedForm/Download...... 5 2.5 Digital Signature...... 6 3 Interpreting The Response...... 7 3.1 PrepopulatedForm/Download...... 7 3.2 PrepopulatedFormDownloadResponse...... 7 3.3 Errors...... 7

of 7 Revenue Online Services Pre-populated Download Web Service Specification 1 DOCUMENT INFORMATION

1.1 Synopsis Specification for the Pre-populated Download web service.

1.2 Change History Table 1: Change History Version Section Change Description Date Number Affected 0.1 ALL Initial Draft 13/01/11 1.0 ALL Final Version 13/01/11

of 7 Revenue Online Services Pre-populated Download Web Service Specification 2 WEB SERVICE OVERVIEW

This document is a specification for the ROS Pre-populated Download web service. It covers all the necessary arrangements for calling this web service that are specific to Pre-populated Form Download. It should be read in conjunction with the Overview Specification, which discusses the general approach to calling a ROS web service.

The ROS web service for Pre-populated Form Download provides 1 basic service:  Provision of pre-populated forms

This service is covered in this document.

of 7 Revenue Online Services Pre-populated Download Web Service Specification 3 CALLING THE SERVICE

The ROS web service for the Pre-populated Form Download is described through the WSDL file and the Schema. This schema is also referenced within the WSDL file.

3.1 WSDL File Download from http://www.ros.ie/schemas/ros.wsdl The WSDL file is discussed in greater detail in the Overview Specification, including  Where the web service is located  What protocol must be used

3.2 Web Service Schemas Download from http://www.ros.ie/PublisherServlet/info/wsindex Please ensure to download the appropriate schema for the return and period that you are attempting to file. Review the schema notes for the chosen return schema for more information on the elements and their validation rules.

3.3 Namespaces, Schemas and Locations The Pre-populated Download web service uses the two namespaces enumerated in the Overview Specification. It also uses an additional namespace specifically for Pre-populated Form Download. This extra namespace is used to define all the elements for describing Pre-populated Form Download.

Description Namespace Location Basic types for ROS http://www.ros.ie/schemas/rostypes/ http://www.ros.ie/schemas/rostypes/schema.xsd schemas and web services Web service messages, http://www.ros.ie/schemas/service/ http://www.ros.ie/schemas/ros.wsdl operations, bindings, etc. The Pre-populated Form Determine namespace from latest http://www.ros.ie/PublisherServlet/info/wsindex Download elements schema

3.4 Operation Headers As discussed in the Overview Specification, it is necessary to provide an Operation header in the SOAP request to identify which web service you wish to call. For the Pre-populated Download web service, there is 1 option depending on which operation you wish to call:  PrepopulatedForm/Download

3.4.1 PrepopulatedForm/Download This operation can be used to request a pre-populated form. When this service is being used, the following must be specified:  Registration Number  Account Type Code  Form Type Code  Period Start Date  Period End Date

of 7 Revenue Online Services Pre-populated Download Web Service Specification

The result from this will be a Pre-populated Form Download web service response, containing the request data submitted. In addition, a Form or Error List element may be returned within the response, depending if the request passes validation and on whether a pre-populated form is available for the request.

3.5 Digital Signature The Pre-populated Download web service may or may not require a digital signature depending on which operation is being accessed, according to the following table.

Operation Signature required (Yes/No) PrepopulatedForm/Download Yes

of 7 Revenue Online Services Pre-populated Download Web Service Specification 4 INTERPRETING THE RESPONSE

The response from this web service will be an Acknowledgement element. This element extends the AcknowledgementType described in the Overview Specification.

In addition to the elements and attributes declared as part of the AcknowledgementType type, there may also be a SummaryCalculation element. This element will only be returned if the validation was successful. It contains details of the calculation and total liability as calculated by Revenue for the submitted Form 11.

4.1 PrepopulatedForm/Download If the operation is PrepopulatedForm/Download, then a successful validation of the form will return a PrepopulatedFormDownloadResponse while an unsuccessful one will return an ErrorList containing the errors. See below for an explanation of the PrepopulatedFormDownloadResponse & ErrorList elements.

4.2 PrepopulatedFormDownloadResponse When a request is send to the web service, a PrepopulatedFormDownloadResponse will be returned. This element contains the submitted request details if the request passes validation and additionally includes a pre-populated form if there is one available for the request. When the request fails validation, a PrepopulatedFormDownloadResponse is still included but it will contain an ErrorList.

4.3 Errors There are two different checks done for any form submitted via Webservice. Firstly, the XML file is validated against the schema. Any errors at this stage will result in an error message like the following: Error validating XML: cvc-complex-type.4: Attribute 'ppsnself' must appear on element 'ns3:Details'.

If the XML validation passes ok, the data within the form is checked. This will include checks on the values for each element and for discrepancies between values in different elements. Attributes of elements are also checked.

Any errors in these checks will produce error text with the name of the element that contained the error and the Panel the error occurred in, like the following: PPSN (Personal Details) is a required field.