Integration Server 10.15 | Web Services Developer’s Guide | Working with Web Service Connectors | Signature for a Web Service Connector
 
Signature for a Web Service Connector
 
How a Web Service Connector Represents the Input and Output Messages
About Transport and Fault Information Returned by a Web Service Connector
Important:
The web service connector signature cannot be modified.
All web service connectors have an identical input and output signature with the exception of:
*The variables used to represent the input and output messages.
For information about how a web service connector represents the input and output messages in the signature, see How a Web Service Connector Represents the Input and Output Messages.
*The format of the fault structure in the output signature is based on the version of the Integration Server on which the web service descriptor is created.
*When the web service descriptor is created on Integration Server 8.2, the output signature of the web service connector contains a generic fault structure.
*For information about how Integration Server maps the contents of a SOAP 1.1 or SOAP 1.2 fault to the generic fault structure, see How a SOAP Fault is Mapped to the Generic Fault Output Structure.
*When the web service descriptor is created on versions of Integration Server prior to 8.2, the output signature of the web service connector contains a SOAP fault document that is specific to the SOAP protocol (i.e., SOAP 1.1 or SOAP 1.2).
Input Parameters
auth
Document Optional. Specifies the transport-level and message-level credentials to include in the request.
Integration Server uses the information provided in auth to create the HTTP request and the SOAP request.
Note:
Information specified in auth overwrites any authentication credentials specified in the consumer web service endpoint alias that is assigned to the binder used by the web service connector.
Key
Description
transport
Document Optional. Specifies the transport-level credentials to include in the HTTP request. Integration Server uses the information specified in the transport variable to populate the Authorization header in the HTTP request.
You only need to provide credentials in transport if the endpoint URL specifies HTTPS and you want to overwrite the credentials specified in the consumer web service endpoint alias assigned to the binder.
Note:
If the Authorization header is passed into transportHeaders, the values specified for the transport document and its children will not be used in the Authorization header.
Key
Description
type
String Optional. Specifies the type of authentication required by the host.
*Specify Basic to use basic authentication (user name and password)
*Specify Digest to use password digest to authenticate the credentials.
*Specify NTLM to use NTLM authentication.
*If type is not specified or if any value other than Basic, Digest, or NTLM is specified, Integration Server uses Basic.
user
String Optional. User name used to authenticate the consumer at the HTTP or HTTPS transport level on the host server.
Note:
If you have specified NTLM as type, you must specify user in the following format:
domain_name\user_name
pass
String Optional. Password used to authenticate the consumer on the host server.
serverCerts
Document Optional. The message signer’s private key and certificate chain.
*keyStoreAlias String Optional Alias to the keystore that contains the private key used to connect to the web service host securely.
*keyAlias String Optional. Alias to the key in the keystore that contains the private key used to connect to the web service host securely. The key must be in the keystore specified in keyStoreAlias.
message
Document Optional. Specifies the message-level credentials to include in the WS-Security SOAP headers included in the SOAP request.
For information about specifying message-level credentials in a web service connector, see Passing Message-Level Security Information to a Web Service Connector.
Note:
You cannot use message level authentication for consumer web service descriptors for which reliable messaging is enabled.
Key
Description
user
String Optional. User name used to authenticate the consumer at the message level.
Specify a value for user if the SOAP message request requires credentials for a UsernameToken.
pass
String Optional. Password used to authenticate the consumer at the message level.
Specify a value for pass if the SOAP message request requires credentials for a UsernameToken.
serverCerts
Document Optional. The message signer’s private key and certificate chain.
*keyStoreAlias String Optional. Alias to the keystore that contains the private key used to:
*Sign outbound SOAP requests
*Include an X.509 authentication token for outbound SOAP requests
*Decrypt inbound SOAP responses
Note:
To verify messages from this consumer, the web services provider must have a copy of the corresponding public key.
*keyAlias String Optional. Alias to the private key used to sign and/or include X.509 authentication token for outbound SOAP messages and/or decrypt inbound SOAP responses. The key must be in the keystore specified in keyStoreAlias.
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.

