One Gate (CSSR)
A2A – Web Service
June 2010 – Version 1.0
Page | 2
© 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.
A2A - One Gate Web Services
Page | 3
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
A2A - One Gate Web Services
Page | 4
0. VERSIONS
Version
1.0
Date
June 2010
Description
First published
Any remarks, additions and corrections to this manuel may be sent to the following emailaddress :
mailto:[email protected].
A2A - One Gate Web Services
Page | 5
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.
2.
3.
4.
The import of CSV-files through the One Gate (CSSR) online application.
The upload of XML-files through the One Gate (CSSR) online application.
You can add an XML-file to an email sent to a welldefined emailaddress
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].
A2A - One Gate Web Services
Page | 6
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).
A2A - One Gate Web Services
Page | 7
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 XMLschemas 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 socalled 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.
A2A - One Gate Web Services
Page | 8
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].
A2A - One Gate Web Services
Page | 9
4. FAULTS AND PROBLEMS
The use of the web service may results in errors. There are two broad categories of errors: HTTPerrors 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 ([email protected] tel. 32 2 221 40 60) should the
server fault persist
A2A - One Gate Web Services
Page | 10
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>
A2A - One Gate Web Services
Page | 11
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:
Test:
https://onegate-certificate.nbb.be/soap/crs
https://onegate-certificate-test.nbb.be/soap/crs
5.2 SCHEMA
5.3 METHODS OF CRS
The service implements three methods:
Method
uploadFile_A2A
feedbackListRequest
feedbackRequest
Description
Upload of data through an XML file.
Request a list of available feedback
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) XMLprotocol. The "old" CSSR format is still accepted. The new XML-protocol is described in [1].
A2A - One Gate Web Services
Page | 12
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
XML validation
Zip
Signing
Encryption
base64 conversion
Mandatory/Optional
optional
optional
depends on the reporting domain but mandatory when the
data are encrypted
depends on the reporting domain
mandatory
Figure 1 summarizes the sequence of actions to be defined.
E F 0 1 .X M L
v a l id a t e
v a l i d a te w i t h
XSD
Y
N
z ip
Y
com press
N
s ig n
Y
s i g n w i th u s e r
c e r ti f i c a t
Y
e n c r y p t w i th
s e r v e r p u b lic
key
N
e n c ry p t
N
base64
E F 0 1 .B I N
Figure 1: transforming the XML-report into the payload for fileUpload_A2A
5.3.1.2 Input: uploadFileRequest
A2A - One Gate Web Services
Page | 13
The input message uploadFileRequest has two properties: FileName and UploadFile.
Property
FileName
Mandatory/Optional
optional
Type
xs:string
UploadFile
mandatory
xs:Base64Binary
Description
The name of the file to be loaded into
One Gate (CSSR). The name will be
used in any feedback.
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
TicketID
Mandatory/Optional
-
Type
xs:Base64Binary
Description
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 ...
A2A - One Gate Web Services
Page | 14
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 FeedbackListRequest 2; 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
NotRead
Mandatory/Optional
see text
Type
EmptyType
Read
see text
ReadType
Description
Indicates you would like to get the
feedback-ids of all feedback that hasn't
been read yet.
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#.
A2A - One Gate Web Services
Page | 15
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
TimeFrame
Mandatory/Optional
Mandatory
Type
TimeFrameType
Description
The structure defines the start date
and the end date of the timespan.
Type
xs:dateTime
xs:dateTime
Description
start date and time of the timespan
end date and time of the timespan
TimeFrameType has two properties:
Property
FromTime
ToTime
Mandatory/Optional
Mandatory
Mandatory
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;
A2A - One Gate Web Services
Page | 16
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
NoFeedback
Feedback
Mandatory/Optional
-
Type
EmptyType
FeedbackType
Description
no feedback available
contains an identifier for each available
feedback item
The datatype FeedbackType has two properties which will help to retrieve the feedback itself:
Property
FeedbackID
Mandatory/Optional
-
Type
MessageIdType
TicketID
-
TicketIdType
Description
The identifier of the feedback. To be
used in retrieving the feedback with
method feedbackRequest.
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
A2A - One Gate Web Services
Page | 17
Property
FeedbackID
Mandatory/Optional
Mandatory
Type
MessageIdType
Description
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
Payload
Mandatory/Optional
-
Type
binary64
Description
An XML file that
requested feedback
contains
the
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>
A2A - One Gate Web Services
Page | 18
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);
}
}
A2A - One Gate Web Services
Page | 19
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.
A2A - One Gate Web Services
Page | 20
//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;
}
A2A - One Gate Web Services
Page | 21
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/>
A2A - One Gate Web Services
Page | 22
<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/"
A2A - One Gate Web Services
Page | 23
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.
A2A - One Gate Web Services
Page | 24
ANNEX 1: REFERENCES
Ref
[1]
[2]
[3]
[4]
Document
One Gate XML-protocol
One Gate (CSSR) declarer's
manuel
crs service wsdl file
server certificate - production
[5]
server certificate - test
[6]
Technical document on One
Gate Web Services
URL
http://www.nbb.be/doc/dq/onegate/xml_e.pdf
http://www.nbb.be/doc/dq/onegate/onegate_external_manual_n.pdf
http://www.nbb.be/doc/dq/onegate/crs.xml
http://www.nbb.be/doc/dq/onegate/DQE_SERVER_PRD_Enc_00100100009-83.cer
http://www.nbb.be/doc/dq/onegate/DQE_SERVER_INT_Enc_00100100009-82.cer
http://www.nbb.be/doc/dq/onegate/onegate_ws.docx
A2A - One Gate Web Services
Page | 25
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
0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Character
A
B
C
D
E
F
G
H
I
J
K
L
M
N
O
P
Index
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
Character
Q
R
S
T
U
V
W
X
Y
Z
a
b
c
d
e
f
Index
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
Character
g
h
i
j
k
l
m
n
o
p
q
r
s
t
u
v
Index
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
Character
w
x
y
z
0
1
2
3
4
5
6
7
8
9
+
/
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.
A2A - One Gate Web Services