IRESS Web Services Version 4

Home

Programmer's Guide

Contents

Please note: the example code snippets in this guide are written in Visual C# .NET syntax.

Overview

This is the latest generation of Web Service interface, for accessing the newest IRESS systems. This version is a Document/Literal style web service, designed for modern SOAP toolkits, such as .NET and Java 6.

Use this version to access:

This version of Web Services also provides a much richer suite of functionality over the previous version, including:

 

There are two different options for accessing Web Services 4:

1. Desktop Web Services

The IRESS front-end can host Web Services 4. This will replace the older style COM Automation API. This solution does not require "Web Services" to be enabled at the Group level in IRESS Web Administrator, rather it will use the client's existing IRESS license.

2. Server Side

Either via our central Web Servers, or via Web Services setup "locally" in the client's data centre. It offers a platform independent, scalable, and redundant server based solution without the need of running the IRESS front-end software. Server side Web Services requires users to be permissioned with "Web Services" at the Group level in IRESS Web Administration. Our central Web Servers would only be offered for solutions involving a limited number of users and/or calling frequency. It would not be used in solutions requiring the watching of updates. The advantage of local Web Services installs in the client's data centre is performance, as well as the ability to watch for updates.

Basics

Getting Started

When you begin a new project, use the following steps as a rough guide.

  1. Add Web Reference

  2. Create an IRESS Session

  3. Create a Service Session if calling methods against IOSPlus, IPS or FIXPlus services

  4. Call desired methods

  5. Process response or handle error for each method

  6. End the Service Session (if calling IOSPlus, IPS or FIXPlus) and end the IRESS Session

These steps will be explained in detail in the following sections.

Adding a Service/Web Reference

 The first thing you need to do is add a reference to the web service from your client application.

Desktop Web Services

The WSDL URL can be constructed under Options | Settings | Desktop Web Services in the IRESS front-end.

You will have to provide:

Server Side Web Services

Navigate to the web service URL you are provided with to get the WSDL form.

You will have to provide:

There are two different authentication modes: HTTP Basic, and Form and URL.

HTTP Basic Authentication

Uses basic access authentication to send the credentials to the server. In this mode, the IRESS User Name and IRESS Company Name should be provided in the format username@company.

HTTP basic authentication

Form and URL Authentication

Uses query string to send the credentials to the server. In this mode, the IRESS User Name and IRESS Company Name are provided in separate edit controls.

Form URL authentication

When the WSDL is accessed the credentials provided will be validated. If the validation succeeds, the WSDL will be dynamically generated.

WSDL                

Requests

After you add your service/web reference, you can make a request.

There are two kinds of requests:

The request Input has two components:

Responses

If a request executes normally, you will receive an Output; otherwise, you will receive a SOAP fault.

A response Output has the following components:

Sessions

IRESS Session

The very first thing you should do is obtain an IRESS session key. This acts as a token that tells the system who you are and what operations you are allowed to execute.

An IRESS session allows you to:

IRESS Session Lifetime

Desktop Web Services

Once an IRESS Session is established, it is valid for the lifetime of the front-end user logon. If the front-end user is logged out and logs back in again, any previous session will expire and cannot be used anymore. Any pending data will be deleted. You will have to establish another session if you want to make more requests.

Server Side Web Services

An IRESS Session by default will expire after two hours of inactivity. The lifetime counter starts after your last request finishes. It resets if you do another request through that session. When a session expires, you can't use it anymore. Any pending data will be deleted. You will have to establish another session if you want to make more requests.

Starting an IRESS Session

To establish an IRESS session and obtain a session key, you call the IRESSSessionStart method. The method takes the following parameters:

If the method is successful, you will get the following:

Ending an IRESS Session

After you finish with using you session, you can explicitly terminate the session and free your login count that the session was using. Alternatively, you could let your session expire. Ending an IRESS session will give you some statistics about your session.

To end an IRESS session you call the IRESSSessionEnd web method. This method does not have any parameters, but you need to set the IRESS session key in the header.

Service Sessions

In order to request data from IOSPlus, IPS and FIXPlus, you need to establish an active session with the server you wish to retrieve data from.

Starting a Service Session

To obtain a Service session key, you call the ServiceSessionStart web method. The method takes the following parameters:

If the method is successful, you will get the following:

Service Session Lifetime

A service session does not expire.

Ending a Service Session

There are two ways to terminate a service session, directly and indirectly.

To terminate the session directly, you call the ServiceSessionEnd method. It does not take any parameters but you need to set the service session key in the header.

To terminate the session indirectly, you can just terminate the IRESS session.

Errors

When writing code to handle errors, clients should not write code to handle specific error numbers rather they should only check for the error number being non-zero, as error numbers may change in the future. This includes error numbers returned in SOAP exceptions (in the IRESSFaultDetail structure), or errors returned in the response for a method call (i.e. methods that include the ErrorNumber/ErrorMessage output columns).

If a web request does not execute properly, it will return a SOAP Fault. Here is an example of what the SOAP fault may look like: SoapFault.XML

Soap Fault

Catching Exceptions

If your client application can handle exceptions, you can catch the following exceptions:

System.ServiceModel.FaultException<IRESSFaultDetail>: If you are using a service reference. 

            try
            {
                .
                .
                .
            }
            catch (System.ServiceModel.FaultException exIressFault)
            {
                // The error message
                System.Diagnostics.Debug.WriteLine(exIressFault.Message);

                // The XML input
                System.Diagnostics.Debug.WriteLine(exIressFault.Detail.Input);

            }

FaultException

System.Web.Services.Protocols.SoapException: if you are using a web reference. 

            try
            {
                .
                .
                .
            }
            catch (System.Web.Services.Protocols.SoapException expSoap)
            {
                // The error message
                System.Diagnostics.Debug.WriteLine(expSoap.Message);
 
                // The XML input
                System.Diagnostics.Debug.WriteLine(expSoap.Detail);
            }

The Message (SOAP faultstring) property will contain the error message returned by the server.

Soap Fault

If you need more information about the error, the Detail property is an XML blob that contains more information. You can parse it and get information about the error number, context and server.

NOTE: Do not rely on the information you get in the Detail as it is subject to change.

Soap Fault

Advanced

Paging Results

The new web services allow for the retrieval of data returned in pages. You can specify how many rows of data each page will contain. This is done by setting the Header.PageSize property of the request. However, this number may not always be honoured, as the data server can override it with a smaller value.

If there are more pages of data, the response StatusCode will be 1 (more data available). Calling the same request again with same request ID will return the next page. Once the last page is received, the response StatusCode will be 2.

Subscribing to Updates

Some methods will have an associated updating request. The name of the method used to retrieve the updates will usually have the same name as the Data method with "Updates" appended at the end.

There are two ways to subscribe to updates:

For either way that you choose you have to set the Header.Updates property of the request to True.

A request will keep watching for updates until one of the following happens:

Troubleshooting

When raising a support query with IRESS, please ensure the following information is logged and provided:

Please send through the SOAP XML Request and Response if possible. If this information cannot be provided, it may hinder or delay the ability for IRESS to troubleshoot.

Was this query previously working with different details? If so, please provide the above details.

Walkthroughs

The following walkthroughs were built using Visual Studio 2008.

Note: These Walkthroughs use a default Web Services URL end-point that points to one of our central Server Side Web Servers.  Please ensure you use the correct URL when using Server Side or Desktop Web Services.

Other Samples

Send feedback on this page.

Copyright (C) 2009 IRESS Market Technology