Web services gateway troubleshooting tips

This topic provides specific tips to help you troubleshoot problems you experience when using the Web services gateway.

To help you identify and resolve Web services gateway-related problems, use the WebSphere® Application Server trace and logging facilities as described in [AIX HP-UX Linux Solaris Windows] Tracing and logging configuration [z/OS] Setting up component trace (CTRACE).

To enable trace for the gateway, set the application server trace string to com.ibm.ws.sib.webservices.*=all=enabled:com.ibm.ws.wsgw.*=all=enabled. If you encounter a problem that you think might be related to the gateway, you can check for error messages in the WebSphere Application Server administrative console, and in the application server SystemOut.log file. You can also enable the application server debug trace to provide a detailed exception dump.

In WebSphere Application Server Version 6, the Web services gateway is implemented as an administrative layer on top of service integration bus (SIBus) Web services. Therefore most known problems that you might experience when using the gateway are actually SIBus Web services-related problems, and are documented in SIBus Web services troubleshooting tips.

WebSphere Application Server system messages are logged from a variety of sources, including application server components and applications. Messages logged by application server components and associated IBM® products start with a unique message identifier that indicates the component or application that issued the message. The prefix for the Web services gateway component is CWWSG and the prefix for the SIBus Web services component is CWSWS.

The Troubleshooter reference: Messages topic contains information about the gateway and SIBus Web services messages, indexed by message prefix. For each message there is an explanation of the problem, and details of any action that you can take to resolve the problem.

Here is a set of tips to help you troubleshoot commonly-experienced problems:

When you pass messages directly to a bus destination, the default RPC-encoded Web services string array message does not interoperate successfully with some target service providers.

You can pass messages directly to a bus destination by overriding the JAX-RPC client binding namespace and endpoint address. However:
  • The default RPC-encoded Web services string array message that is generated might not interoperate successfully with some target service providers.
  • The string array message produced is not exactly the same as the standard JAX-RPC equivalent, which can interoperate successfully.
Here are examples of the two different messages:
  • Service integration bus message:
    <partname env:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/ xsi:type='ns1:ArrayOf_xsd_string'>
      <item xsi:type='xsd:anySimpleType'>namevalue</item>
    </partname>
    
  • JAX-RPC client message:
    <partname xsi:type="soapenc:Array" soapenc:arrayType="xsd:string[1]">
      <item>namevalue</item>
    </partname>
To modify the default behavior to send a string array message that is fully compatible with standard JAX-RPC, set the following JVM custom property. Setting this property modifies the default behavior for all outbound JMS Web services invocations sent from the bus:
  1. Start the administrative console.
  2. Navigate to Servers > Application servers > server_name > [Server Infrastructure] Java and Process Management > Process Definition > [Additional Properties] Java Virtual Machine > [Additional Properties] Custom Properties > New.
  3. Create the following JVM custom property. Note that the values shown are case sensitive.
    • Name: com.ibm.websphere.sib.webservices.useTypeSoapArray
    • Value: true
  4. Restart the application server.

A SOAP over JMS Web service message is sent by the Web services gateway as a JmsBytesMessage, rather than a JmsTextMessage.

By default on WebSphere Application Server Version 6, a SOAP over JMS Web service message sent by the Web services gateway is sent as a JmsBytesMessage, whereas on WebSphere Application Server Version 5.1 the Web services gateway sends a JmsTextMessage.

To modify the default behavior to send a compatible JmsTextMessage, set the following JVM custom property. Setting this property modifies the default behavior for all outbound JMS Web services invocations sent from the bus:
  1. Start the administrative console.
  2. Navigate to Servers > Application servers > server_name > [Server Infrastructure] Java and Process Management > Process Definition > [Additional Properties] Java Virtual Machine > [Additional Properties] Custom Properties > New.
  3. Create the following JVM custom property. Note that the values shown are case sensitive.
    • Name: com.ibm.ws.sib.webservices.useSOAPJMSTextMessages
    • Value: true
  4. Restart the application server.

If you create a gateway service, its WSDL description is not created in the SDO repository until you attempt to access the gateway service WSDL file through a Web browser.

Every gateway service has an associated inbound service. The gateway service WSDL file is associated with this inbound service and should only be needed if the message originates from an inbound service. Therefore the WSDL description is created in the SDO repository the first time it is called by an inbound service or through a Web browser.

