WebSphere Lombardi Edition 7.2 > Modeling processes > Advanced modeling tasks > Integrate with other systems > Create outbound integrations


Understand outbound Web Service security, header, and other options

Read the following topics to learn about all options available when using a Web Service Integration component for outbound integrations in a Lombardi Integration service. Troubleshooting tips and additional resources for building outbound Web Service integrations are also covered.

Build an Integration service provides step-by-step instructions for building a sample service that illustrates how you can easily use existing Web services in your Lombardi BPDs.


Specify URIs

When you specify the URI for a Web Service integration component, relative URIs are also supported. When you use a relative URI, it must be relative to the current working directory of the application server: [Lombardi_home]\[process-center|process-server]

You can store shared XML schemas within the [Lombardi_home]\process-center|process-server\webservices\ws directory. For those schemas to be resolved properly, you must edit the [Lombardi_home]\[process-center|process-server]\webservices\xml-catalog.xml file and add an entry to map the XML schema target namespace to the XML schema file as follows: 

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
<group  prefer="public" xml:base="ws/">
<public publicId="http://www.w3.org/2001/XMLSchema" uri="XMLSchema.xsd" />
<system systemId="http://www.w3.org/2001/XMLSchema" uri="XMLSchema.xsd" />
</group>
</catalog>


Use the Registry Explorer

Web Service integration components use a Simple Object Access Protocol (SOAP) connection to discover the ports and parameters from the Web Service Definition Language (WSDL). The Registry Explorer in Lombardi Authoring Environment enables you to browse both Universal Description Discovery and Integration (UDDI) and WebSphere Service Registry and Repository (WSRR) registries for available Web services and gives you information about the function of each Web service.

  1. To use the Registry Explorer, click the Browse... button in the implementation properties for a Web Service integration component as shown in the following image:

  2. When the Explorer Wizard starts, select the registry type from the drop-down list: WebSphere Service Registry and Repository (WSRR) or UDDI Registry

  3. Type in the Registry URL.

    The Registry Explorer Wizard stores the WSRR and UDDI registry URLs that you type in, enabling you to select previously used URLs from the drop-down list.

    For WSRR registry URLs, you must provide the WSRR Rest Root URL in the following format: http://[host_name]:[port]/WSRR/7.0/ (See the WSRR Information Center for more information about the WSRR Rest Root URL: http://publib.boulder.ibm.com/infocenter/sr/v7r0/topic/com.ibm.sr.doc/rwsr_rest.html)

  4. For protected services, enable the Is Protected check box in the Registry Explorer Wizard, and then provide the user name and password.

    If security is enabled for the WebSphere Application Server on which the WSRR registry resides, you must configure the Lombardi Process Server. See Configure access to a secure WebSphere Application Server in the Lombardi Administration Guide before you can access the registry.

    Click the Next button in the Registry Explorer Wizard.

  5. In the Name field, type a partial or complete Web service name.

    For UDDI registries, you can use the % symbol as a wildcard that matches any character and returns a list of all services in the registry. For WSRR registries, you can use .* as a wildcard to return a list of all services in the registry.

    Click the Search services... button to generate a list of available Web services for the selected registry.

    Select a Web service, and then click the Next button.

    The wizard displays the Web service details, including the service key and the WSDL URI.

  6. If you are satisfied with the WSDL URI, the service key, and the implementation, click the Finish button.

    Lombardi populates the WSDL URI field in the implementation properties for the Web Service integration component.

  7. Click the Discover button to discover the WSDL.

See Build an Integration service to learn how to fully implement a Web service.


Specify a runtime endpoint address URL

In the Endpoint Address URL field in the Implementation properties for a Web Service integration component, you can specify a URL that points to a different instance of the Web service. Or this address can point to a proxy server, enabling you to monitor network traffic.


Use SOAP headers

Web Service integration components use a SOAP/XML connection to call out to Web services by discovering the ports and parameters from the WSDL, enabling Lombardi to access objects from a Web service over the Internet. SOAP/XML data can also be passed through firewalls so that applications can exchange information easily without causing security risks. SOAP messages are exchanged in a request/response format. When Lombardi sends a request to a Web service, the Web service returns the requested values. These values are specified in a SOAP message, which is a block of XML code that contains several elements.

