Web services gateway troubleshooting tips

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

(ZOS) To help you identify and resolve web services gateway-related problems, use the WebSphere Application Server trace and logging facilities as described in Set 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 we encounter a problem that you think might be related to the gateway, we can check for error messages in the WAS administrative console, and in the application server SystemOut.log file. We 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 we might experience when using the gateway are actually bus-enabled web services-related problems, and are documented in Bus-enabled web services troubleshooting tips.

WAS 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 we can take to resolve the problem.

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

• 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
• A SOAP over JMS web service message is sent by the web services gateway as a JmsBytesMessage, rather than a JmsTextMessage
• Create a gateway service, the WSDL description is not created in the SDO repository until we attempt to access the gateway service WSDL file through a web browser
• Migrate a gateway from WAS v5.1 to a later version
• Generate a web service client from the WSDL for the target service, rather than the gateway service
• Migrate a gateway containing filters from WAS v5.1 to a later version, and your filters no longer work
• Migrate a gateway containing filters from WAS v5.1 to v7.0 or later, destinations with names ending StorageQueue were created
• Client application that works under WAS v5.1, but we get problems caused by poorly-formed requests or responses in later versions
• JAX-RPC client running on WAS v5.1 uses SOAP over JMS to invoke a web service running on a v5.1 application server
• Gateway panels in the administrative console are only available in WAS Network Deployment

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

We 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 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 -> [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 WAS v6 or later, a SOAP over JMS web service message sent by the web services gateway is sent as a JmsBytesMessage, whereas on WAS v5.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 -> [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.

Create a gateway service, the WSDL description is not created in the SDO repository until we 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 the applications are posting messages into the bus from sources other than the inbound service (for example if we 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.

Migrate a gateway from WAS v5.1 to a later version

When the v5 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 our WSDL binding and encoding style is document literal then the clients still work with the migrated gateway, because document literal style does not use the namespace attribute. However, if we used the v5.1 gateway service WSDL to generate the web service clients and the WSDL binding and encoding style is not document literal, then after migration we must regenerate the client stubs using the new gateway service WSDL.

Generate 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 we 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 associated with a gateway service.

This approach is not flagged by default as a possible error in WAS v5.1, so we might encounter this problem for the first time when we migrate a gateway configuration from a v5.1 application server to the gateway capability on an application server on a later version. After migration, we have two choices:

• 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.

• If we no longer need this flexibility, regenerate the client stubs using the gateway service WSDL of the later version.

Migrate a gateway containing filters from WAS v5.1 to a later version, and your filters no longer work

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

Migrate a gateway containing filters from WAS v5.1 to v7.0 or later, destinations with names ending StorageQueue were created

These additional destinations were required to support existing v5.1 gateway filters in the v6 environment. Gateway filters are no longer supported, and so these "StorageQueue" destinations are no longer needed in v7.0 or later. However they are not removed automatically when we migrate to v7.0 or later or you delete the gateway instance.

During migration to v6, these additional destinations were created in one of the following two ways:

• If we 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 we 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 WAS v5.1, but we 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 WAS v5.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 v5.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 WAS v5.1 uses SOAP over JMS to invoke a web service running on a v5.1 application server

JAX-RPC client running on WAS v5.1 uses SOAP over JMS to invoke a web service running on a v5.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: Migrate a v5.1 application server to WAS v7.0 or later

Gateway panels in the administrative console are only available in WAS Network Deployment

The panels are not available in a WAS Network Deployment stand-alone server profile. However, the wsadmin command scripts that provide equivalent functions 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. Create a gateway instance and its associated default proxy WSDL location information through the wsadmin scripting client using Jacl.

(iSeries) Note: (iSeries) The wsadmin scripting client is run from Qshell. (iSeries) See Configure Qshell to run WebSphere scripts . Here is an example script:

• Use 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" )
  

• Use 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 WAS AdminConfig object, enter "AdminConfig.help()" from the wsadmin command line.