Tips, Tricks and Code Tips, Tricks and Code

ESB and...

Understanding Web Services

Created by Janey Solwold, last modified on Tue, 20 Aug 2019, 05:10

This article describes various aspects of a Web service and its WSDL file. It also describes how certain of these aspects are supported by the different versions of Integration Server.

Submitted by: Shailen Prasad, Software AG, January 2012 Applicable Versions: 6.5 and later.

Table of Contents [-]

WSDL ComponentsAll the Web Service components in a WSDL 1.1 file can be broadly classified into two parts:#

  1. Abstract components: The abstract components are those which can be massaged and edited even after the webService is being created.
    - Port Types
    - Operation
    - Message
    - Schema
  2. Concrete components: The concrete components are those which fixed for a particular webService provider and cannot be changed.
    - Ports
    - Endpoints
    - Bindings
    !!!WSDL Bindings (Styles & Uses)A Web Service Definition Language (WSDL) document describes one or more web services. A WSDL binding describes how the service is bound to a messaging protocol, particularly the SOAP messaging protocol. A WSDL SOAP binding is associated with the “Style” of the web service. The two choices are either Document Style or Remote Procedure Call (RPC) style. In addition to the “Style” each input or output message is associated with “Use” attribute. The use can be either “Literal” or “Encoded”. The use defines the encoding used on the Web Services calls.
    \Use=Literal indicates that portions of the SOAP Message may be validated using an XML Schema that describes their format. Use=Encoded indicates that the XML fragments are encoded following the encoding scheme defined in section 5 of the SOAP 1.1 Specification.
    \This combination of Style and Use gives you four possible combinations:
  3. Document/literal
  4. RPC/literal
  5. RPC/encoded
  6. Document/encoded
    But in reality, the use=encoded is only defined for the RPC Style Web Services, which leaves only 3 valid Style/Use combinations for Web Services.
  7. Document/literal
  8. RPC/literal
  9. RPC/encoded
    Additionally, the Web Services Interoperability Organization (WS-I) has published “profiles” to be followed allowing for better Web Service interoperability among various implementations. The WS-I profile has disallowed the use of RPC/encoded for web services.
    \This leaves us with only Document/literal and RPC/literal as the only two WS-I compliant style/use combinations for Web Services. And of those two use/style combinations, Document/Literal Web services are by far the most common Web Services in use today.
    \!!WSDL Binding “Styles” and “Uses” supported by webMethods Products
Note: The term SOAPMSG as defined in IS 6.5 is actually Document/literal while the 6.5 SOAPRPC means RPC/Encoded.

WS-Security (Web Services Security, short WSS)WS-Security is a flexible and feature-rich extension to SOAP to apply “Message Level Security” to web services. It is a member of the WS-* family of web service specifications. #

The protocol specifies how integrity and confidentiality can be enforced on messages and allows the communication of various security token formats, such as SAML, Kerberos, and X.509. Its main focus is the use of XML Signature and XML Encryption to provide end-to-end security.

WS-Security support for IS web services was first introduced with Integration Server Release 7.1 and continues to be supported in the current 8.2 release. Prior to the 8.2 release, the WS-Security configuration was controlled with a proprietary policy format we refer to below as the “WS-Security Facility”. For the 8.2 release, we have adopted the standard WS-Policy, more specifically the WS-Security Policy, as the means to configure WS-Security for IS web services. The WS-Policy based approach is meant to replace the original WS-Facility configuration going forward. The WS-Facility policies are only left in place for backward compatibility of existing web services.

WS Security Implemented and Supported Across Different webMethods Versions
WS Security Policy:#

Starting with Integration Server 8.2, you can implement WS-Security using standardWS-SecurityPolicy. Integration Server only supports attaching WS-Policies at the service level by attaching WS-Policies to consumer and provider Web service descriptors. The WS-Policies that you can attach to Web service descriptors must reside in WS-Policyfiles. Integration Server provides pre-defined WS-Policies with settings for a number ofstandard security configurations.

Important: The WS Security Policies are stored in the Integrations Server at the following location: webMethods Install Directory\IntegrationServer\config\wss\policies

Note: In order to support WS-Addressing the above folder now includes an additional policy file named Addressing. Policy which can be attached to a Web service descriptor to include addressing assertions.

WS Security Facility:

The policy files that the WS-Security facility uses are not standard WS-Policy files. They are a unique format used only by the Integration Server WS-Security facility. To Use WS-Security facility you create policy files. When configuring the WS-Security facility, you map a policy file to a Web service descriptor file. Each time a message is sent or received by the Web service, the authentication, signing, and encryption settings specified in the policy file are applied to the web service request or reply.

Important: The WS security Facility policy files are stored in the Integrations Server at the following location: webMethods Install Directory\IntegrationServer\config\policy

WebService End Point AliasIntegration Server uses the endpoint URL to determine which Web service descriptor and which binder in that Web service descriptor contain the operation to invoke. The endpoint URL for an operation in a WSDL document generated by Integration Server has the following format: #