kerberos Settings
Document Optional. Kerberos-related details that will be used to provide Kerberos authentication for web service requests.
*jaasContext String Optional. The custom JAAS context used for Kerberos authentication.
Integration Server includes a JAAS context named IS_KERBEROS_OUTBOUND that can be used with outbound requests.
*clientPrincipal String Optional. The name of the client principal to use for Kerberos authentication.
The IS_KERBEROS_OUTBOUND JAAS context does not include a principal parameter. You must specify clientPrincipal if you specified IS_KERBEROS_OUTBOUND as the jaasContext value.
*clientPassword String Optional. The password for the specified client principal. You must specify clientPassword if the specified jaasContext does not specify a keytab file.
*servicePrincipal String Optional. The name of the principal that is used with the service that the Kerberos client wants to access. This can be obtained from the WSDL document published by the provider of Kerberos service. Specify the Service Principal Name in the following format:
principal-name.instance-name@realm-name
*servicePrincipalForm String Optional. The format in which you want to specify the principal name of the service that is registered with the principal database. Specify host-based to represent the principal name using the service name and the hostname, where hostname is the host computer. Specify username to represent the principal name as a named user defined in the LDAP or central user directory used for authentication to the KDC.
Note:
When using Keberos authentication, principal name and principal password can be specified in the JAAS context file and in the web service connector. If the principal name and password are specified in the JAAS context file supplied to jaasContext and in the web service connector inputs, the values in the JAAS context file take precedence.
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.
If timeout is not specified or specifies a value < 0, Integration Server uses one of the following values:
*For HTTP, Integration Server uses the value of the watt.server.SOAP.request.timeout server property as the timeout value.
*For JMS, Integration Server uses the value of the watt.server.soapjms.request.timeout server property as the timeout value.
For more information about server configuration properties, see webMethods Integration Server Administrator’s Guide.
A timeout 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 web service connector ends with an exception and a status code of 408.
Integration Server ignores timeout if the name/value pair jms.async= true is passed in to transportHeaders.
_port
String Optional. Specifies the port that Integration Server uses to invoke the operation represented by the web service connector. You only need to specify a value for _port when the portType in the WSDL is associated with multiple bindings. Reference the WSDL document to determine the names of the ports associated with the bindings for a given portType.
If you do not specify a value for _port, Integration Server uses the first port defined in the WSDL for the web service.
_url
String Optional. The URL to use as the endpoint URL for the web service. If supplied, the value of _url overwrites the endpoint URL in the original WSDL.
If a consumer web service endpoint alias is assigned to the binder used by the web service connector, the host and/or port in the consumer web service endpoint alias overwrite the host and/or port specified in _url. For more information about how Integration Server constructs the endpoint URL, see How Integration Server Builds the Consumer Endpoint URL.
endpointAlias
String Optional. The endpoint alias to use as the endpoint alias for the web service. If supplied, the value of endpointAlias overwrites the endpoint alias in the original WSDL.
To invoke the operations represented by the web service connector, you must have the credentials and user group membership permission to execute this endpoint alias as specified in its Execute ACL property.
Note:
The endpointAlias parameter is not available in Integration Server versions prior to 9.5 SP1. To include this parameter in the signature of web service connectors created in previous versions of Integration Server, refresh the web service connectors.

transport Headers
Document Optional. Transport-specific header fields that you want to explicitly set in the request issued by the web service connector. 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. For information about using transportHeaders with HTTP/S requests including a description of the default Integration Server behavior, see Setting Transport Headers for HTTP/S.
For information about using transportHeaders with JMS requests including a description of the default Integration Server behavior, see Setting Transport Headers for JMS.

message Addressing Properties
Document Optional. WS-Addressing-specific header fields that you want to explicitly set in the request issued by the web service connector. Integration Server uses this information to specify addressing information for a SOAP message, such as the message’s destination or where to reply to the message, without relying on transport-specific headers.
For more information about WS-Addressing, see Web Services Addressing (WS-Addressing).
Note:
The messageAddressingProperties parameter is not available in Integration Server versions prior to 9.0.
Key
Description
messageID
String Optional. Unique identifier of the SOAP message. If no message ID is specified, Integration Server generates a unique ID.
to
Document Optional. The endpoint reference to which you are sending the SOAP message.
Key
Description
address
Address of the intended receiver of the message and it attributes, which includes namespaceName, localname, and their values.

reference Parameters
Parameters that correspond to <wsa:ReferenceParameters> properties of the endpoint reference to which the message is addressed.
from
Document Optional. The endpoint reference that specifies the source of the SOAP message. The from input parameter includes:
*attributes, which includes namespaceName, localname, and their values.
*address and its attributes and values.
*referenceParameters
*metadata and its attributes and elements.
*extensibleElements, which are any other elements usually provided for future extensions.
replyTo
Document Conditional. The endpoint reference that specifies the destination address of the response (reply) message. The replyTo input parameter includes:
*attributes, which includes namespaceName, localname, and their values.
*address and its attributes and values.
*referenceParameters
*metadata and its attributes and elements.
*extensibleElements, which are any other elements usually provided for future extensions.
faultTo
Document Conditional. The endpoint reference that specifies the address to which the SOAP fault messages are routed. The faultTo input parameter includes:
*attributes, which includes namespaceName, localname, and their values.
*address and its attributes and values.
*referenceParameters
*metadata and its attributes and elements.
*extensibleElements, which are any other elements usually provided for future extensions.