If your applications are posting messages into the bus from sources other than the inbound service (for example if you are using mediation handlers to manipulate SDO messages to or from a gateway service), the applications should use either the WSDL associated with the target (outbound) service or some other compatible WSDL.

You migrate a gateway from WebSphere Application Server Version 5 to Version 6. When you try to access a gateway service, your client receives one or more error messages stating No response body is available, or Null response message, or The message body did not match any of the definitions in the WSDL.

When the Version 5 gateway generates WSDL for a gateway service, the generated namespace contains the service name. For example: namespace="http://griddev:9080/wsgw#yourService". However in Version 6 the generated WSDL for a gateway service does not contain the service name. For example: namespace="http://griddev:9080/wsgw".

If your WSDL binding and encoding style is document literal then your clients still work with the migrated gateway, because document literal style does not use the namespace attribute. However, if you used the Version 5 gateway service WSDL to generate your Web service clients and your WSDL binding and encoding style is not document literal, then after migration to Version 6 you must regenerate the client stubs using the new gateway service WSDL.

You choose to generate a Web service client from the WSDL for the target service, rather than the gateway service. When you try to access the target service through the gateway, your client receives the following error message: CWSIF0304E: The message body did not match any of the definitions in the WSDL.

The benefit of choosing to generate a Web service client from the WSDL for the target service is that you can move between going to the target service directly or going through the gateway to the target service just by changing the URL in the generated stubs. To enable this approach in this version of the gateway, use the administrative console to set the custom property com.ibm.websphere.wsgw.mapSoapBodyNamespace to false on each inbound service that is associated with a gateway service.

Note: This approach is not flagged by default as a possible error in WebSphere Application Server Version 5, so you might encounter this problem for the first time when you migrate a gateway configuration from a Version 5 application server to the new gateway capability on a Version 6 application server. After migration, you have two choices:
  • If you want to retain the flexibility to reroute your messages by changing the URL in the generated stubs, set the custom property com.ibm.websphere.wsgw.mapSoapBodyNamespace to false as described above.
  • If you no longer need this flexibility, regenerate the client stubs using the Version 6 gateway service WSDL.

You migrate a gateway that contains filters from WebSphere Application Server Version 5 to Version 6, and your routing filters no longer work.

