Copyright © Cloud Software Group, Inc. All Rights Reserved

SOAP Request Reply

Activity

The SOAP Request Reply activity performs a request on the specified web service and optionally expects a reply from the web service. You can invoke both document and RPC web services with this activity.

Configuration

The Configuration tab has the following fields.

Field	Global Var?	Description
Name	No	The name to appear as the label for the activity in the process definition.
Description	No	Short description of the activity.
Service	No	This two-part field specifies the namespace and the name of the web service. The service specified must be a concrete service that has a binding to an actual network endpoint. You can use the Browse button to bring up the Select a Resource dialog. This dialog allows you to select the available services and operations from the specified WSDL file. The Port, Operation, and Endpoint URL fields will then be populated by the choices made in this dialog.
Port	No	The port in the WSDL file containing the desired operation. The drop down list in this field is populated based on the specified service.
Operation	No	The operation that this activity invokes. This field is automatically populated when an operation is selected using the Select a Resource dialog (see the Service field for more information).
SOAP Action	Yes	The soapAction header for the operation. See the SOAP specification for more information about soapAction.
Timeout (sec)	Yes	The time to wait (in seconds) for the operation to complete. Note: You can also select Timeout as milliseconds (msec). Seconds (sec) is default.
Attachment Style	No	This field allows you to choose the attachment style. Two attachment styles are available: SwA and MTOM.

Reload Button

The Reload Button reloads the WSDL file. If the WSDL file has changed since it was last loaded, the configuration, input, output, and error output are updated with the changes.

Test Transport Connection

The Test Transport Connection button is only available when the transport is JMS. This button tests the connection to the JMS server.

Transport Details

The Transport Details tab allows you to specify additional configuration information based on the type of transport used for the SOAP request. When HTTP is the transport, the HTTP sub-tab appears on this tab. When JMS is the transport, the JNDI and JMS sub-tabs appear. See SOAP Messages Over the JMS Transport for more information about SOAP over the JMS transport.

The Transport Details tab contains the following fields:

