Handbuch ESR

E-bill
Instruction for a client implementation
of the B2B web service
Edition: August 2008

Contents
1. Introduction....................................................................................................3
2. Background ....................................................................................................3
2.1 Preparation for implementation in C#............................................................................ 3
2.2 Preparation for implementation in Java......................................................................... 3
3. Specification ...................................................................................................4
3.1 Web service for biller ....................................................................................................... 4
3.1.1 Upload Services ......................................................................................................... 4
3.1.1.1 The UploadFiles method.............................................................................................. 4
3.1.1.2 The UploadFilesReport method.................................................................................... 5
3.1.2 Download Services.................................................................................................... 5
3.1.2.1 GetInvoiceListWithIDs.................................................................................................. 5
3.1.2.2 GetInvoiceByID ............................................................................................................ 5
3.1.2.3 GetInvoiceList (omitted)............................................................................................... 6
3.1.2.4 GetInvoice (omitted).................................................................................................... 6
3.1.2.5 GetProcessProtocolList................................................................................................. 6
3.1.2.6 GetProcessProtocol...................................................................................................... 7
3.1.2.7 GetRegistrationList ...................................................................................................... 7
3.1.2.8 GetRegistration ........................................................................................................... 8
3.2 Web service for payer ...................................................................................................... 8
3.2.1 Download Services.................................................................................................... 8
3.2.1.1 GetInvoiceListWithIDs.................................................................................................. 8
3.2.1.2 GetInvoiceByID ............................................................................................................ 9
3.2.1.3 The GetOpenList / GetArchiveList methods (omitted)................................................... 9
3.2.1.4 The GetInvoices/GetInvoicesArchive methods ............................................................ 10
3.2.1.5 The GetPDF / GetPDFArchive methods....................................................................... 10
4. Implementation............................................................................................11
4.1 Interfaces......................................................................................................................... 11
4.2 Implementation in C#..................................................................................................... 12
4.3 Implementation in Java ................................................................................................. 14
5. Final comments ............................................................................................18
Annex A..............................................................................................................19
Links relating to the integration.............................................................................................. 19
Links relating to production..................................................................................................... 19
Files provided ............................................................................................................................ 19
2/19

1. Introduction
Within the e-bill project with PostFinance there is a requirement to allow bills to be uploaded and
downloaded through an automated interface to/from the yellowbill system. The decision was to use SOAP
web services for this purpose. For security reasons the web services must be implemented on the basis of
WS-Security. This document serves as a brief instruction guide for a client implementation of the web
services in the programming languages C# 1.1 (WSE2.0) and Java (JWSDP 1.5). Knowledge of the
mentioned programming languages, the SOAP web services and the WS-Security specification is a
requirement and those are therefore not further discussed in this document.
2. Background
You are a biller or a payer and wish to use the bill upload or download web services provided by
PostFinance. You can implement your client in any programming language you wish as long as the XML
requests correspond to the SOAP specifications with the WS-Security extension. Because those XMLs are
fairly comprehensive there are a variety of frameworks that simplify implementation of the web services
considerably. You therefore do not have to create the SOAP XML "by hand". This document describes the
client implementation of the yellowbill web services in C# and Java.
2.1 Preparation for implementation in C#
In order to implement the client with Microsoft .NET, the .NET SDK 1.1 or .NET SDK 2.0 framework must
be installed. It can be downloaded free of charge from ht tp://msdn2.microsoft.com/en-us/netframework/
default.aspx. The WS-Security extensions which are part of Microsoft's WSE 2.0 for .NET 1.1 or WSE 3.0
for .NET 2.0 (Web Services Enhancements) are also required. This package can also be downloaded free
of charge at this link http://msdn2.microsoft.com/en-us/webservices/default.aspx. The presence of
Microsoft’s Visual Studio 2003 or Visual Studio 2005 is an advantage but not a requirement. The SDK
.NET framework provides all the necessary tools, e.g. compiler, generation of the proxy classes from the
wsdl file, etc. Install the framework first and then WSE 2.0 respectively WSE 3.0.
2.2 Preparation for implementation in Java
If the client application has to be implemented in Java, you will require Java 2 Platform Standard Edition
(J2SE), version 1.4.2 or higher. Sun provides it free of charge at ht tp://java.sun.com/j2se/index.jsp.
An extension for the web service functionality is also required for Java. This package is called Java Web
Services Developer Pack (Java WSDP) and can also be downloaded free of charge. Version 1.5 is required:
ht tp://java.sun.com/webservices/jwsdp/index.jsp. Now you have all the necessary tools to create proxy
classes, compiling, etc. Install J2SE first and then JWSDP.
There are several other Java frameworks to implement web services (with the WS-Security extension), e.g.
using Apache Axis or webMethods GLUE, etc. You are free to use any existing frameworks provided that
they conform to the specifications.
3/19

