Document Control s2

Revenue Online Services
Web Services
Client List Specification / File name: spec.doc
Status: Final
Version: 1.0
Prepared by: Brian Jones
Date: 13/11/02

Page 2 of 8

Revenue Online Services
Web Services
Client List Specification / File name: spec.doc
Status: Final
Version: 1.0

DOCUMENT CONTROL

Document Holder

Brian Jones

Change History

Version / Date / Change
1.0 / 13/11/01 / Document Created
1.1 / 26/06/2012 / Updated the following fields to allow them to support the new format registration numbers. The update involves a change to the regular expression used to determine if a number is valid.
Change Details:
Before: “[0-9]{7,8}[A-Wa-w][TWXtwx ]?”
After: “[0-9]{7,8}[A-Wa-w][A-ITWXZa-itwxz ]?”
Sample Numbers:
Existing Format: 1234567T
New Format: 1234567FA
Section / Field
Section 2 / Client Search – registration
Section 2 / TaxRegistration - registration
Appendix A / Added A3 – Sample response with new format numbers.

CONTENTS

1. Introduction 3

2. Calling the Service 4

2.1. Namespaces, Schemas and Locations 4

2.2. Operation Header 4

2.3. Digital Signature 4

3. Interpreting the Response 5

A. Examples 6

A.1. Request to retrieve a full client list 6

A.2. Response 7

Prepared by: Brian Jones
Date: 13/11/02

Page 2 of 8

Revenue Online Services
Web Services
Client List Specification / File name: spec.doc
Status: Final
Version: 1.0

1. Introduction

This document is a specification for the ROS web service for retrieving an agent’s client list. It covers all the necessary arrangements for calling this web service that are specific to this operation. 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 retrieving the client list can be used to retrieve a full or partial client list for an agent. The list will include the client’s name and a full list of all their registrations, to which the agent has access.

A partial list can be retrieved by specifying search criteria for the list. This criteria can consist of the start of the client’s name, the date from which the agent-client relationship started, or the registration of the client.

2. Calling the Service

The ROS web service for the client list is described through the WSDL file and the schema for the client list. This schema is also referenced within the WSDL file. These files will be located at

· http://www.ros.ie/schemas/ros.wsdl

· http://www.ros.ie/schemas/client/schema.xsd

The WSDL file is discussed in greater detail in the Overview Specification, including

· Where the web service is located

· What protocol must be used

2.1. Namespaces, Schemas and Locations

The client list web service uses the two namespaces enumerated in the Overview Specification. It also uses an additional namespace specifically for the client list. This extra namespace is used to define all the elements for describing the administration services and its responses.

Description / Namespace / Location
The client list elements / http://www.ros.ie/Ê
schemas/client/ / http://www.ros.ie/Ê
schemas/client/schema.xsd
Basic types for ROS schemas and web services / http://www.ros.ie/Ê
schemas/rostypes/ / http://www.ros.ie/Ê
schemas/rostypes/schema.xsd
Web service messages, operations, bindings, etc. / http://www.ros.ie/Ê
schemas/service/ / http://www.ros.ie/Ê
schemas/ros.wsdl

2.2. Operation Header

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 client list web service, the operation header should be

· Client/ClientList/Retrieve

Client/ClientList/Retrieve
This operation can be used to retrieve a full or partial list of an agent’s clients.

2.3. Digital Signature

The client list web service will always require a digital signature.

3. Interpreting the Response

The response from this web service will be a ClientList element. This will contain a series of ClientDescription elements, each of which will contain a series of TaxRegistration elements.

The ClientDescription element has a name attribute that specifies the client name. It then contains all the registrations of the client to which the agent has access. Each one of these is contained in a TaxRegistration element, which has attributes taxtype and registration which together fully specify the registration of the client.

If the search criteria specified in the input does not match any of the agent’s clients, an empty ClientList element will be returned. (Note that in the ClientSearch input document, if the registration attribute is completed without the taxtype attribute, it will be ignored).

A. Examples

A.1. Request to retrieve a full client list

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Header>

<wsse:Security xmlns:wsse=”http://schemas.xmlsoap.org/ws/2002/04/secext”>

<wsse:BinarySecurityToken valueType=”wsse:X509v3”

encodingType=”wsse:Base64Binary” id=”X509Token”>

MIIEZzCcA9cgwaABQfd86afd2g...

</wsse:BinarySecurityToken>

<ds:Signature xmlns:ds=”http://www.w3.org/2000/09/xmldsig#”>

<ds:SignedInfo>

<ds:CanonicalizationMethod>

Algorithm=”http://www.w3.org/2001/10/xml-enc-c14n#”/>

</ds:CanonicalizationMethod>

<ds:SignatureMethod

Algorithm=”http://www.w3.org/2000/09/xmldsig#hmac-sha1”/>

<ds:Reference URI=”#MsgOperation”>

<ds:DigestMethod Algorithm=”http://www.w3.org/2000/09/xmldsig#sha1”/>

<ds:DigestValue>DJbchm5gk...</ds:DigestValue>

</ds:Reference>

<ds:Reference URI=”#MsgBody”>

<ds:DigestMethod Algorithm=”http://www.w3.org/2000/09/xmldsig#sha1”/>

<ds:DigestValue>DJbchm5gk...</ds:DigestValue>

</ds:Reference>

</ds:SignedInfo>

<ds:SignatureValue>LyLsF0pi4wPu...</ds:SignatureValue>

<ds:KeyInfo>

<wsse:SecurityTokenReference>

<wsse:Reference URI=”#X509Token”/>

</wsse:SecurityTokenReference>

</ds:KeyInfo>

</ds:Signature>

</wsse:Security>

<Operation xmlns="http://www.ros.ie/schemas/admin/"

id=”MsgOperation”>Client/ClientList/Retrieve</Operation>

</soap:Header>

<soap:Body id=”MsgBody”>

</soap:Body>

</soap:Envelope>

A.2. Sample Response 1 (Existing format numbers)

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

</ClientDescription>

</ClientDescription>

</ClientList>

</soap:Body>

</soap:Envelope>

A.3. Sample Response 2 (New format numbers)

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

</ClientDescription>

</ClientDescription>

</ClientList>

</soap:Body>

</soap:Envelope>

Prepared by: Brian Jones
Date: 13/11/02

Page 2 of 8