SOAP Faults in Web Services Call-In

Uniface-Generated SOAP Faults

Uniface generates a SOAP fault in the following cases:

• The Uniface Server could not create an instance of one of the components specified by the $SOAP_CALLIN_CB assignment setting
• The Uniface Server could not create an instance of the requested web service component.
• The requested operation on the web service component does not exist
• An error occurred while parsing the SOAP envelope after the SOAP_CALLIN_PRE operations successfully finished
• One of the callback operations returned a negative value

By default, all SOAP faults that are generated by Uniface (as opposed to a callback operation) set the <faultcode>, <faultstring>, and <faultactor> fields in the SOAP fault.

However, you can change this behavior so that all error information is put into the <faultstring> field by setting the assignment setting $SOAP_CALLIN_FAULT to limited. This may be required if you have existing web services used by third-party clients, because it was the default behavior prior to Uniface 9.5.

If Uniface generates a SOAP fault during SOAP call-in, or a call-in callback function returns -1, the SOAP fault is returned in an HTTP status 500 message.

Callback Operation SOAP Faults

In the call-in callback operations, you can generate a SOAP fault by returning a negative value (-1) and setting the value of the Envelopeinout parameter to the error message. The value of Envelope is put into the <faultstring> field of the SOAP fault, and default values are put in the <faultcode> and <faultactor> fields.

If you want to provide more detail about the error, set the Envelope parameter to an associative list containing the keywords.

If you do not specify one or more of keywords, Uniface provides default values, making it very easy to generate meaningful SOAP faults.

SOAP Error Information for SOAP Callback Operations

Keyword	SOAP Fault Field	Meaning	Default, if not specified
CODE	<faultcode>	Error code	Server
MESSAGE	<faultstring>	Error message. Complete returned envelope string, if none of these items are found and the envelope does contain a returned string.	An error was detected by a callback operation
ACTOR	<faultactor>	URI that identifies the exact callback operation that detected the error.	"urn:uniface:applic:callback:CallbackComponentName.Operation"
DETAIL	<detail>	String giving more details about the error; this can be a simple string or an XML-encoded string with a complex structure.	""

If you specify your own value for the ACTOR keyword, the information about where the error occurred is lost. To ensure that this information is still available, you can use ProcScript functions such as $componentname, or you can provide it in the DETAIL. For example:

"...·;ACTOR=urn:myownapp:myownpath:%%$componentname:callin_pre·;..."

The detail item will be inserted into the SOAP fault <detail> element exactly as provided. However, Uniface removes the <detail> start tag and anything before it, and the end tag and anything after it . If you provide an XML-formatted string, make sure it is completely self-contained and that namespaces are resolved.

operation soap_callin_pre
 params
  string envelope: inout
  string servvars: in
 endparams
 ; code that detects an error ...
 envelope = "Something bad happened"
 return -1
end;

operation soap_callin_pre
 params
  string envelope: inout
  string servvars: in
 endparams
 variables
  string vDetail
 endvariables
 ; code that detects an error ...
 vDetail = "%%^%\
 <detail>%%^%\
  <cause nr=1>The moon is full</cause>%%^%\
  <cause nr=2>The tide is high</cause>%%^%\
 </detail>"
 envelope = "CODE=MustUnderstand;MESSAGE=I don’t understand this magic formula!;
   ACTOR=http:/wicked/witch/of/the/west;DETAIL=%%vDetail"
 return -1
end;