3. Specification
The advantage of web services is that we will not have to worry about communications or the protocol
on the client side or the server side. The various frameworks usually do this work for you. Thanks to the
generated proxy classes the client can call up functionalities as if they were local classes. An explanation
of the yellowbill web service functionalities follows.
3.1 Web service for biller
3.1.1 Upload Services
The UploadInvoice web service is intended for billers and provides methods for uploading bill files.
The following listed bill types are supported. The FileType determinate the file extension of the uploaded
file. This is important for further processing.
Bill Types FileType (File Extension)
PDF bill detail for presentment "PDF"
PDFOnly bill format "PDFOnly.PDF"
ybInvoice or CreateBill format "XML"
Custom XML bill format like SAPiDoc "EAI.XML"
Custom EDIFACT bill format "EAI.EDI"
3.1.1.1 The UploadFiles method
The interface of the UploadFiles method is as follows:
NotProcessedInvoice[] UploadFiles( Invoice[] invoices, String BillerID );
The method expects an array of type Invoice (see below) and the BillerID of the biller to be passed. It
returns an array of the type NotProcessedInvoice (see below).
To avoiding timeout and peformance problems while uploading a greater amount of Invoices, we
recommend to call the UploadFiles Methode for each Invoice rather than to upload them all together
with one single call.
The type Invoice is a self-declared data type representing a file. It is defined as follows:
public class Invoice
{
public String FileType;
public String TransactionID;
public byte[] Data;
}
The FileType
The TransactionID is the biller’s bill identification and must be identical to the one in the bill file. The
Data field contains the file contents in the form of a binary stream. A byte array, however, cannot be
simply transferred via http. The binary stream must be converted into a base64-encoded string and then
converted back again on the other side. This conversion, however, is usually done automatically by the
SOAP framework.
The NotProcessedInvoice data type has the following structure:
public class NotProcessedInvoice
{
public String FileType;
public String TransactionID;
}
4/19

