Integration
Services
Creating
an Integration Service
Integration Service Properties
Web Services Configuration Panel
Configuring
Web Service Security
Testing an Integration Service
Error handling and SOAP Faults
Publishing an Integration Service
See also: Integration
Server, Integration Resources
Integration Service
An Integration Service
represents a SOAP web service that is published to the outside world. It will
receive an XML request document and return an XML response document. From a
designers perspective, an Integration Service is very similar to a regular form
but with the interactive features removed.
Each Integration Service
contains:
- At least one Integration Resource (this is
mandatory to enable the Integration Service to be published as a Web
Service)
- A Web Service definition
- One Integration Event
- One On Error Event (Optional)
- Fields, tables and resources
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 at least one Integration Resource and each resource must contain at
least one integration adapter where
each adapter represents one operation.
See Working with Integration
Resources for more information.
An Integration Service is published as a web service and is then invoked using the following URL:
http://<domain-name>:<port>/ufs/integration/<ws_name>
The WSDL can be viewed by invoking:
http://<domain-name>:<port>/ufs/integration/<ws_name>?wsdl
After an Integration Service has been created, you can control its operation using the Server Administration Application - Configuring Web Services Operation on the Server. This allows you to enable/disable the service and re-deploy it when changes have been made.
Creating
an Integration Service
An Integration Service can
be created by selecting New > SOAP
Web Service > Integration Service, and edited by double clicking on a
service name.
This presents the
Integration Service Editor panel which is similar to the Form Editor with the following differences:
- The main panel is the Web Services Configuration Panel
where you configure the web service request URL published to the outside
world and any security
- Only the Fields View,
Tables View, Resources
View and Properties View panels are
shown. The other panels are not required as an Integration Service has no
pages.
- The toolbar has two additional items:
·
Integration Resource Wizard
creates an Integration Resource from the fields and tables within the
Integration Service
·
View available
integration service operations
- The Integration Service properties differ from
Form properties and are shown in the next section
Integration
Service Properties
General Tab:
- Web Services
Integration Resource: Lists the resources from the Resources View panel that are Integration
Resources. This is a read-only panel.
- 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.
Web Services Configuration Panel
The Web Services Configuration Panel is the central panel within the Integrated Service Editor. It allows you to configure the URL used to invoke the Integration Service and to configure security headers.
To qualify as a valid Web Service, an Integration Service must contain at least one Integration Resource that contains at least one Integration Adapter. The operations are configured through the Integration Resources which are associated to the Integration Service. This determines the operations available to the Web Service. To remove an operation from a web service, it must be removed from the Integration Service (by removing the associated Integration Resource).
This table defines all the web services which can be used to access the Integration Service. When an Integration Service is first created, a web service with the same name is also created. Each web service can be used to access all available operations, and in most cases only one web service is required. Web service names must be unique within the workspace.
- Click
the
icon to create a new web service name - Click
the
icon to delete a web service name - Click
the
icon to test the Integration Service - Click
the
icon to show
the WSDL
|
Web Service Name |
This is the web service name and forms part of the URL used by callers see above |
|
Soap Version |
You can select the Soap Version used to publish the web service. This is useful when client applications will only work with a certain version of the Soap specification. Note that if Soap 1.2 is selected, the web service can be used by either a Soap 1.1 or Soap 1.2 client. But if Soap 1.1 is selected, only Soap 1.1 clients can be used. This selection also affects the WSDL that is generated; if you need to publish both Soap 1.1 and Soap 1.2 WSDL, create two web services names. |
|
Web Service
Security |
Click the button to configure WS-Security .See Configuring Web Service Security (next section). |
Configuring Web Service
Security
Click the button to the right of the Web Service Security column to display the WS-Security Configuration panel. If WS-Security is configured it applies to all operations.
- Click
the icon to create a new WS-Security header
- Click
the icon to delete a WS-Security header
- Click
the
icons to change the order in which the
WS-Security headers are positioned
Three types of WS-Security header are supported and can be added:
- User Token Plain Text: unencrypted username and password authentication
- User Token Hashed Text: username and encrypted password authentication
- WSS Timestamp - configure a time limit on the web service call before the request/response expires
For more information regarding WS-Security protocol, please refer to the OASIS WS-Security specification.
User Token Plain Text
This token supports basic username and password authentication when a web service is invoked. If the client username and password does not match the integration web service username and password, a SOAP Fault is returned back to the client. This method of authentication supports both plain text and hashed text passwords.
|
Username |
User name. Substitutable field and environment field variables can be used starting with && e.g. &&$ENV_USERXX. |
|
Password |
Password. Substitutable field and environment field variables can be used as above. |
|
Confirm password |
Same as password |
User Token Hashed Text
This is the same as the plain text token above except that the password is encrypted using the SHA-1 hashing algorithm.
WSS Timestamp
This token supports the ability to set an expiry time on the web service call. If a request is received from the client that is out-of-date then a standard web SOAP Fault is returned to the client stating that the web service call has expired.
|
Timestamp duration |
Enter the time in seconds or milliseconds depending on the timestamp precision attribute |
|
Timestamp precision |
If checked, the above field is entered in milliseconds, if unchecked in seconds |
Testing an Integration Service
Select a web
service then click the test icon 
on the toolbar.
The test dialog lists all the available operations associated to the web service. See the view operations section for more details.
The test dialog also supports WS-Security headers that are configured for the web service. These are inserted into the SOAP document after the Submit is pressed and are hidden from the user. The entire SOAP message can be viewed in the server log including the WS-Security headers as the test is invoked on the server. See the Configuring Security for more details.
To test the web service:
1) Select the operation to test.
2) Edit the request SOAP document by replacing all the element values highlighted in black, where applicable.
3) Click the Submit button to perform the test.
4) The response from the test call will automatically populate the response panel.
View Operations
To view the operations associated with the web service,
select the web service, then click the View
Operations icon on the toolbar. This shows a list of all the
operations available by gathering a list of all the Integration Adapters in all
the associated Integration Resources contained within 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
An Integration Service is published automatically and no specific action is needed. If required, an Integration Service can be disabled or enabled using the Server Administration Application.
Generate WSDL
To preview the WSDL generated for a particular web service,
select the web service and click the Generate
WSDL icon on the toolbar. This will show the WSDL in a
preview panel; a client application can use this to connect to the Integration
Service. You can generate a WSDL even if the web service is disabled.
Generating a WSDL shows the same information as calling http://<domain-name>:<port>/ufs/integration/<ws_name>?wsdl
from a browser window.
WSDL content details
A Web Service uses document encoding and consists of the following:
− Service Description Defines the Web Service name and port name and SOAP address
− SOAP Bindings Defines the type of web service call, request/response style and document literal types
− Port Type Defines the operations available in the Web Service. These are generated from the Integration Resource/Adapters associated to the Integration Service
− Message Types Input and Output messages for each operation
− Types Schema types associated to the Input and Output Messages. These will be associated to Integration Resource Source Fields.
