Introduction

Ebase Integration Server is a module that provides the ability to publish an Ebase Integration Service as a Web Service. This allows remote Web Service client applications to execute an Ebase Integration Service via a web service call. The Integration Service provides the ability to receive data, process an Integration Service and return a response using SOAP messaging. Both SOAP 1.1 and SOAP 1.2 are supported.

An Ebase Web Service provides a published WSDL definition of the Integration Service. This represents a definition of an integration Web Service to allow any remote application to configure their Web Service client.

An Integration Service is very similar to a standard Ebase form except that it contains no pages. An Integration Service supports one main event - an Integration Event - that is processed immediately when the Service is invoked. An On Error Event can also be configured to execute when an error occurs. An Integration Service has no user and runs in the background.

The Integration Server only supports request/response SOAP messaging. The style of the Web Service definition is document literal.

Integration terms

− Integration Service - An Integration Service is similar to an Ebase form with no user interactivity. An Integration Service must contain at least one Integration Resource to qualify as a valid Integration Service.

− Integration Web Service - A Web Service is a published Integration Service containing at least one Integration Resource. Each Web Service is mapped to a single Integration Service.

− Integration Resource - An Integration Resource is an extension to the XML resource that contains at least one integration adapter. It must contain at least one integration adapter to qualify as an Integration Resource.

− Integration Script - An integration script is an Ebase server side script that can only be processed from an Integration Service.

Architecture

The Web Services Integration Server is a servlet that accepts SOAP requests via HTTP. The SOAP Body populates the Integration Service fields and processes the integration event associated with the requested Web Service operation. Upon processing completion of the integration event a response SOAP message is returned to the calling client based on the response configured for the operation. Fields and Tables are added to an Integration Service in the same way as with an Ebase form. See understanding Ebase integration for more details about standard Ebase Forms.

Each Integration Service can be created to publish one or more operations. Only one Integration Service can be configured for each Web Service definition (WSDL). For more information see the Web Services section.

Integration Service

An Integration Service is a basic Ebase Form without some features that a standard Ebase form contains.

The Integration Service contains:

One Integration Resource (mandatory to become a Web Service)
One Integration Event
One On Error Event (Optional)
Fields and Tables

An Integration Service does not have any user interaction and is run as a background process. Information comes into the service via the Integration Resource associated with the Integration Service. The incoming message (request) populates the fields, and tables are populated by calling the fetchtable FPL command or the API Table.fetchtable() method. The outgoing message (response) populates automatically after the integration script associated with the Integration Service completes execution. Outgoing message tables must be updated using the updatetable FPL command or the API Table.updatetable() method at the end of the integration script.

An Integration Service must contain one or more Integration Resources. Each Integration Resource associated to an Integration Service publishes one or more Web Service operations. An Integration Resource must contain one or more integration adapters. Each adapter represents one Web Service operation published by the Integration Web Service. See Working with Integration Resources for more information. Ebase recommends creating one Integration Resource per operation when designing Integration Services.

Creating an Integration Service

An Integration Service can be created by selecting File -> New -> Integration -> Integration Service, and edited by selecting the service you wish to edit under Integration Server -> Services.

This presents the Integration Service Editor panel which is very similar to the Form Editor, with the following differences:

Only the Fields View, Tables View and Properties View panels are shown. The other panels are not required as an Integration Service has no pages.
The toolbar has an additional item Create Integration Resource Wizard (click here for details)
The Integration Service properties differ from Form properties and are shown below

Integration Service Properties

General Tab

Business View: the Business View associated with this Integration Service. This is the link between the Integration Service and all the external resources (e.g. databases, email services, etc.) accessed by the Integration Service. Double-clicking on the Business View will open the Business View editor. (See Understanding Ebase Integration and Working with Business Views for more information)

Web Services Integration Resource: Lists the resources from the Business View that are Integration Resources. This is a read-only panel. To remove an Integration Resource from the Business View, double-click the business view selected in the Business View combo to open the Business View Panel, remove the Integration Resource from there and save.

Optimistic Locking: Applies to database updates only. When checked, the system will check that the record about to be updated has the same values as it did when it was read from the database using a fetch command. This check is applied only to mapped fields as Ebase is not concerned with the state of any other fields on the database record. If the values are unchanged then the update is performed, otherwise command status is set accordingly. (See update command in FPL script command syntax or the API DatabaseResource.update() method) Unchecked is the default setting and then the update is performed without any checks. Optimistic locking is supported only for update of a single database record using the update command/method – update of multiple records using updatetable is not supported.

Events Tab

Integration event scripts: Scripts associated with the Integration Service at runtime. Add Integration scripts which are run when the Integration Service is invoked.

On Error scripts: Scripts associated with the Integration Service when an error occurs. Add on error scripts which are run when an error occurs when processing the Integration Service.

Error handling and SOAP Faults

SOAP faults are generated automatically by the system when an Integration Service fails. Either a SOAP 1.1 or SOAP 1.2 fault is generated, depending on the protocol used by the client. See Integration Server Error Handling for additional information regarding Integration Server error handling.

Publishing an Integration Service

Once created, an Integration Service is published using the Web Services Panel.

Testing an Integration Service

An Integration Service is tested from the Web Services panel. First create a Web Service associated with the Integration Service, then click the Test Web Service button. When changes have been made to an Integration Service, the corresponding Web Service should be redeployed.

Getting Started with Integration Server

This section gives a brief outline of the steps to create an Ebase Integration Service. It is recommended to start the process from the Integration Service and create the Integration Resource from the service as described here, although this is not essential. (It is also possible to create an integration resource independently and then import the fields and tables into an integration service).

Create a new Integration Service. A new service can be created from the designer menu by clicking File -> New -> Integration -> Integration Service.
Add fields and any tables to the integration service.
Associate fields to the required resources (if applicable) e.g DB Resource, Email Resource etc…
Create an Integration Script. Note that when working with tables you must call fetchtable <tablename> to populate the fields within the table from the integration request, or updatetable <tablename> to update the table contents after data has been added to the table to populate the integration response. Fields will be automatically populated from the integration request and to the integration response field mappings.
Click the icon on the Service Toolbar to bring up the Creating Integration Resource from Service wizard. Follow the simple steps and in the wizard and create your request and response service SOAP messages.
After creating the resource from the wizard, check the request and response messages are as expected. Note that it is possible to change the XML Structure by using the Schema Editor.
Open the Web Services panel by selecting the Integration -> Web Services from the Designer Tree.
Create a new web service and associate the integration service by selecting the appropriate service from the dropdown menu. Select the enabled checkbox. Save the web services. After saving the web service, check the operations and WSDL are correct by clicking the associated buttons at the bottom of the web services panel.
Verify that you can call the web service by invoking the WSDL from a web browser. Type in the URL http://<hostname>:<port>/ufs/integration/<web_service_name>?WSDL. If creating the service on your local machine, with a Web Service name of GET_CUSTOMERS, the URL may look like : http://localhost:3030/ufs/integration/GET_CUSTOMERS?WSDL