must Understand
String Optional. Specifies whether the recipients (the actor or role to which the header is targeted) are required to process the WS-Addressing headers. Recipients that cannot process a mandatory WS-Addressing header reject the message and return a SOAP fault.
Value
Description
true
Indicates that processing the WS-Addressing headers is required by the recipients (the actor or role to which the header is targeted).If you specify True for mustUnderstand and the SOAP node receives a header that it does not understand or cannot process, it returns a fault.
false
Indicates that processing the WS_Addressing headers is optional. This is the default.
soapRole
String Optional. Target of the WS-Addressing headers in the SOAP message. soapRole determines the value of the role attribute of the WS-Addressing headers. The actor or role attribute specifies a URI for the recipient of WS-Addressing header entries. soapRole can be any valid URI that you specify or any of the following predefined roles.
Value
Description
Ultimate Receiver
Indicates that the recipient is the ultimate destination of the SOAP message. This is the default.
Next
Specifies the following URI for the role attribute:
*For SOAP 1.2: http://www.w3.org/2003/05/soap-envelope/role/next
*For SOAP 1.1: http://schemas.xmlsoap.org/soap/actor/next
None
Specifies http://www.w3.org/2003/05/soap-envelope/role/none for the role attribute.

reliable Messaging Properties
Document Optional. WS-ReliableMessaging-specific header fields that you want to explicitly set in the request issued by the web service connector. Integration Server uses this information to specify reliable messaging information for a SOAP message. For more information about WS-ReliableMessaging, see Web Services Reliable Messaging (WS-ReliableMessaging).
Note:
The reliableMessagingProperties parameter is not available in Integration Server versions prior to 9.0.
Key
Description
sequenceKey
String Optional. Unique identifier of the SOAP message sequence.
A reliable messaging client associates a sequence key to a message sequence based on the endpoint URL to which the message sequence is directed. In cases where there are several message sequences directed to the same endpoint URL, you can specify a custom sequence key to identify each sequence. Each sequence is then uniquely identified by the endpoint URL and the user-specified sequence key.
Note:
The user-specified sequence key should not exceed 32 characters in length.
You use the pub.soap.wsrm:createSequence service to create a new message sequence. You can specify the sequence key as the input of this service.

isLast Message
String Optional. Whether the message issued by the web service connector is the last message in the specified sequence key.
Value
Description
false
Specifies that the message is not the last message in the sequence. This is the default. This is the default.
true
Specifies that the message is the last message in the sequence.
message Number
String Optional. Specifies the message number in the message sequence. In cases where there are several message numbers in the message sequence, you can specify a custom message number.
acksTo
Document Optional. Consumer response endpoint address to which the reliable message destination must send the acknowledgement. To specify the consumer response endpoint address, use the Response endpoint address template binder property of the consumer web service descriptor for which the reliable message sequence is to be created, as the address template and replace the placeholders <server> and <port> with appropriate values.
If no address is specified as acksTo, the acknowledgement messages are sent back to the replyTo address. If no address is specified as replyTo, the acknowledgement messages are sent back to the requester.
Key
Description
address
Document Document that contains the address to which the acknowledgement message is to be sent.
*value String Address to which the acknowledgement message is to be sent.
Output Parameters
transportInfo
Document Conditional. Headers from response and request messages.
The contents of the transportInfo vary depending on the actual transport (HTTP, HTTPS or JMS) used by the connector.
transportInfo contains the following keys:
Key
Value
requestHeaders
Document Conditional. Header fields from the request message. The contents of the requestHeaders document are not identical to transportHeaders used as input to the web service connector. The transport can add, remove, or alter specific headers while processing the request.
Whether or not the web service connector returns the requestHeaders parameter depends on the success or failure of the connector. In the case of failure, the point at which the failure occurs determines the presence of the requestHeaders parameter. For more information, see About Transport and Fault Information Returned by a Web Service Connector.
*For the HTTP or HTTPS transports, the requestHeaders 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 requestHeaders 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 requestHeaders. The JMS provider uses the information in these properties to populate the JMS message header fields that correspond to the properties.
responseHeaders
Document Conditional. Header fields from the response. Each key in responseHeaders 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 web service connector returns the responseHeaders parameter depends on the success or failure of the connector. In the case of failure, the point at which the failure occurs determines the presence of the responseHeaders parameter. For more information, see About Transport and Fault Information Returned by a Web Service Connector.
*For the HTTP or HTTPS transports, the responseHeaders parameter contains any HTTP/HTTPS headers present in the response.
*For the JMS transport, the responseHeaders parameter contains the JMS headers present in the response.
status
String Conditional. Status code from the request, returned by the underlying transport.
For more information about status codes and status messages returned by a web service connector, see About Transport and Fault Information Returned by a Web Service Connector.
statusMessage
String Conditional. Description of the status code returned by the transport.
For more information about status codes and status messages returned by a web service connector, see About Transport and Fault Information Returned by a Web Service Connector.

