Copyright © Cloud Software Group, Inc. All Rights Reserved

SOAP Event Source

Process Starter

The SOAP Event Source process starter creates a process instance for incoming SOAP requests. SOAP is a standard protocol for invoking web services. This allows you to create a web service using process definitions.

At runtime, a client can retrieve the WSDL file for a process containing this process starter using an HTTP request (see the description of the Retrieve Resources activity for more information). Once the WSDL file is retrieved, the client can perform a SOAP request to invoke the web service.

WSDL File and SOAP Event Source

A WSDL File specifies the characteristics (input message, output message, fault message, and so on) of a web service. The SOAP Event Source process starter configuration determines the concrete WSDL file that describes the web service that the process definition implements.

The Configuration tab of this process starter requires that you specify a Port Type. This port type is taken from a WSDL file resource. Instead of creating a new WSDL File resource, you can use an existing concrete service description. However, the concrete description of the service will be generated based on the configuration of this process starter.

Only Bytes Message must be used when using MTOM attachments.

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.
Port Type	No	The Port Type field is a two-part field. The first part is the namespace of the stored WSDL file that contains the service description. This is specified or imported as a WSDL File resource. See Chapter 19, WSDL Palette for more information about specifying abstract and concrete service descriptions. The second part of the Port Type field is the name of the port type in the WSDL file that contains the operation you want to implement with this process definition. This is a drop down list that is populated after the WSDL file is specified.
Operation	No	The operation that this process definition implements. The drop down list in this field is populated with the operations contained in the specified port type in the specified WSDL. You can choose one operation to implement per process definition. If you want to implement multiple operations, you must create a process definition for each.
Transport	No	The transport used by the incoming SOAP request. The transport can be one of the following: • HTTP — specify a HTTP Connection shared configuration resource. • JMS — specify a JMS Connection shared configuration resource Both HTTP and JMS allow you to use the SSL protocol for secure connections.
SOAP Version	No	Specify either SOAP 1.1 or SOAP 1.2 for the version of the SOAP specification to which incoming messages should comply. See SOAP Specification Compliance for more information.
Expose Security Context	No	Places the information from the user’s security context (either authentication or SSL certificate information) into the Context/SecurityContext output element. This is a fairly expensive operation and SSL certificates can consume memory resources, so check this option only if you require information from the user’s security context for later use in your process definition.

Transport Details

The Transport Details tab allows you to specify additional configuration information based on the type of transport used for the SOAP request. 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 Transport
Use Basic Authentication	No	When checked, this field specifies that incoming SOAP requests must supply a valid username and password. The user name and password specified in the incoming request must exist in the domain (users are created and managed in the domain using TIBCO Administrator).
Endpoint URI	No	Specify endpoint URI here. This is optional.
JMS Transport
JMS Destination	No	Name of the JMS destination for incoming requests. 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 and a destination type in the JMS Destination Type field. The Browse button displays a list of configured destinations in the JMS server that are of the specified type.
JMS Destination Type	No	Specify either Queue or Topic as the destination type.
Durable Subscription	No	This field is only available when Topic is selected in the JMS Destination Type field. This field specifies a durable subscription. You must specify a name in the Subscription name field that is registered with the JMS application as the durable subscription name.
Subscription Name	No	This field is only available when Topic is selected in the JMS Destination Type field. This field specifies the subscription name registered with the JMS application for durable subscriptions. This field is only available when the Durable subscription field is checked. Once a durable subscription is created, it can only be removed by accessing the administration tool of the JMS provider. See the documentation of your JMS provider for more information about managing durable subscriptions.
JMS 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.
Acknowledge Mode	Yes	This field is available when a JMS transport is selected. This field specifies the acknowledgement mode to be used for incoming messages. It can be one of the following: • Auto : the message is automatically acknowledged when it is received. • Client: the message is acknowledged when the process implementing the operation ends successfully. • Dups OK : the message is acknowledged automatically when it is received. JMS provides this mode for lazy acknowledgement, but TIBCO ActiveMatrix BusinessWorks acknowledges messages upon receipt. • TIBCO EMS Explicit : (only available for TIBCO Enterprise Message Service) a message which is not acknowledged using the Confirm activity before the process instance ends, are redelivered instead of all messages in the session. The session is not blocked and one session handles all incoming messages for each process instance. Note — In the TIBCO ActiveMatrix BusinessWorks 5.10 release, a change occurs in the behavior of this feature. Now only the messages that are not confirmed, are redelivered. • TIBCO EMS Explicit Dups OK : (only available for TIBCO Enterprise Message Service) a message which is not acknowledged using the Confirm activity before the process instance ends, are redelivered instead of all messages in the session. The session is not blocked and one session handles all the incoming messages for each process instance. The messages however, would be lazily acknowledged.
Max Sessions	No	This field is available when Client is selected as the Acknowledge Mode. If the JMS Destination Type is Topic, this field is read-only. If the JMS Destination Type is Queue, the value of this field can be altered. This field specifies the maximum number of JMS sessions to create for incoming queue messages. When a JMS queue message is received, the session is blocked until the message is acknowledged. Because the acknowledgement can comes at a later time when the process ends, this field allows you to specify a maximum number of new sessions to create to handle incoming messages. Once the maximum number of sessions is reached, no new incoming messages can be processed. Once an incoming message is confirmed, the total number of active sessions is decreased and another incoming message can be processed.
JMS Application Properties		Any application-specific message properties that will be part of the message. This is specified by the JMS Application Properties shared configuration object.
Enable W3C SOAP JMS 1.0 Compliance	No	Select the check box to enable the W3C SOAP Over JMS 1.0 specification. By default, the check box is not selected and the service complies with the TIBCO specifications.
Target Service	No	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, it’s value is reflected in the WSDL as a query parameter.

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 output schema element for a message part that contains an attachment will hold 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.

