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 externally. The Integration Service provides the ability to receive data, process an Integration Service and return a response using SOAP messaging.

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. An Integration Service contains only one page, it does not allow actionable event triggers, e.g buttons, immediate validation fields, etc. An Integration Service only supports one event - an Integration Event - that is processed immediately, similar to a before form event,. 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 Ebase Integration Server module is licensed separately.

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 has one page to allow adding tables and no buttons or other user-driven triggers. 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 FPL 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)
One Page for table processing
Fields and Tables
No Buttons or Actions on fields

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. 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 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.

The graphical panel is very similar to creating an Ebase Form. However, it is not possible to add a new page or buttons to an Integration Service; this would serve no purpose as there is no user interaction.

It is not necessary to add fields to the graphical Integration Service Panel. Fields should only be created in the Fields Panel and can be accessed directly from FPL. Tables must be added to the page in order to be used. This is standard throughout all of Ebase Forms.

Service Toolbar functions

Save: saves the Integration Service.

Form properties: displays the Integration Service properties dialog box.

Test Integration Service: first saves the Integration Service and then shows a dialog shows a message stating that an integration service can only be tested through the web services panel. This is useful for debugging.

Display the resource mappings panel: Displays the mappings between associated resources and service fields.

Maintain Language texts: (See Working with Form Texts).

Parameters: displays a list of those fields which can be passed to the Service when it is invoked. To designate a field as a parameter, click the parameter checkbox in the field properties. Note that LANGUAGE can always be passed and does not need to be specified. These parameters are not mandatory.

Create resource: this button opens a dialog that allows the creation of an external resource, e.g. a database or email resource. The dialog asks for the type and name of the new resource and the form fields that should be included in the resource.(See Understanding Ebase Integration for more information).

Delete: deletes the Integration Service.

Maintain metadata: Not applicable to Integration Service.

Documentation: allows documentation to be maintained for the Integration Service.

Export to Integration Resource: Export the Integration Service to an Integration Resource. (See Export Integration Resource)

Help: Displays the help documentation for working with Integration Service.

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.

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.

Transactions tab

This tab allows you to specify behaviour associated with writing to external resources: databases, email, message systems such as MQSeries, XML, Web Services. (See Transaction Support for more information

− Transactional: This cannot be switched off for Integration Services. If set to ‘No’ then this will have no effect and transactions will still be active.

− Optimistic Locking: applies to database updates only. If set to 'Yes' 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). 'No' is the default setting and if set to 'No' then the update is performed without any checks.

Info tab

This is display-only information.

− created by: user who created the Integration Service

− created date: date Integration Service was created

− imported by: user who imported the Integration Service

− imported date: date Integration Service was imported

− last updated by: user who last updated the Integration Service

− last updated date: date Integration Service was last updated

− start of text range: the start of the range of text ids used for this Integration Service

− high used text id: the highest used text id for this Integration Service

− number of fields: total number of fields in the Integration Service

Form Fields Panel

This contains a list of all the fields of the Integration Service. The list will normally be in alphabetical order except that any newly added fields will appear at the top. The columns of the display can be re-sized by dragging the column heading borders or re-organised by dragging the column headers. Double-clicking on a field selects the field properties dialog. Right-clicking presents a menu allowing you to delete selected fields, convert link to embedded or display the service fields dialog box.

The tabular display contains:

− Field name: this is display only. If you need to change this, use field properties, General tab.

− Display type: Not applicable for Integration Service.

− Field type: clicking on this field presents a dropdown list of the supported internal Ebase field types. (See Supported field types)

− List: shows the list (static or dynamic) that is associated with this field. This is display only. To select a different list, use field properties lists tab.

Form Fields toolbar

− Field properties: displays the Field properties dialog.

− Delete selected fields: deletes any highlighted fields in the tabular fields display area. A single field can also be deleted by right-clicking in the fields display area and selecting delete.

− Add field: adds a new field to the top of the fields panel.

