AbaConnect WebService Examples

This document contains information about the AbaConnect WebService examples. The examples implement many of the main AbaConnect interfaces. The examples are grouped by applications. Each example implements a number of AbaConnect interface that are relevant for the particular application.

Important Information

The AbaConnect WebService examples are designed to show basic concepts for the AbaConnect WebService implementations. Please observe the following points :

1. The AbaConnect Examples have not been through any Quality Assurance Testing. For this reason, supplied source code should not be used for commercial applications.
2. The latest WSDL's should be taken from the ABACUS Homepage. It cannot be guaranteed that the generated source code used in the examples uses the latest WSDL available. Therefore, never copy the source code from the examples into commercial projects.


General AbaConnect WebService Information

The AbaConnect WebServices always use the "AbaDefault" Mapping of the particular AbaConnect interface.

AbaConnect interfaces are separately configured by Abacus to be accessible via the ABACUS Menu in Prog 625 and/or via WebService. Generally, if an AbaConnect interface is available as an XML interface via the ABACUS Menu, then it often accessible as a WebService.

Required ABACUS Installation

The AbaConnect Framework and AbaConnect WebServices are available as of ABACUS V2007. AbaConnect WebService require an ABACUS VI (Network-Server) installation with the following services :

* AbaWebServcer (previously AbaSioux)
* AbaInterfaceServer
* AbaApplicationServer
Note : After an ABACUS installation, the Update (Program 695) from the ABACUS Menu should be run for the Demo Mandant to update the Demo-Mandant 7777 database, before using AbaConnect interfaces.

AbaConnect WebService Technologies

The AbaConnect WebServices use the following technologies :

* WSDL 1.1
* XSD
* SOAP 1/1.2 Server
* SOAP Document Style, Exceptions
* SOAP Attachments (for binary data) using MTOM/XOP

The AbaConnect WebService ABACUS Server is developed uses the following technologies:
* SOAP Server-Engine Apache AXIS2 1.6 (or later depends on Abacus Version)
* Java 8 (or later depends on Abacus Version)

Note for Java and .NET : The use of W3C Standard MTOM/XOP (Message Transmission Optimization Mechanism) is available with Java, Apache AXIS2 1.6.1 and Java 8 and for .NET, Microsoft Products .NET Framework v4.5+.

AbaConnect WebService Functionality

The following methods are standard for all AbaConnect WebService Interfaces
* Ping - This operation can be used to test the connect to the server without logging in with a user name and password.
* Login - Used to Login to ABACUS via the interfaces. The Username and password must be supplied once. Thereafter the user can be identified with a login token returned in the login response.
* Logout - Logs a user out of ABACUS and ends the user session.
* Interoperability Test - A test operation to test compatibility of dates and special characters.
* IsSessionAlive - A method to check if the ABACUS server user session is still active.

The following methods are dependent on the specific AbaConnect WebService Application Interface and may, or may not, be available.
* Insert - Creates a new data record. If the data record already exists then an error message will be returned.
* Update - Updates an existing data record. If the data record does not exists then an error message will be returned.
* Delete - Deletes an existing data record.
* Save - Saves a data record. It is a combination of Insert and Update. If the data record already exists the existing record will be updated. If the data record does not exist a new record will be created.
* Find - Requests particular data from the server. There are different possibilites available to retrieve data via the interfaces.
* DefaultValues - Returns a default structure with various default values preset. Note : Only a few interfaces implement this operation.


N.B. : The WebService methods Insert, Update, Save and Delete can be compared to the manual Import of XML data files via the ABACUS UI AbaConnect Prog 625. The WebService method name corresponds to the "mode" attribute in an AbaConnect XML import file. The XML data structure used by the AbaConnect WebService is identical to the XML data structure used for XML data file import via ABACUS UI AbaConnect Prog 625. Generally, during the development stage, it is useful to prepare the import data in an AbaConnect XML data file and import the data via the Prog 625. The WebService error messages created by the specific ABACUS Applications can mostly be reproduced by importing the same data structure as a file via the ABACUS UI Prog 625.

Example UI Layout

The UI layout of the examples is always the same. The example written with Microsoft Visual Studio have the same layout as those written in JAVA. Be aware that the Miscrosoft Visual Studio and JAVA examples are 2 independent implementations of the same iterfaces. Generally, the examples are very similar in functionality, but it can occur that the JAVA example demonstrates extra features of an AbaConnect interface, than the Microsft Visual Studio example, or vice versa.


Example UI Layout for JAVA 		 
Example UI Layout for Miscroft Visual Studio .NET
Info : Move the mouse pointer over the above UI images to highlight the various areas in the description table below.

Description