All SOAP messages must contain a SOAP envelope element, which identifies the XML code as a SOAP message. Some WSDLs require that SOAP headers also be passed with each request. A SOAP header is an element in a SOAP message that resides in the message's SOAP envelope and provides detailed information about the SOAP message. For WSDLs that require SOAP headers to be passed with each request, Lombardi supports passing such headers for SOAP operations. SOAP headers for a selected WSDL operation are identified in brackets in the Parameters section of the Header properties, . There are two types of SOAP headers: headers that are directly specified as part of the SOAP binding and headers that are not.

SOAP headers that are part of the SOAP binding are indicated specifically by the use of <soap:header> in the <wsdl:input> and <wsdl:output> elements in the code that you see when you open the WSDL URI in a Web browser. For example, the following figure shows the GetServerInfo operation in http://localhost:8081/webapi/services/WebAPIService?WSDL. You can see where the <soap:header> element is used in this operation. When Lombardi sends a request to the server that hosts the Web service, the SOAP message includes the SOAP header. For example, the SOAP header used for the GetServerInfoRequest input is ClientInfo.

SOAP headers that are not part of the SOAP binding typically are not specified in the WSDL. There is only one SOAP header section in any SOAP request. A SOAP envelope, which is passed across the Internet as the request and response, consists of a header section and a body section. SOAP headers can be input, output, or input/output, , and they do not have to be specified in the WSDL. For example, you can see the SOAP headers in the tw-outbound_webservices.log and tw-inbound_webservices.log files in...

Lombardi also supports passing arbitrary SOAP headers using the Web Service integration component. This enables you to add a new SOAP header to a SOAP request without having to manually add the SOAP header to the WSDL. To define a new SOAP header parameter, click the Add Input Header button, as shown in the following image. The new SOAP header is added to the Input tree in the Parameters section. Type a name for the new header in the Parameter Name field. You can manually specify a Default Value and a Web Service Type for the header parameter. In the Header Details section (available only for SOAP header parameters), you can also specify the following optional properties for the SOAP header parameter:

Property Description Syntax
Actor Specify a SOAP actor attribute. soap:actor="URI"
Must understand Specify a SOAP mustUnderstand attribute.

soap:mustUnderstand="0"
soap:mustUnderstand="1"

Use script When you enable this edit box, you can manually write a script that generates the SOAP/XML content for the SOAP header. If you select this option, the Default Value, Web Service Type, Actor, and Must understand fields are disabled. N/A

To delete a header from the Input tree, select the header and then click the Remove button.


Serializing Lombardi objects for use in Web services

Authors can add metadata to Lombardi objects to control how those objects are serialized into XML elements in a SOAP request for Web services. When sending Complex types as input parameters to Web services, Lombardi often needs hints as to how to structure the data. These methods are built on the structure because a structure is, by definition, a Complex type.

Serializing Lombardi objects for use in Web services is primarily for advanced users, and is now required only when using Record objects with Web services instead of the generated types.

The following methods have been added to the tw.object.Record() object to assist in forming the SOAP request:

Example:

You are passing an object of type NameUpdateRequest as an argument to a Web service. This object is defined in the namespace http://www.lombardisoftware.com/schemas/NameUpdateRequest. The NameUpdateRequest object contains two properties, First (string) and Last (string).

Following is example code to generate the XML that is part of the SOAP call: 

