Integration Services

Documentation home

 

Integration Service. 1

Creating an Integration Service. 2

Integration Service Properties 2

Web Services Configuration Panel 3

Configuring Web Service Security. 4

User Token – Plain Text 5

User Token – Hashed Text 5

WSS Timestamp. 5

Testing an Integration Service. 5

View Operations 6

Error handling and SOAP Faults 7

Publishing an Integration Service. 7

Generate WSDL 8

WSDL content details 8

 

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 designer’s perspective, an Integration Service is very similar to a regular form but with the interactive features removed.

 

Each Integration Service contains:

 

 

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:

 

·         * Integration Resource Wizard – creates an Integration Resource from the fields and tables within the Integration Service

·          View available integration service operations

 

Integration Service Properties

 

General Tab:

 

 

Events Tab:

 

 

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.

 

 

 

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.

 

 

 

Three types of WS-Security header are supported and can be added:

 

 

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.