cannectors
ModulesOutputs

soapRequest

Send records to a SOAP endpoint in batch or single mode.

soapRequest is the SOAP output module. It builds a SOAP envelope from a raw XML body fragment and sends either one request for the whole batch or one request per record. It supports SOAP 1.1, SOAP 1.2, HTTP transport authentication, WS-Security UsernameToken, MTOM, retries, and success conditions.

Minimal example

output:
  type: soapRequest
  endpoint: https://soap.example.com/orders
  soapAction: urn:SubmitOrder
  operation: SubmitOrder
  requestMode: single
  body: |
    <m:SubmitOrder xmlns:m="urn:orders">
      <m:OrderId>{{ record.orderId }}</m:OrderId>
    </m:SubmitOrder>

Options

propertytypedefaultdescription
typerequired
"soapRequest"—Module type discriminator. Must be `soapRequest` 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.
success
object——
retry
object——
requestMode
string"batch"Request mode: 'batch' (all records in one request, default) or 'single' (one request per record).
batchsingle
batchSize
integer—Maximum number of records per request when requestMode is 'batch'. Records are split into consecutive batches, one request each; the body template sees record.records / record.recordCount for the current batch only. When omitted, all records are sent in a single request. Invalid with requestMode 'single'.

Request mode

requestMode: batch       # one SOAP request for the whole batch
requestMode: single      # one SOAP request per record

Use single when the SOAP operation accepts one business object at a time or when the body references scalar fields from each record. Use batch when the operation accepts an array or wrapper object.

In batch mode the body template sees the batch, not a single record:

  • record.records — the list of records in the batch
  • record.recordCount — how many records the batch holds
requestMode: batch
body: |
  <m:SubmitOrders xmlns:m="urn:orders">
  {%- for row in record.records %}
    <m:Order><m:Id>{{ row.orderId }}</m:Id></m:Order>
  {%- endfor %}
  </m:SubmitOrders>

Batch size

By default requestMode: batch sends every record in a single request. Set batchSize to cap how many records each request carries — useful when the service limits payload size or the number of business objects per call.

requestMode: batch
batchSize: 50        # 120 records -> 3 requests of 50, 50, 20

Records are split into consecutive batches in order, and one request is sent per batch. batchSize is only valid with requestMode: batch — combining it with single is rejected when the pipeline starts.

record.recordCount is the size of the current batch, not the total number of records the pipeline produced. A body that reports a total will report the batch count instead once batchSize is set.

Three consequences worth planning for:

  • No atomicity. Without batchSize the send is all-or-nothing. With it, a failure on the third batch leaves the first two already applied on the remote side. Cannectors does not compensate them.
  • onError applies per batch. fail stops at the failing batch and reports how many records were sent before it; skip and log carry on with the remaining batches and exclude the failed one from the sent count.
  • Retries replay a whole batch. The retry policy applies per request, so a batch that timed out but was actually applied may be sent again. Idempotency is the destination's responsibility — key it on a business identifier.

--dry-run previews one request per batch, so the preview count matches what a real run would send.

MTOM output

Outgoing MTOM requires both an XOP include in the XML and a matching attachment declaration:

body: |
  <m:UploadDocument xmlns:m="urn:documents">
    <m:File>
      <xop:Include xmlns:xop="http://www.w3.org/2004/08/xop/include" href="cid:{{ record.documentId }}"/>
    </m:File>
  </m:UploadDocument>
mtom:
  enabled: true
  attachments:
    - contentId: "{{ record.documentId }}"
      contentType: application/pdf
      sourceField: documentBase64
      encoding: base64

Use encoding: base64 for JSON-originated binary payloads encoded as strings.

WS-Security

wsSecurity:
  username: soap-user
  password: ${SOAP_PASSWORD}
  passwordType: PasswordDigest
  mustUnderstand: true

Only UsernameToken PasswordText and PasswordDigest are supported. Use the standard authentication block separately when the HTTP transport itself needs Basic, bearer, API key, or OAuth2 authentication.

Success conditions

By default, successful SOAP requests are 2xx responses with no SOAP fault. Add a success block when a destination distinguishes multiple successful 2xx statuses or requires a response-body expression.

