Integration Server 10.5 | Built-In Services Reference Guide | Client Folder | Summary of Elements in this Folder | pub.client:soapClient
 
pub.client:soapClient
WmPublic. Creates and sends SOAP 1.1 and SOAP 1.2 messages over HTTP, HTTPS, or JMS transports for any style/use combination supported by Integration Server.
Input Parameters
address
String String specifying the URI of the web service endpoint. If you are submitting the request to an Integration Server, remember to direct it to the default SOAP processor (ws) as shown in the following example:
http://rubicon:5555/soap/ws/example:calculator
request
Document The input parameters that are to be passed to the web service.
wsdName
String The name of the consumer web service descriptor that contains the operation you want to invoke.
wsdBinderName
String The name of a binder that contains information to use to create and send the request. This binder must be in the consumer web service descriptor specified in wsdName.
Note:
The consumer web service endpoint alias assigned to a binder indicates which proxy server Integration Server uses to send the request. For more information about proxy server usage and web service endpoint aliases, see Creating an Endpoint Alias for a Provider Web Service Descriptor for Use with HTTP/S.
wsdOperationName
String The name of the operation that you want to invoke. This operation must be contained in the binder specified in wsdBinderName.
targetInputSignature
String Fully qualified name of the IS document type to use to validate and encode the contents of request.
targetOutputSignature
String Fully qualified name of the IS document type to use to validate and decode the output value returned by the web service.
soapHeaders
Document Optional. Header documents included in the SOAP request as SOAP headers.
transportHeaders
Document Optional. Transport header fields that you want to explicitly set in the request issued by the pub.client:soapClient service.
Specify a key in transportHeaders for each header field that you want to set, where the key's name represents the name of the header field and the key's value represents the value of that header field.
The names and values supplied to transportHeaders must be of type String. If a transport header has a name or value that is not of type String, the header will not be included in the message.
The headers that you pass in to transportHeaders vary depending on the transport used to send the SOAP message. The supplied wsdBinderName determines the transport.
For more information about specifying transportHeaders, refer to the Usage Notes.
method
Document Optional. The QName of the requested procedure. The name is defined as follows:
Key
Value
namespaceName
String Namespace portion of the procedure's QName.
localName
String Local portion of the procedure's QName.
Note:
The method parameter applies when style is RPC.
auth
Document Optional. Parameters specifying the credentials that are to be submitted to the server specified in address.
Integration Server allows two levels of authorization credentials: transport level and message level.
Each element is defined as follows:
Key
Description
transport
Document Optional. Transport level authorization parameters.
Key
Description
type
String Optional. Type of authentication that the service will perform. Set to:
*Basic to submit a user name and password. This is the default.
*Digest to submit a password digest for authentication.
*NTLM to use NTLM authentication.
user
String Optional. User name that this service will use if one is requested.
Note:
If you have specified NTLM as type, you must specify user in the following format:
domain_name\user_name
pass
String Optional. Password that this service will submit if one is requested.
serverCerts
Document Optional. The message signer's private key and certificate chain.
privateKey Object The SOAP message signer's private key.
certChain Object List A list containing the signer's complete certificate chain, where element 0 in the list contains the signer's certificate and element 1 contains the CA's certificate.
message
Document Optional. Message level authorization parameters.
Key
Description
user
String Optional. User name that this service will use if one is requested.
pass
String Optional. Password that this service will submit if one is requested.
serverCerts
Document Optional. The message signer's private key and certificate chain.
privateKey Object The SOAP message signer's private key.
certChain Object List A list containing the signer's complete certificate chain, where element 0 in the list contains the signer's certificate and element 1 contains the CA's certificate.
partnerCert
Object Optional. The partner's complete certificate chain, where element 0 in the list contains the message signer's certificate and element 1 contains the CA's certificate.
timeout
String Optional. Time (measured in milliseconds) to wait for a response from the server hosting the web service before timing out and terminating the request.
A value of 0 means Integration Server waits for a response indefinitely. If the connection to the host or JMS provider ends before Integration Server receives a response, the service ends with an exception and a status code of 408.
If this parameter is not specified, or an invalid (non-numeric) value is specified, Integration Server uses one of the following values:
*For HTTP, Integration Server uses the value of the watt.server.SOAP.request.timeout server configuration parameter as the timeout value
*For JMS, Integration Server uses the value of the watt.server.soapjms.request.timeout server configuration parameter as the timeout value.
For more information about watt.server.SOAP.request.timeout and watt.server.soapjms.request.timeout server configuration parameter, see webMethods Integration Server Administrator’s Guide.
Integration Server ignores timeout if the name/value pair jms.async= true is passed in to transportHeaders.
soapAction
String Optional. Specifies one of the following:
*If soapProtocol is set to SOAP 1.1 Protocol, specifies the value to which you want to set the SOAPAction HTTP header.
*If soapProtocol is set to SOAP 1.2 Protocol, specifies the value to which you want to set the action attribute in the Content-Type header.
Integration Server ignores soapAction in either of the following situations:
*The Content-Type header is passed in to transportHeaders and soapProtocol is set to SOAP 1.2 Protocol.
*The soapAction header is passed into transportHeaders and soapProtocol is set to SOAP 1.1 Protocol.
soapProtocol
String Optional. Indicates the SOAP protocol the service uses to send messages. Valid values are SOAP 1.1 Protocol or SOAP 1.2 Protocol.
encoding
String Optional. Specifies the encoding method. Default value is UTF-8.
Integration Server ignores encoding if the Content-Type header is passed in to transportHeaders.
useJSSE
String Optional. Whether to enable the use of the Java Secure Socket Extension (JSSE) socket factory for creating outbound HTTPS connections. Set to:
*yes if the connection requires the use of TLS 1.1 or TLS 1.2. When set to yes, Integration Server creates the connection using the Java Secure Socket Extension (JSSE) socket factory.
*no if the connection does not require support for TLS 1.1 or TLS 1.2. When set to no, the connection supports only SSL 3.0 and TLS 1.0 and Entrust IAIK library is used to create the outbound HTTPS connection.
Note:
A value of yes or no for the useJSSE input parameter overrides the value of the watt.net.ssl.client.useJSSE server configuration property.
Note:
To control the cipher suites used on JSSE sockets that are used while making outbound HTTPS requests, set the server configuration property watt.net.jsse.client.enabledCipherSuiteList. For more information, see webMethods Integration Server Administrator’s Guide.
Output Parameters
soapResponseData
Object A SOAP object containing the SOAP response message returned by the server specified in address.
response
Document Output parameters returned from the web service.
header
Document Conditional. Headers from the response and request messages.
header contains the following keys:
Key
Value
requestLines
Document Conditional. Header fields from the request message. Each key in requestLines represents a line (field) in the request header. Key names represent the names of header fields. The keys' values are Strings containing the values of the fields.
The contents of the requestLines document are not identical to transportHeaders. The transport can add, remove, or alter specific headers while processing the request.
Whether or not the web service connector returns the requestLines parameter depends on the success or failure of the pub.client:soapClient service. In the case of failure, the point at which the failure occurs determines the presence of the requestLines parameter. For more information, see the usage notes for this service.
For the HTTP or HTTPS transports, the requestLines parameter will not contain any HTTP headers that the transport mechanism added or modified when sending the request.
For the JMS transport, each key in requestLines represents a JMS message header. Key names represent the names of header fields. Key values are Strings containing the values of the header fields. The JMS provider populates some JMS message header fields after it successfully receives the JMS message. Additionally, the Integration Server specific run-time properties (properties that begin with the “jms.” prefix) are not returned in JMS transport, each key in requestLines. The JMS provider uses the information in these properties to populate the JMS message header fields that correspond to the properties.
lines
Document Header fields from the response. Each key in lines represents a field (line) of the response header. Key names represent the names of header fields. The keys' values are Strings containing the values of the fields.
Whether or not the pub.client:soapClient service returns the lines parameter depends on the success or failure of the service. In the case of failure, the point at which the failure occurs determines the presence of the lines parameter. For more information, see the usage notes for this service.
For the HTTP or HTTPS transports, the lines parameter contains any HTTP/HTTPS headers present in the response.
For the JMS transport, the lines parameter contains the JMS headers present in the response.
status
String Status code from the request, returned by the underlying transport. response. For more information about status codes returned by the service, see the usage notes for this service.
statusMessage
String Status message returned by the transport. For more information about status messages returned by the service, see the usage notes for this service.
soapStatus
String Flag indicating whether the SOAP request message was processed successfully.
A value of...
Indicates that...
0
The remote server successfully processed the SOAP request and returned a SOAP response message.
1
The remote server returned a SOAP fault, indicating that the SOAP request was received but was not processed successfully.
2
The server returned an error that was not a SOAP fault. This indicates that some type of HTTP error occurred (often, an HTTP 404). You can check the status field in header to determine the type of HTTP error that occurred.
Usage Notes
If the address begins with https:, you must specify a private key and certificate chain. You can use the auth/transport/serverCerts parameters to do so. If you do not specify them using the auth/transport/serverCerts parameters, pub.client:soapClient uses the web service endpoint alias specified in the binder. If the endpoint alias does not have an associated private key and certificate chain, then the default outbound SSL certificate settings are used to authenticate the resources.
Note:pub.client:soapClient supports NTLM protected web service over HTTP as well as HTTPS.
As part of executing pub.client:soapClient, Integration Server executes any service handlers assigned to the consumer web service descriptor specified in wsdName.
When a document type contains a String variable that represents a required attribute (meaning that the variable name starts with the "@" symbol and the Required property is set to True in Designer) and the input document does not contain the required attribute, Integration Server adds an empty attribute during document encoding. For example, if the document type contains a required String variable named @myAttribute but @myAttribute is missing from the input document, Integration Server adds myAttribute ="" to the XML document.
Note:
Because empty xmlns attributes are invalid, if the document type contains a required String variable named @xmlns and the input document does not specify a value for the @xmlns attribute, Integration Server does not add xmlns="" to the XML document.
Keep the following points in mind when specifying transportHeaders for HTTP or HTTPS:
*For any header name/value pair supplied in transportHeaders, Integration Server simply passes through the supplied headers and does not perform any validation for the headers.
*If you do not set transportHeaders or do not specify the following header fields in transportHeaders, Integration Server adds and specifies values for the following header fields:
*Accept
*Authorization
*Connection
*Content-Type
*Host
*SOAPAction (Added when soapProtocol is SOAP 1.1 only)
*User-Agent
Important:
Pass in the preceding headers to transportHeaders only if you are an experienced web service developer. Incorrect header values can result in failure of the HTTP request.
*If you specify Content-Type in transportHeaders, Integration Server ignores the value of the encoding input parameter.
*If you specify Content-Type in transportHeaders and the soapProtocol input parameter is set to SOAP 1.2, Integration Server ignores the value of the soapAction input parameter.
*If you specify the SOAPAction header in transportHeaders and the soapProtocol input parameter is set to SOAP 1.1 Protocol, Integration Server ignores the value of the soapAction input parameter.
*If MTOM processing converts any portion of the SOAP request to an MTOM/XOP attachment, it will overwrite the Content-Type value supplied to the transportHeaders input.
*Integration Server sets the value of Content-Length automatically and overrides any value passed in to transportHeaders.
*Integration Server automatically adds the Cookie header to the HTTP header and supplies any cookies established between Integration Server and the HTTP server with which it is interacting. If you supply the Cookie header to transportHeaders, Integration Server prepends the values you supply to the already established Cookie header value.
*The following headers are considered to be standard and require the specified capitalization: Accept, Authorization, Connection, Content-Type, Cookie, Host, SOAPAction, User-Agent.
*Using capitalization other than that which is specified results in undefined behavior.
*Supplying duplicate entries for any standard header results in undefined behavior.
Keep the following points in mind when specifying transportHeaders for JMS:
*Specify a key in transportHeaders for each header field that you want to set, where the key’s name represents the name of the header field and the key’s value represents the value of that header field.
*You can specify the following JMS message header fields in transportHeaders:
*JMSCorrelationID
*JMSType
Note:
The JMSCorrelationID and JMSType names are case-sensitive.
*You can specify the following JMS-defined properties in transportHeaders:
*JMSXGroupID
*JMSXGroupSeq
If the value of JMSXGroupSeq is not an integer, Integration Server ignores the name/value pair and does not place it in the message header.
Note:
The JMSXGroupID and JMSXGroupSeq names are case-sensitive.
*The “JMSX” prefix is reserved for JMS-defined properties. If a header whose name starts with “JMSX” is passed into transportHeaders and it is not named JMSXGroupID or JMSXGroupSeq, Integration Server generates a fault and returns it to the service.
*You can set any provider-specific property whose name starts with “JMS_” in transportHeaders. Integration Server maps a supplied name/value pair whose name starts with “JMS_” directly to a JMS message property. Because the JMS standard reserves the prefix “JMS_<vendor_name>” for provider-specific properties, Integration Server does not validate the name or value of this content.
Note:
The JMS provider determines which provider-specific properties to accept and include in the JMS message properties. For more information about provider-specific message properties how the JMS provider handles them, review the JMS provider documentation.
*You can use transportHeaders to specify run-time properties that affect the values of the JMS message and JMS message headers. The following table identifies these properties and indicates the JMS message header fields affected by each property.
Property Name
Description
jms.async
Indicates whether this is a synchronous or asynchronous request/reply. This run-time property does not affect a JMS message header field.
Note:
This property applies when pub.client:soapClient calls an operation with an In-Out message exchange pattern only
Value
Description
true
Indicates this is an asynchronous request/reply. Integration Server does not wait for a response message before executing the next step in the flow service.
If jms.async is true, Integration Server ignores the timeout input parameter.
false
Default. Indicates this is a synchronous request/reply. Integration Server waits for a response before executing the next step in the flow service.
jms.deliveryMode
Specifies the message delivery mode for the message. Integration Server uses this value to set the JMSDeliveryMode header.
Value
Description
PERSISTENT
Indicates the request message is persistent.
2
Default. Indicates the request message is persistent.
NON_PERSISTENT
Indicates the request message is not persistent.
1
Indicates the request message is not persistent.
Note:
If the jms.deliveryMode is not one of the above values, Integration Server ignores the name/value pair and uses the default value of 2.
jms.messageType
Message type identifier for the message. Integration Serveruses this value to set the JMSType header.
Specify one of the following:
*BytesMessage
*TextMessage
Note:
If thejms.messageTypevalue is not BytesMessage or TextMessage, Integration Server ignores the name/value pair and uses the default value of BytesMessage
jms.timeToLive
Length of time, in milliseconds, that the JMS provider retains the message. A value of 0 means that the message does not expire.
The JMS provider uses this value to set the JMSExpiration header in the sent JMS message.
Note:
If the jms.timeToLivevalue is not a valid Long, Integration Server ignores the property and uses the default value of 0.
jms.priority
Specifies the message priority. The JMS standard defines priority levels from 0 to 9, with 0 as the lowest priority and 9 as the highest.
Integration Server uses this value to set the JMSPriority header.
If the jms.priority value is not a value between 0 to 9, Integration Server ignores the property and uses the default value of 4.
*The lowercase “jms.” prefix is reserved for run-time properties used by Integration Server. If a header starts with “jms.”and is not one of the “jms.” properties defined by Integration Server, Integration Server ignores the property.
The header information returned when pub.client:soapClient executes an operation in a web service descriptor created on Integration Server version 8.2 or later varies depending on the following:
*The transport used to send the SOAP message which is determined by the wsdBinderName
*The success or failure of the pub.client:soapClient service and if failure occurs, the point at which that happens
*The message exchange pattern for the operation specified in wsdOperationName
Note:
The same conditions that affect the contents of header also determine whether the soapResponseData contains a SOAP response, a SOAP fault, or an exception.
The following table identifies the basic success and failure scenarios when pub.client:soapClient service executes an operation in a web service descriptor created on Integration Server version 8.2 or later and the header information that would be returned in each scenario. The table also indicates whether the scenario results in a SOAP response, SOAP fault, or exception being returned in soapResponseData.
Note:
JMS status codes as well as the status code 900 are specific to Integration Server and are not derived from any standard.
Use Case
The pub.client:soapClient service fails before sending the SOAP request.
Parameter
Description
status
900
statusMessage
Error occurred while preparing SOAP request
requestLines returned?
Yes, if the web service connector created the SOAP request successfully but execution failed before sending the request.
lines returned?
No
soapResponseData
Contains an exception.
Use Case
The pub.client:soapClient service fails while sending the SOAP request.
Parameter
Description
status
For HTTP, the status code will be the value returned by the HTTP server.
For JMS, the status code will be 400.
statusMessage
For HTTP, the status message will be the message returned by the HTTP server.
For JMS, the status message will be: Error occurred while sending request to JMS provider.
requestLines returned?
Yes
lines returned?
For HTTP, lines may be returned. For example, when the provider returns a status code in the 300 range or 400 range, it is possible that the provider populated response headers.
For JMS, lines will not be returned.
soapResponseData
Contains an exception.
Use Case
The pub.client:soapClient service fails while sending the SOAP request because a timeout occurs.
Parameter
Description
status
408
statusMessage
Timeout
requestLines returned?
Yes
lines returned?
No
soapResponseData
Contains an exception.
Use Case
The pub.client:soapClient service executes successfully.
Parameter
Description
status
For HTTP, the status code will be the value returned by the HTTP server. The status code will typically be in the 200 range.
For JMS and an In-Out or Robust In-Only operation, the status code will be 200.
For JMS and an In-Only operation, the status code will be 202.
statusMessage
For HTTP, the status message will be the message returned by the HTTP server.
For JMS, the status message will be: OK
requestLines returned?
Yes
lines returned?
Depends on the message exchange pattern (MEP) of the operation.
For In-Only and Robust In-Only, lines is not returned.
For In-Out, lines is returned.
soapResponseData
Contains the SOAP response for In-Out MEP only.
Use Case
The pub.client:soapClient service executes successfully but the JMS provider is not available, causing Integration Server to write the JMS message to the client side queue.
Note:
This use case applies to JMS only. It occurs only when the client side queue is enabled for the JMS binder specified in wsdBinderName.
Parameter
Description
status
300
statusMessage
Message written to the client side queue.
requestLines returned?
Yes
lines returned?
No.
soapResponseData
Not returned.
Use Case
The pub.client:soapClient service sends the SOAP request successfully but receives a SOAP fault from the web service provider.
Parameter
Description
status
For HTTP, the status code will be the value returned by the HTTP server. The status code will typically be in the 500 range.
For JMS, the status code will be 500.
statusMessage
For HTTP, the status message will be the message returned by the HTTP server.
For JMS, the status message will be: SOAP Fault
requestLines returned?
Yes
lines returned?
No
soapResponseData
Contains an SOAP fault.
Use Case
The pub.client:soapClient service fails while processing the SOAP response.
Parameter
Description
status
900
statusMessage
Error occurred while processing SOAP request
requestLines returned?
Yes
lines returned?
Yes
soapResponseData
Contains an exception.
When invoking pub.client:soapClient to execute an In-Out operation asynchronously using SOAP over JMS, keep the following information in mind:
*For an asynchronous request/reply, you must pass jms.async= true into the transportHeaders input parameter.
*To instruct Integration Server to write the request message for an asynchronous request/reply to the client side queue when the JMS provider is not available, the JMS binder must be configured to use the client side queue. Specifically, in the consumer web service descriptor, the Use CSQ property for the JMS binder must be set to true.
*When pub.client:soapClient sends an asynchronous request it executes to completion without populating any response headers for the lines output parameter.
*Even though pub.client:soapClient does not wait for a SOAP response, it will execute the response handlers assigned to the consumer web service descriptor. However, the messageContext that is available to handler services will not contain a response message. Handler services that do not operate on the response message and instead perform activities such as clean up following a request handler invocation might still provide value for an asynchronous request/reply.
*If you want to retrieve the SOAP response from the provider, you need to receive and process the response with a custom solution. This might include using standard JMS trigger or an on-demand message consumer to receive the message and then using the pub.soap* services to process the SOAP message.
Note:
Using a JMS trigger or message consumer to receive the response bypasses any response handlers or policies applied to the SOAP response, including any WS‑SecurityPolicy. The SOAP response does not undergo any processing provided by the response handlers or policies attached to the consumer web service descriptor. Any response messages that require decryption or authentication will not be usable. Consequently, do not use an asynchronous request/reply to invoke an In-Out operation to which the WS-SecurityPolicy is applied.
When using pub.client:soapClient to execute a Robust In-only operation using SOAP over JMS, keep the following information in mind:
*For a consumer web service descriptor, Integration Server provides partial support for Robust In-Only operations with a SOAP over JMS binding. When Integration Server creates a consumer web service descriptor from a WSDL that contains a Robust In-Only operation and that operation is defined as part of a portType with a SOAP over JMS binding, Integration Server populates the reply destination in the JMS message header (the JMSReplyTo header field) but otherwise treats the operation as In-Only.
Specifically, pub.client:soapClient will not produce or wait for any output besides the transportInfo parameter. If an exception occurs while the provider processes the request, the web service connector does not retrieve or process the SOAP response.
*If you want to retrieve a SOAP response (which includes the SOAP fault) that the provider sends when an exception occurs during web service execution, you need to receive and process the response with a custom solution. This might include using a standard JMS trigger or an on-demand message consumer to receive the message and using the pub.soap* services to process the SOAP message.
Note:
Using a JMS trigger or message consumer to receive the response bypasses any policies applied to the SOAP response and any response handlers assigned to the consumer web service descriptor. The SOAP response does not undergo any processing provided by the response handlers or policies attached to the consumer web service descriptor. Any response messages that require decryption or authentication will not be usable. Consequently, do not use an asynchronous request/reply to invoke an In-Out operation to which the WS-SecurityPolicy is applied.
See Also
pub.client:soapHTTP
pub.client:soapRPC