Search

SOAP Connector

Version 22.0.8473

SOAP Connector

SOAP Connectors support sending SOAP messages to remote web services and retrieving the response.

Overview

The input to a SOAP connector should be the the full SOAP message that should be sent to the web service. A template for the SOAP message can be generated by importing a WSDL for the target web service, and more information can be found in the SOAP Templates section.

The SOAP connector supports HTTP Authentication and can add digital encryption and signatures to the outgoing SOAP message for Web Service Security. After sending the SOAP request, the connector stores the response or passes it along to the next connector in the CData Arc flow.

Connector Configuration

This section contains all of the configurable connector properties.

Settings Tab

Partner Info

Settings for identifying the target web service.

  • Connector Id The static name of the connector. All connector-specific files are held in a folder by the same name within the Data Directory.
  • Connector Description An optional field to provide free-form description of the connector and its role in the flow.
  • Service Endpoint The URL to which SOAP requests should be sent.
  • SOAP Action The web service action to be triggered on the remote server.
  • Import from WSDL WSDLs can be imported from a URL or from a local file, and automatically populate configuration fields in the connector. Additionally, importing a WSDL allows for generating an XML template for SOAP requests when connected to an XML Map connector. Please see the SOAP Templates section for more details.

WS-Security

Settings related to securing the web service transmissions.

  • Send Message Security Whether to sign and/or encrypt outgoing SOAP requests.
  • Receive Message Security Whether to require that signatures and encryption are present for incoming SOAP responses. An error will be thrown if a received message does not have a required security parameter.
  • Time To Live The length of time the connector will wait for a connection response before throwing a timeout error.

Client Certificate

Settings related to the private local certificates.

  • Private Certificate The private certificate used for signing outgoing requests and decrypting incoming responses.
  • Certificate Password The password for accessing the private certificate.

Server Certificates

Settings related to the server’s public certificates.

  • Encryption Certificate The public certificate used for encryption when sending messages and signature verification when receiving responses.
  • SSL Server Certificate The public certificate used to verify the identity of an SSL/TLS server. Only necessary if sending requests over HTTPS (rather than HTTP). In the absence of a specific server certificate, this setting can be left blank, to allow the underlying OS/JVM to perform certificate validation, or it can be set to ‘Any Certificate’ to unconditionally trust the target server’s identity.

Automation Tab

Automation Settings

Settings related to the automatic processing of files by the connector.

  • Send Whether files arriving at the connector will automatically be sent as SOAP requests.
  • Retry Interval The amount of time before a failed send is retried. A retry is triggered when the server does not respond to a send attempt, or responds negatively to communicate that the file was not received.

Advanced Tab

SSL Client Authentication

Settings related to client authentication when two-way SSL authentication is required.

  • Private Certificate The private certificate presented during SSL client authentication.
  • Certificate Password The password required to access the SSL client certificate.

HTTP Authentication

Settings related to HTTP client authentication.

  • Use HTTP Authentication Whether client HTTP Authentication is enabled.
  • HTTP Authentication Type Whether to provide HTTP authentication credentials in an encrypted format (Digest) or in plain text (Basic). Basic authentication should only be used if the the connection is an HTTPS connection (rather than HTTP).
  • User The User credential for HTTP client authentication.
  • Password The Password credential for HTTP client authentication.

Custom Headers

An arbitrary set of custom headers to be included as part of the outgoing message.

Performance

Settings related to the allocation of resources to the connector.

  • Max Workers The maximum number of worker threads that will be consumed from the threadpool to process files on this connector. If set, overrides the default setting from the Profile tab.
  • Max Files The maximum number of files that will be processed by the connector each time worker threads are assigned to the connector. If set, overrides the default setting from the Profile tab.

Other Settings

Settings not included in the previous categories.

  • Encryption Algorithm The algorithm to use when encrypting outgoing messages.
  • Signature Algorithm The algorithm to use when signing outgoing messages. The same algorithm will be requested for the corresponding MDN receipts.
  • Verification Certificate The public certificate used to verify incoming SOAP responses. This field is only necessary if a different certificate should be used to verify signatures than the public certificate set in Encryption Certificate.
  • Send Filter A glob pattern filter to determine which files in the Send folder will be sent by the connector (e.g. *.txt). Negative patterns may be used to indicate files that should not be processed by the connector (e.g. -*.tmp). Multiple patterns may be separated by commas, with later filters taking priority except when an exact match is found.
  • Local File Scheme A filemask that determines how the connector will name files downloaded and pushed to the Output/Receive Folder. The following macros are supported:

    %ConnectorId%
    %Filename%
    %FilenameNoExt%
    %EXT%
    %ShortDate%
    %LongDate%
    %RegexFilename:%
    %DateFormat:%

    For example: %%FilenameNoExt%_%ShortDate%%EXT%
  • Parent Connector The connector from which settings should be inherited, unless explicitly overwritten within the existing connector configuration. Must be set to a connector of the same type as the current connector. Log Level The verbosity of logs generated by the connector. When requesting support, it is recommended to set this value to Debug.
  • Sign Header Payload Whether to sign the SOAP header in outgoing requests.
  • Normalize Issuer Subject Whether certificate issuer data should be normalized into a simple string for validation by the web service.
  • Log Messages Whether logs from processed files will include a copy of the file itself.
  • Save to Sent Folder Whether files processed by the connector should be copied to the Sent folder for the connector.
  • SSL Enabled Protocols The list of SSL/TLS protocols supported when establishing outgoing connections. It is strongly recommended to only use TLS protocols. Some obsolete operating systems do not support TLS 1.2.

Miscellaneous

Settings for specific use cases.

  • Other Settings Allows configuration of hidden connector settings in a semicolon-separated list, like setting1=value1;setting2=value2. Normal connector use cases and functionality should not require use of these settings.

Establishing a Connection

The Service Endpoint and Service Action for the target web service are required to establish a connection. Some web services may require one or more security features for SOAP requests:

  • Encryption/Signing (WS-Security)
  • Client SSL Authentication
  • HTTP Authentication

SOAP Templates

The SOAP connector can simplify the process of generating SOAP requests through the use of a WSDL file and an XML Map connector that is connected to the SOAP connector in the flow. The WSDL file defines the appropriate XML structure for SOAP requests, and the XML Map connector can transform any arbitrary XML structure into this target structure.

After using the Import WSDL button to import the file, connect an XML Map connector to the SOAP connector (so that files processed by the XML Map connector will then be sent to the SOAP connector). After saving these flow changes, the XML Map connector can dynamically read the WSDL XML and use it as a Destination File template. Then, upload any arbitrary source XML structure as the Source File in the XML Map connector.

After the Source File and Destination File are set in the XML Map connector, the visual designer will be populated with the source and destination structures. Drag-and-drop elements from the source to the destination to map the relationship between the two XML structures. After the mapping is complete, files that match the Source File will be automatically converted into SOAP requests by the XML Map connector.