success:
  statusCodes: [200, 202]

Non-2xx responses with no SOAP fault are treated as HTTP errors.

Examples

examples/43-soap-output-batch.yamlview source ↗
43-soap-output-batch.yaml
name: soap-output-batch
version: 1.0.0
description: Send records to a SOAP operation in batch mode.
tags:
  - soap
  - soap-output
input:
  type: webhook
  path: /webhooks/orders
filters: []
output:
  type: soapRequest
  endpoint: https://soap.example.com/import
  soapAction: urn:ImportOrders
  operation: ImportOrders
  requestMode: batch
  body: |
    <m:ImportOrders xmlns:m="urn:orders">
      <m:RecordCount>{{record.recordCount}}</m:RecordCount>
      <m:FirstOrderId>{{record.records[0].orderId | default('')}}</m:FirstOrderId>
    </m:ImportOrders>
  success:
    statusCodes:
      - 200
      - 202
examples/44-soap-output-mtom-emission.yamlview source ↗
44-soap-output-mtom-emission.yaml
name: soap-output-mtom-emission
version: 1.0.0
description: Send a SOAP request with a base64 record field decoded into an outgoing MTOM attachment.
tags:
  - soap
  - mtom
input:
  type: webhook
  path: /webhooks/documents
filters: []
output:
  type: soapRequest
  endpoint: https://soap.example.com/documents/upload
  soapAction: urn:UploadDocument
  operation: UploadDocument
  requestMode: single
  body: |
    <m:UploadDocument xmlns:m="urn:documents">
      <m:DocumentId>{{record.documentId}}</m:DocumentId>
      <m:File>
        <xop:Include xmlns:xop="http://www.w3.org/2004/08/xop/include" href="cid:{{record.documentId}}"/>
      </m:File>
    </m:UploadDocument>
  mtom:
    enabled: true
    attachments:
      - contentId: "{{record.documentId}}"
        contentType: application/pdf
        sourceField: documentBase64
        encoding: base64
examples/45-soap-output-wssecurity-passwordtext.yamlview source ↗
45-soap-output-wssecurity-passwordtext.yaml
name: soap-output-wssecurity-passwordtext
version: 1.0.0
description: Send a SOAP request using WS-Security UsernameToken PasswordText.
tags:
  - soap
  - ws-security
input:
  type: webhook
  path: /webhooks/orders
filters: []
output:
  type: soapRequest
  endpoint: https://soap.example.com/secure/orders
  soapAction: urn:SubmitOrder
  operation: SubmitOrder
  requestMode: single
  body: |
    <m:SubmitOrder xmlns:m="urn:orders">
      <m:OrderId>{{record.orderId}}</m:OrderId>
    </m:SubmitOrder>
  wsSecurity:
    username: soap-user
    password: ${SOAP_PASSWORD}
    passwordType: PasswordText
    mustUnderstand: true
examples/45b-soap-output-wssecurity-passworddigest.yamlview source ↗
45b-soap-output-wssecurity-passworddigest.yaml
name: soap-output-wssecurity-passworddigest
version: 1.0.0
description: Send a SOAP request using WS-Security UsernameToken PasswordDigest.
tags:
  - soap
  - ws-security
input:
  type: webhook
  path: /webhooks/orders
filters: []
output:
  type: soapRequest
  endpoint: https://soap.example.com/secure/orders
  soapAction: urn:SubmitOrder
  operation: SubmitOrder
  requestMode: single
  body: |
    <m:SubmitOrder xmlns:m="urn:orders">
      <m:OrderId>{{record.orderId}}</m:OrderId>
    </m:SubmitOrder>
  wsSecurity:
    username: soap-user
    password: ${SOAP_PASSWORD}
    passwordType: PasswordDigest
    mustUnderstand: true

Cross-references

SOAP guide

Versions, templating, MTOM, WS-Security, response parsing.

httpRequest output

The HTTP-shaped counterpart.

Authentication

HTTP transport authentication schemes.

keys

List of key configurations for extracting values from records and using them in path, query, or headers.

headers

Raw SOAP header XML fragments.

On this page

Minimal exampleOptionsRequest modeBatch sizeMTOM outputWS-SecuritySuccess conditionsExamplesCross-references