A NotProcessedInvoice entry indicates that the file could not be uploaded. The biller can tell which
invoice is concerned by checking the TransactionID. The biller receives more detailed information in a
separate processing log delivered daily.
To comply with the WS-Security specification, requests always have a username token and a timeout.
Further details below.
3.1.1.2 The UploadFilesReport method
The request for UploadFilesReport is similar to the method above. But in the response more detailed
information about the transmission status of the files is given.
The result is returned in the form of an array of type ProcessedInvoice with the following structure.
public class ProcessedInvoice
{
public String FileType;
public DateTime SubmitDate;
public String TransactionID;
public String ProcessingState;
}
This type of report entry corresponds to a daily report for each file type. The FileType may be one of the
list above. The SubmitDate are date and time of the request and the TransactionID is the unique invoice
ID supplied by the biller at upload. Processing contains the state of the submitted data. They may be
"OK" or "NOK" by uploaded data. This information may be used for the download methods.
3.1.2 Download Services
The Download web service provides the biller with eight bill management methods. A distinction is made
between outstanding bills, protocols and registrations (never downloaded) and archived data (already
downloaded). It can be controlled by ArchiveData (true / false). Data already collected remain available
for 40 days after the first download.
3.1.2.1 GetInvoiceListWithIDs
This method returns a report list of available bills with the most important details. It replaces the omitted
method GetInvoiceList.
The interfaces are as follows:
InvoiceReportWithID[] GetInvoiceList( String BillerID, bool ArchiveData );
The method expect the BillerID and the ArchiveData flag as parameters to be passed. To list already
downloaded bills, the ArchiveData flag must be set to true.
The result will be returned in an array of type InvoiceReportWithID with the following structure.
public class InvoiceReportWithID
{
public String BillerID;
public String TransactionID;
public DateTime DeliveryDate;
public String FileType;
}
This type of report contains the follwing details for each bill. The TransactionID is the unique invoice ID
and the DeliveryDate is the invoice date supplied by the biller when uploading it. The FileType may be
"RGXMLSIG"or "EDIFACT". Bills which are embedded as an appendix in a ybInvoice like the SAPiDoc are
also of the FileType "RGXMLSIG". All this information may be used for the download methods.
3.1.2.2 GetInvoiceByID
This method allows to download a single signed invoice by its TransactionID. It replaces the omitted method
GetInvoce. For obtaining the TransactionID, the GetInvoiceListWithID method has to be called first.
DownloadFile GetInvoiceByID( String BillerID, string TransactionID );
5/19

The BillerID and the TransactionID are expected as parameters to be passed. The downloaded file is
returned in a structure of the type DownloadFile.
public class DownloadFile
{
public byte[] Data;
public String Filename;
}
It contains the Filename and the content in the form of a binary stream (Data). Now you can save it into
a file. Any further processing of the invoice is in the responsibility of the biller.
3.1.2.3 GetInvoiceList (omitted)
This method is omitted. It’s recommended to use the GetInvoiceListWithIDs method instead.
The method returns a list of available downloads with the most important details. The interfaces are as
follows:
Report[] GetInvoiceList( String BillerID, bool ArchiveData );
The method expects the BillerID and the ArchiveData flag as parameters to be passed. For listing already
downloaded bills, the ArchiveData flag must be set to true. The result will be returned as an array of
type Report with the following structure.
public class Report
{
public DateTime DeliveryDate;
public String FileType;
public int Count;
}
This type of report entry corresponds to a daily report for each file type. The DeliveryDate is the invoice
date supplied by the biller when uploading it. The FileType may be "RGXMLSIG" or "EDIFACT". Count
contains the number of downloadable files with the same DeliveryDate. This information may be used for
the download methods.
3.1.2.4 GetInvoice (omitted)
This method is omitted. It’s recommended to use the GetInvoiceByID method instead.
The method allows signed invoices to be downloaded of the given DeliveryDate.
DownloadFile[] GetInvoices( String BillerID, DateTime DeliveryDate, boolean
ArchiveData );
The method expects the BillerID and the ArchiveData flag as parameters to be passed. For listing already
downloaded bills, the ArchiveData flag must be set to true. Each downloaded file is returned in a
structure of the type DownloadFile.
public class DownloadFile
{
public byte[] Data;
public String Filename;
}
It contains the Filename and the contents in the form of a binary stream (Data). You now save it into a
file. Any further processing of the invoice is the biller’s responsibility.
3.1.2.5 GetProcessProtocolList
This method returns a list of available downloads with the most important details. The interfaces are as
follows:
Report[] GetProcessProtocolList( String BillerID, boolean ArchiveData );
They expect the BillerID parameter (unique identifier of biller) to be passed. The result is returned in the
form of an array of type ProtocolReport with the following structure.
6/19

