soapRequest

Processor that acts as a producer of messages to a SOAP endpoint. Reference to a WSDL specification must be provided.

Properties

Name Summary

Name	Summary
`wsdlSpecId`	Required ID of the WSDL specification following the pattern `<type>:<resourceId>:<revision>`. Set `<revision>` to `latest` to retrieve the latest one. For example: `WSDLv1:my-wsdl:latest`.
`serviceName`	Name of the service from the WSDL specification to use. Must be present unless the WSDL spec has only one service. In such a case, the single service is used as the default.
`portName`	Name of the service port from the WSDL specification to use. Must be present unless the chosen service has only one port. In such a case, the single port is used as the default.
`address`	URL of the backend service to call.
`operation`	Operation name to invoke. Optional.
`soapAction`	SOAP action to use in the call.
`responseNamespacePrefixMapping`	Optional mapping of prefixes to namespaces in the XML response body. The provided prefix mappings are used in the JSON compliant format the response payload is converted to. The special `_default` prefix can be assigned to a single namespace, which is then used as the default namespace for the document and not assigned a prefix. Defining the prefix mappings here is highly recommended if you are doing any processing of the JSON compliant payload, since it is the only way you can mandate the prefixes yourself. Namespaces not defined here will have automatic prefixes in the form `ns1`, `ns2`, etc. generated for them. This property is a string on the standard Java Properties format. Each line contains a prefix specification on the format `<prefix> = <namespace>`. Note that namespaces can only be assigned to a single prefix. Duplicated namespaces are not allowed.
`authenticationConfigKey`	Secrets key used to look up credentials to append to the request (e.g., as an authorization header). Also supports a comma separated list of Secrets keys, if multiple authentication methods are required on the same request. Optional.
`connectionTimeoutMillis`	Connection timeout value.
`receiveTimeoutMillis`	Socket timeout value.
`sslAuthenticationConfigKey`	Optional key from the server configuration used to look up SSL credentials for server and client authentication.
`wsSecurityPolicyConfigKey`	Optional key from the server configuration used to look up WS-Security details for complying with required WS-Security policy. This key can be a comma separated list to allow for the declaration of multiple policies, such as Message Signing or Encryption, Username Token, etc.
`gzipOfRequest`	Optional `GzipStrategy` to specify how to compress the outbound request. No compression is used if the property is not set. Otherwise, only the following values apply: `negotiate`: GZIP with negotiation `enforce`: Force GZIP without negotiation
`gzipCompressionThreshold`	GZIP compression threshold in bytes. Messages smaller than this threshold will not be compressed. The field will be ignored unless `gzipOfRequest` is also used.
`soapResponseProxyingStrategy`	Optional `SoapResponseProxyingStrategy` to change the response processing. By default, the SOAP response payload is parsed into a JSON compliant object and used as the result of this processor. If the request results in a SOAP fault, a message processing failure is raised. In some rare cases, it is desirable to return the full SOAP envelope as the processing result instead (e.g., to deliver it as the response of an upstream `soapApi` request when implementing "SOAP proxy" style flows). The `SoapResponseProxyingStrategy` can be used to achieve such a scenario and supports the following values: `verbatim`: The processing result is the full serialized SOAP envelope as returned by the downstream server. This is also true if the response is a SOAP fault.
`name`	Optional, descriptive name for the processor.
`id`	Required identifier of the processor, unique across all processors within the flow. Must be between 3 and 30 characters long; contain only lower and uppercase alphabetical characters (a-z and A-Z), numbers, dashes ("-"), and underscores ("_"); and start with an alphabetical character. In other words, it adheres to the regex pattern `[a-zA-Z][a-zA-Z0-9_-]{2,29}`.
`exchangeProperties`	Optional set of custom properties in a simple jdk-format, that are added to the message exchange properties before processing the incoming payload. Any existing properties with the same name will be replaced by properties defined here.
`retainPayloadOnFailure`	Whether the incoming payload is available for error processing on failure. Defaults to `false`.

