Web services gateway troubleshooting tips

Use this set of specific tips to help you troubleshoot problems you experience when using the web services gateway.

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.

The web services gateway is implemented as an administrative layer on top of service integration bus-enabled web services. Therefore most known problems that you might experience when using the gateway are actually bus-enabled web services-related problems, and are documented in Bus-enabled 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 bus-enabled web services component is CWSWS.

The Troubleshooter reference: Messages topic contains information about the gateway and bus-enabled 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.

Passing 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 -> Server Types -> WebSphere application servers -> server_name -> [Server Infrastructure] Java and Process Management -> Process Definition > [Additional Properties] Java Virtual Machine -> [Additional Properties] Custom Properties then click 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 or later, 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 -> Server Types -> WebSphere application servers -> server_name -> [Server Infrastructure] Java and Process Management -> Process Definition > [Additional Properties] Java Virtual Machine -> [Additional Properties] Custom Properties then click 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.

Creating a gateway service, the 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.

Migrating a gateway from WebSphere Application Server Version 5.1 to a later version

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 later versions 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.1 gateway service WSDL to generate your web service clients and your WSDL binding and encoding style is not document literal, then after migration you must regenerate the client stubs by using the new gateway service WSDL.

Generating a web service client from the WSDL for the target service, rather than the gateway service

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.1, so you might encounter this problem for the first time when you migrate a gateway configuration from a Version 5.1 application server to the gateway capability on an application server on a later version. 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 by using the gateway service WSDL of the later version.

Migrating a gateway that contains filters from WebSphere Application Server Version 5.1 to a later version, and your filters no longer work

The use of filters was deprecated in Version 5.1.1 and support for filters was removed in Version 7.0. The role formerly played by filters is now undertaken by a combination of JAX-RPC handlers and service integration bus mediations. If you migrate a web services gateway that includes a routing filter, you can recreate the filter functions.

Migrating a gateway that contains filters from WebSphere Application Server Version 5.1 to Version 7.0 or later, destinations with names ending StorageQueue were created

These additional destinations were required to support existing Version 5.1 gateway filters in the Version 6 environment. Gateway filters are no longer supported, and so these "StorageQueue" destinations are no longer needed in Version 7.0 or later. However they are not removed automatically when you migrate to Version 7.0 or later or you delete the gateway instance.

During migration to Version 6, these additional destinations were created in one of the following two ways:
  • If you specified the -Q parameter (shared filter correlation queue name), then a single queue destination of the specified name was created (if it did not already exist) and shared by all gateway services that had associated filters.
  • If you did not specify the -Q parameter, then a separate queue destination was created for each gateway service that had 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.

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 .

Client application that works under WebSphere Application Server Version 5.1, but you get problems caused by poorly-formed requests or responses in later versions

Bus-enabled web services check the validity of web service messages more thoroughly than is done in WebSphere Application Server Version 5.1. 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.1, are identified as poorly-formed in later versions. For the steps to take to resolve the problem, see Toleration of poorly-formed SOAP messages

JAX-RPC client running on WebSphere Application Server Version 5.1 uses SOAP over JMS to invoke a web service running on a Version 5.1 application server

JAX-RPC client running on WebSphere Application Server Version 5.1 uses SOAP over JMS to invoke a web service running on a Version 5.1 application server. No user ID or password is required on the target MQ Series queue. After the application server is migrated to a later version, and to use 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: Migrating a Version 5.1 application server to WebSphere Application Server Version 7.0 or later

Gateway panels in the administrative console are only available in WebSphere Application Server Network Deployment

The panels are not available in a WebSphere Application Server Network Deployment stand-alone server profile. However, the wsadmin command scripts that provide equivalent functions by using the wsadmin tool are available for both the stand-alone 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 by using Jacl.
[IBM i] Note: The wsadmin scripting client is run from Qshell. For more information, see Configuring Qshell to run WebSphere scripts using wsadmin scripting.
Here is an example script:
  • Using Jython:
    wsgwAttribs = []
    wsgwAttribs.append(["name", wsgwName])
    wsgwAttribs.append(["wsdlServiceNamespace", wsgwNamespace])
    wsgw = AdminConfig.create("WSGWInstance", bus, wsgwAttribs )
    wsgwWsdlAttribs = []
    wsgwWsdlAttribs.append(["WSDLLocation", wsgwWsdlLocation])
    AdminConfig.create("SIBWSWSDLLocation", wsgw, wsgwWsdlAttribs,
     "defaultProxyWSDLLocation" )
  • Using Jacl:
    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 or $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 object, enter "AdminConfig.help()" from the wsadmin command line.
Reference topic    

Terms and conditions for information centers | Feedback

Last updated: April 18, 2014 05:01 AM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-iseries&topic=rwsg_prob0
File name: rwsg_prob0.html