7.4 Consumed SOAP Web Services & Error Handling

7.4 Consumed SOAP Web Services & Error Handling

Scope note: SOAP is not named in the eight published Intermediate exam sections (Agile, Security, Microflows, Pages, Domain Model, Modules, Translation, XPath). What is scored here is the microflow half of the topic — choosing the right error handling mode, inspecting $latestError, and reasoning about integration failure — so read this section for that, and treat the WSDL and SOAP Fault detail as delivery knowledge you will need on legacy-integration projects rather than as guaranteed exam questions.

Integrations are the most common source of runtime application failures. Networks fluctuate, external services crash, credentials expire, and payloads fail validation. Designing enterprise-grade Mendix applications requires mastering both XML-based SOAP integration and robust, fault-tolerant error-handling patterns across all network communication.

---

Consuming SOAP Web Services in Mendix

SOAP (Simple Object Access Protocol) is an XML-based protocol characterized by formal interface contracts defined via WSDL (Web Services Description Language).

1. The Consumed Web Service Document

To consume a SOAP service in Studio Pro:

1. Create a Consumed web service document (Add Other > Consumed web service).
2. Import the WSDL contract by specifying a live URL (e.g., https://services.enterprise.com/billing?wsdl) or uploading a local .wsdl file along with any referenced .xsd schema files.
3. Studio Pro parses the WSDL and displays all available Port types, Operations, request structures, and response structures.

2. The 'Call Web Service' Activity

To invoke a SOAP operation in a microflow, developers use the Call web service activity:

CALL WEB SERVICE CONFIGURATION
├── 1. Operation Selection (Selects Consumed Web Service & specific Operation)
├── 2. SOAP Request Header (WS-Security credentials, authentication tokens)
├── 3. SOAP Request Body (Export mapping or simple parameter serializing domain data)
└── 4. SOAP Response (Import mapping to deserialize XML response into entities/NPEs)

• SOAP Header: Many enterprise SOAP services require WS-Security (UsernameToken profile with timestamp and password digest) or custom XML headers passed in the <soapenv:Header> block.
• SOAP Body: The business payload encapsulated in <soapenv:Body>. Studio Pro uses an Export Mapping to serialize Mendix entities into the operation's target XML schema.
• Response Handling: The XML response inside the body is deserialized via an Import Mapping into Mendix entities or NPEs.

---

Understanding SOAP Faults

Unlike REST services that utilize a wide variety of HTTP status codes, SOAP web services typically transmit all functional errors inside a standardized XML envelope called a SOAP Fault, usually returned alongside an HTTP 500 Internal Server Error status:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Body>
    <soapenv:Fault>
      <faultcode>soapenv:Client</faultcode>
      <faultstring>Invalid Account Number: ACCT-99214</faultstring>
      <faultactor>https://services.enterprise.com/billing</faultactor>
      <detail>
        <errorCode>ERR_INVALID_ACCOUNT</errorCode>
        <errorDescription>The specified account is closed or does not exist.</errorDescription>
      </detail>
    </soapenv:Fault>
  </soapenv:Body>
</soapenv:Envelope>

Core Elements of a SOAP Fault:

• <faultcode>: Identifies the broad error class (e.g., Client if the caller provided invalid data, or Server if downstream processing failed).
• <faultstring>: A human-readable explanation of the error.
• <faultactor>: Identifies who caused the fault in a multi-hop transmission.
• <detail>: Contains application-specific XML data providing granular error details.

When a Mendix Call web service activity receives an HTTP 500 containing a SOAP Fault, the Mendix Runtime intercepts the fault, triggers the activity's error handler, and injects the fault details into the $latestError microflow variable.

Microflow Error Handling Modes: Rollback vs. Without Rollback

In Mendix Studio Pro, right-clicking an integration activity (such as Call REST service or Call web service) allows developers to configure Set error handling. The four available options operate with distinct transactional rules:

Exam Trap: If you select Custom with rollback and attempt to create and commit an IntegrationAuditLog entity inside the error handling branch, that log record will be completely wiped out when the transaction finishes rolling back! Always use Custom without rollback when persisting failure diagnostics or error audit records to the database.

---

Inspecting $latestError and $latestHttpResponse

When execution enters a custom error branch, the Mendix Runtime makes special contextual inspection variables available:

Every microflow carries two predefined error objects: $latestError (a System.Error object) and $latestSoapFault (a System.SoapFault object, which is a specialization of System.Error). After a REST call there is a third, $latestHttpResponse. None of the three should ever be returned as the result of a microflow to a nanoflow, page, or widget — Mendix warns that doing so produces unexpected behaviour.

1. The $latestError System Variable

Available in all custom error handlers:

• $latestError/ErrorType: The Java exception class or fault type (e.g., com.mendix.core.CoreException or javax.xml.ws.soap.SOAPFaultException).
• $latestError/Message: The high-level error summary or SOAP faultstring.
• $latestError/Stacktrace: The detailed execution stack trace.

Entity-access caveat: In microflows that apply entity access, you may not be able to read the attributes of error objects at all, for security reasons. The documented workaround is to pass the error object into a sub-microflow that does not apply entity access and inspect it there.

2. The $latestSoapFault Variable

Set specifically when the failure was a SOAP fault, and empty otherwise — which is exactly how you test whether an error came from a web service: check $latestSoapFault for empty. It is a System.SoapFault object with five string attributes mapping onto the SOAP fault elements:

Because System.SoapFault specializes System.Error, a SOAP failure gives you both the generic Java-exception view through $latestError and the structured fault view through $latestSoapFault.

3. The $latestHttpResponse Variable

Specifically available after a Call REST service activity encounters an error:

• $latestHttpResponse/StatusCode: The numeric HTTP response code (e.g., 404, 500, 503).
• $latestHttpResponse/ReasonPhrase: The HTTP status description (e.g., 'Not Found', 'Service Unavailable').
• $latestHttpResponse/Content: The raw string payload returned by the remote server (often containing a JSON error response like {"code": "ITEM_OUT_OF_STOCK"}).
• $latestHttpResponse/Headers: Association to a list of System.HttpHeader objects, allowing inspection of headers such as Retry-After.

---

HTTP Status Codes Taxonomy & Response Strategies

Designing resilient integrations requires handling HTTP response codes semantically according to standard IETF specifications:

---

Resiliency Patterns: Exponential Backoff & Circuit Breakers

When external services experience transient instability, naive integrations can cause catastrophic cascades across your application.

1. Exponential Backoff with Jitter

When retrying transient errors (HTTP 503, 429, socket timeouts):

• Exponential Growth: Instead of retrying immediately (which hammers an already struggling server), increase the delay exponentially: $2^n$ seconds (e.g., 2s, 4s, 8s, 16s).
• Jitter (Randomness): Add a randomized variance of roughly ±20% to the delay. This prevents the "thundering herd" problem where hundreds of waiting Mendix threads wake up at the exact same millisecond and crash the external service again.

2. The Circuit Breaker Pattern

A Circuit Breaker monitors external service health using a finite state machine:

[ CLOSED (Normal) ] ──(Failure Threshold Exceeded)──► [ OPEN (Tripped) ]
         ▲                                                      │
         │                                                (Sleep Window Expires)
         │                                                      ▼
  (Success Count Met) ◄── [ HALF-OPEN (Canary Test) ] ──────────┘

• Closed (Normal Operation): Requests pass through to the external service. If calls fail repeatedly, reaching a failure threshold (e.g., 5 consecutive failures), the breaker trips to Open.
• Open (Failing Fast): The Mendix application stops attempting external network calls entirely. Requests immediately fail fast or return fallback cached data, saving network threads and preventing UI delays.
• Half-Open (Canary Testing): After a cooldown period (e.g., 60 seconds), the breaker allows a single "canary" request through. If it succeeds, the breaker resets to Closed; if it fails, the breaker returns to Open.

3. Asynchronous Integration via Task Queues

For non-interactive integrations (such as transmitting invoices to an external tax authority or syncing warehouse inventory), never block user-facing microflows with synchronous REST or SOAP calls. Instead, commit an integration work entity and submit a microflow to a Task Queue. The Mendix background worker processes the request asynchronously, automatically handling retries and failure logging without impacting user interface responsiveness.