Field	Global Var?	Description
HTTP Sub-Tab
Endpoint URL	Yes	The URL of the web service that you are sending a request to. This field is automatically populated with the choice made when selecting the service. You can specify URLs that use the HTTPS (secure sockets) protocol. If you specify HTTPS as the protocol, the SSL field becomes enabled.
Use HTTP Proxy	No	When checked, this field specifies that an HTTP proxy server is used to connect to the SOAP server. Enabling this field causes the Proxy field to appear.
Proxy	No	Appears when the Use HTTP Proxy field is enabled. This field specifies the Proxy Configuration shared configuration resource that describes the HTTP proxy server. See Proxy Configuration for more information.
HTTP Authentication	No	Specifies what authentication should be used . An authentication can be of the following three types: • NONE - is default. • BASIC - to continue with the current implementation of using username and password credentials. The Identity field appears when this field is enabled. • NTLM - Identity and Domain fields appear when NTLM is selected. Identity is a reference of the Username and Password combination.
Identity	No	This is an Identity resource that contains the client’s username and password. This identity is used to perform only Basic and NTLM authentication.
Domain	No	Specifies the domain to be used for Authentication. The user name and password specified in the Identity field must exist in the domain.
JNDI Sub-Tab
Context URL	Yes	This is the URL to the JNDI service provider (javax.naming.Context.PROVIDER_URL). The value for this field is taken from the WSDL file, if it is available in the <jndi:context> element in the service specification. You can override the supplied value, if you want to use a different JNDI service provider. See your JNDI provider documentation for the syntax of the URL.
User Name	Yes	User name to use when logging into the JNDI server (javax.naming.Context.SECURITY_ PRINCIPAL). If the JNDI provider does not require access control, this field can be empty.
Password	Yes	Password to use when logging into the JNDI server (javax.naming.Context.SECURITY_ CREDENTIALS). If the JNDI provider does not require access control, this field can be empty.
Context Factory	Yes	The initial context factory class for accessing JNDI (javax.naming.Context.INITIAL_CONTEXT_ FACTORY). The value for this field is taken from the WSDL file, if it is available in the <jndi:context> element in the service specification. You can override the supplied value, if you want to use a different context factory. Note: TIBCO ActiveMatrix BusinessWorks attempts to find the class. However, you may need to add the Java file supplied by your JNDI service provider to the CLASSPATH environment variable to use JNDI.
Connection Factory	Yes	The QueueConnectionFactory object stored in JNDI. This object is used to create a queue connection with a JMS application. The value for this field is taken from the WSDL file, if it is available in the <jms:connectionFactory> element in the service specification. You can override the supplied value, if you want to use a different connection factory. See your JNDI provider documentation for more information about creating and storing QueueConnectionFactory objects.
SSL	No	Specifies whether you want to use SSL for the connection to the JNDI server. SSL is used when the Use SSL? check box is selected. Click the Configure SSL button to configure the SSL connection parameters. See Configure SSL for more information.
SSL Password	Yes	Password to use during the SSL connection.
Validate Security Context	Yes	Checking this field ensures that the security context provided on this tab is the one used to connect to the JNDI server. Some application servers store the security context on the thread used to establish the JNDI connection. Therefore the first activity to use this resource will establish the security context, and then subsequent activities will use the same security context, unless this field is checked. Checking this field ensures that each activity that uses this resource examines the security context to determine if the activity uses the same security context as the security context established on the thread. If they are different, the activity’s configured security context is used. Checking this field causes additional overhead for activities that use this resource. The only supported application server that requires this field to be checked is WebLogic.
Properties	No	Any additional properties to supply for the connection. You specify a name, datatype, and value for each property. These properties are typically vendor-specific. See your JNDI provider documentation for more information about the available properties.
JMS Sub-Tab
User Name	Yes	User name to use to authenticate to the JMS server.
Password	Yes	Password to use to authenticate to the JMS server.
JMS Destination	Yes	Name of the JMS destination for the SOAP request. The syntax of the destination name is specific to the JMS provider you are using. See your JMS provider documentation for more information about destination names. Note: If you are using TIBCO Enterprise Message Service as your JMS provider, you can use the Browse button next to this field after specifying a valid connection in the JMS Connection field. The Browse button displays a list of configured destinations in the JMS server that are appropriate for this activity.
Message Type	Yes	The type of the message. This can be one of the following: • Bytes Message — A stream of bytes. • Text Message — The message is a java.lang.String.
Delivery Mode	Yes	The delivery mode of the message. Can be one of the following: • PERSISTENT: signifies the messages are stored and forwarded. • NON-PERSISTENT: messages are not stored and may be lost due to failures in transmission. • TIBCO EMS Reliable: this mode is only available when using TIBCO Enterprise Message Service. See the TIBCO Enterprise Message Service documentation for more information about this mode.
Expiration	Yes	Corresponds to JMSExpiration property that specifies how long the message can remain active (in seconds). If set to 0, the message does not expire. This field is set in seconds, but the JMSExpiration property is displayed in milliseconds.
Priority	Yes	Priority of the message. You may set the priority to a value from 0-9. The default value is 4.
Use Shared JMS Configuration	No	Check this field if you want to specify a JMS Connection shared configuration resource to override the JMS transport parameters in the concrete WSDL. When checked, this JMS Connection field appears.
JMS Connection	No	This field only appears when the Use Shared JMS Configuration field is checked. This field allows you to specify a JMS Connection shared configuration resource that contains the connection information you want to use to override the JMS transport parameters in the concrete WSDL.
Enable W3C SOAP JMS 1.0 Compliance		This is a read-only field that displays whether the service is W3C SOAP Over JMS 1.0 compliant or not.
Target Service		This field is available only when the check box Enable W3C SOAP JMS 1.0 Compliance is selected. Specify the target service value, if any. Note: If Target Service is configured, the value is reflected in the WSDL as a query parameter.
Application Properties (Input Message)		Any application-specific message properties that are a part of the input message.
Application Properties (Output Message)		Any application-specific message properties that are a part of the output message.

Configure SSL

This button allows you to configure the SSL connection parameters for connecting to the SOAP server. This button brings up a dialog with the following fields:

Field	Description
Trusted Certificates Folder	Folder in the project containing one or more certificates from trusted certificate authorities. This folder is checked when connecting to a server to ensure that the connection is to a server that is trusted. This prevents connections to rogue servers that attempt to impersonate trusted servers.
Identity	This is an Identity resource that contains the client’s digital certificate and private key. See TIBCO Designer Palette Reference for more information.
Verify Host Name	This field specifies that the host name of the SOAP server should be checked against the host name listed in the server’s digital certificate. This provides additional verification that the host name you believe you are connecting to is in fact the desired host. If the host name specified in the Endpoint URL field on the Configuration tab is not an exact match to the host name specified in the server’s digital certificate, the connection is refused. Note: If you specify an equivalent hostname (for example, an IP address) in the Endpoint URL field, but the name is not an exact match of the hostname in the host’s digital certificate, the connection is refused.
Strong Cipher Suites Only	When checked, this field specifies that the minimum strength of the cipher suites used can be specified with the bw.plugin.security.strongcipher.minstrength custom engine property. See TIBCO ActiveMatrix BusinessWorks Administration for more information about this property. The default value of the property disables cipher suites with an effective key length below 128 bits. When this field is unchecked, only cipher suites with an effective key length of up to 128 bits can be used.