public class ProtocolReport
{
public DateTime CreateDate;
public String FileType;
}
This type of report entry corresponds to a daily report for each file type. The CreateDate is the date of
the creation by yellowbill system. The FileType is "P".
3.1.2.6 GetProcessProtocol
This method allow ProcessProtocols to be downloaded.
DownloadFile[] GetProcessProtocol( String BillerID, DateTime CreateDate,
boolean ArchiveData );
Each downloaded file is returned in a structure of the type DownloadFile.
public class DownloadFile
{
public byte[] Data;
public String Filename;
}
It contains the Filename and the contents in the form of a binary stream (Data). You now save it into a
file. Any further processing of the Process Protocol is the biller’s responsibility. Aditionnal explication for
the Process Protocol is available in the e-bill manual.
3.1.2.7 GetRegistrationList
This method returns a list of available downloads with the most important details. The interfaces are as
follows:
Report[] GetRegistrationList( String BillerID, boolean ArchiveData );
They expect the BillerID parameter to be passed. The result is returned in the form of an array of type
ProtocolReport with the following structure.
public class ProtocolReport
{
public DateTime CreateDate;
public String FileType;
}
This type of report entry corresponds to a daily report for each file type. The CreateDate is the date of the
creation by yellowbill system. The FileType is "R".
7/19

3.1.2.8 GetRegistration
This method allow registrations to be downloaded.
DownloadFile[] GetRegistration( String BillerID, DateTime CreateDate,
boolean ArchiveData );
Each downloaded file is returned in a structure of the type DownloadFile.
public class DownloadFile
{
public byte[] Data;
public String Filename;
}
It contains the Filename and the contents in the form of a binary stream (Data). You now save it into a
file. Any further processing of the registrations is the biller’s responsibility. Aditionnal explication for the
registration information is available in the e-bill manual.
3.2 Web service for payer
3.2.1 Download Services
The DownloadInvoice web service provides the payer with eight bill management methods. A distinction
is made between outstanding bills (never downloaded and thus not yet paid) and archived bills (already
downloaded). Bills already collected remain available in the archive for 40 days after the first download.
The bills that can be collected are digitally signed XMLs.
3.2.1.1 GetInvoiceListWithIDs
This method returns a report list of available bills with the most important details. It replace the omitted
methods GetOpenList and GetArchiveList.
The interfaces are as follows:
InvoiceReportWithID[] GetInvoiceListWithIDs( String eBillAccountID, bool
ArchiveData );
The method expects the eBillAccountID and the ArchiveData flag parameters to be passed. For listing
already downloaded bills, the ArchiveData flag must be set to true. The result is returned as an array of
type InvoiceReportWithID with the following structure.
public class InvoiceReportWithID
{
public String BillerID;
public String TransactionID;
public DateTime DeliveryDate;
public String FileType;
}
This type of report contains the follwing details for each bill. The BillerID is the Biller’s Identification. The
TransactionID is the unique invoice ID and the DeliveryDate is the invoice date supplied by the biller
when uploading it. The FileType may be "PDF", "RGXMLSIG"or "EDIFACT". Bills which are embedded
as an appendix in a ybInvoice like the SAPiDoc are also of the FileType "RGXMLSIG". All this information
may be used for the download methods.
8/19

3.2.1.2 GetInvoiceByID
This method allows to download a single signed invoice or a PDF billdetail by its TransactionID. It replaces
the omitted method GetInvoces, GetInvoicesArchive, GetPDF and GetPDFArchive. For obtaining the
BilerID and TransactionID, the GetInvoiceListWithID method has to be called first.
DownloadFile GetInvoiceByID( string eBillAccountID, string BillerID, string
TransactionID, string FileType );
The eBillAccountID, BillerID, TransactionID and FileType are expected as parameters to be passed.
The downloaded file is returned in a structure of the type DownloadFile.
public class DownloadFile
{
public byte[] Data;
public String Filename;
}
It contains the Filename and the content in the form of a binary stream (Data). Now you can save it into
a file. Any further processing of the invoice is the responsibility of the payer.
3.2.1.3 The GetOpenList / GetArchiveList methods (omitted)
These methods are omitted. It’s recommended to use the GetInvoiceWithIDs method instead.
Both methods return a list of available downloads with the most important details. The interfaces are as
follows:
Report[] GetOpenList( String eBillAccountID );
Report[] GetArchiveList( String eBillAccountID );
They expect the eBillAccountID parameter (unique identifier of payer) to be passed. The result is returned
in the form of an array of type Report with the following structure.
public class Report
{
public DateTime DeliveryDate;
public String FileType;
public int Count;
}
This type of report entry corresponds to a daily report for each file type. The DeliveryDate is the invoice
date supplied by the biller when uploading it. The FileType may be "PDF", "RGXMLSIG" or "EDIFACT".
Count contains the number of downloadable files with the same DeliveryDate. This information may be
used for the download methods.
9/19