The Version 5 gateway target service identity values are not migrated to Version 6, so filters that use the Routing interface to select a target service by identity either fail with this exception:
WSGWException: CWWSG3026E: Target service identity information identity not matched for gateway service 
gateway_service_name
or fail to find any identity values for the target services.
Although deprecated, the Routing interface and target service identity values are still supported in WebSphere Application Server Version 6. However, the Version 5 gateway backup command does not save the target service identity values, so they are not imported into the Version 6 configuration when you run the migration command. To add the missing identity values back into the Version 6 configuration, complete the following steps:
  1. Get the cell name, bus name, gateway instance name, gateway service name, and target service names for the target services that need identity values. You can get some of this information from the parameters that you set when you migrated the gateway, and get the rest of this information from the Version 6 administrative console panels.
  2. Determine the identity value for each of these target services. You can examine the original Version 5 gateway service definitions, or use other methods to determine these identity values.
  3. Save a copy of the following script on the machine on which the Version 6 gateway is running, with a file name of setIdentity.jacl:
    #-------------------------------------------------------------------------------
    # Jacl script to set the Identity attribute on a WSGW Gateway Target Service
    #
    # 2004/11/17 add copyright and disclaimer notices
    #
    #-------------------------------------------------------------------------------
    
    # Copyright (C) 2004 International Business Machines Corporation
    
    # INTERNATIONAL BUSINESS MACHINES CORPORATION
    # PROVIDES THIS SOFTWARE ON AN "AS IS" BASIS
    # AND IBM DISCLAIMS ALL WARRANTIES, EXPRESS OR
    # IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE 
    # WARRANTY OF NON-INFRINGEMENT AND THE IMPLIED
    # WARRANTIES OF  MERCHANTABILITY OR FITNESS
    # FOR A PARTICULAR PURPOSE.  IBM SHALL NOT BE
    # LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
    # SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT
    # OF THE USE OR OPERATION OF THIS SOFTWARE.  
    # IBM HAS NO OBLIGATION TO PROVIDE MAINTENANCE, 
    # SUPPORT, UPDATES, ENHANCEMENTS OR MODIFICATIONS
    # TO THE SOFTWARE.
    
    #---------------------------------------------------------------------------
    # Clean the environment
    #---------------------------------------------------------------------------
    
    $AdminConfig reset
    
    #---------------------------------------------------------------------------
    # Check correct usage
    #---------------------------------------------------------------------------
    
    if {[llength $argv] != 6} {
        puts ""
        puts "ERROR: Incorrect usage."
        puts ""
        puts {Usage: wsadmin [-conntype none] -f setIdentity.jacl <cell> <bus> <instance> <gateway> 
              <target> <identity>}
        puts ""
        puts "Where:"
        puts ""
        puts "  '-conntype none' is optional, but is required if the server is not running."
        puts ""
        puts "Also:"
        puts ""
        puts "  <cell>     = the name of the cell containing the <bus>"
        puts "  <bus>      = the name of the bus containing the <instance>"
        puts "  <instance> = the name of the WSGW Gateway Instance containing the <gateway>"
        puts "  <gateway>  = the name of the WSGW Gateway Service containing the <target>"
        puts "  <target>   = the name of the WSGW Target Service to be modified"
        puts "  <identity> = the new Target Service Identity value to be added to or altered in the <target>"
        puts ""
        puts "All parameters are mandatory."
        puts "If the <identity> value has spaces in it, the value should be enclosed in double-quotes."
        puts ""
        exit
    }
        
    #---------------------------------------------------------------------------
    # Extract the arguments
    #---------------------------------------------------------------------------
    
    set cellName [lindex $argv 0]
    set busName [lindex $argv 1]
    set wsgwInstanceName [lindex $argv 2]
    set gatewayServiceName [lindex $argv 3]
    set targetServiceName1 [lindex $argv 4]
    set targetServiceIdentity1 [lindex $argv 5]
    
    puts "--- Cell Name : $cellName"
    puts "--- Bus Name : $busName"
    puts "--- Gateway Instance Name : $wsgwInstanceName"
    puts "--- Gateway Service Name : $gatewayServiceName"
    puts "--- Target Service Name : $targetServiceName1"
    puts "--- Target Service Identity : $targetServiceIdentity1"
    puts ""
    
    #-------------------------------------------------------------------------------
    # Set constants
    #-------------------------------------------------------------------------------
    
    set gatewayServiceType "WSGWGatewayService"
    set targetServiceType "WSGWTargetService"
    set identityAttrib "targetServiceIdentity"
    
    #-------------------------------------------------------------------------------
    # proc to return the object id for a given object name and type within a scope
    #-------------------------------------------------------------------------------
    proc getScopedObjectId {idType idName scopeId} {
    
      global AdminConfig
      set ids [$AdminConfig list $idType $scopeId]
      foreach id $ids {
        set thisName [$AdminConfig showAttribute $id name]
        if {[sameString $thisName $idName]} {
          return $id
        }
      }
    # name not found
      return 0
    }
    
    #-------------------------------------------------------------------------------
    # proc to compare 2 strings
    #-------------------------------------------------------------------------------
    proc sameString {string1 string2} {
    
      #-- if the object name supplied is * then return true --#
      set anything "*"
    
      if {[string compare $string2 $anything] == 0} {
        return 1
      }
      #-- if the 2 names are the same then return true --#
      if {[string compare $string1 $string2] == 0} {
        return 1
      }
      #-- return false --#
      return 0
    }
    
    #-------------------------------------------------------------------------------
    
    puts "+++ Getting Gateway Instance ID for $cellName $busName $wsgwInstanceName"
    set wsgwInstanceId [$AdminConfig getid /Cell:$cellName/SIBus:$busName/WSGWInstance:$wsgwInstanceName/]
    
    puts "+++ Getting Gateway Service ID for $gatewayServiceName"
    set gatewayServiceId [getScopedObjectId $gatewayServiceType $gatewayServiceName $wsgwInstanceId]
    
    puts "+++ Getting Target Service ID for $targetServiceName1"
    set targetServiceId1 [getScopedObjectId $targetServiceType $targetServiceName1 $gatewayServiceId]
    
    puts "+++ Setting Identity for Target Service $targetServiceName1 to $targetServiceIdentity1"
    set identargs {}
    lappend identargs [list $identityAttrib $targetServiceIdentity1]
    $AdminConfig modify $targetServiceId1 $identargs
    puts "--- Target Service Identity set"
    
    $AdminConfig save
    puts "Configuration saved"
    
  4. Change to the app_server_root/bin directory (where app_server_root is the root directory for the installation of IBM WebSphere Application Server), and use the wsadmin scripting client to run the setIdentity.jacl script for each target service and related identity value:
    wsadmin [-conntype none] -f path_and_filename_for_setIdentity.jacl cell_name bus_name 
    gateway_instance_name gateway_service_name target_service_name target_service_identity
  5. You might need to restart the server to enable the new identity values.