For an outbound SOAP Message with MTOM attachments sent by SOAP Request Reply or SOAP Send Reply activities, 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.

For an inbound SOAP Message with MTOM attachments received by the SOAP Event Source or SOAP Request Reply activities, 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.

Advanced

The Advanced tab contains the following fields:

Field	Description
General Sub-Tab
Service URI	The Service URI portion of the URL that can be used to retrieve the WSDL file. For clients to retrieve WSDL files from TIBCO ActiveMatrix BusinessWorks, you must define a process definition that accepts HTTP requests and uses the Retrieve Resources activity to generate the WSDL file. See Using Retrieve Resources on page 628 for more information. The URL to retrieve WSDL files is the following: http://<host>:<port>/<serviceURI>?wsdl where <serviceURI> is the value in this field.
SOAP Action	The soapAction that is expected from incoming SOAP requests. See the SOAP specification for more information about soapAction.
WSDL Namespace	The namespace for the concrete WSDL file specified by this activity.
Style	The SOAP binding style. You can specify either Document or RPC style.
Encoding	The encoding type for the body of the SOAP input and output messages. This can be either literal or encoded. Encoded messages support more complex datatypes such as SOAP arrays. When encoded is specified, you can optionally specify the namespace for input, output, and fault messages.
Input Message Namespace	The namespace for input messages.
Output Message Namespace	The namespace for output messages.
Fault Message Namespace	The namespace for fault messages.
Embed Interface	When checked, specifies that all referenced WSDL files should be included inline in the concrete WSDL file. Otherwise, all referenced WSDL files are imported.
Embed Types	When checked, specifies that all referenced XSD files should be included inline in the concrete WSDL file. Otherwise, all referenced XSD files are imported.
Embed JNDI Properties	When checked, specifies that JDNI properties should be included inline in the service specification in the WSDL Source tab.
Input Attachments Binding Sub-Tab
Mime Content Type	The table containing this column allows you to specify the mime content type of each message part. This is especially useful for describing parts that contain attachments. See the mime specification for more information on the valid syntax of the content type. If specified, the content type appears in the WSDL for the specified part. Use the X, +, and arrow keys to delete, add, and move parts in the list.
Message Part	The message part that you would like to specify the content type for. This field is a drop down list of message parts.
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. 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, completey 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 Data 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.
Output Attachments Binding Sub-Tab
Attachment Style	This field allows you to choose the attachment style for the outbound/response messages. Two attachment styles are available: SwA and MTOM.
Mime Content Type	The table containing this column allows you to specify the mime content type of each message part. This is especially useful for parts that contain attachments. See the mime specification for more information on the valid syntax of the content type. If specified, the content type appears in the WSDL for the specified part. Use the X, +, and arrow keys to delete, add, and move parts in the list.
Message Part	The message part that you would like to specify the content type for. This field is a drop down list of message parts.
Input Headers Sub-Tab The Input Headers sub-tab allows you to specify a SOAP message parts used for any SOAP headers expected in the incoming request. The specified input headers are also included in the concrete bindings in the generated WSDL file. When an incoming request supplies a header, the SOAP Event Source process starter places the information contained in the header into the output process variables for the SOAP Event Source. The header information is then available to subsequent activities in the process definition. Use the +, X, and arrow keys to add, delete and move the input header messages in the list.
Message Name	The message in a WSDL file to use as the input header for the incoming SOAP request. This WSDL file does not have to be the same as the file used for output headers or the file used to configure the port type and operation of the incoming request. Use the Browse button in this field to search for valid WSDL File resources and to select the desired message in the WSDL File.
Part Name	This field contains a drop down list with all parts of the specified SOAP message. You can specify a namespace or encoding for the part, if applicable.
Binding	Binding used for the part. This field must be "soap".
Ouput Headers Sub-Tab The Output Headers sub-tab allows you to specify a SOAP message parts used for any SOAP headers expected in the outgoing reply. The specified output headers are also included in the concrete bindings in the generated WSDL file. Use the +, X, and arrow keys to add, delete and move the input header messages in the list.
Message Name	The message in a WSDL file to use as the output header for the SOAP request. This WSDL file does not have to be the same as the file used for input headers or the file used to configure the port type and operation of the incoming request. Use the Browse button in this field to search for valid WSDL File resources and to select the desired message in the WSDL File.
Part Name	This field contains a drop down list with all parts of the specified SOAP message. You can specify a namespace or encoding for the part, if applicable.
Binding	Binding used for the part. This field must be "soap".