wsdlSpecId

Required ID of the WSDL specification following the pattern <type>:<resourceId>:<revision>. Set <revision> to latest to retrieve the latest one. For example: WSDLv1:my-wsdl:latest.

serviceName

Name of the service from the WSDL specification to use. Must be present unless the WSDL spec has only one service. In such a case, the single service is used as the default.

portName

Name of the service port from the WSDL specification to use. Must be present unless the chosen service has only one port. In such a case, the single port is used as the default.

address

URL of the backend service to call.

operation

Operation name to invoke. Optional.

soapAction

SOAP action to use in the call.

responseNamespacePrefixMapping

Optional mapping of prefixes to namespaces in the XML response body. The provided prefix mappings are used in the JSON compliant format the response payload is converted to. The special _default prefix can be assigned to a single namespace, which is then used as the default namespace for the document and not assigned a prefix.

Defining the prefix mappings here is highly recommended if you are doing any processing of the JSON compliant payload, since it is the only way you can mandate the prefixes yourself. Namespaces not defined here will have automatic prefixes in the form ns1, ns2, etc. generated for them.

This property is a string on the standard Java Properties format. Each line contains a prefix specification on the format <prefix> = <namespace>. Note that namespaces can only be assigned to a single prefix. Duplicated namespaces are not allowed.

authenticationConfigKey

Secrets key used to look up credentials to append to the request (e.g., as an authorization header). Also supports a comma separated list of Secrets keys, if multiple authentication methods are required on the same request. Optional.

connectionTimeoutMillis

Connection timeout value.

receiveTimeoutMillis

Socket timeout value.

sslAuthenticationConfigKey

Optional key from the server configuration used to look up SSL credentials for server and client authentication.

wsSecurityPolicyConfigKey

Optional key from the server configuration used to look up WS-Security details for complying with required WS-Security policy. This key can be a comma separated list to allow for the declaration of multiple policies, such as Message Signing or Encryption, Username Token, etc.

gzipOfRequest

Optional GzipStrategy to specify how to compress the outbound request. No compression is used if the property is not set. Otherwise, only the following values apply:

negotiate: GZIP with negotiation
enforce: Force GZIP without negotiation

gzipCompressionThreshold

GZIP compression threshold in bytes. Messages smaller than this threshold will not be compressed. The field will be ignored unless gzipOfRequest is also used.

soapResponseProxyingStrategy

Optional SoapResponseProxyingStrategy to change the response processing.

By default, the SOAP response payload is parsed into a JSON compliant object and used as the result of this processor. If the request results in a SOAP fault, a message processing failure is raised. In some rare cases, it is desirable to return the full SOAP envelope as the processing result instead (e.g., to deliver it as the response of an upstream soapApi request when implementing "SOAP proxy" style flows).

The SoapResponseProxyingStrategy can be used to achieve such a scenario and supports the following values:

verbatim: The processing result is the full serialized SOAP envelope as returned by the downstream server. This is also true if the response is a SOAP fault.

name

Optional, descriptive name for the processor.

id

Required identifier of the processor, unique across all processors within the flow. Must be between 3 and 30 characters long; contain only lower and uppercase alphabetical characters (a-z and A-Z), numbers, dashes ("-"), and underscores ("_"); and start with an alphabetical character. In other words, it adheres to the regex pattern [a-zA-Z][a-zA-Z0-9_-]{2,29}.

exchangeProperties

Optional set of custom properties in a simple jdk-format, that are added to the message exchange properties before processing the incoming payload. Any existing properties with the same name will be replaced by properties defined here.

retainPayloadOnFailure

Whether the incoming payload is available for error processing on failure. Defaults to false.

Sub-builders

Name	Summary
processingStrategy	Strategy for providing message processing hints to the server. Optional.
externalSystemDetails	Strategy for describing the external system integration. Optional.
circuitBreakerStrategy	Strategy for configuring the processor’s circuit breaker. Optional.
messageLoggingStrategy	Strategy for describing how a processor’s message is logged on the server.
payloadArchivingStrategy	Strategy for archiving payloads.
inboundTransformationStrategy	Strategy that customizes the conversion of an incoming payload by a processor (e.g., string to object). Should be used when the processor’s default conversion logic cannot be used.