messageAddressing Info
Document Conditional. Message addressing headers from response and request messages.
Note:
The messageAddressingInfo parameter is not available in Integration Server versions prior to 9.0.
The messageAddressingInfo parameter contains the following keys:
Key
Value

requestMessage Addressing Properties
Document Conditional. Message addressing header fields from the request message. The value of this parameter can be the values you provide while executing the web service connector, the values specified in the associated endpoint alias, or the values that Integration Server generates (for example, messageID and action).
Key
Description
messageID
String Conditional. Unique identifier of the SOAP message.
action
String Conditional. WS-Addressing action specified in the message addressing property of the SOAP message.
to
Document Conditional. The endpoint reference that specifies the address of the intended receiver of the SOAP message. The to endpoint reference includes:
*attributes, which includes namespaceName, localname, and their values.
*address and its attributes and values.
*referenceParameters
*metadata and its attributes and elements.
*extensibleElements, which are any other elements usually provided for future extensions.
from
Document Conditional. The endpoint reference that specifies the source of the SOAP message. The from endpoint reference includes:
*attributes, which includes namespaceName, localname, and their values.
*address and its attributes and values.
*referenceParameters
*metadata and its attributes and elements.
*extensibleElements, which are any other elements usually provided for future extensions.
replyTo
Document Conditional. The endpoint reference that specifies the destination address of the response (reply) message. The replyTo endpoint reference includes:
*attributes, which includes namespaceName, localname, and their values.
*address and its attributes and values.
*referenceParameters
*metadata and its attributes and elements.
*extensibleElements, which are any other elements usually provided for future extensions.
faultTo
Document Conditional. The endpoint reference that specifies the address to which the SOAP fault messages are routed. The faultTo endpoint reference includes:
*attributes, which includes namespaceName, localname, and their values.
*address and its attributes and values.
*referenceParameters
*metadata and its attributes and elements.
*extensibleElements, which are any other elements usually provided for future extensions.

response Message Addressing Properties
Document Conditional. Header fields from the response.
Key
Description
messageID
String Conditional. Unique identifier of the SOAP message.
relatesTo
Document List Conditional. Contains the relation ship information to another SOAP message.
Key
Description
value
String Message ID of the related message.

relationship Type
String Conditional. The relationship type.
action
String Conditional. WS-Addressing action specified in the message addressing property of the SOAP message.
to
Document Conditional. The endpoint reference that specifies the address of the intended receiver of the SOAP message. The to endpoint reference includes:
*attributes, which includes namespaceName, localname, and their values.
*address and its attributes and values.
*referenceParameters
*metadata and its attributes and elements.
*extensibleElements, which are any other elements usually provided for future extensions.
from
Document Conditional. The endpoint reference that specifies the source of the SOAP message. The from endpoint reference includes:
*attributes, which includes namespaceName, localname, and their values.
*address and its attributes and values.
*referenceParameters
*metadata and its attributes and elements.
*extensibleElements, which are any other elements usually provided for future extensions.
replyTo
Document Conditional. The endpoint reference that specifies the destination address of the response (reply) message. The replyTo endpoint reference includes:
*attributes, which includes namespaceName, localname, and their values.
*address and its attributes and values.
*referenceParameters
*metadata and its attributes and elements.
*extensibleElements, which are any other elements usually provided for future extensions.
faultTo
Document Conditional. The endpoint reference that specifies the address to which the SOAP fault messages are routed. The faultTo endpoint reference includes:
*attributes, which includes namespaceName, localname, and their values.
*address and its attributes and values.
*referenceParameters
*metadata and its attributes and elements.
*extensibleElements, which are any other elements usually provided for future extensions.