Web Service endpoint aliases may be used for both Consumer and Provider Web Service Descriptors (WSDs) to control the Endpoint URL as well as to supply other runtime settings, such as security credentials. When used with Provider WSDs, the information from the endpoint alias is used to construct the endpoint URL contained in the WSDL generated for the web service. When used with a Consumer WSD, the endpoint alias information will override the endpoint URL information originally contained in the WSDL used to create the Consumer WSD.

In IS 6.5 there was no concept of Web Service alias definitions. IS 7.1 introduced a single list web service alias definitions that was shared by both consumers and providers. In the 8.0 release, the properties contained within an endpoint alias were split into data important for Providers and another set of properties important for Consumers. Additionally each endpoint alias was associated with a specific Transport protocol (HTTP or HTTPS) the endpoint alias definitions were maintained within distinct lists based on Transport protocol and direction (provider/consumer). With 8.0 and higher only the alias definitions matching the direction and transport will be presented when assigning an alias to a Binder. 

End point Alias implementation and support across different webMethods versions

SOAP Fault HandlingWhen the Web service descriptor is created on Integration Server 8.2, the output signature of the Web service connector contains a generic fault structure, regardless of which SOAP version (1.1 or 1.2) is in use. #

Web service descriptors created on versions of Integration Server prior to 8.2, generated Web service connectors with an output signature that contained a SOAP fault document for both the SOAP 1.1 and SOAP 1.2 protocols. Then at runtime, a SOAP Fault is mapped to the appropriate elements based on the version of SOAP (1.1 or 1.2) used by the invocation.

Message Exchange ProtocolMEP type decides weather the provider of the WSDL needs to send any response (including fault message if the error happens) or not. Prior to webMethods 8.2 (including compatibility mode = true) Integration server only supported MEP type IN-OUT. Starting version 8.2 (compatibility mode =false), Integration Server includes or omits the <wsdl:fault> element based on the service’s output signature. If the service has defined output, Integration Server includes a <wsdl:output> element, and the operation uses In-Out MEP. If the service has no defined output, Integration Server omits the wsdl:output> element, and in such case the operations can use In-Only if there is no <wsdl:fault> and will use MEP type Robust In-Only if it has <wsdl:fault> defined in the wsdl. #

WebService-HandlerWebService Handlers allow you to process SOAP message header traffic for the remote call to the Web service. The SOAP header is defined by the SOAP standard. JAX-RPC Handlers support the Java API for XML-Based RPC (JAX-RPC) and Web Services for J2EE standards. IS Service Handlers are defined by the Integration Server. They consist of a set of up to three IS Services (Flow or Java) to be invoked during Web Service processing, one each for processing “handleRequest”, “handleResponse” and “handleFault”. #

  • IS 6.5 - no handler support
  • IS 7.1 - JAX-RPC based hander support introduced
  • IS 7.1.3 - Service Handlers introduced and the use of JAX-RPC handlers deprecated
  • IS 8.0 - 8.2 (with compatibility mode=true) same as 7.1.3. JAX-RPC handler use deprecated, but still supported. Service Handlers were the preferred approach.
  • 8.2 (compatibility mode= false) - Only Service Handlers supported, no support for JAX-RPC handlers.
    The order of the handlers on the Handlers tab determines the order in which Integration Server invokes them during processing.
    • Note: For 7.x and 8.x (compatibility mode=true) web services, the WS-Security Facility is treated as a Handler. The order of the ws-security processing in regard to the other handlers can be controlled by changing the order of the defined handlers.

For 8.2 (compatibility mode=false) services WS-Security is not implemented as a Handler but is built into the Web Services processing when enabled. On inbound messages, Integration Server will invoke all handlers after the WS-Security processing has been applied. For outbound messages, Integration Server will invoke all handlers before it applies the WS-Security processing.

SOAP AttachmentsIntegration Server has gone through many changes in the past few versions in terms of supporting Attachments in SOAP messages. #

SOAP Attachments Across Different webMethods Versions

WebService TroubleshootingIn order to troubleshoot webServices issues it is sometimes very important to see what SOAP messages are being sent and received over the protocol used. #

  • For IS with MWS installed one can use SOAP Monitor which comes with MWS.
  • For IS without MWS one can use TCPMon. TCPMon is a utility that allows the messages to be viewed and resent. It is very much useful as a debug tool while working with webServices issues. This third party utility can be downloaded from the following location: /commons/tcpmon/download.cgi
    Apart from the above mentioned tools there are numerous other Watt server parameters which can be enabled to log additional debug messages to the Integration Server logs.
  • watt.server.SoapRPC.checkHeaders
  • watt.server.SoapRPC.debug
  • watt.server.SoapRPC.trace
  • watt.server.SoapRPC.verbose
    Some of the below mentioned IS logging facility can be adjusted to the higher debugging levels to collect some useful information related to webService troubleshooting:
  • HTTP Header
  • HTTP Request
  • HTTP Response
  • HTTP Cookie

4 Attachments
Average (7 Votes)
Useful information. Thanks for sharing.
Posted on 5/7/13 6:15 AM.
Nice post... Can this be updated for v9.6
Posted on 4/23/14 11:01 AM.
Hi , is there any limitations for a webservice call, with respect to the data (number of records) in a in-line (with out attachment).

Posted on 4/30/15 1:09 PM.
Thanks for the useful info.
Posted on 5/12/15 2:26 PM.