Name

Summary

processingStrategy

Strategy for providing message processing hints to the server. Optional.

externalSystemDetails

Strategy for describing the external system integration. Optional.

circuitBreakerStrategy

Strategy for configuring the processor’s circuit breaker. Optional.

messageLoggingStrategy

Strategy for describing how a processor’s message is logged on the server.

payloadArchivingStrategy

Strategy for archiving payloads.

inboundTransformationStrategy

Strategy that customizes the conversion of an incoming payload by a processor (e.g., string to object). Should be used when the processor’s default conversion logic cannot be used.

Details

Payloads

The payload received by the soapRequest processor must be an XML compliant JSON object or a payload that can be deserialized to an XML compliant JSON object. See the Payload Types documentation for examples.

If the incoming payload is not of the required type (e.g., a string), the processor tries to convert it to an object. When conversion requires a characterSet config, these character encoding constants are supported. By default, the payload is unmarshalled using XML format.

If the SOAP operation that was called has a request-response style, the response received by the processor is sent downstream as an XML compliant JSON object. The format of the inputted object will vary based on the SOAP operation’s schema.

WSDL Documents

The soapRequest processor is configured with a WSDL document.

WSDL documents must satisfy the following criteria:

Version 1.1 (version 2.0 is not supported)
Uses SOAP as web service protocol
Uses only a one-way or request-response operation type
Uses Document style messages (not RPC)
- Each <message> element has exactly one <part> element
Has unique operation names and operation input types (inside each <portType> element)
No imports of other documents (like external XSDs)

Use the SDK’s merge tool to consolidate imported documents.

The processor will throw a ValidationException if one of the following occurs:

Parsing of WSDL document fails (malformed document, wrong version, contains imports, etc.)
Document doesn’t contain required parts (<message>, <portType>, <binding>, etc.)
WSDL doesn’t specify SOAP-related data

Authentication

The authenticationConfigKey property supports secrets of the following types:

See the Secret Types documentation for formatting details of each type.

WS-Security policy

The processor supports WS-Security policy, that is defined in the service WSDL and / or through policy configuration using the wsSecurityPolicyConfigKey property.

The wsSecurityPolicyConfigKey property is a comma separated list of secret keys.

The following features of the WS-Security specifications are supported.

WS-Security SOAP Message Security

When a WSDL with security policy is used, a client key store and server trust store must be provided using a Tls secret. All requests that do not comply with the defined policy will fail.

When specified, the following elements will be added to the outgoing SOAP Security element as described in WS-Security SOAP Message Security:

Timestamp
BinarySecurityToken
Signature

Signatures can also be added for WSDLs that do not provide a security policy. This is achieved by providing a WssSignature secret instead of the Tls secret. This secret type is a superset of the Tls secret type and allows for configuring the security policy in the secret instead of in the WSDL.

WS-Security Username Token Profile

This is enabled through the use of a WssUserNameToken secret. When specified, a UsernameToken element will be added to the outgoing SOAP Security element as described in WS-Security Username Token Profile.

TLS (SSL) Configuration

Requests can be sent to third-party web services using HTTPS protocol.

If the target service is using a valid SSL certificate, signed by a trusted CA, there is no need for additional configuration. However, configuration must be provided if you require one of the following features:

Providing a client certificate (if requested by the server).
Providing a truststore for server certificate validation. This is useful, for example, when the root certificate has not been signed by a trusted CA.
Limiting the server certificate to a specified public key.
Accepting a self-signed server certificate.
Accepting a server certificate issued for a host other than the one being requested.

To enable these features, the sslAuthenticationConfigKey property must be set and point to a secret of type Tls. See the Secret Types documentation for formatting details.

Was this page helpful?