<#
out = new tw.object.Record();
out.setSOAPElementNS("http://www.lombardisoftware.com/schemas/
NameUpdateRequest");
out.setSOAPElementName("NameUpdateRequest");
out.defineSOAPProperty("First", "http://www.w3.org/2001/
XMLSchema", "string", false, "");
out.defineSOAPProperty("Last", "http://www.w3.org/2001/
XMLSchema", "string", false, "");
out.First = "John";
out.Last = "Smith";
#>

This generates the following XML element: 

<NameUpdateRequest xmlns="http://www.lombardisoftware.com/schemas/
NameUpdateRequest">
<first xmlns="">John</first>
<last xmlns="">Smith</last>
</NameUpdateRequest>


Calling a Web service that requires authentication

Lombardi supports the following runtime authentication mechanisms that do not require client certificates:

For Protected WSDL authentication, you can simply enable the Protected WSDL check box in the implementation properties for the Web Service integration component, and then provide the user name and password in the provided fields. The other authentication options are available in the security properties for Web Service integration components :

The following table describes the information that you must provide for each option:

Option Description
HTTP Authentication Requires a user name and password. Lombardi never stores the password in plain text in its database or export files, and no plain text passwords are required in Lombardi configuration files.
UsernameToken

When using UsernameToken authentication in Lombardi, a user name and password are passed to a Web service in the header of the SOAP request. UsernameToken allows for different algorithms and formats for passing the password.

Lombardi supports passwords in the following formats: Plain text and Digest

UsernameToken authentication is an alternative to using a certificate on the client. If you select either of the UsernameToken options, the Sign request option is disabled. If you select the Sign request, the UsernameToken option is disabled.

The specification for UsernameToken authentication with Password in Digest describes two optional elements that can be supplied:

  • wsse:Nonce
  • wsu:Created

The Lombardi implementation of this standard always provides wsse:Nonce and wsu:Created. This is compatible with the behavior of Microsoft WSE 2.0 Toolkit when using UsernameToken digest authentication.


Calling a Web service that is secured by SSL

Lombardi supports standards for calling Web services that are secured by the SSL protocol. The procedure for modeling the integration between Lombardi and a Web service that is secured by SSL is generally the same as for non-secured Web services, if the certificate comes from a trusted certificate authority.

However, if the certificate that is used for SSL is not from one of the certificate authorities that Java recognizes by default, you need to install the certificate in the SSL certificate store that Java uses. If not, you get an error stating No trusted certificate is found when you click the Discover button in the implementation properties for the Web Service integration component.


Calling a Web service that uses client and server certificates

If you call a Web service that uses X509 client and server certificates, you must provide the certificate aliases when you select the HTTP Authentication option in the security properties for a Web Service integration component.

A developer or administrator must add the certificates to the Lombardi keystore and make appropriate configuration changes.

When you select the HTTP Authentication option in the security properties for a Web Service integration component, the following fields are available for certificate aliases:

Client certificate alias Identify the certificate that can be used to sign a Web service request or to decrypt a Web service response.
Server certificate alias Identify the certificate that can be used to encrypt Web service requests or to verify signatures on Web service responses.


Troubleshooting outbound Web Service integrations

The following table describes some common problems that you might encounter when creating services that include outbound Web Service Integration components:

Issue Error message when you click Discover Possible resolutions
Incorrect WSDL URI value PARSER ERROR: Problem parsing '[path_name]\WebAPIService.':The markup in the document following the root element must be well formed.

You have incorrectly typed the URI value. Navigate to the URI using a Web browser to verify that you have the correct WSDL. A common problem is that the ?wsdl argument is missing from the end of the URI.

For file protocol URIs, the URI does not exist on disk. If you are unable to validate the location of the URI on disk, contact your network administrator.

Nonexistent host Unknown Host Exception

You have incorrectly typed the host value. Navigate to the URI using a Web browser to verify that you have the correct host information.

The server that hosts the URI is offline (not running). Contact your network administrator to determine if this is causing the problem.

The network is experiencing connectivity problems. Contact your network administrator to determine if this is causing the problem.

Authentication required for WSDL access Runtime Exception: Unauthorized access to '[path_name]\WebAPIService?WSDL'

The WSDL URI is protected by an authentication mechanism. If you have permission to access the Web service, check the Protected WSDL check box, and then enter the Username and Password.

Navigate to the WSDL URI using a Web browser and save the text of the WSDL to a file so that you can use the file location as the target WSDL URI.


Recommended reading for outbound Web service integrations

To learn more about Web service standards and how they might apply to your Lombardi environment, the following Web resources are recommended:

Parent topic: Create outbound integrations

+

Search Tips   |   Advanced Search