One Gate (CSSR)A2A – Web Service

June 2010 – Version 1.0

Page | 2

A2A - One Gate Web Services

© National Bank of Belgium, Brussels All rights reserved. The document or parts of it may be copied for educational and non-commercial purposes providing reference is made to the original document.

Page | 3

A2A - One Gate Web Services

0. VERSIONS ............................................................................................................................................... 4

1. INTRODUCTION AND SCOPE ................................................................................................................... 5

1.1 SCOPE ................................................................................................................................................. 5 1.2 AUDIENCE AND OVERVIEW ........................................................................................................................ 5 1.3 OTHER MANUALS ................................................................................................................................... 5

2.WEBSERVICES .......................................................................................................................................... 6

2.1 WHAT ARE WEB SERVICES? ....................................................................................................................... 6 2.2 BASIC CONCEPTS .................................................................................................................................... 6

2.2.1 SOAP........................................................................................................................................... 7 2.2.2 REST ........................................................................................................................................... 7

3. PREREQUISITES ....................................................................................................................................... 8

4. FAULTS AND PROBLEMS ......................................................................................................................... 9

4.1 HTTP ERROR AND STATUS CODES ............................................................................................................... 9 4.2 SOAP FAULTS ....................................................................................................................................... 9

4.2.1 Client SOAP Faults ....................................................................................................................... 9 4.2.2 Server SOAP Faults ...................................................................................................................... 9

5. ONE GATE (CSSR) WEB SERVICE .............................................................................................................11

5.1 THE URL OF THE WEB SERVICE ..................................................................................................................11 5.2 SCHEMA ..............................................................................................................................................11 5.3 METHODS OF CRS .................................................................................................................................11

5.3.1 uploadFile_A2A ..........................................................................................................................11 5.2.2 FeedbackListRequest ..................................................................................................................14 5.2.3 feedbackRequest ........................................................................................................................16

6. EXAMPLES .............................................................................................................................................18

6.1 VISUAL STUDIO.NET - C# .......................................................................................................................18 6.1.1 uploadFile_A2A ..........................................................................................................................18 6.1.2 feedbackListRequest/feedbackRequest .......................................................................................19

6.2 JAVA ..................................................................................................................................................21 6.3 SOAP ................................................................................................................................................21

6.3.1 uploadFile_A2A ..........................................................................................................................21 6.3.2 feedbackListRequest ..................................................................................................................21 6.3.3 feedbackRequest ........................................................................................................................22

6.4 OTHER TOOLS .......................................................................................................................................23

ANNEX 1: REFERENCES ..............................................................................................................................24

ANNEX 2: BASE64 ENCODING ....................................................................................................................25

Page | 4

A2A - One Gate Web Services

0. VERSIONS

Version Date Description 1.0 June 2010 First published Any remarks, additions and corrections to this manuel may be sent to the following emailaddress : mailto:onegate@nbb.be.

Page | 5

A2A - One Gate Web Services

1. INTRODUCTION AND SCOPE

One Gate (CSSR) offers the user a wide range of tools to report data. In many cases reporting will use the online surveyforms available in the webbased application. This is without doubt the easiest way to report data. But in some cases the volume of data to report will be too large for the "manual" reporting. And there are situations where the data to report are already available in electronic form e.g. in a database. You only need the programs to retrieve data from the database to make the report to One Gate (CSSR). To resolve the problem of voluminous reports and to leverage the existing investments in software One Gate (CSSR) offers alternatives to the manual reporting using webforms. We have the following reporting channels:

1. The import of CSV-files through the One Gate (CSSR) online application. 2. The upload of XML-files through the One Gate (CSSR) online application. 3. You can add an XML-file to an email sent to a welldefined emailaddress 4. The use of Web Services. The reporter's software will "converse" directly with the One

Gate (CSSR) application. The communication protocol for both the contents (reporting data) and the packaging is XML.

5. The use of HTTPS entrypoints

1.1 SCOPE

This manual will deal with a description of the web service (channel 4) only. The XML-protocol used for data reporting is described in this document.

1.2 AUDIENCE AND OVERVIEW

The intended audience of this manual are software developers. The contents of the manual:

Chapter 2 explains the philosophy behind web services Chapter 3 talks about the access to the One Gate (CSSR) Web Service Errors and faults are the object of chapter 4. Finally chapter 5 describes the methods and messages of the web service. Examples of use are given in chapter 6. A couple of annexes complete the manual.