3.2.1.4 The GetInvoices/GetInvoicesArchive methods
These methods are omitted. It’s recommended to use the GetInvoiceByID method instead.
These methods allow signed invoices to be downloaded. The yellowbill system considers any bill collected
using GetInvoices as paid from this moment onwards. The payer is then responsible for settling the
amount through the usual payment channels.
DownloadFile[] GetInvoices( String eBillAccountID, DateTime DeliveryDate );
DownloadFile[] GetInvoicesArchive( String eBillAccountID, DateTime DeliveryDate );
Not only the eBillAccountID but also a DeliveryDate is supplied, as already mentioned above. It can be
taken from the response above. Each downloaded file is returned in a structure of the type
DownloadFile.
public class DownloadFile
{
public byte[] Data;
public String Filename;
}
It contains the Filename and the contents in the form of a binary stream (Data). You now save it into a
file. Any further processing of the invoice is the payer’s responsibility.
3.2.1.5 The GetPDF / GetPDFArchive methods
These methods are omitted. It’s recommended to use the GetInvoiceByID method instead.
These methods enable the invoice details to be downloaded as a PDF file (in print format). The bill
recipient can then archive these details electronically. These methods are used in the same way as those
above.
DownloadFile[] GetPDF( String eBillAccountID, DateTime DeliveryDate );
DownloadFile[] GetPDFArchive( String eBillAccountID, DateTime DeliveryDate
);
10/19

4. Implementation
This section serves as a short tutorial on the implementation of the web service clients. The programming
languages C# and Java will be addressed. For Java there are of course numerous frameworks for
implementing SOAP web services. Only JWSDP will be addressed here.
4.1 Interfaces
The interface of a SOAP web service is described by the WSDL file (Web Service Description Language)
which is published by the web service and describes the methods that can be called up by the client. This
file serves as a basis so that the various frameworks can generate the necessary proxy classes.
Please note that no information concerning the implemented WS-Security recommendations can be read
from the WSDL file.
The WSDL file for the upload web service is available at the following URL:
ht tps://ebill-test.yellowworld.ch/B2BWebServices/UploadInvoice.asmx?WSDL
The interface description for the download web service is at the following link:
ht tps://ebill-test.yellowworld.ch/B2BWebServices/DownloadInvoice.asmx?WSDL
11/19