reliableMessaging Info
Document Conditional. Reliable messaging headers from response and request messages.
Note:
The reliableMessagingInfo parameter is not available in Integration Server versions prior to 9.0.
The reliableMessagingInfo parameter contains the following keys:
Key
Value

responseReliable Messaging Properties
Document Header fields from the response.
Key
Description

server SequenceId
String Unique identifier of the SOAP message sequence.
Note:
The serverSequenceId is returned as the output parameter of the pub.soap.wsrm:createSequence service. The serverSequenceId is used as the input parameter of pub.soap.wsrm:closeSequence, pub.soap.wsrm:sendAcknowledgementRequest, pub.soap.wsrm:terminateSequence, and pub.soap.wsrm:waitUntilSequenceCompleted services. For more information about these services, see webMethods Integration Server Built-In Services Reference.
fault
Document Conditional. The retrieved fault block. The web service connector returns fault when:
*A SOAP fault occurs, returning the SOAP fault information in fault.
*Any exception occurs while executing the web service connector, returning information about the exception in fault.
code
Document Contains the fault code and possible subcodes.
Key
Descriptions

namespace Name
String Conditional. For a SOAP fault, namespace name for the SOAP fault code. For an exception in the client side connector, namespaceName will not be returned.
localName
String For a SOAP fault, a code that identifies the fault. For an exception in the client side connector, localName is set to Exception.
subCodes
Document List Conditional. Subcodes that provide further detail. Each Document in the subCodes Document List contains:
*namespaceName for the subcode
*localName that identifies the subcode
reasons
Document List Reasons for the fault. Each Document in the Document List contains a human readable explanation of the cause of the fault.
Key
Descriptions
*body
String Text explaining the cause of the fault.
@lang
String Conditional. Language for the human readable description.
node
String URI to the SOAP node where the fault occurred.
role
String Conditional. Role in which the node was operating at the point the fault occurred.
detail
Document Conditional. Application-specific details about the fault.
Output Parameters for a web service descriptor created on Integration Server prior to 8.2
SOAP-FAULT
Document Conditional. Document containing the SOAP fault returned by the web service. A SOAP fault is returned when an error occurs during invocation of the web service operation.
Key
Description
soapProtocol
String Specifies the SOAP protocol used to send messages to and receive messages from the web service host.
A value of...
Indicates that...
SOAP 1.1 Protocol
Messages were sent using SOAP 1.1 protocol.
SOAP 1.2 Protocol
Messages were sent using the SOAP 1.2 protocol.
Fault_1_1
Document Conditional. Fault information. Fault_1_1 and its child variables are populated only when a SOAP fault is returned to the web service connector and soapProtocol is SOAP 1.1 Protocol.
Key
Description
faultcode
String Conditional. A code that identifies the fault. This field corresponds to the faultcode element in SOAP 1.1.
faultstring
String Conditional. A human readable explanation of the fault. This field corresponds to the faultstring element in SOAP 1.1.
faultactor
String Conditional. Information about the cause of the fault. This field corresponds to the faultactor element in SOAP 1.1.
detail
Document Conditional. Application-specific details about the SOAP fault. This field corresponds to the detail element in SOAP 1.1.
Fault_1_2
Document Conditional. Fault information. Fault_1_2 and its child variables are populated only when a SOAP fault is returned to the web service connector and soapProtocol is SOAP 1.2 Protocol.
Key
Description
SOAP-ENV:Code
Document Conditional. Contains the fault code.
*SOAP-ENV:Value String A code that identifies the fault. This corresponds to the Code element in SOAP 1.2.
SOAP-ENV:Reason
Document Conditional. Document containing the reason for the SOAP fault. This corresponds to the Reason element in SOAP 1.2.
*SOAP-Env:Text Document Conditional. Document containing the human readable explanation of the cause of the fault.
*@XML:lang String Conditional. Specifies the language for the human readable description. This field corresponds to the xml:lang attribute in SOAP 1.2.
**body String Conditional. Text explaining the cause of the fault. This field corresponds to the content of the Text element in SOAP 1.2.
SOAP-ENV:Node
String Conditional. URI to the SOAP node where the fault occurred. This field corresponds to the Node element in SOAP 1.2.
SOAP-ENV:Role
String Conditional. Role in which the node was operating at the point the fault occurred. This field corresponds to the Role element in SOAP 1.2.
SOAP-ENV:Detail
Document Conditional. Application-specific details about the SOAP fault. This field corresponds to the Detail element in SOAP 1.2.