1.3 OTHER MANUALS

A strictly technical manual is available at [6].

Page | 6

A2A - One Gate Web Services

2.WEBSERVICES

2.1 WHAT ARE WEB SERVICES?

A web service is just another way of performing a Remote Procedure Call (RPC). The term RPC says it all; we are dealing with a function or a procedure that is to be executed on a machine other than the machine where the user of the web service is located. The communication between the user and the web service uses a network. For the time being web services are the final stage in a long technological evolution to make RPC's happen. DCE RPC, CORBA, DCOM, .NET Remoting and others are some of the predecessors of web services. Most of these protocols were pretty complex. They often relied on a given software platform and they needed a lot of local (and remote) infrastructure to function well. Web services on the other hand are very "light" in the sense that only minimal investments need to be done on the user's side. The small footprint has one major drawback: the functionality offered by web services can never be as rich as that offered by some of the heavy alternatives. DCOM for instance relies on a permanent connection between the client and the server-object. We have a session going on and a lot of session-related information can be saved and re-used. Web services don't offer this facility: server-objects will only live for the duration of the call and if you want to maintain a session other means will have to be used. Web services are meant for relatively simple operations where the user will send a message (e.g. a date, the name of a stock market and the tickercode of a stock) and where he receives a message in return (e.g. the value of the stock on the given date and market).

2.2 BASIC CONCEPTS

The easiest way to describe a web service is to think of it as a program that lives on a given webaddress (or URL) and that reacts to messages sent to it. But a web service won't react to arbitrary messages. Every web service recognizes a set of well defined messages - called methods. The names and the contents of the acceptable messages are agreed upon. And the same applies to the responses sent back to the user. In classical computer terms the web service corresponds to a class or an interface that implements some functions or methods (the messages) which take well defined parameters and which may (or may not) return values of a given nature1. The name, the (optional) list of parameters and the (optional) return type define the function's signature. The signature can be seen as a contract between the user and the provider of the function or the service. The concept of "contract" is very important in the world of web services. The contract is formalized in the so-called WSDL-files. WSDL - which stands for Web Services Description Language - is an XML-schema developed to describe web services. It defines the messages, the parameters and the result of the operations. WSDL-files are the contract and the documentation of the web service. WSDL-files are structured and adhere to a schema and that makes them suiteable for use by a large collection of tools that will almost automatically translate the WSDL into client-code. This of course greatly facilitates the use of web services. How can one obtain the WSDL of a web service?

sometimes the WDSL-file will be available on a website The WSDL can be generated on-the-fly by the server that hosts the web service. When

you know the URL of the server and the name of the service kent, you can produce the WSDL as follows

1 Some programming languages distinguish between methods returning values (called functions) and other (called subroutines, procedures etc).

Page | 7

A2A - One Gate Web Services

http://url.of.server/nameOfService?wsdl There are several ways to implement web services and to communicate with them. The most common protocols are SOAP and REST. In both cases HTTP(S) will be the networkprotocol. 2.2.1 SOAP SOAP stands for Simple Object Access Protocol. The protocol defines a collection of XML-schemas that specify the use of web services. The message and the parameters - aka as the method call - on the one hand and the result of the call on the other hand will be sent using so-called SOAP-enveloppes. These enveloppes are the payload of the HTTP POST requests and responses between the client and the server. See Chapter 5 for more details. 2.2.2 REST Web services using the SOAP-protocol are sometimes described as heavy-weight web services. Following the fashion in other domains of live a "light" version of web services has been developed: REST. REST is short for "Representational State Transfer". What it means is that every web service will be available as a resource on a server; using the web service is just a matter of typing the correct URI in a browser. e.g. http://url.of.server/stocks/Euronext Brussels/20100324/NBB http://url.of.server/stocks/Euronext Amsterdam/20100324/ING ... The One Gate (CSSR) web services use the SOAP-protocol.

Page | 8

A2A - One Gate Web Services

3. PREREQUISITES