When you migrate a gateway that contains filters from WebSphere Application Server Version 5 to Version 6, destinations with names ending StorageQueue are created. These destinations are not removed if you subsequently delete the migrated gateway.

These additional destinations are required to support existing Version 5 gateway filters in the Version 6 environment. However they are not part of the standard Version 6 configuration model, and consequently are not removed automatically if you delete a Version 6 gateway instance.

During migration, these "StorageQueue" destinations are created in one of the following two ways:
  • If you specify the -Q parameter (shared filter correlation queue name), then a single queue destination of the specified name is created (if it does not already exist) and shared by all gateway services that have associated filters.
  • If you do not specify the -Q parameter, then a separate queue destination is created for each gateway service that has associated filters. Each of these destinations has a name derived from the name of the corresponding gateway service request and reply destinations, and ending in StorageQueue.

These "StorageQueue" destinations are required to support existing filters in a migrated gateway configuration, and they should not be removed unless the gateway instance is deleted. After you delete the gateway instance, identify each associated storage queue destination by name, and delete it as described in Deleting a non-topic space bus destination .

You have a client application that works under WebSphere Application Server Version 5, but under Version 6 you get problems caused by poorly-formed requests or responses.

SIBus Web services performs more validation on Web service messages than is done in WebSphere Application Server Version 5. As a result, some client applications that use poorly-formed requests or responses (where the message parts are misnamed), and that work when using Version 5, are identified as poorly-formed in Version 6. For the steps to take to resolve the problem, see Toleration of poorly-formed SOAP messages

A JAX-RPC client running on WebSphere Application Server Version 5 uses SOAP over JMS to invoke a Web service running on a Version 5 application server. No user ID or password is required on the target MQ Series queue. After the application server is migrated to Version 6, and using Version 6 default messaging, client requests fail because basic authentication is now enabled.

The problem appears as a log message:
SibMessage    W   [:] CWSIT0009W: A client request failed in the application server with endpoint 
<endpoint_name> in bus your_bus with reason: CWSIT0016E: The user ID null failed authentication in bus 
your_bus.

For the steps to take to resolve the problem, see the following service integration technologies troubleshooting tip: Service integration bus security - troubleshooting tips

The gateway panels in the administrative console are only available in WebSphere Application Server Network Deployment if you are working with a deployment manager profile.

The panels are not available in a WebSphere Application Server Network Deployment standalone server profile. However, the wsadmin command scripts that provide equivalent functionality using the wsadmin tool are available for both the standalone and deployment manager profiles. The gateway administrative commands cover all the main requirements, except for creating a new gateway instance. You can create a gateway instance and its associated default proxy WSDL location information through the wsadmin scripting client using Jacl. Here is an example script:
set wsgwAttribs {}
lappend wsgwAttribs [list "name" $wsgwName]
lappend wsgwAttribs [list "wsdlServiceNamespace" $wsgwNamespace]
set wsgw [$AdminConfig create "WSGWInstance" $bus $wsgwAttribs]
set wsgwWsdlAttribs {}
lappend wsgwWsdlAttribs [list "WSDLLocation" $wsgwWsdlLocation]
$AdminConfig create "SIBWSWSDLLocation" $wsgw $wsgwWsdlAttribs "defaultProxyWSDLLocation"
In this example, $bus is the ID of the service integration bus in which the gateway instance is created. For more information about the WebSphere Application Server $AdminConfig function, enter '$AdminConfig help' from the wsadmin command line.



Related tasks
Working with the Web services gateway
Reference topic    

Terms of Use | Feedback

Last updated: Aug 29, 2010 10:43:27 PM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=v602web&product=was-nd-mp&topic=rwsg_prob0
File name: rwsg_prob0.html