Integration Web Services
What
are Integration Web Services?
Configuring Integration WS-Security
See also:
What are Integration Web Services?
An
Integration Web Service is an Integration Service published as a web service.
All the fields and tables contained within the Integration Service are added to
the WSDL and mapped through an Integration Resource. The Integration Resource
is also responsible for creating the operation(s) available to the web service.
There is a
one-to-one mapping of a Web Service name and an Integration Service.
A Web
Service is 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
An
Integration Web Service is document encoded 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.
To qualify
as a valid Web Service, an Integration Service must contain at least one
Integration Resource that contains at least one Integration Adapter. A Web
Service can only be mapped to one Integration Service. 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).
The Web
Service is created dynamically when the Integration Service is published as a
web service. It gathers up all the information from the associated Integration
Resources and builds all the operations and schema types available to the web
service from the Integration Resources.
Creating a New Web Service
A Web
service can be created by selecting the Web Services node on the Ebase Designer
Tree.
To add a
web service click the ‘Add Web Service’ button on the bottom of the web
services panel. This will insert a new line into the web services table.
Double-click the Web Services name and enter a name for the web service.
Select an
Integration Service from the drop-down list. Only valid Integration Services
that contain at least one Integration Resource will be shown.
To enable the
web service, check the ‘Enabled’ checkbox associated with it. To disable the
web service (i.e. un-register), uncheck the ‘Enabled’ checkbox associated with
the web service.
To activate
the web service, you must save the changes by clicking the Save button at the
bottom of the panel. The web service will become active the first time the web
service is called from an external client (if enabled).
Removing a Web Service
To remove a
web service, select the web service that you want to remove and click the
‘Remove Web Service’ button at the bottom of the panel. Click the Save button.
Disabling the web service un-registers the web service and it will no longer be
available.
Alternatively,
you can select the web service and uncheck the ‘Enabled button’, and then click
the ‘Save’ button. This will un-register the web service from the Integration
Server and it will not be available to call from an external client. If a web
service is disabled, it is still possible to generate a WSDL file by clicking
the Generate WSDL button and list the operations
by clicking the View Operations button.
Re-deploy Web Service
If any
changes have been made to the Integration Service or an Integration Resource
associated with the Integration Service, then the web service must be
redeployed.
Select the
web service that you want to re-deploy and click the Redeploy Web Service
button at the bottom of the panel. This un-registers the web service, which
will become active again when the next call comes in from an external client.
Designer
Note: The Web
Service does not need to be re-deployed if an Integration Script has been
modified. This is because the structure of the Web Service has not changed.
View Operations
To view the
operations associated to the web service, click the View Operations button at
the bottom of the web services panel. 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.
In the example
below the web service WS_3 is associated to the INT_CUSTOMERS Integration
Service. The Integration Service INT_CUSTOMERS contains two operations –
getCustomers and addCustomer. The INT_CUSTOMER Integration service contains two
Integration Resources with one Integration Adapter configured in each resource.
Generate WSDL
To preview
the WSDL generated for a particular web service, select the web service and
click the ‘Generate WSDL’ button at the bottom of the web services panel. This
will show the WSDL in a preview panel that the client will use to integrate
their application to Ebase Integration Server. 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.
Validate Web Services
Press the
‘Check’ button at the bottom of the web services panel to validate all configured
web services. This validation checks that each web service contains a valid
Integration Service and the Integration Service contains at least one
Integration Resource. If the Web Service is not valid an error message will be
displayed.
Configuring Integration WS-Security
Integration
web services supports two basic WS-Security Token types:
−
User
token – Username and Password Authentication. For more information regarding
User Token Authentication see the WS-Security -
User Token section.
−
Timestamp
token – Configurable time limit on the web service call before the
request/response expires. For more information regarding User Token
Authentication see the WS-Security - User Token
section.
If
WS-Security is enabled for a web service it enables the WS-Security for all the
operations within the web service.
Integration
WS-Security User Token
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.
To
configure and enable the User Token WS-Security for a particular Integration
Web Service:
1)
Click
the ‘Configure WSS’ button on the Web Service you require WS-Security enabled.
2)
Select
Username Token – Plain Text or Username Token - Hashed Text. NB, both methods
can handle either plain text or hashed text as the password type is specified
by the client and is written into the SOAP Header information.
3)
Select
the enabled checkbox.
4)
Enter
a username and password for basic authentication.
5)
Click
OK
Integration
WS-Security Timestamp Token
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.
To
configure and enable the Timestamp Token WS-Security for a particular
Integration Web Service:
1)
Click
the ‘Configure WSS’ button on the Web Service you require WS-Security enabled.
2)
Select
the Timestamp Token
3)
Select
the enabled checkbox.
4)
Enter
time in seconds/milliseconds
5)
Select
the timestamp precision checkbox to change the precision from seconds to
milliseconds
6)
Click
OK.
For more
information regarding WS-Security protocol, please refer to the OASIS
WS-Security specification.
NB The
request received from the client must conform to the OASIS WS-Security SOAP
Headers as described in the WS-Security Section
(depending of the WS-Security Token selected).
Testing a Web Service
Press the Test Web Service button to perform a test on the web service.
The web
service test dialog lists all the available operations associated to the web
service. See the view operations section for
more details.
The web
service test also supports WS-Security headers that are configured with the web
service. This is inserted into the SOAP document after the Submit is pressed and is hidden from the user. The entire SOAP
message can be viewed in the server log which includes the WS-Security headers
as the test is invoked on the server. See the Configuring Integration
WS-Security for more details.
NB If an
integration service has been modified, it has to be re-deployed before changes
will take affect for testing. See the re-deploy
web service section web service for more details.
To test the
web service:
1)
Select
the operation to test. By selecting the operation, automatically creates a request SOAP document template in the request
panel.
2)
Edit
the request SOAP document by
replacing all the element values highlighted in red, where applicable.
3)
Click
the Submit button to perform the test.
4)
The
response from the test call will automatically populate the response panel.
