In order to bring you the best possible user experience, this site uses Javascript. If you are seeing this message, it is likely that the Javascript option in your browser is disabled. For optimal viewing of this site, please ensure that Javascript is enabled for your browser.
Login  |   Cloud ERP  |   Home  |   qad.com



  •     QAD Glossary

  • SOAP Faults
    As previously discussed, any errors detected in the preprocessing of an inbound QDoc are thrown to the sender as SOAP faults. SOAP faults are SOAP response messages that contain a single instance of the Fault element inside the SOAP body, with no other data content.
    The purpose of SOAP faults is to describe a single fatal error to the sender of the original SOAP message using a standard syntax.
    Note: Aside from the commonality mentioned above, considerable differences exist in the way that SOAP faults are handled in SOAP 1.0 and SOAP 1.1. QXtend version 1.4 uses SOAP 1.1 syntax; QXtend version 1.3 and below use SOAP 1.0 syntax. Refer to the appropriate section for the version of QXtend being used.
    SOAP Faults in SOAP 1.1
    The SOAP Fault element defines the following four subelements:
    faultcode (mandatory). The faultcode element is intended to allow software to provide a way to identify the fault. The faultcode value must be a qualified name; see page here for descriptions of faultcode names. SOAP defines the following SOAP fault codes covering basic SOAP faults:
    VersionMismatch. For details see the section SOAP Faults in SOAP 1.0.
    MustUnderstand. For details see the section SOAP Faults in SOAP 1.0.
    Client. Indicates that the message was not well-formed or that it did not contain the appropriate information in order to succeed. This fault code indicates that the message requires modification before being resent.
    Server. Indicates that the message was not processed because of errors—communication problems with servers, for example—not related to the contents of the message itself. The message might succeed if sent later.
    faultstring (mandatory). The faultstring element is intended to provide a human-readable explanation of the nature of the fault.
    faultactor. The faultactor element is intended to identify who caused the fault within the message path. It is similar to the SOAP actor attribute but instead indicates the source of the fault. The value of the faultactor attribute is a URI identifying the source. The faultactor element is not used as it is presumed that the QAD application is always the ultimate receiver of the SOAP message.
    detail (mandatory). The detail element is intended to carry application-specific error information related to the Body element. If the detail element is absent, this indicates that the fault is not related to processing of the Body element. This can be used to distinguish whether the Body element was processed or not in case of a fault situation.
    Immediate child elements of the detail element are called detail entries. Each detail entry is encoded as an independent element within the detail element.
    Other Fault subelements may be present provided they are namespace-qualified.
    This partial example of an outbound QAD Enterprise Applications QDoc response contains a SOAP fault.
     
    <!-- Here is an outbound QDoc response message envelope
    containing a SOAP fault. -->
    <?xml version="1.0" ?>
    <soapenv:Envelope xmlns:soapenv= "http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsa="http://www.w3.org/2005/08/addressing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <soapenv:Header>
    ...
    </soapenv:Header>
    <soapenv:Body>
    <!-- The SOAP fault follows, with no other QDoc content
    allowed -->
    <soapenv:Fault xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:faultcode>Client.qdocVersionNotSupported
    </soapenv:faultcode>
    <soapenv:faultstring>QDoc is not supported</soapenv:faultstring>
    <soapenv:faultactor />
    <soapenv:detail>
    <ns1:dsExceptions xmlns:ns1="urn:schemas-qad-com:xml-services:common">
    <ns2:temp_err_msg xmlns:ns2="urn:schemas-qad-com:xml-services">
    <ns1:tt_msg_nbr>QdocExceptionex005</ns1:tt_msg_nbr>
    <ns1:tt_msg_desc>QDoc is not supported</ns1:tt_msg_desc>
    <ns1:tt_msg_sev>error</ns1:tt_msg_sev>
    <!-- field and context are not relevant to this type of error -->
    <ns1:tt_msg_field />
    <ns1:tt_msg_context />
    <ns1:tt_msg_data>QdocException: Qdoc Receiver is not recognized. The Receiver is not setup in the Qdoc Server instance at com.qad.qxtend.qdocs...
    ...
    </ns1:tt_msg_data>
    <ns1:tt_msg_keys />
    <ns1:tt_msg_keys />
    <ns1:tt_msg_keys />
    <ns1:tt_msg_keys />
    <ns1:tt_msg_keys />
    <ns1:tt_msg_keys />
    <ns1:tt_msg_datetime>2007-05-31T17:54:18+1000</ns1:tt_msg_datetime>
    <ns1:tt_msg_processed>false</ns1:tt_msg_processed>
    <ns1:tt_level />
    <ns1:tt_msg_index>0</ns1:tt_msg_index>
    </ns2:temp_err_msg>
    </ns1:dsExceptions>
    </soapenv:detail>
    </soapenv:Fault>
    </soapenv:Body>
    </soapenv:Envelope>
    SOAP Faults in SOAP 1.0
    The Fault element contains:
    Mandatory Code element
    Mandatory Reason element
    Optional Node, Role, and Detail elements
    The Code element values for common errors, as well as related Subcode element values, are predefined in the SOAP 1.0 specification:
    VersionMismatch: The message envelope does not conform to the SOAP specification.
    MustUnderstand: A Header element was not understood even though the SOAP mustUnderstand attribute was set to true. This is not applicable to QDocs, as the mustUnderstand attribute is not used.
    DataEncodingUnknown: The SOAP encodingStyle attribute has a value other than:
    http://www.w3.org/2002/12/soap-encoding
    Sender: The QDoc was incorrectly formed by the sender in some fashion not covered by the other general error conditions, as further described by the Subcode element.
    Receiver: The QDoc could not be processed by the receiver for reasons other than its syntax or content, as further described by the Subcode element.
    The following Subcode value elements are used with the Sender code to describe errors in the QDoc request syntax:
    QDocNotWellFormed: The QDoc body’s XML content is not well formed and cannot be parsed.
    QDocEnvelopeInvalid: The QDoc’s envelope does not have valid syntax, and the contained QDoc cannot be unwrapped.
    QDocNotRecognized: No QDoc with the given name is supported by the installation.
    QDocSyntaxInvalid: The QDoc is recognized and its XML content is well formed, but it does not have valid syntax with respect to its XML schema. For example, the wrong input parameters are provided.
    QDocReceiverNotRecognized: The receiver attribute of the QDoc message envelope was not recognized; therefore, the QDoc cannot be processed.
    QDocVersionNotSupported: No QDoc is supported by the installation with the given combination of name, version, and receiver attributes.
    The following Subcode value element is used with the Receiver code to describe errors in the QAD application responsible for processing the QDoc request:
    QDocApplicationNotAvailable: The QAD application responsible for processing the QDoc request is not available. For example, the QAD Enterprise Applications database server is not running, or the QDoc server is not able to communicate with Progress clients or AppServers.
    The Detail element of a QDoc SOAP Fault contains one or more exception elements of the type ExceptionType describing the nature of the preprocessing problem. In all such exceptions, the number element is blank, severity is error, and description contains an error message describing the problem. The possible error messages consist of text equivalent to the QDoc-specific Subcode values listed here.
    The SOAP Reason element is set to the value of the description element of exception, essentially the text of the error message that would be displayed to a human user. The SOAP Node and Role elements are not needed or used, as it is presumed that the QAD application is always the ultimate receiver of the SOAP message.
    The following XML schema fragment defines the QAD-specific Subcodes.
    <schema xmlns="http://www.w3.org/2001/XMLSchema"
    xmlns:qcom="http://www.qad.com/qdoc/common"
    targetNamespace="http://www.qad.com/qdoc/common">
    <element name="soapFaultSubcodeValue">
    <simpleType>
    <restriction base="QName">
    <enumeration value="qcom:qdocNotWellFormed"/>
    <enumeration value="qcom:qdocEnvelopeInvalid"/>
    <enumeration value="qcom:qdocNotRecognized"/>
    <enumeration value="qcom:qdocSyntaxInvalid"/>
    <enumeration value="qcom:qdocReceiverNotRecognized"/>
    <enumeration value="qcom:qdocVersionNotSupported"/>
    <enumeration
    value="qcom:qdocApplicationNotAvailable"/>
    </restriction>
    </simpleType>
    </element>
    </schema>
    This partial example of an outbound QAD Enterprise Applications QDoc response contains a SOAP fault.
    <!-- Here is an outbound QDoc response message envelope
    containing a SOAP fault. -->
    <?xml version="1.0" encoding="UTF-8"?>
    <env:Envelope
    xmlns:env="http://www.w3.org/2002/12/soap-envelope"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <env:Header>
    ...
    </env:Header>
    <env:Body>
    <!-- The SOAP fault follows, with no other QDoc content
    allowed -->
    <env:Fault>
    <env:Code>
    <env:Value>env:Sender</env:Value>
    <env:Subcode>
    <!-- Subcode value is QAD-defined -->
    <env:Value
    xmlns:qcom="http://www.qad.com/qdoc/common">
    QDocNotWellFormed
    </env:Value>
    </env:Subcode>
    </env:Code>
    <!-- Reason is taken from the QDoc exception description
    -->
    <env:Reason xml:lang="en-US">
    QDoc is not well formed
    </env:Reason>
    <env:Detail>
    <!-- Here is the QDoc exception element -->
    <qcom:exception
    xmlns:qcom="http://www.qad.com/qdoc/common">
    <qcom:number></qcom:number>
    <qcom:description>
    QDoc is not well formed
    </qcom:description>
    <qcom:severity>error</qcom:severity>
    <!-- field and context are not relevant to this
    type of error -->
    <qcom:field/>
    <qcom:context/>
    </qcom:exception>
    </env:Detail>
    ...
    </env:Fault>
    </env:Body>
    </env:Envelope>