cannectors
ModulesFilters

soap_call

Per-record SOAP enrichment with caching and merge strategies.

The soap_call filter sends a SOAP request for each record and merges the parsed SOAP response back into that record. It supports the same cache and merge strategy model as http_call, plus SOAP-specific XML body templating, WS-Security, and MTOM.

Minimal example

filters:
  - type: soap_call
    endpoint: https://soap.example.com/customers
    soapAction: urn:GetCustomer
    operation: GetCustomer
    body: |
      <m:GetCustomer xmlns:m="urn:customers">
        <m:CustomerId>{{record.customerId}}</m:CustomerId>
      </m:GetCustomer>
    dataField: Envelope.Body.GetCustomerResponse.Customer
    mergeStrategy: append
    resultKey: customer

Options

propertytypedefaultdescription
typerequired
"soap_call"—Module type discriminator. Must be `soap_call` for this module.
id
string—Unique identifier within the pipeline.
name
string—Human-readable name.
description
string——
enabled
booleantrueWhether module is active.
tags
array<string>——
onError
string"fail"Default error action. Case-insensitive; normalized to lowercase by the runtime.
endpointrequired
string—SOAP endpoint URL. Templates are accepted; the final URL is validated at runtime after template resolution.
soapVersion
string"1.1"SOAP envelope and HTTP binding version.
1.11.2
soapAction
string—SOAP action. SOAP 1.1 sends this as the SOAPAction header; SOAP 1.2 sends it as a Content-Type action parameter.
operationrequired
string—Logical SOAP operation name.
bodyrequired
string—Raw XML body fragment. Templates ({{record.field}}) are XML-escaped at runtime.
headers
array<object>—Raw SOAP header XML fragments.
authentication
union (4 variants)—HTTP transport authentication.
wsSecurity
object——
mtom
object——
httpHeaders
map<string, string>—Additional HTTP headers. Content-Type and SOAPAction are controlled by the SOAP version.
timeoutMs
integer—Request timeout in milliseconds. When omitted, each module applies its own runtime default.
keys
array<object>—List of key configurations for extracting values from records and using them in request metadata.
cache
object——
mergeStrategy
string"merge"How to merge SOAP response with input records.
mergereplaceappend
resultKey
string—Key for storing the SOAP response when append mode is used.
dataField
string—Field path to extract from the parsed SOAP response map before merge/replace/append. When omitted, the full parsed SOAP response is used.
retry
object——

Merge strategies

StrategyEffect
merge (default)Deep-merge response fields into the current record. Nested objects are merged; response values overwrite conflicts.
replaceOverlay SOAP response fields onto the current record. Existing fields not present in the response are preserved.
appendStore the SOAP response under resultKey.

append requires resultKey so the filter has a stable destination for the SOAP result.

Caching

Use the cache block to deduplicate SOAP enrichment calls that would resolve to the same result:

cache:
  enabled: true
  maxSize: 1000
  ttlSeconds: 300
  key: "{{record.customerId}}"

If cache.key is omitted, the resolved endpoint and operation shape are used as the cache identity. Set an explicit per-record key when the SOAP body varies by record.

Error handling

onError uses the same strategies as other filters:

ValueEffect
failStop the pipeline on the first SOAP error.
skipDrop the failing record.
logLog the SOAP error and keep the original record.

SOAP faults are surfaced as SOAP errors, so downstream logs include the fault code and reason when the server returns one.

Examples

examples/42-soap-call-enrichment.yamlview source ↗
42-soap-call-enrichment.yaml
name: soap-call-enrichment
version: 1.0.0
description: Poll orders every five minutes, enrich each record with a SOAP lookup, cache responses, and append the SOAP result under a result key.
tags:
  - soap
  - enrichment
input:
  type: httpPolling
  schedule: "*/5 * * * *"
  endpoint: https://source.example.com/api/orders
  dataField: orders
filters:
  - type: soap_call
    endpoint: https://soap.example.com/customers
    soapAction: urn:GetCustomer
    operation: GetCustomer
    body: |
      <m:GetCustomer xmlns:m="urn:customers">
        <m:CustomerId>{{record.customerId}}</m:CustomerId>
      </m:GetCustomer>
    dataField: Envelope.Body.GetCustomerResponse.Customer
    mergeStrategy: append
    resultKey: customer
    cache:
      enabled: true
      maxSize: 1000
      ttlSeconds: 300
      key: "{{record.customerId}}"
output:
  type: httpRequest
  endpoint: https://destination.example.com/api/orders/enriched
  method: POST
  requestMode: batch
  headers:
    Content-Type: application/json

Cross-references

SOAP guide

Raw XML body templates, response paths, MTOM, WS-Security.

http_call filter

The HTTP-shaped counterpart.

Retry & error handling

Retries, onError, and transient failures.

retry

retry configuration for the http_call module.

headers

Raw SOAP header XML fragments.

On this page

Minimal exampleOptionsMerge strategiesCachingError handlingExamplesCross-references