4.2 Implementation in C#
It is presumed that the preparations in section 2.1 have already been carried out. The first step is to
generate the proxy classes. If you are working with Visual Studio .NET you can open a new or existing
project. Then select "Add Web Reference" to add a web reference to the project. Enter the URL of the
WSDL file in the window that now appears. Next, you can change the namespace, if necessary.
The generated class is located in the Reference.cs file. In this case, minor adjustments have to be made to
this file. We therefore recommend that you copy the contents of Reference.cs and paste them into a new
file, e.g. UploadInvoiceProxy.cs. The new file can, for example, be stored in the project root folder.
Because WSE 2.0 is being used, the class declaration needs to be changed:
After generation it reads:
public class UploadInvoice : System.Web.Services.Protocols.SoapHttpClientProtocol
Edit it to read as follows:
public class UploadInvoice : Microsoft.Web.Services2.WebServicesClientProtocol
The reference to Microsoft.Web.Services2.dll also needs to be added to the project. The WebReferences
directory can then be deleted provided that no other web services are linked in.
The functionality of the new class can now be used just like an ordinary C# class.
You can also create the proxy class with the wsdl command line tool. For our example the command
syntax could be as follows:
ws dl /n:B2BWebServices /o:UploadInvoiceProxy.cs /protocol:SOAP /l:CS
ht tps://ebill-test.yellowworld.ch/B2BWebServices/UploadInvoice.asmx?WSDL
In this case as well, the class has to be adjusted as above.
Now for the implementation itself. Here we will only show the example of the biller, i.e. the upload client.
The bill issuer must have a valid username and password. If possible these should be stored in a separate
file or database and must on no account be accessible to unauthorized persons. First there is an initialization
block in which the username, password and BillerID are read in. How you read them in is up to you.
Invoice[] invoices = new Invoice[txtFilenames.Lines.Length];
NotProcessedInvoice[] npInvoices = null;
String Username = ……;
String Password = ……;
String BillerID = ……;
Next, the invoices array is filled with the FileType, TransactionID and Data of each file. This should present
no problems.
The WS-Security specification defines a username token which can be used for authenticating web
services (for further information refer to
ht tp://w ww.oasis-open.org/committees/download.php/16782/wss-v1.1-spec-os
UsernameTokenProfile.pdf).
12/19