Messages With Attachments

SOAP messages can have message parts that contain attachments. For a message part to contain an attachment, specify the Special Type in the Type field of the Part Details section of the Message resource when creating a WSDL file configuration. See Chapter 19, WSDL Palette for more information about creating WSDL files.

Depending on the SOAP version being used, messages with attachments can conform to one of the following styles:

•	Messages with Attachments (SwA) - available with SOAP version 1.1 and 1.2.

•	Message Transmission Optimization Mechanism (MTOM) - available with SOAP version 1.1 and 1.2.

Messages with Attachments (SwA)

SOAP clients that send messages with attachments in the SwA style must conform to the SOAP Messages with Attachments specification (http://www.w3.org/TR/SOAP-attachments).

The input or output schema element for a message part that contains an attachment holds the content ID of the attachment instead of holding the actual attachment data. The actual data for attachments is always contained within the mimeEnvelopeElement of the output schema for this resource. This element contains a repeating element named mimePart that holds the list of attachments in the SOAP message. The attachment list can be correlated to the message parts containing the attachments by using the content-id mimeHeader element.

Message Transmission Optimization Mechanism (MTOM)

Message Transmission Optimization Mechanism (MTOM) provides another way of sending binary content or attachment processing by serializing SOAP messages with attachments. Optimization is only available for element content that is in a canonical lexical representation of xs:base64Binary data type. MTOM conforms to the specification http://www.w3.org/TR/soap12-mtom.

Any element of type xs:base64Binary (or an extension of xs:base64Binary) in the SOAP response message is treated as an MTOM attachment and appears as a separate MIME part on the wire. The SOAP message will have a XOP include reference to the attachment. Any XOP include reference in the SOAP message will be replaced by the corresponding attachment’s content encoded in Base64. Any MIME attachment that is not referenced from the SOAP Message using XOP include reference will be ignored by the MTOM Processing layer. Note that the attachment is a part of the SOAP Infoset. See TIBCO ActiveMatrix BusinessWorks Process Design Guide for more information about MTOM and Write to File.

Overriding the Content Type MimeHeader

Currently, the BusinessWorks activities hard codes the Content Type mimeHeader with the value "application/octet-stream" while sending MTOM messages.

Now you can over ride the value of contentType mime header if the Content Type attribute (with namespace http://www.w3.org/2005/05/xmlmime) has been declared corresponding to a binary element in the message schema while sending MTOM messages

To enable this feature, add the Content Type attribute as explained below:

 

<xs:element name = "picture" xmlns:ns1 = "http://www.w3.org/2005/05/xmlmime">

<xs:complexType>

<xs:simpleContent>

<xs:extension base = "xs:base64Binary">

<xs:attribute ref = "ns1:contentType"/>

</xs:extension>

</xs:simpleContent>

</xs:complexType>

</xs:element>

 

This feature is applicable for all activities in the SOAP and Service Palette that send outbound MTOM messages.

Advanced

The Advanced tab is used to specify the behavior of attachment for the reply message. This is useful if large messages are sent and you want to write them to files instead of storing them in memory. The Advanced tab has the following fields.

Field	Description
Write to File	Checking this field specifies that incoming messages whose attachments exceed the specified threshold size should be written to a file instead of stored in memory. This allows you to accept large incoming attachments without consuming a great deal of memory. When this field is checked, the Directory and Threshold Size fields appear. Leaving this field unchecked specifies that attachments of incoming messages should be kept in memory. Note: Once written, the files created by using this option are not deleted automatically. You must manage the storage used by these files and delete them when they are no longer used. Although Write to File exists for SwA and MTOM, Soap over JMS completely depends on the heap size configuration as JMS specifications do not support writing JMS messages in parts as is the case with Soap over HTTP, which can be written over wire in parts. Hence, writing large JMS messages to JMS after configuring Write to File, completely depends on the Heap size.
Directory	The directory to write attachments that are above the specified threshold. The process engine does not attempt to create the directory if the specified directory does not exist. Therefore, create the directory before starting the process engine.
Create Non-Existing Directories	When checked, all directories in the path specified in the Directory field are created, if they do not already exist. If this field is unchecked and there are one or more directories in the specified path in the Directory field that do not exist, an exception is raised.
Threshold Size (bytes)	The maximum size (in bytes) of an incoming message attachment that can be kept in memory. Attachments larger than the specified size are written to a file in the specified directory. The file’s name is output so that subsequent activities in the process definition can access the file and read its contents. Specifying zero (0) in this field causes all incoming messages to be saved to a file.

Input

See TIBCO ActiveMatrix BusinessWorks Process Design for more information about mapping and transforming input data.

The input for the activity is the following.

Input Item	Datatype	Description
inputMessage or <operationName>	complex	The root class for the input of the SOAP Request Reply activity. This class contains all input items for the activity. If this is a document request, the input is named inputMessage. If the request is an RPC, the input is the name of the operation.
_configData	complex	Specifies the values to use to override transport-specific configuration values, if desired. The content of the _configData element depends upon the type of transport used.
endpointURL	string	Available only when HTTP is the transport. Specifies the Endpoint URL of the service. Specifying a value in this input item overrides any value specified in the Endpoint URL field on the Configuration tab.
host	string	Available only when HTTP is the transport. Specifies the host machine where the SOAP service resides as host:port. This should be used when sending a message through a tunnel.
Transport Properties - HTTP
Headers
Accept	string	This field specifies media types that are acceptable for response messages for the request. For example, text/*, text/html. Media types are described in the HTTP specification. If no Accept header field is specified, then the server assumes that all media types are acceptable.
Accept-Charset	string	This field specifies the character sets that are acceptable for response messages for the request. For example, iso-8859-5, unicode-1-1. Character sets are described in the HTTP specification. If no Accept-Charset header is specified, then the server assumes that any character set is acceptable.
Accept-Encoding	string	This field specifies the content-coding values that are acceptable for response messages. For example, compress, gzip. See the HTTP specification for more information about this header.
Cookie	string	A name/value pair (also known as a cookie) containing information that the HTTP server may be expecting. You can set the Cardinality field for this element to Repeating (*) to specify more than one cookie. You can also specify multiple name/value pairs in a single non-repeating element by separating each pair with a comma (for example, "name1=value1, name2=value2"). You set the custom engine property bw.plugin.http.protocol.single-cookie-header to true, multiple name/value pairs are sent as a single header element. See TIBCO ActiveMatrix BusinessWorks Administration for more information about custom engine properties.
Pragma	string	This field is used to include implementation-specific directives that might apply to the receiver. See the HTTP specification for more information about using this field.
Authentication Credentials
username	string	The username for logging into the HTTP server. This overrides the value specified in the Identity resource. Note: You can override the username only if the activity is configured for Basic or NTLM authentication.
password	string	The password for logging into the HTTP server. This overrides the value specified in the Identity resource. Note: You can override the password only if the activity is configured for Basic or NTLM authentication.
domain	string	Specify the domain to be used. This overrides the value specified in the configuration. Note: You can override the domain name only if the activity is configured for NTLM authentication.
soapAction	string	Specifies the soapAction header for the operation. See the SOAP specification for more information about soapAction. Specifying a value in this input item overrides any value specified in the Action field on the Configuration tab.
timeout	number	The time to wait (in seconds) for the operation to complete.
mimeEnvelopeElement	complex	This element contains the message attachments when mime attachments are used. This element contains a repeating element named mimePart that contains each mime attachment.
mimepart
mimeHeaders	complex	This element contains the mime header for each mimePart. Mime headers can contain the following information: • content-disposition • content-type • content-transfer-encoding • content-id • other mime header information Note: When the content type is specified as "text/*" (for example, "text/xml"), the attachment content is expected to be in either the textContent input element or the file name storing the attachment is expected to be in the fileName input element. When the content type is anything other than "text/*", the attachment content is expected to be in either the binaryContent input element or the file name storing the attachment is expected to be in the fileName input element.
binaryContent | textContent | fileName	choice	This element contains the mime attachment. The element can be one of the following: • binaryContent — content of the attachment when the attachment is binary data. • textContent — content of the attachment when the attachment is text data. • fileName — the file name of the attachment when the attachment is stored in the file system.
Transport Properties - JMS
JMSTargetDestination	string	Available only when JMS is the transport. Specifies the JMS destination (queue) name used to send messages.
JMSReplyDestination	string	Available only when JMS is the transport. Specifies the JMS destination (queue) name used to send the response. The JMSReplyDestination specified has to be unique for every message. Set the JMSReplyDestination to a non-static variable such as Job-Id to use the same JMSReplyDestination multiple times.
JMSCorrelationID		This ID is used to link a response message with its related request message. This property is usually set to the message ID of the message you are replying to, but any value can be used. Note: This is applicable only when JMSReplyDestination is configured with SOAP over JMS. The JMSCorrelationID of the reply message is set as follows: • When the JMSCorrelationID field is configured with a unique value, the JMSCorrelationID property of the request message is set with the unique value. The same value is also set as the JMSCorrelationID of the corresponding response message. • When the JMSCorrelationID input element is not configured, the value of the message ID of the JMS Request message is set as the JMSCorrelationID property of the response message.
JMSPriority	number	Available only when JMS is the transport. Specifies the priority of the message.
JMSExpiration	number	Available only when JMS is the transport. Corresponds to JMSExpiration property that specifies how long the message can remain active (in seconds).

Output

The output for the activity is the following.

Output Item	Datatype	Description
outputMessage or <operationName>Response	complex	The root class for the output of the SOAP Request Reply activity. This class contains all output items for the activity. If this is a document request, the output is named outputMessage. If the request is an RPC, the output is the name of the operation with "Response" appended.
mimeEnvelopeElement	complex	This element contains the reply message attachments when mime attachments are used. This element contains a repeating element named mimePart that contains each mime attachment.
mimeHeaders	complex	This element contains the mime header for each mimePart. Mime headers can contain the following information: • content-disposition • content-type • content-transfer-encoding • content-id • other mime header information Note: When the content type is specified as "text/*" (for example, "text/xml"), the attachment content is expected to be in either the textContent output element or the file name storing the attachment is expected to be in the fileName output element. When the content type is anything other than "text/*", the attachment content is expected to be in either the binaryContent output element or the file name storing the attachment is expected to be in the fileName output element.
headers	complex	Any output headers defined in the WSDL file. The headers are stored in an element named Header.<partName> where <partName> is the element name of the output header schema. The Header.<partName> element also contains an item named @mustUnderstand. This boolean value is set to true if the server specifies that the SOAP client must understand the header.
binaryContent | textContent | fileName	choice	This element contains the mime attachment. The element can be one of the following: • binaryContent — content of the attachment when the attachment is binary data. • textContent — content of the attachment when the attachment is text data. • fileName — the file name of the attachment when the Write to File field is checked on the Output Attachment Bindings tab.
Transport Properties - HTTP
Headers
Allow	string	This field lists the set of methods supported by the resource identified by RequestURI.
Content-Type	string	This field indicates the media type of the entity body for the outgoing message and the incoming response. Media types are described in the HTTP specification. An example of the media type is text/html; charset=ISO-8850-4.
Content-Length	string	This field indicates the size of the entity body (in decimal number of OCTETs) of the response message.
Content-Encoding	string	This field is used as a modifier to the content-type. When present, its value indicates what additional content encodings have been applied to the entity-body, and thus what decoding mechanisms must be applied in order to obtain the media-type referenced by the Content-Type header field. Content-Encoding is primarily used to allow a document to be compressed without losing the identity of its underlying media type. See the HTTP specification for more information about this field.
Date	string	The date and time when the response message was sent.
Location	string	This field was used to redirect the receiver to a location other than the Request-URI for completion of the request or for identification of a new resource.
Set-Cookie	string	See the HTTP specification for more information about this field.
Pragma	string	This field is used to include implementation-specific directives that might apply to the receiver. See the HTTP specification for more information about using this field.

Error Output

The Error Output tab lists the possible exceptions that can be thrown by this activity. See TIBCO ActiveMatrix BusinessWorks Error Codes for more information about error codes and corrective action to take.

Exception	Thrown When...
defaultFaultElement	The server returned a default SOAP fault.
ActivityTimedOutException	The activity reached the specified timeout and a response has not been received from the server.
<customFault>	The SOAP server has returned a custom fault. These faults are defined in the WSDL file and are listed as a choice element.
Errors when HTTP is the transport
HttpClientException	The SOAP server has reported a client error.
HttpServerException	The SOAP server has reported an internal error.
HttpCommunicationException	An HTTP communications error occurred.
Errors when JMS is the transport
JMSMessageCreateException	An error occurred when creating the request message.
JMSSessionCreteException	An error occurred when creating the JMS session to send the request message.
JMSSendException	An error occurred when attempting to send the JMS message.
JMSReceiveException	An error occurred when attempting to receive the JMS reply message.

Copyright © Cloud Software Group, Inc. All Rights Reserved