WSDL Source

This tab displays the WSDL file that can be used to call the web service implemented by this process definition. This information is presented for display purposes only, and this file cannot be edited. You can copy this WSDL file and send it to anyone who wants to invoke the web service.

Normally, an application would use a web request to retrieve the WSDL file of a web service (see the description of the Retrieve Resources activity for more information about sending a WSDL file as a response to a web request). This tab allows you to see the WSDL file that contains the concrete service description for this process.

Misc

The Misc tab contains the following fields:

Field	Description
Sequencing Key	This field can contain an XPath expression that specifies which processes should run in order. Process instances with sequencing keys that evaluate to the same value will be executed sequentially in the order the process instance was created. See TIBCO ActiveMatrix BusinessWorks Process Design for more information about controlling the execution order of process instances and about XPath expressions.
Custom Id	This field can contain an XPath expression that specifies a custom ID for the process instance. This ID is displayed in the View Service dialog of TIBCO Administrator, and it is also available in the $_processContext process variable.

Output

The output for the activity is the following.

Output Item	Datatype	Description
inputMessage or <operationName>	depends upon type specified in WSDL	The message parts specified in the WSDL file for the incoming SOAP request. The incoming request could contain multiple parts and attachments, and each part would be a message defined in the WSDL file. In case of MTOM attachments, the attachments appear embedded in the message.
mimeEnvelopeElement	complex	This element contains the message attachments when MIME attachments with SwA style 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.
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 Input Attachment Bindings sub-tab of the Advanced tab.
headers	complex	The header data supplied by the SOAP request. The structure of this input item is defined by the schema on the Input Headers sub-tab of the Advanced tab.
Header.<partName>	complex	Headers can contain multiple parts. The headers element contains all header parts supplied by the incoming SOAP request. These parts are specified on the Input Headers sub-tab of the Advanced tab. The header parts are stored in an element named Header.<partName> where <partName> is the name of the part specified on the Input Headers tab. Each Header.<partName> element also contains an attribute named @mustUnderstand. This boolean value is set to true in the incoming request if the client specifies that the server must understand the header part.
Context	complex	This element holds the optional SecurityContext element and the RemoteAddress and RemoteHost elements described below.
SecurityContext	complex	This output element is only available when the Expose Security Context field is checked on the Configuration tab. This element contains information about the requestor’s authentication or certificate information, depending upon the security scheme used. See the description of the following elements contained in the SecurityContext element for more information.
Transport	complex	This element is only available when HTTP is the transport, this element is not available when JMS is the transport. This element contains the transport-level security context. This includes the following: • CertificateToken— complex element containing the subject, issuer, serial number, fingerprint, and X509 certificate. • UsernameToken — complex element containing the username, password, and nonce (random number, if one is set by the calling application).
WSSE	complex	This element contains the WSS policy security context. This includes the Authentication and Signature elements. See the description of these elements below.
Authentication	complex	This element contains the authentication information from the client. The type of information in this elements depends upon how the client authenticated. This element can contain one of the following: • UsernameToken — complex element containing the username, password, and nonce (random number, if one is set by the calling application). • KeyInfo — the client’s public key.
Signature	complex	This element contains information from the user’s digital signature. This element contains the following: • Value — this element contains the raw signature sent by the client. • Token — either a UsernameToken or a KeyInfo element. A UsernameToken element contains the username, password, and nonce, if available. A KeyInfo element contains information about the client’s digital certificate or public key.
RemoteAddress	string	IP address of the remote host that sent the HTTP request. This element is only available when HTTP is the specified transport. This element is not available for the JMS transport.
RemoteHost	string	Host name of the remote host that sent the HTTP request. This element is only available when the Enable DNS Lookups field is checked on the Advanced tab of the HTTP Connection used by this activity. This element is only available when HTTP is the specified transport. This element is not available for the JMS transport.
TransportProperties - HTTP Transport
Method	string	The HTTP method to use for the request. All HTTP 1.1 methods are supported, but the CONNECT method is unnecessary because TIBCO ActiveMatrix BusinessWorks automatically uses the correct method when connecting by way of a proxy server. If no method is specified in this element, the GET method is used by default.
RequestURI	string	The address portion of the request. This is the portion of the URI before the question mark (?).
HTTPVersion	string	Version field of the HTTP request.
Command	string	Command portion of the HTTP request.
QueryString	string	The query string portion of the request. This is the portion after the question mark (?).
Header	complex	The header fields to send for the request. This element is specified on the Input Headers tab, and you can use this input item to supply values for the header when sending the request.
Protocol	string	Can be either HTTP or HTTPS depending upon the protocol used by the request.
Port	integer	The port number that the HTTP server uses for incoming requests. Specifying a value for this input item overrides any value specified on the Configuration tab.
Headers	Complex
Accept	string	This field specifies media types that are acceptable for response messages for the incoming request. For example, text/*,text/html. Media types are described in the HTTP specification. If no Accept header field is present, then it is assumed that the client accepts all media types.
Accept-Charset	string	This field specifies the character sets that are acceptable for response messages for the incoming request. For example, iso-8859-5, unicode-1-1. Character sets are described in the HTTP specification. If no Accept-Charset header is present, then it is assumed that the client accepts any character set.
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 field.
Content-Type	string	This field indicates the media type of the entity body sent to the receiver. 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) sent to the receiver and takes into account the encoding of the message body.
Connection	string	This field allows the requestor to specify options desired for this connection. For example, the option close specifies that the requestor would like the connection to be closed when the request is complete.
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.
TransportProperties - JMS Transport
JMSHeaders
JMSDestination	string	Destination where a message is sent.
JMSReplyTo	string	The JMS application where the reply message should be sent.
JMSDeliveryMode	string	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: using TIBCO Enterprise Message Service, the JMSDeliveryMode header can be TIBCO EMS Reliable. See the TIBCO Enterprise Message Service documentation for more information about this mode.
JMSMessageID	string	The unique ID of the message.
JMSTimestamp	long	The time a message was handed off to a JMS provider to be sent. The time is expressed as the amount of time, in milliseconds, since midnight, January 1, 1970, UTC.
JMSExpiration	long	The expiration time of the message. The time is expressed as the amount of time, in milliseconds since midnight, January 1, 1970, UTC. If set to 0, the message does not expire. For outgoing messages, this is set by specifying the JMSExpiration field on the activity’s Advanced tab.
JMSRedelivered	boolean	Typically this item is set when the JMS provider has delivered the message at least once before.
JMSPriority	integer	The priority of the message. Priority is a value from 0-9. Higher numbers signify a higher priority (that is, 9 is a higher priority than 8). For outgoing messages, the default priority is 4. This is set on the activity’s Advanced tab.
JMSCorrelationID	string	This ID is used to link a response message with its related request message. This is usually the message ID of a request message when this field is found in a reply message. See the following topics for more information about JMSCorrelationID: • JMS Queue Requestor • JMS Queue Sender • JMS Topic Publisher • JMS Topic Requestor • Reply To JMS Message
JMSType	string	The JMS provider-supplied string to describe the type of the message. Some JMS providers use this property to define messages in the provider’s repository. See your JMS provider documentation for more information about the use of this field.
JMSProperties
JMSXUserID	string	The ID of the user sending the message. This property is optionally set on incoming messages by the JMS application. This property is not set on outgoing messages.
JMSXAppID	string	The ID of the application sending the message. This property is optionally set on incoming messages by the JMS application. This property is not set on outgoing messages.
JMSXProducerTIXID	string	The transaction identifier of the transaction where this message was produced. This property is optionally set on incoming messages by the JMS application. This property is not set on outgoing messages.
JMSXConsumerTXID	string	The transaction identifier of the transaction where this message was consumed. This property is optionally set on incoming messages by the JMS application. This property is not set on outgoing messages.
JMSXRcvTimestamp	integer	The time the JMS server delivered the message to the consumer. The time is expressed as the amount of time, in milliseconds since midnight, January 1, 1970, UTC. This property is optionally set on incoming messages by the JMS server. This property is not set on outgoing messages.
JMSXDeliveryCount	integer	The number of delivery attempts for this message.
JMSXGroupID	string	The identity of the message group this message is a part of. You can set this property on outgoing messages to group messages into a numbered sequence.
JMSXGroupSeq	integer	The sequence number of this message in its group. You can set this property on outgoing messages to group messages into a numbered sequence.

Error Output

The Error Output tab lists the following possible exceptions that can be thrown by this activity.

Activity Errors

InvalidEnvelopeException

InternalException

ConfigurationException

DeserializationException

ServerException

 

Copyright © Cloud Software Group, Inc. All Rights Reserved