UI-Area Description
Server Name and Port The name and port of the Abacus server computer can be entered. This changes the URL for the desired ABACUS Server computer. Default is localhost. The server name and port number can be changed before the login. The port number corresponds to the Abacus AbaWebServer (or AbaSioux) which is shown in the ABACUS ServiceManager. Default is 40000.
Interface URLs This field displays the current URL of the interfaces implemented in the example. Changes to the computer server name or port number will be shown here.
Information Area This field displays the current interface data returned via the find methods for the currently selected interface.
Search Input A search text can be entered and the text found in the Information panel will be highlighted when Enter is pressed or when the Information panel is refreshed.
Login / Logout Click the login after setting the computer server name and port number. A login dialog will be shown, where the Username, Password and Mandant number can be entered. After a successful login, the login status is shown below the login button. Click to logout button to logout. The user will also be automatically logged out when the example application closes.
Interface Selection /
Find Index		 Selects the current interface for the operations of find and save. The combo box contains a list of the interface names listed in the Interface URLs.
The Find Index used for browsing and find-request can be selected for the actual interface. The Find Index defines the data record sorting order, and defines the available Find-Parameters.
Browsing Browses through the selected interface with FIRST, NEXT, LAST or PRIOR, using the Bookmark of the previous data record. If no previous data is available, a find FIRST or LAST will be executed. The returned data will be displayed in the Information Area. Some of the interfaces allow the index (i.e. sorting order of records) for the browsing to be selected in the current index list box (e.g. in Address Index=1 sorts by address number and index=4 sorts by Name)
Find Depending on the interface and what is implemented in the example application it may be possible to execute a Find for a selected interface. Specific parameters can be entered into the Find parameter table. Click Find to execute the find operation with the entered values. The possible input values for the find depend on the selected interface and what is implemented in the example. Generally, the Find.GREATER_EQUAL and Find.EQUAL can be selected from the Find-Operation drop down list.
Application Parameters Depending on the selected interface, application parameters may be available and can be selected and sent with the requests. Each application parameter can be selected individually. The application parameters are normally optional. Application parameters may only have an effect for import or export of data. Consult the further AbaConnect documenatation to determine if the parameter is required for import or export.
Additional Parameters Many AbaConnect interfaces support additional parameters for including Extended Field, Dossiers, or empty elements by the Find requests. If the interface supports these features they can normally be selected via the checkbox, if the current interface supports such features.
New/Save Many of the examples also implement the save/new for a selected interface. The Save button may be inactive if it is not available or implemented in the example. The example source code can be inspected to see what is implemented. For a few interfaces other button or options may be shown in this area, depending on the functionality that is implemented in the example (e.g. delete or update)


JAVA Examples

The Java AbaConnect examples use JAX-WS and are written with Java 8. The Source code can also be compiled with Java 11 and later when the jax-ws components are included. As of Java 11 the JAX-WS components (java.xml.ws) are no longer bundled with the default Java Installation. The JAX-WS is available in a separate dependency available in the Maven artifacts for com.sun.xml.ws : jaxws-ri 
    <dependency>
      <groupId>com.sun.xml.ws</groupId>
      <artifactId>jaxws-ri</artifactId>
      <version>2.3.2</version>
      <type>pom</type>
    </dependency>
When using the later releases of Jakarta EE9 API from V3.0 some packages need to be changed from javax.xml.ws.* to jakarta.xml.ws.*

Specifically, for the references used in the examples the following package references would be changed when using the Jakarta EE9 API V3.0 :

until JAXWS-RI 2.3.3     from JAXWS-RI 3.0.0
javax.xml.soap.* ==> jakarta.xml.soap.*
javax.xml.bind.* ==> jakarta.xml.bind.*
javax.jws.* ==> jakarta.jws.*
javax.activation.* ==> jakarta.activation.*
javax.xml.soap.* ==> jakarta.xml.soap.*



Microsoft .NET Examples

The Microsoft .NET examples are originally written using the Microsoft Windows Communication Foundation (WCF) included with Microsoft .NET Framework 4.8, but can also use a more recent Microsoft .NET Framework versions. The Microsoft .NET Frameworks can be downloaded from the Microsoft .NET Framework Download Homepage or specific versions such as Microsoft .NET Framework 4.8 Homepage.

Generating Source Code from AbaConnect WSDL's

The latest AbaConnect WSDL's are available on the ABACUS Homepage. The source code should be generated from the latest WSDL's, and not copied from the examples. The Examples may be using an older version of the WSDL than is available on the ABACUS Homepage. Generally, a batch file for generating the JAVA and .NET source code from the WSDL, is included with the examples.

JAVA JAX-WS Examples
Command-line example for ADRE address_2021_00 :
"...\jdk\bin\wsimport.exe" -s "generated_jaxws" -Xnocompile address.wsdl -wsdllocation "http://localhost:40000" -p ch.mycompany.acws.v202100.adreaddress -b address.xsd -b addressTypes.xsd -b AbaConnectTypes.xsd -b xmlmime.xsd

The "*.wsdl" and "*.xsd" files are available from the AbaConnect WSDL ZIP files on the ABACUS Homepage. The java package "ch.mycompany.acws.v202100.adreaddress" can be defined for each interface. It is recommended to include the interface version and application to uniquely define the package for each interface.

Microsoft .NET Examples
Command-line example for ADRE address_2021_00 :
"...\bin\NETFX 4.8 Tools\SvcUtil.exe" /out:"dotnet_stub_cs\address.cs" /language:CS /namespace:*,AbaConnectAdreaddress2021 /config:"dotnet_stub_cs\address.config" "address.wsdl" "AbaConnectTypes.xsd" "address.xsd" "addressTypes.xsd" "xmlmime.xsd"

The "*.wsdl" and "*.xsd" files are available from the AbaConnect WSDL ZIP files on the ABACUS Homepage. The namespace "AbaConnectAdreaddress2021" can be defined for each interface. It is recommended to include the interface version and application to uniquely define the namespace for each interface.