Because the web service is located behind a proxy, a redirection URL and a destination URL have to be
specified when initializing the proxy class.
UploadServiceDestination ht tps://ebill-test.yellowworld.ch:9443/B2BWebServices/UploadInvoice.asmx
UploadServiceVia ht tps://ebill-test.yellowworld.ch/B2BWebServices/UploadInvoice.asmx
UsernameToken token = new UsernameToken( Username, Password, PasswordOption.SendPlainText );
UploadInvoiceProxy.UploadInvoiceProxy uploadProxy = new
UploadInvoiceProxy.UploadInvoiceProxy();
Microsoft.Web.Services2.Addressing.EndpointReference epr = new
Microsoft.Web.Services2.Addressing.EndpointReference(new
Uri(ConfigurationSettings.AppSettings["UploadServiceDestination"]));
epr.Via = new Uri(ConfigurationSettings.AppSettings["UploadServiceVia"]);
uploadProxy.Destination = epr;
uploadProxy.RequestSoapContext.Security.Tokens.Add( token );
For stronger authentication security it’s fairly recommended to use additionally to the username token,
the binary security token (for further information refer to
ht tp://ww w.oasis-open.org/committees/download.php/16785/wss-v1.1-spec-os-x509TokenProfile.pdf).
To use a binary security token, a client certificate is required. The following example shows how to
implement a binary security token in a webservice client.
// create SecurityToken
X509SecurityToken x509Token = new X509SecurityToken(x509Certificate);
// add SecurityToken
uploadProxy.RequestSoapContext.Security.Tokens.Add(x509Token);
// sign the message
uploadProxy.RequestSoapContext.Security.Elements.Add(new MessageSignature(x509Token));
For a further level of security, WS-Security defines a timestamp
ht tp://w ww.oasis-open.org/committees/download.php/16790/wss-v1.1-spec-os-SOAPMessageSecurity.pdf
with which you can ensure that the request is only valid for a certain time period.
uploadProxy.RequestSoapContext.Security.Timestamp.TtlInSeconds = 60;
Now comes the actual web service call.
npInvoices = uploadProxy.UploadFiles(invoices, BillerID);
The client must have the time zone set to GMT +1 and the time difference between client and server may
not exceed more than 1 minute.
Finally, a simple evaluation of the returned value is performed.
StringBuilder sb = new StringBuilder();
if (npInvoices != null && npInvoices.Length > 0)
{
sb.Append("Nicht eingelieferte Files!\r\n");
sb.Append("**************************\r\n\r\n");
for (int i=0; i

4.3 Implementation in Java
As already mentioned, we will discuss only the JWSDP 1.5 framework. The preparations described in
section 2.2 must have been completed. Here, too, the first step is to generate the proxy classes. The Sun
documentation is usually based on the assumption that one wants to publish a web service and therefore
they require the installation of a web container such as Tomcat. In our case, we really only need the client
and there is thus no need for an application server or web container.
The generation of client proxy classes using WS-Security extensions is not well documented. Therefore, we
recommend that you take the enclosed configuration files and edit them.
First of all, the webserviceclient.props file has to be edited. Values must be assigned to all parameters
except the proxy information. The meanings of the individual parameters can be taken from the
comments in Fig 1.
# place where Java is installed
javahome=C:/Java/2sdk1.4.2_07
# place where JWSDP is installed
jwsdp.home=C:/Java/jwsdp-1.5
# Destination of the generated classes
build.dir=build
# Destination of generated jar File
dist.dir=dist
# Location of the Configuration-File
configfile=config/client-config.xml
# Proxy Server Host if there is one
proxy.host=
# Proxy Server Port if there is a Proxy Server
proxy.port=
# Name of the jar File
jarname=DownloadInvoiceProxy
# Set to true or false to control jaxrpc tool output
jaxrpc.tool.verbose=true
Fig 1: Contents of the webserviceclient.props file
The webserviceclient.xml file is a control file for the ant tool which is included in the JWSDP package. It is
located in \apache-ant\bin. The XML file references the configuration above, assembles
the class path, contains compiler instructions for generating classes and much more. In our case, nothing
has to be changed in this file. We still recommend, however, that you have a look at it in order to
understand the procedure.
Next, the client-config.xml file has to be edited. Here you have to enter the URL of the WSDL file and the
name of the package to be generated.
Fig 2: Contents of the client-config.xml file
14/19

There is another configuration file called user-pass-authenticate-client.xml. This file contains all the
information necessary to ensure that the WS-Security extensions are included when generating the proxy
classes.
Yellowworld.WSSecurirty.ClientSecurityEnvironmentHandler
Fig 3: Contents of user-pass-authenticate-client.xml
This configuration file defines that the SOAP request must contain a username token and a
timestamp (as per WS-Security specification
ht tp://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0.pdf and
ht tp://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf).
The framework automatically inserts this XML node at runtime. You do not have to do this.
The only thing you may have to change here is the class name of the callback handler. In our case this is
the ClientSecurityEnvironmentHandler. In this class you can define how you wish to read in the username
and password, e.g. from a file, from a database, etc.
Once you have made all the necessary changes, you can start generating the proxy classes with the ant
tool. To do this, enter the following command on the command line:
ant –f webserviceclient.xml
15/19

The procedure is logged in the cmd window and takes a few seconds. The generated source files, the
compiled classes and the complete jar are now available in the Build directory. The jar file must be now be
referenced when implementing the client program on the classpath. A whole lot of jar files have to be
included in the class path in order to be able to compile and execute the client program. These are listed
below.
• jwsdp-shared
jaxp
jaxrpc
saaj
xws-security
lib
lib
lib
lib
lib
activation.jar
jax-qname.jar
mail.jar
endorsed
jaxp-api.jar
jaxrpc-impl.jar
jaxrpc-spi.jar
jaxrpc-api.jar
saaj-impl.jar
saaj-api.jar
security-plugin.jar
soapprocessor.jar
xmlsec.jar
xws-security_jaxrpc.jar
xws-security.jar
dom.jar
xercesImpl.jar
xalan.jar
Now for the implementation of the client. Our example here will show the retrieval of the list of open
bills, i.e. the biller’s view. This person must have a valid username and password. If possible, these should
be stored in a separate file or database and must on no account be accessible to unauthorized persons.
First, there is an initialization block. In this example, the URLs of the web service and the eBillAccountID
are stored in a properties file and read in via a property object. However, you can decide about this
yourself. The important thing is to initialize the stub class and set the ENDPOINT_ADDRESS_PROPERTY.
String serviceURL = pApplication.getProperty("ServiceUrl");
DownloadInvoiceSoap_Stub stub =
(DownloadInvoiceSoap_Stub)(dwnlService.getDownloadInvoiceSoap());
stub._setProperty(javax.xml.rpc.Stub.ENDPOINT_ADDRESS_PROPERTY, serviceURL);
String eBillAccountID = pApplication.getProperty("eBillAccountID");
Next, you can already call up the method itself, because the proxy classes add the WS-Security extensions
here (see Fig 3).
ArrayOfReport report = stub.getOpenList(eBillAccountID);
16/19

Next, there is a simple evaluation of the returned value. We recommend that you save these returned
values so that the actual XML or PDF files can be retrieved.
Report[] arrReport = report.getReport();
System.out.println("*** Open List ***");
System.out.println();
if (arrReport.length > 0)
{
for (int i=0; i

5. Final comments
This document has shown a simple reference implementation for the use of the web services in the
environment of the yellowbill system. For the sake of brevity, the details of SOAP, WS-Security, .NET, C#,
Java, etc were deliberately omitted.
The web service links provided in the document refer to our integration platform on which new customer
connections are usually tested when they are set up. Due to possible maintenance windows, we cannot
guarantee 100% availability of the integration platform.
The links and a list of the enclosed documents are listed once more in the Annex.
18/19

Annex A
Links relating to the integration
• Biller upload web service
WSDL ht tps://ebill-test.yellowworld.ch/B2BWebservices/UploadInvoice.asmx?WSDL
Webservices ht tps://ebill-test.yellowworld.ch/B2BWebservices/UploadInvoice.asmx
• Biller download web service
WSDL ht tps://ebill-test.yellowworld.ch/B2BWebServices/BillerDownloadServices.asmx?WSDL
Webservices ht tps://ebill-test.yellowworld.ch/B2BWebServices/BillerDownloadServices.asmx
• Payer download web service
WSDL ht tps://ebill-test.yellowworld.ch/B2BWebservices/DownloadInvoice.asmx?WSDL
Webservices ht tps://ebill-test.yellowworld.ch/B2BWebServices/DownloadInvoice.asmx
Links relating to production
• Biller upload web service
WSDL ht tps://ebill.yellowworld.ch/B2BWebservices/UploadInvoice.asmx?WSDL
Webservices ht tps://ebill.yellowworld.ch/B2BWebservices/UploadInvoice.asmx
• Biller download web service
WSDL ht tps://ebill.yellowworld.ch/B2BWebServices/BillerDownloadServices.asmx?WSDL
Webservices ht tps://ebill.yellowworld.ch/B2BWebServices/BillerDownloadServices.asmx
• Payer download web service
WSDL ht tps://ebill.yellowworld.ch/B2BWebservices/DownloadInvoice.asmx?WSDL
Webservices ht tps://ebill.yellowworld.ch/B2BWebservices/DownloadInvoice.asmx
Files provided
The preparations described in section 2.1 and section 2.2 are necessary for the generation of proxy classes
to work.
C#
…\C#\bin
Complete testing program as a Windows GUI. The .NET framework must be installed on
the local machine.
…\C#\ProxyGeneration
Batch files for generating the proxy classes. The wsdl files are also included for your
information. It is, however, better to reference the files online on the web server.
…\C#\src Here is the source code including the Visual Studio .NET project file for the test client.
Java
…\Java\bin
Test program for download as a console application. Java Runtime JRE 1.4.1 or higher
must be installed.
…\Java\ProxyGeneration\
DownloadClientGenerator
Batch file and configuration files for generating the proxy classes for the download client.
…\Java\ProxyGeneration\
UploadClientGenerator
Batch file and configuration files for generating the proxy classes for the upload client.
…\Java\src Java source code for the download test client.
19/19