To identify the cause of a SOAP problem, you typically need the following information:
It is also extremely useful to handle faults correctly so that you receive the best possible information. See SOAP Fault Handling.
InterSystems IRIS SOAP Log
To log the SOAP calls made to or from an InterSystems IRIS namespace, set the following nodes of the ^ISCSOAP global in that namespace as described below.
Important:
The SOAP log is voluminous, so it is important to enable it only when needed and disable it as soon as possible. See the notes after the table for details.
| Node |
Purpose |
| ^ISCSOAP("Log") |
Specifies the type of data to include in the log. Use one of the following case-sensitive values:
-
"i" — Log inbound messages.
-
"o" — Log outbound messages.
-
"s" — Log security information. Note that this option provides more detail than is generally contained in the SOAP fault, which is intentionally vague to prevent follow-on security attacks.
-
"h" — Log only SOAP headers. You must combine “h” with "i" and/or "o". When you use "h" with "i", the log includes only the SOAP Envelope and Header elements for inbound messages. Similarly, when you use "h" with "o", the log includes only the SOAP Envelope and Header elements for outbound messages. The corresponding SOAP Body elements are not logged.
-
"H" — Log HTTP headers. You must combine “H” with "i" and/or "o". When you use "H" with "i", the log includes HTTP headers for inbound messages. Similarly, when you use "H" with "o", the log includes HTTP headers for outbound messages. HTTP headers are logged in addition to any SOAP data.
You can also use a string that contains any combination of these values, for example: "iosh" |
| ^ISCSOAP("LogFile") |
Specifies the complete path and filename of the log file to create. |
The log indicates the sender or the recipient as appropriate, so that you can see which web service or client participated in the exchange.
The following shows a partial example of a log file with line breaks added for readability:
01/05/2010 13:27:02 *********************
Output from web client with SOAP action = https://www.mysecureapp.org/GSOAP.AddComplexSecureWS.Add
<?xml version="1.0" encoding="UTF-8" ?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV='https://schemas.xmlsoap.org/soap/envelope/'
...
<SOAP-ENV:Header>
<Security xmlns="https://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
</SOAP-ENV:Header>
<SOAP-ENV:Body>
...
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
**** Output HTTP headers for Web Client
User-Agent: Mozilla/4.0 (compatible; InterSystems IRIS;)
Host: hostid
Accept-Encoding: gzip
**** Input HTTP headers for Web Client
HTTP/1.1 200 OK
CACHE-CONTROL: no-cache
CONTENT-ENCODING: gzip
CONTENT-LENGTH: 479
CONTENT-TYPE: application/soap+xml; charset=UTF-8
...
01/05/2010 13:27:33 *********************
Input to web client with SOAP action = https://www.mysecureapp.org/GSOAP.AddComplexSecureWS.Add
ERROR #6059: Unable to open TCP/IP socket to server devsys:8080
string
Note the following points:
-
With InterSystems IRIS XML tools, you can validate signatures of signed XML documents and decrypt encrypted XML documents. If you perform these tasks in this namespace, the log contains details for them as well. See Using XML Tools.
-
The InterSystems IRIS SOAP log captures SOAP calls even when no message is sent on the wire (that is, when the service and client are both on a single machine).
-
If a severe error occurs, the system stops writing to the SOAP log. See the messages log instead. For information, see Monitoring Log Files in the Monitoring Guide.
-
The Task Manager CheckLogging task, which runs every night, creates an alert if SOAP logging is left on for too long (by default, 2 days). Because the SOAP log is voluminous, it is important to pay attention to this alert.
Third-Party Tracing Tools
To test your web service, you can use tracing tools such as Wireshark, ProxyTrace, tcpTrace, XMLSpy, soapUI, or Web Service Studio Express. Some of these tools are free and others are licensed. Note that InterSystems does not make any specific recommendations about these tools; they are listed here for your general information.
Tracing tools enable you to see the actual method call, as well as the response. A tracing session listens on a certain port, shows you the messages it receives there, forwards those messages to a destination port, shows the responses, and forwards the responses to the listening port.
For example, suppose you have a web service at https://devsys/csp/mysamples/GSOP.Divide.CLS
And suppose you have a web client that you created to talk to that service. The web client has a LOCATION parameter equal to "https://devsys/csp/mysamples/GSOP.Divide.CLS"
To trace messages between the client and service, you need to do two things:
-
In the tracing tool, start a tracing session that listens on port 8080 (for example) and that uses the destination port 52773.
-
In the web client, edit the LOCATION parameter to use port 8080 instead of 52773. Then recompile.
Or, in your code that invokes the web client, change the Location property of the web client:
//reset location to port 8080 to enable tracing
set client.Location="https://devsys:8080/csp/mysamples/GSOP.DivideWS.cls"
Now when you use the web client, the tracing tool intercepts and displays messages between the client and the web service, as shown in the following example:
The top area shows the request sent by the client. The bottom area shows the response sent by the web service.