− Import fields from external resource: allows you to import fields from an external resource. This will create one field for each external resource field that is imported and will also create the mapping between the service field and the resource field. The format and lengths will automatically be set to the appropriate values. A Business View containing the required resources must already be associated with the Integration Service (see Integration Service properties general tab). Clicking this icon displays a dialog as shown below:

Select the resource from the dropdown list at the top of the window - this list contains all the resources in the business view. Then select all the required fields and click ‘OK’. You can use the ‘select all’ and ‘de-select all’ buttons. You can also select a range of fields by holding down the SHIFT key, or select multiple fields using the CTRL key.

Field properties

The field properties are a mixture of attributes that apply to the field itself, e.g. field type, and display attributes that apply to the field when it is displayed on a page, e.g. display type. For the latter group, the properties apply to the field on all pages where it is displayed.

General tab

− Field name: changing the field name will automatically rename the field on all pages where it is displayed.

− Field type: This can also be changed by selecting from the dropdown list in the fields area. (See Supported field types)

− Rounding option: this applies only to fields of field type Numeric and Currency and specifies the rounding mode applied each time a numeric value is stored and the value contains more decimal places than the target field (see previous paragraph). The following options are available:

The following examples assume a target field with 2 decimal places:

o Up Values are rounded up.
For example: 2.193 becomes 2.20, 2.459 becomes 2.46, -2.193 becomes -2.20, -2.459 becomes -2.46

o Down Values are rounded down.
For example: 2.193 becomes 2.19, 2.459 becomes 2.45, -2.193 becomes -2.19, -2.459 becomes -2.45

o Ceiling The same as Up except negative numbers are rounded down
For example: 2.193 becomes 2.20, 2.459 becomes 2.46, -2.193 becomes -2.19, -2.459 becomes -2.45

o Floor The same as Down except negative numbers are rounded up.
For example: 2.193 becomes 2.19, 2.459 becomes 2.45, -2.193 becomes -2.20, -2.459 becomes -2.46

o Half up Values less than 5 are rounded down, values of 5 and above are rounded up.
For example: 2.193 becomes 2.19, 2.459 becomes 2.46, 3.455 becomes 3.46

o Half down Values of 5 or less are rounded down, values of 5 and above are rounded up.
For example: 2.193 becomes 2.19, 2.459 becomes 2.46, 3.455 becomes 3.45

o Half even Values of less than 5 are rounded down, values greater than 5 are rounded up, values of 5 are rounded towards the nearest even number.
For example: 2.193 becomes 2.19, 2.459 becomes 2.46, 3.455 becomes 3.46, 4.455 becomes 4.46. Note that this is the rounding mode that minimises cumulative error when applied repeatedly over a sequence of calculations.

The default is Half up.

− Default value: Enter the default value initially assigned to the field, if required. The value must be consistent with the field type.

− Control field: Not applicable to Integration Service

− Return field: Not applicable to Integration Service

− Workflow Priority Field: Not applicable to Integration Service

− Parameter: Not applicable to Integration Service

− Encrypted: this checkbox is only enabled if the parameter checkbox is also enabled. It indicates that an additional parameter will be passed containing an encrypted value of the parameter value. The encrypted value will be checked against the parameter value to ensure that the parameter has not been changed. (See Encryption of form parameters for more information)

− Validation: Not applicable to Integration Service

Presentation tab

Not applicable to Integration Service

Texts tab

Not applicable to Integration Service

Lists tab

Not applicable to Integration Service

Form Editor Panel – Table View

Not applicable to Integration Services

Fields-on-Page Toolbar

Not applicable to Integration Services

Field-on-Page Properties

Not applicable to Integration Services

Form Action Buttons

Not applicable to Integration Services

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. NB, Fields do not need to be added to the page whereas and tables must be added to the graphical page to allow interaction from any resource.
Associate fields to the required resources (if applicable) e.g DB Resource, Email Resource etc…
Create Integration Script. NB. 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. NB 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