Using the One Gate (CSSR) web services requires the https protocol. The user needs a valid certificate (respecting the X.509 recommandation - see http://www.itu.int/rec/T-REC-X.509/en) to access the services. The certificate must be registered at the National Bank of Belgium (NBB). The NBB accepts certificates from Global Sign, Certipost and Isabel. The NBB will install a login proxy in the near future; applications must be able to perform a URL redirect. The wsdl-description of the One Gate (CSSR) web service is found at [3].

Page | 9

A2A - One Gate Web Services

4. FAULTS AND PROBLEMS

The use of the web service may results in errors. There are two broad categories of errors: HTTP-errors and SOAP-faults.

4.1 HTTP ERROR AND STATUS CODES

An overview of HTTP error codes can be found in http://www.rfc-editor.org/rfc/rfc2616.txt. The one you will most probably meet is error 403 ("Forbidden"). The most likely cause of the error is related to the client certificate used in the communication with the web service. As mentionned in Prerequisites the certificate must be valid and it must be registered at the NBB prior to using the web service. Potential client certificate problems are:

No client certificate was sent with the SOAP request The certificate is not valid The certificate is valid but not registered for use at the NBB. The certificate has expired.

<error 403 if volume limit exceded?> The NBB will install a login proxy in the near future; a server redirect returns the status code 302.

4.2 SOAP FAULTS

SOAP faults may originate at the client or at the server. 4.2.1 CLIENT SOAP FAULTS Client SOAP faults are usually the result of errors in using the methods (wrong method name, wrong input/output types, ...). The SOAP fault enveloppe looks like the following: <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <SOAP-ENV:Fault> <faultcode>SOAP-ENV:Client</faultcode> <faultstring>Validation error</faultstring> <faultactor></faultactor> <detail> <spring-ws:ValidationError xmlns:spring-ws="http://springframework.org/spring-ws"> cvc-complex-type.2.4.b: The content of element 'tns:FeedbackListRequest' is not complete. One of '{"http://www.onegate.eu/2010-01-01":NotRead, "http://www.onegate.eu/2010-01-01":Read}' is expected. </spring-ws:ValidationError> </detail> </SOAP-ENV:Fault> </SOAP-ENV:Body>

</SOAP-ENV:Envelope> The solution is straightforward: correct the client code to get rid of the SOAP fault. 4.2.2 SERVER SOAP FAULTS Problems on the One Gate (CSSR) server will be the cause of this kind of error. Please contact the Service Desk of the National Bank of Belgium (servicedesk@nbb.be tel. 32 2 221 40 60) should the server fault persist

Page | 10

A2A - One Gate Web Services

An example of a Server SOAP Fault: <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <SOAP-ENV:Fault> <faultcode>SOAP-ENV:Server</faultcode> <faultstring>[ISS.0088.9112] An Exception was thrown in the server:Failure occurred while receiving message. </faultstring> <faultactor>http://onegate-certificate-test.nbb.be/ws/CRS.in.nbb:crs</faultactor> <detail xmlns:webM="http://www.webMethods.com/2001/10/soap/encoding"> <webM:exception> <webM:className>com.wm.lang.flow.FlowException</webM:className> <webM:message xml:lang="">Failure occurred while receiving message. </webM:message> </webM:exception> </detail> </SOAP-ENV:Fault> </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Page | 11

A2A - One Gate Web Services

5. ONE GATE (CSSR) WEB SERVICE

5.1 THE URL OF THE WEB SERVICE

The One Gate (CSSR) web service deals with data upload and related methods; it is called crs. The service is to be found at the following URL: Production: https://onegate-certificate.nbb.be/soap/crs

Test: https://onegate-certificate-test.nbb.be/soap/crs

5.2 SCHEMA

5.3 METHODS OF CRS

The service implements three methods: Method Description uploadFile_A2A Upload of data through an XML file. feedbackListRequest Request a list of available feedback feedbackRequest request specific feedback. 5.3.1 UPLOADFILE_A2A 5.3.1.1 Description The main method of the web service is used to upload data into One Gate (CSSR). The input is a message of type uploadFileRequest. The output is a message of type uploadFileResponse. uploadFileResponse uploadFile_A2A(uploadFileRequest). uploadFileRequest will hold the data to be loaded into One Gate (CSSR) - aka the payload. The payload has to respect the following rules and limitations:

The file containing the data is an XML-file according to the One Gate (CSSR) XML-protocol. The "old" CSSR format is still accepted. The new XML-protocol is described in [1].

Page | 12

A2A - One Gate Web Services

The size of the payload is limited to 10MB. The files may be compressed but the resulting zip-file should contain at most one file.

The Manager of your reporting domain may impose the electronic signing of the data you load into the system. Signing will be performed using the private key of the sender's certificate.

The Manager of your reporting domain may impose the encryption of the data you load into the system. The One Gate (CSSR) server's public key must be used for encryption. You will find the key for the production/test server at [4],[5] respectively. Encryption implies electronic signing.

The contents must be converted to base64 (see Annex 2). To summarize: Step Mandatory/Optional XML validation optional Zip optional Signing depends on the reporting domain but mandatory when the

data are encrypted Encryption depends on the reporting domain base64 conversion mandatory Figure 1 summarizes the sequence of actions to be defined.

E F 0 1 .X M L

v a l id a te

z ip

s ig n

e n c r y p t

b a s e 6 4

v a l id a te w i th X S DY

N

c o m p r e s sY

N

s ig n w i th u s e r c e r t i f i c a tY

N

e n c r y p t w i th s e r v e r p u b l ic

k e yY

N

E F 0 1 .B IN

Figure 1: transforming the XML-report into the payload for fileUpload_A2A

5.3.1.2 Input: uploadFileRequest

Page | 13

A2A - One Gate Web Services

The input message uploadFileRequest has two properties: FileName and UploadFile. Property Mandatory/Optional Type Description FileName optional xs:string The name of the file to be loaded into

One Gate (CSSR). The name will be used in any feedback.

UploadFile mandatory xs:Base64Binary The contents of the file to be loaded in base64 (and after optional zipping, signing and encryption).

5.3.1.3 Output: uploadFileResponse

The result of a succesful web service call is a message of type uploadFileResponse which has a single property: TicketID: Property Mandatory/Optional Type Description TicketID - xs:Base64Binary The reference number of the file

upload action. When the web service call succeeds you will find a valid TicketID in uploadFileResponse. The TicketID will allow the user to follow-up the processing of the data in One Gate (CSSR). More details can be found at [2]. 5.3.1.4 Errors and problems HTTP errors and SOAP faults are discussed in Chapter 4 The presence of a TicketID in uploadFileResponse does not imply that the contents of the file are acceptable to One Gate (CSSR). The TicketID means that One Gate (CSSR) has received the file without any problems. The contents of the file will be validated by an asynchronous process. There will be some delay before the results are available. The results of the validation and the processing are available as feedback from One Gate. You can use the online application or the web methods feedbackListRequest and feedbackRequest to retrive this feedback. Potential problems with the payload are:

Problems related to security and encoding o The payload is not encrypted nor signed but the domain imposed signing and/or

encryption. o The payload was encrypted using the wrong certificate. o base64 encoding was not applied. o ...

Problems related to the contents of the file o Violations of the One Gate (CSSR) XML protocol o Unknown domain, report or form codes o data do not respect validation rules o ...

Page | 14

A2A - One Gate Web Services

5.2.2 FEEDBACKLISTREQUEST This method - usually combined with the third method feedBackRequest - will help you to retrieve feedback on the file upload from One Gate (CSSR). The purpose of feedbackListRequest is to get a list of feedback-ids from the database. Each of these ids can then be used to retrieve the detailed feedback. De input is a message of type FeedbackListRequest2; the output is a message of type FeedbackListResponse. Note The result of this method will be used in method feedbackRequest. One might wonder why there are two methods to retrieve the feeback when one method could easilly do the job. The reason is twofold. First of all feedback in One Gate (CSSR) is identified by an internal number which in general is unknown to the user. So they must be provided prior to their use. Secondly the amount of available feedback is potentially very large. The user must be able to be selective before retrieving the feedback. Selecting feedback is the raison d'être of the method feedbackListRequest; the user specifies the nature of the feedback and the points in time between which the feedback has been produced. The user can only retrieve feedback on file uploads which he initiated. The use of the web services implies the identification of the user by means of a certificate. Within One Gate (CSSR) the certificate is linked to a user identification. Feedback will be selected based on this user id. 5.2.2.1 FeedbackListRequest

The input message specifies the scope of the feedback to be retrieved. The properties are: Property Mandatory/Optional Type Description NotRead see text EmptyType Indicates you would like to get the

feedback-ids of all feedback that hasn't been read yet.

Read see text ReadType Indicates you would like to get the feedback-ids of all feedback generated between a start and an end date.

The schema makes clear that NotRead and Read are part of an XML schema "choice" element. This implies that only one of those values should be present in the SOAP-request, not both3.

2 The input message type and the method have the same name but for the initial capital. XML and SOAP are case sensitive so this is not a problem. 3 In object oriented programming languages like Java and C# this will be called polymorphism. One property can show multiple faces. As we will see in the C# examples the property will be called "Item" and will be of type object - the most generic type in C#.

Page | 15

A2A - One Gate Web Services

The datatype EmptyType doesn't have any properties or methods. Specifying "NotRead" in the SOAP-request is enough to retrieve the identifiers of the unread feedback.

The datatype ReadType has a single property that defines the timespan of the feedback. Property Mandatory/Optional Type Description TimeFrame Mandatory TimeFrameType The structure defines the start date

and the end date of the timespan.

TimeFrameType has two properties: Property Mandatory/Optional Type Description FromTime Mandatory xs:dateTime start date and time of the timespan ToTime Mandatory xs:dateTime end date and time of the timespan Chapter 6 has some examples on the use of this input message.

5.2.2.2 FeedbackListResponse

A succesfull execution of feedbackListRequest gives you a FeedbackListResponse return message. The contents of this datatype are also polymorphic4. In case no feedback corresponds to the search criteria in FeedbackListRequest the return type will contain "NoFeedback". This property is of type EmptyType and it doesn't contain any useful information..

4 Every development environment translates these XML/Soap concepts in its own way. Visual Studio.NET puts the contents of FeedbackListResponse in a property called "Items": FeedbackListResponse flr = crs1.feedbackListRequest(flrc); object[] items = flr.Items; "NoFeedback" corresponds to a null-value in "Items". When feedback is available - "Feedback" is present - "Items" will be an array of type object. Every element in the array can be casted to a variabele of type FeedbackType: string FeedbackId = ((FeedbackType)items[0]).FeedbackId;

Page | 16

A2A - One Gate Web Services

When feedback is available for the given search criteria the response will be "Feedback" of type FeedbackType. For every available feedback item there will be an element of this type in de response. To summarize: Property Mandatory/Optional Type Description NoFeedback - EmptyType no feedback available Feedback - FeedbackType contains an identifier for each available

feedback item

The datatype FeedbackType has two properties which will help to retrieve the feedback itself: Property Mandatory/Optional Type Description FeedbackID - MessageIdType The identifier of the feedback. To be

used in retrieving the feedback with method feedbackRequest.

TicketID - TicketIdType The ticketid generated at data upload time

MessageIdType is a non-negative integer; TicketIdType is of type string.

5.2.2.3 Fouten en problemen HTTP errors and SOAP faults are discussed in Chapter 4 <to be completed> 5.2.3 FEEDBACKREQUEST The method retrieves feedback for a given feedbackidentifier. The input is a message of type FeedbackRequest; the output is a message of type FeedbackResponse5. Datatype FeedbackRequest and the method feedbackRequest have more or less the same name but are different concepts. 5.2.3.1 FeedbackRequest

The message FeedbackRequest contains the identifier of the feedback we would like to retrieve. The element has a single property:

5 The input message type and the method have the same name but for the initial capital. XML and SOAP are case sensitive so this is not a problem

Page | 17

A2A - One Gate Web Services

Property Mandatory/Optional Type Description FeedbackID Mandatory MessageIdType The identifier of the feedback. The FeedbackID returned in FeedbackListReponse can immediately be used as a parameter in FeedbackRequest. 5.2.3.2 FeedbackResponse

The result of feedbackRequest is an element of type FeedbackResponse. It has a single property. Property Mandatory/Optional Type Description Payload - binary64 An XML file that contains the

requested feedback The result - Payload - is a binary file (base64). It must be decoded to make it readeable. One Gate (CSSR) will sign/encrypt the payload if the original file was. To get the contents of payload you will have to:

decode from base64 (optionally) check the electronic signature (using the server's certificate) (optionally) decrypt the contents using your private key.

The result is an XML file with the following information (Payload is only partially shown).

<?xml version="1.0"?> <tns:Body xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tns="http://www.onegate.eu/2010-01-01"> Validation report for ticket number [C-161725147] </tns:Body> <tns:Attachment contentType="text/xml" contentName="feedback.xml" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tns="http://www.onegate.eu/2010-01-01"> PD94bW...Pg==

</tns:Attachment>

The example shows the ticketnumber produced when the file was loaded - C-161725147 - and the name of the feedback file - feedback.xml. The contents of the file are added as an attachment. The contents of "Attachment" are coded in base64. 5.2.3.3 Errors and problems HTTP errors and SOAP faults are discussed in Chapter 4 <to be completed>

Page | 18

A2A - One Gate Web Services

6. EXAMPLES

6.1 VISUAL STUDIO.NET - C#

Consuming web services in Visual Studio .NET is straightforward. To add new web services in the Solution Explorer use the option Add Web Reference available in the node Web References.

Proxy classes are generated automatically once you have added the web services. From now on the web service can be used as any other class. 6.1.1 UPLOADFILE_A2A The following code snippet shows how you can upload a file in One Gate (CSSR) static void CheckUpload() { try { X509Certificate cert = X509Certificate.CreateFromCertFile (@"c:\users\docs\onegate\certificate\nuin_003.cer"); crs crs1 = new crs(); crs1.ClientCertificates.Add(cert); crs1.Url = "https://onegate-certificate-test.nbb.be/soap/crs"; crs1.AllowAutoRedirect = true; UploadFileRequest ureq = new UploadFileRequest(); ureq.FileName = "FE01.XML"; byte[] b = ConvertFileToBinary(@"c:\users\docs\onegate\A2A\upload.xml"); ureq.UploadFile = b; UploadFileResponse resp = crs1.uploadFile_A2A(ureq); string ticket = resp.TicketID; } catch (Exception ex) { Console.WriteLine(ex.Message); } }

Page | 19

A2A - One Gate Web Services

The user (or the program in this case) must be identified to One Gate (CSSR) using a certificate. The first statements in the code deal with reading a certificate file and placing the certificate in the certificate cache of the web service. X509Certificate cert ...

...

crs1.ClientCertificates.Add(cert); The web service is listening for requests on a given URL. The next line of code sets the correct URL for the web service. In this case we will use the testversion of One Gate (CSSR). The property AllowAutoRedirect determines whether server redirects will be implied automatically. crs1.Url = "https://onegate-certificate-test.nbb.be/soap/crs"; crs1.AllowAutoRedirect = true;

The inputparameter UploadFileRequest is loaded with the correct values: UploadFileRequest ureq = new UploadFileRequest(); ureq.FileName = "FE01.XML"; byte[] b = ConvertFileToBinary(@"c:\users\docs\onegate\A2A\upload.xml"); ureq.UploadFile = b;

The variable b (an array of bytes) represents the contents of upload.xml in base64 encoding6. The final step is the call to uploadFile_A2A and the retrieval of the result: UploadFileResponse resp = crs1.uploadFile_A2A(ureq); string ticket = resp.TicketID;

That is all there is to upload an XML-file in One Gate (CSSR) using the web service in Visual Studio.NET. 6.1.2 FEEDBACKLISTREQUEST/FEEDBACKREQUEST The next code snippet shows how to retrieve available feedback. We define a timespan for which feedback identifiers will be retrieved. Next each of the available feedback items - if any - will be retrieved from the database using the identifiers from the previous step. static void CheckFeedback() { try { X509Certificate cert = X509Certificate.CreateFromCertFile (@"c:\users\docs\onegate\certificate\nuin_003.cer"); crs crs1 = new crs(); crs1.ClientCertificates.Add(cert); crs1.Url = "https://onegate-certificate-test.nbb.be/soap/crs"; FeedbackListRequest flrc = new FeedbackListRequest(); TimeFrameType tft = new TimeFrameType(); tft.FromTime = new DateTime(2010, 3, 1); tft.ToTime = new DateTime(2010, 4, 9); ReadType rt = new ReadType(); rt.TimeFrame = tft; flrc.Item = rt; /* to get all unread feedback comment the previous statement * and remove the comment slashes from the next line */

6 In Visual Studio.NET the conversion to base64 will be performed automatically. Property UploadFile of message type UploadFileRequest is defined as binary64 in the wsdl description. The proxy classes generated by Visual Studio.NET will encode and decode automatically. In this example ConvertFileToBinary is actually a no-op.

Page | 20

A2A - One Gate Web Services

//flrc.Item = new EmptyType(); FeedbackListResponse flr = crs1.feedbackListRequest(flrc); if (flr == null) return; object[] items = flr.Items; foreach (object o in items) { FeedbackRequest fr = new FeedbackRequest(); fr.FeedbackId = ((FeedbackType)o).FeedbackId; FeedbackResponse frep = crs1.feedbackRequest(fr); // do things with frep.Payload; } } catch (Exception ex) { Console.WriteLine(ex.Message); } }

The first couple of statements load the user's certificate into the certificate cache and set the URL where the web service lives. The following code defines the search criteria for the feedback identifiers: FeedbackListRequest flrc = new FeedbackListRequest(); TimeFrameType tft = new TimeFrameType(); tft.FromTime = new DateTime(2010, 3, 1); tft.ToTime = new DateTime(2010, 4, 9); ReadType rt = new ReadType(); rt.TimeFrame = tft; flrc.Item = rt;

We opt for feedback identifiers generated between two specific dates. We will define a ReadType object with a TimeFrame set to the right start date (FromTime) end end date (ToTime). The main code snippet tells you how to get unread feedback identifiers. Call the method next. The result will be null when no feedback identifiers exist in One Gate(CSSR) for the search criteria. FeedbackListResponse flr = crs1.feedbackListRequest(flrc); if (flr == null)

return;

In the other case (ids are available) we will retrieve the feedbackids from the property "Items" of FeedbackListResponse. We use a C# construct (foreach) to loop through the elements of the collection to retrieve each of the feedbackidentifiers. Remark: Items is a collection of type "object". We need to cast each element to a specific datatype - FeedbackType in this case - before we can do something useful with the information. object[] items = flr.Items; foreach (object o in items) { FeedbackRequest fr = new FeedbackRequest(); fr.FeedbackId = ((FeedbackType)o).FeedbackId; FeedbackResponse frep = crs1.feedbackRequest(fr); // do things with frep.Payload; }

Page | 21

A2A - One Gate Web Services

6.2 JAVA

<to be completed>

6.3 SOAP

The examples in 6.1 en 6.2 don't seem to use any SOAP. The methods of the web service look like ordinary class methods. Visual Studio and Java are using frameworks which hide all SOAP details. The code in the examples will in the end be transformed into SOAP requests by these frameworks before being sent through the wire. It is perfectly possible to communicate with the web service using raw SOAP. Several tools exist in the market; one example being SoapUI (http://www.soapui.org). The next sections show examples of SOAP requests and SOAP responses for all three methods of the web service crs. We leave communication details like client certificates, URLs and others out of the picture. Starting with version 3.5.1 of SoapUI you will find an option "Follow Redirects". When set to TRUE the application will automatically perform a server redirect as imposed by the future NBB login proxy. 6.3.1 UPLOADFILE_A2A A typical SOAP request for uploadFile_A2A would be: <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:esb="http://www.onegate.eu/2010-01-01/esb"> <soapenv:Header/> <soapenv:Body> <esb:UploadFileRequest> <esb:FileName>"upload.xml"</esb:FileName> <esb:UploadFile>RGF0ZTog.......E9PQ==</esb:UploadFile> </esb:UploadFileRequest> </soapenv:Body> </soapenv:Envelope> For clarity's sake we only show part of UploadFile. This element contains the XML file optionally encrypted and signed and converted to base64. The SOAP response looks like this: <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <crs:UploadFileResponse xmlns:crs="http://www.onegate.eu/2010-01-01/esb"> <crs:TicketID>618</crs:TicketID> </crs:UploadFileResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

6.3.2 FEEDBACKLISTREQUEST The method will retrieve identifiers of feedback relating to file transfers. In the example we would like to get all the identifiers of feedback generated between 2010-03-01 and 2010-05-25. Mind we need to use the full dateTime syntax (YYYY-MM-DDThh:mm:ss). <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:esb="http://www.onegate.eu/2010-01-01/esb"> <soapenv:Header/>

Page | 22

A2A - One Gate Web Services

<soapenv:Body> <esb:FeedbackListRequest> <esb:Read> <esb:TimeFrame> <esb:FromTime>2010-03-01T00:00:00</esb:FromTime> <esb:ToTime>2010-05-25T23:59:59</esb:ToTime> </esb:TimeFrame> </esb:Read> </esb:FeedbackListRequest> </soapenv:Body> </soapenv:Envelope>

The result looks like this: <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <crs:FeedbackListResponse xmlns:crs="http://www.onegate.eu/2010-01-01/esb"> <crs:Feedback> <crs:FeedbackId>53524</crs:FeedbackId> <crs:TicketId>C-161725147</crs:TicketId> </crs:Feedback> <crs:Feedback> <crs:FeedbackId>53526</crs:FeedbackId> <crs:TicketId>C-162806300</crs:TicketId> </crs:Feedback> </crs:FeedbackListResponse> </SOAP-ENV:Body>

</SOAP-ENV:Envelope> The SOAP request to retrieve the identifiers of unread feedback would be similar to: <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:esb="http://www.onegate.eu/2010-01-01/esb"> <soapenv:Header/> <soapenv:Body> <esb:FeedbackListRequest> <esb:NotRead/> </esb:FeedbackListRequest> </soapenv:Body> </soapenv:Envelope>

6.3.3 FEEDBACKREQUEST The method retrieves the feedback for a given identifier. The example retrieves the feedback associated with identifier 53526. <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:esb="http://www.onegate.eu/2010-01-01/esb"> <soapenv:Header/> <soapenv:Body> <esb:FeedbackRequest> <esb:FeedbackId>53526</esb:FeedbackId> </esb:FeedbackRequest> </soapenv:Body> </soapenv:Envelope>

The result is the following SOAP envelope. The contens of "Payload" have been reduced to improve readability. <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"

Page | 23

A2A - One Gate Web Services

xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <crs:FeedbackResponse xmlns:crs="http://www.onegate.eu/2010-01-01/esb"> <crs:Payload> PD94b...g== </crs:Payload> </crs:FeedbackResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

The contents of Payload is in base64 and it needs to be converted before being useful.

6.4 OTHER TOOLS

The list with possible web service consumers goes on endlessly. One tool that deserves being mentionned is curl (http://curl.haxx.se/docs/manpage.html). curl is a tool for data transfers to or from a server. curl supports all standard internetprotocols to do so (FTP, HTTP, ...). Check the link to get a detailed overview of the possibilities and the options.

Page | 24

A2A - One Gate Web Services

ANNEX 1: REFERENCES

Ref Document URL [1] One Gate XML-protocol http://www.nbb.be/doc/dq/onegate/xml_e.pdf [2] One Gate (CSSR) declarer's

manuel http://www.nbb.be/doc/dq/onegate/onegate_external_manual_n.pdf

[3] crs service wsdl file http://www.nbb.be/doc/dq/onegate/crs.xml [4] server certificate - production http://www.nbb.be/doc/dq/onegate/DQE_SERVER_PRD_Enc_001-

00100009-83.cer [5] server certificate - test http://www.nbb.be/doc/dq/onegate/DQE_SERVER_INT_Enc_001-

00100009-82.cer [6] Technical document on One

Gate Web Services http://www.nbb.be/doc/dq/onegate/onegate_ws.docx

Page | 25

A2A - One Gate Web Services

ANNEX 2: BASE64 ENCODING

Several methods of the crs web service need base64 encoding. This is a technique to transform binary files (using 8-bit ASCII) into readeable ASCII characters. base64 encoding is useful because many internet protocols rely on 7-bit characters; 8-bit characters may cause problems in some cases. base64 is not a compression technique. The base64 encoded files take about 33% more space than the original file. An alternative to base64 encoding would be hexadecimal encoding - all binary values are transformed to the characters 0-9 and A-F. But hexadecimal encoding doubles the file size. The algorithm for base64 encoding is pretty simple:

1. every three consecutive bytes - 24 bits b1b2b3- are split into 4 groups of 6 bits each: e1e2e3e4

2. the binary value of every ei lies between 0 and 63. Every ei serves as an index in a table with 64 readeable characters. (hence the name base64). Replace every ei by the character at the index represented by ei.

3. The resulting base64 file must by padded with '=' characters. This is done to make the total number of bytes a multiple of three.

De conversion table looks like this: Index Character Index Character Index Character Index Character 0 A 16 Q 32 g 48 w 1 B 17 R 33 h 49 x 2 C 18 S 34 i 50 y 3 D 19 T 35 j 51 z 4 E 20 U 36 k 52 0 5 F 21 V 37 l 53 1 6 G 22 W 38 m 54 2 7 H 23 X 39 n 55 3 8 I 24 Y 40 o 56 4 9 J 25 Z 41 p 57 5 10 K 26 a 42 q 58 6 11 L 27 b 43 r 59 7 12 M 28 c 44 s 60 8 13 N 29 d 45 t 61 9 14 O 30 e 46 u 62 + 15 P 31 f 47 v 63 / Decoding is equally simple. Every character in the file is transformed into its binary value according to the conversion table. 4 consecutive groups of 6 bits are combined into 3 bytes and the original file is restored.