The connector processes two kinds of business objects:
For event processing the connector allows two kinds of TLOs--synchronous and asynchronous. This section discusses synchronous event processing TLOs.
Figure 4 shows the business object hierarchy for synchronous event processing. Request and Response objects are required, Fault objects are optional.
Figure 4. Business object hierarchy for synchronous event processing
The TLO contains object-level ASI as well as attributes with attribute-level ASI. Both kinds of ASI are discussed below.
Object-level ASI provides fundamental information about the nature of a TLO and the objects it contains. Figure 5 shows the object-level ASI for SERVICE_SYNCH_OrderStatus, a sample TLO for synchronous event processing.
Figure 5. Top-level business object for synchronous event processing
Table 4 below describes the object-level ASI for a synchronous event
processing TLO.
Table 4. Synchronous event processing TLO object ASI
Object-level ASI | Description |
---|---|
ws_eventtlo=true |
If this ASI property is set to true, the connector treats this object as a TLO for event processing only. Note that the WSDL Configuration Wizard uses this ASI to determine whether
a business object is a TLO. For more on this see WSDL Configuration Wizard.
|
ws_collab=collabname |
This ASI tells the connector which collaboration to invoke. Its
value is the name of the collaboration. (This ASI is also used during
WSDL generation to determine the TLO for a collaboration. For more on
this see WSDL Configuration Wizard.) In the sample shown inFigure 5, the collaboration name is
SERVICE_SYNCH_OrderStatus_Collab)
|
ws_verb=verb |
Before delivering the TLO to the collaboration, the connector uses this ASI
to set the verb on the TLO. In the sample shown inFigure 5, the verb is Retrieve.
|
ws_mode=synch |
During event notification, the connector uses this ASI property to determine whether to invoke the collaboration synchronously (synch) or asynchronously (asynch). For synchronous processing, this ASI must be set to synch. The default is asynch.
|
Each synchronous event processing TLO has attributes and attribute-level ASI. Figure 6 shows the attributes of SERVICE_SYNCH_OrderStatus, a sample TLO. It also shows the attribute-level ASI in the App Spec Info column.
Figure 6. TLO attributes for synchronous event processing
Table 5 summarizes the attribute-level ASI for the Request,
Response, Fault, MimeType, and Charset attributes of an synchronous event
processing TLO.
Table 5. Synchronous event processing TLO attribute ASI
TLO attribute | Attribute-level ASI | Description |
---|---|---|
MimeType | None | Optional attribute; if specified, its value is used as the mime type of the data handler to invoke for the synchronous response. The type is String and the default is xml/soap. |
Charset | None | This optional parameter of type String specifies the charset to be set on the data handler when transforming an outgoing business object to the message. NOTE: the charset value specified in this attribute will not be propagated in the Content-Type protocol header of the response message. |
Request
| ws_botype=request |
This attribute corresponds to a web service request. The connector uses its ASI to determine whether this TLO attribute is of type SOAP Request BO. This ASI, not the attribute name, determines the attribute type. If there is more than one request attribute, the connector uses the ASI of the first one. This attribute is required for synchronous event processing TLOs.
|
Response
| ws_botype=response |
This attribute corresponds to the response returned by a web service. The connector uses this ASI to determine whether this TLO attribute is of type SOAP Response BO. This ASI, not the attribute name, determines the attribute type. If there is more than one response attribute, the connector uses the ASI of the first one. This attribute is required for synchronous event processing TLOs.
|
Fault | ws_botype=fault
ws_botype=defaultfault |
This attribute, optional for synchronous event processing, corresponds to a
fault message returned by a collaboration when it cannot successfully populate
a response. The connector uses this ASI, not the attribute name, to
determine if the attribute is of type SOAP Fault BO.If
ws_botype=defaultfault,then the WSDL Configuration Wizard uses this
Fault business object for header processing. For further information,
see Header fault processing.
|
A Request business object is a child of a TLO and is required for synchronous event processing. A Request business object has object-level ASI. For example, if you open SERVICE_SYNCH_OrderStatus_Request in Business Object Designer and click the General tab, the object level ASI is displayed as shown in Figure 7.
Figure 7. Object-level ASI for synchronous event processing request object
The object-level ASI for a Request business object for synchronous event processing is described in Table 6. As shown in Figure 7, you can specify a default verb for the Request business object. You do so by specifying:
DefaultVerb=true;
in the ASI field for the verb in the Supported Verbs list at the
top-level of the Request business object. If DefaultVerb ASI
is not specified and the data handler processes a business object with no verb
set, the business object is returned without a verb.
Table 6. Synchronous event processing: object-level ASI for Request business objects
Object-level ASI | Description |
---|---|
cw_mo_soap=SOAPCfgMO | The value of this ASI must match the name of the attribute that
corresponds to the SOAP Config MO. This is the meta-object that defines
the data handler transformation for the Request business object. For
further information, see SOAP Config MO.
|
cw_mo_jms=SOAPJMSCfgMO
or cw_mo_http=SOAPHTTPCfgMO | The value of this ASI must match the name of the attribute that corresponds to the Protocol Config MO. The first ASI designates the SOAP/JMS protocol listener; the second designates the SOAP/HTTP or SOAP/HTTPS protocol listener. Both the ASI and the Protocol Config MO are optional. For further information, see Protocol Config MO. |
ws_tloname=tloname | This ASI specifies the name of the web services TLO that this object belongs to. During event processing, the connector uses this ASI to determine whether the Request business object delivered by the data handler is a child of the TLO. If so, the connector creates the specified TLO, sets the Request business object as its child, and uses the TLOs object-level ASI to deliver it to the subscribing collaboration. |
A Response business object is a child of a TLO and is required for
synchronous event processing. The object-level ASI for a Response
business object for synchronous event processing is described in Table 7.
Table 7. Synchronous event processing: object-level ASI for Response business objects
Object-level ASI | Description |
---|---|
cw_mo_soap=SOAPCfgMO | The value of this ASI must match the name of the attribute that corresponds to the SOAP Config MO. This is the SOAP Config MO that defines the data handler transformation for the Response business object. For further information, see SOAP Config MO. |
A Fault business object is a child of a TLO and is optional for synchronous
event processing. The object-level ASI for a Fault business object for
synchronous event processing is described in Table 8.
Table 8. Synchronous event processing: object-level ASI for Fault business objects
Object-level ASI | Description |
---|---|
cw_mo_soap=SOAPCfgMO | The value of this ASI must match the name of the attribute that corresponds to the SOAP Config MO. This is the SOAP Config MO that defines the data handler transformation for the Fault business object. For further information, see SOAP Config MO. |
Figure 8 shows a sample SOAP Config MO, expanded in Business Object Designer.
Figure 8. SOAP Config MO attributes for synchronous event processing
The SOAP Config MO defines the formatting behavior for one data handler transformation -- either a SOAP-message-to-business-object or business-object-to-SOAP-message transformation. Each Request, Response, and Fault attribute has a SOAP Config MO. Its attributes, BodyName, BodyNS, Style, Use, TypeInfo, TypeCheck and BOVerb, are always of type String. They correspond to SOAP message elements and their values determine how messages and objects are read and validated by the SOAP data handler. For more information on SOAP Config MOs and attributes, see SOAP configuration meta-object: child of every SOAP business object.. All SOAP Config MOs, whether for a request, response, or fault object, must have unique entries for default values of BodyName and BodyNS.
Figure 9 shows a JMS Protocol Config MO, whose attributes correspond to headers in the inbound SOAP message.
Figure 9. JMS Protocol Config MO attributes for synchronous event processing
This MO is optionally included as a child of the request, response, or fault business objects for event processing. Typically you specify it when you need to read (from request messages) or propagate (to response or fault messages) the protocol headers and custom properties. As noted above, the request business object optionally declares the name of the Protocol Config MO as business-object-level ASI:
During event processing, the connector uses protocol listeners (SOAP/HTTP,
SOAP/HTTPS or SOAP/JMS) to retrieve events from the transport. These
events are messages from internal or external web service clients requesting
service from collaborations that have been exposed as web services.
Each transport has its own header requirements. The connector uses the
Protocol Config MO to convey the protocol-specific header information from the
protocol listener to the collaboration. The Protocol Config MO
attributes correspond to headers in the inbound SOAP/JMS message. The
connector sets the value of these attributes in the business object using
inbound SOAP message content. For SOAP/JMS protocol, the Protocol
Config MO attributes for event and request processing are as follows:
Table 9. SOAP JMS Protocol Config MO attributes:event and request processing
SOAP/JMS Protocol Config MO attribute | JMSHeaderName | Description |
---|---|---|
CorrelationID | JMSCorrelationID | Inbound messages: this atrribute will be populated with the value
from JMSCorrelationID header.
Outbound messages: : the value from this attribute will be set as the JMSCorrelationID header of outgoing message. |
MessageId | JMSMessageId | Inbound messages: this atrribute will be populated with the value
from the JMSMessageId header.
Outbound messages: this attribute is not used for outbound messages. |
Priority | JMSPriority | Inbound messages: this atrribute will be populated with the value from the JMSPriority header. Outbound messages: the value from this attribute will be set in the JMSPriority header of outgoing message. |
Expiration | JMSExpiration | Inbound messages: this atrribute will be populated with the value from the JMSExpiration header. Outbound messages: the value from this attribute will be set in the JMSExpiration header of outgoing message. |
DeliveryMode | JMSDeliveryMode | Inbound messages: : this atrribute will be populated with the value from the JMSDeliveryMode header. Outbound messages: the value from this attribute will be set in the JMSDeliveryMode header of outgoing message. |
Destination | JMSDestination | Inbound messages: this atrribute will be populated with the value
from the JMSDestination header.
Outbound messages: Request processing the value from this attribute will be used as the destination queue name and will indirectly be set in the JMSDestination header of outgoing messages to the derived destination path. Synchronous response in event notification: this attribute is not used. |
Redelivered | JMSRedelivered | Inbound messages: this atrribute will be populated with the value from the JMSRedelivered header. Outbound messages: the value from this attribute will be set in the JMSRedelivered header of outgoing message.. |
ReplyTo | JMSReplyTo | Inbound messages: this atrribute will be populated with the value from the JMSReplyTo header. Outbound messages: the value from this attribute will be set in the JMSReplyTo header of outgoing message |
TimeStamp | JMSTimeStamp | Inbound messages: this atrribute will be populated with the value from the JMSTimeStamp header. Outbound messages: the value from this attribute will be set in the JMSTimeStamp header of outgoing message.. |
Type | JMSType | Inbound messages: this atrribute will be populated with the value
from the JMSType header.
Outbound messages: the value from this attribute will be set in the JMSType header of outgoing message. |
UserDefinedProperties | See User-defined properties for event processing. | This optional read/write attribute will hold the user-defined protocol properties business object. For further information, seeUser-defined properties for event processing. |
For SOAP/HTTP(S) protocol, the Protocol Config MO attributes are as
follows:
Table 10. HTTP/HTTPS Protocol Config MO Attributes for Event Processing
Attribute | Required | Type | Description |
---|---|---|---|
Content-Type | No | String | The value of this attribute defines the Content-Type header of the outgoing message (which includes message ContentType and 0 or more parameters --the charset-- for the outgoing message). The syntax is the same as that for the Content-Type header in the HTTP Protocol, for example: text/html; charset=ISO-8859-4. If there is no Content-Type attribute defined, the connector uses the ContentType of the request as the ContentType of the response/fault message. |
UserDefinedProperties | No | Business object | This attribute holds the user-defined protocol properties business object. |
One or more HTTP headers | No | String | This attribute allows the handler to pass or retrieve the value for the specified HTTP header. |
Authorization_UserID | No | String | This attribute corresponds to the userID of the HTTP basic authentication. |
Authorization_Password | No | String | This attribute corresponds to the password of the HTTP basic authentication |
These attributes are described in:
For further information on protocol listeners, see Protocol listeners.(For information describing the Protocol Config MO for request processing, see Synchronous request processing TLOs).
You can optionally specify custom properties in the HTTP(S) Protocol Config MO. You do so by including the UserDefinedProperties attribute. This attribute corresponds to a business object that has one or more child attributes with property values. Every attribute in this business object must define a single property to be read (or, for synchronous responses, written) in the variable portion of the message header as follows:
Table 11summarizes the application-specific information for these
attributes.
Name | Value | Description |
---|---|---|
ws_prop_name (case-insensitive; if not specified the attribute name will be used as the property name | Any valid protocol property name | This is the name of the protocol property. Some vendors reserve certain properties to provide extended functionality. In general, you should not define custom properties that begin with JMS (for JMS protocol) unless you are seeking access to these vendor-specific features. |
ws_prop_type (case insensitive, optional for JMS - if not specified String is assumed; irrelevant for HTTP(S) since only String types make sense) | String, Integer, Boolean, Float, Double, Long, Short | The type of the protocol property. For JMS protocol, the JMS API provides a number of methods for setting property values in the JMS Message: setIntProperty, setLongProperty, setStringProperty, etc. The type of the JMS property specified here dictates which of these methods will be used for setting the property value in the message. |
If the given custom property ASI (either the ws_prop_name or ws_prop_type) is invalid and there is no logical way to process this header (such as ignoring the property type for HTTP processing), the connector logs a warning and ignores this property. If the value of the custom property can neither be set nor retrieved after the necessary check against ws_prop_name or ws_prop_type has been performed, the connector logs the error and fails the event.
If the UserDefinedProperties attribute is specified, the connector will create an instance of a UserDefinedProperties business object. The connector then attempts to extract property values from the message and store them in the business object. If at least one property value is successfully retrieved, the connector will set a modified UserDefinedProperties attribute in the Protocol Config MO.
For synchronous event processing, if a UserDefinedProperties attribute is specified and its business object is instantiated, the connector will process each attribute of this child business object and set the message property value accordingly.
For the purpose of credential propagation, the connector supports the Authorization_UserID and Authorization_Password attributes in the HTTP Protocol Config MO. The support is limited to the propagation of these credentials as part of the HTTP Basic authentication scheme.
If a SOAP/HTTP or SOAP/HTTPS protocol listener processes a SOAP/HTTP web service request that includes an authorization header, the listener will parse the header to determine whether it conforms to HTTP Basic authentication. If so, the listener extracts and decodes (using Base64) the username and password. This decoded string consists of a username and password separated by a colon. If the protocol listener finds the Authorization_UserID and Authorization_Password attributes in the Protocol Config MO, the listener sets these values with those extracted from the event authorization header.
Figure 10 shows the expanded header container attribute, OrderHeader.
Figure 10. Header container and child business objects
The header container attribute, also known as the SOAP header attribute, corresponds to a business object that contains only child business objects. Each child represents a header entry in the SOAP message. In the example shown in Figure 10, the request header container is OrderHeader. SOAP header attributes have application-specific information (ASI) required by the SOAP data handler. For example, a header container business object is identified by its ASI: soap_location=SOAPHeader. For information on header processing, see SOAP data handler processing.
All SOAP business objects, whether a Request, Response, or Fault object, have one and only one header container.
In the example shown Figure 10, the two child attributes of the request header container (OrderHeader) are 1) transaction of type SERVICE_SYNCH_OrderStatus_TransactionHeaderChild and 2) affiliate of type SERVICE_SYNCH_OrderStatus_TradingPartnerHeaderChild. These attributes correspond to header child business objects. Each represents a single header element in a SOAP message. The header element is an immediate child of the SOAP-Env:Header element of the SOAP message. As shown Figure 10, the header child business objects may have an actor and a mustUnderstand attribute. These attributes correspond to the actor and mustUnderstand attributes of the SOAP header element. For information on header processing, see SOAP data handler processing.
There may be as many header child objects as are needed to represent the SOAP header message elements.
Figure 11 shows the business object hierarchy for asynchronous event processing. A request object only is required.
Figure 11. Business object hierarchy for asynchronous event processing
The TLO contains object-level ASI as well as attributes with attribute-level ASI. Both kinds of ASI are discussed below. For information on the header container and header child business objects, see Header container business objects.
Object-level ASI provides fundamental information about the nature of a TLO and the objects it contains. Figure 12 shows the object-level ASI for SERVICE_ASYNCH_TLO_Order, a sample TLO for asynchronous event processing.
Figure 12. Top-level business object for asynchronous event processing
Table 4 below describes the object-level ASI for an asynchronous
event processing TLO.
Table 12. Asynchronous event processing TLO object ASI
Object-level ASI | Description |
---|---|
ws_eventtlo=true |
If this ASI property is set to true, the connector treats this object as a TLO for event processing. Note that the WSDL Configuration Wizard uses this ASI to determine whether
a business object is a TLO. For more on this see WSDL Configuration Wizard.
|
ws_verb=verb |
Before delivering the TLO to the collaboration, the connector uses this ASI
to set the verb on the TLO. In the sample shown inFigure 12, the verb is Create.
|
ws_mode=asynch |
During event notification, the connector uses this ASI property to determine whether to invoke the collaboration synchronously (synch) or asynchronously (asynch). For asynchronous processing, this ASI must be set to asynch. The default is asynch.
|
Each asynchronous event processing TLO has a single attribute that corresponds to a Request business object. Figure 13 shows the request attribute of SERVICE_ASYNCH_TLO_Order, a sample TLO, and the attribute's ASI.
Figure 13. TLO attribute for asynchronous event processing
Table 13 summarizes the attribute-level ASI for the request attribute
of an asynchronous event processing TLO.
Table 13. Asynchronous event processing TLO attribute ASI
TLO attribute | Attribute-level ASI | Description |
---|---|---|
Request
| ws_botype=request |
This attribute corresponds to a web service request. The connector uses its ASI to determine whether this TLO attribute is of type SOAP Request BO. This ASI, not the attribute name, determines the attribute type. If there is more than one request attribute, the connector uses the ASI of the first one. This attribute is required for synchronous event processing TLOs.
|
A Request business object is a child of a TLO and is required for asynchronous event processing. You can specify a default verb for the Request business object. You do so by specifying:
DefaultVerb=true;
in the ASI field for the verb in the Supported Verbs list at the
top-level of the Request business object. If DefaultVerb ASI
is not specified and the data handler processes a business object with no verb
set, the business object is returned without a verb. The object-level
ASI for a Request business object for asynchronous event processing is
described in Table 14.
Table 14. Asynchronous event processing: object-level ASI for Request business objects
Object-level ASI | Description |
---|---|
cw_mo_soap=SOAPCfgMO | The value of this ASI must match the name of the attribute that corresponds to the SOAP Config MO. This is the SOAP Config MO that defines the data handler transformation for the Request business object. For further information, see SOAP Config MO. |
cw_mo_jms=SOAPJMSCfgMO
or cw_mo_http=SOAPHTTPCfgMO | The value of this ASI must match the name of the attribute that corresponds to the Protocol Config MO. The first ASI designates the SOAP/JMS protocol listener; the second designates the SOAP/HTTP or SOAP/HTTPS protocol listener. Both the ASI and the Protocol Config MO are optional. For further information, see Protocol Config MO. |
ws_tloname=tloname | This ASI specifies the name of the web services TLO that this object belongs to. During event processing, the connector uses this ASI to determine whether the Request business object delivered by the data handler is a child of the TLO. If so, the connector creates the specified TLO, sets the Request business object as its child, and uses the TLOs object-level ASI to deliver it to the subscribing collaboration. |
In the sample shown in Figure 14, the Request attribute contains a SOAP Config MO and header container (OrderHeader), as well as a content-related attribute (OrderLineItems). The requirements and characteristics of the SOAP Config MO, Protocol Config MO, SOAP header container, and header child business objects are the same for asynchronous event processing as they are for synchronous event processing. For further information, see these topics above in Synchronous event processing TLOs.
Figure 14. Request attributes for asynchronous event processing
If the object-level ASI ws_eventtlo=true is not present in a business object, the connector concludes that the object is not a TLO. During event processing, the connector can process non-TLOs--generic business objects and application specific business objects. With non-TLOs, the same business object represents the Request and Response business object.
Non-TLOs do not have SOAP Config MOs. When you expose a collaboration as a web service, the WSDL Configuration Wizard configures the WSCollaborations property of the connector. The connector uses the WSCollaborations property to determine the BodyName and BodyNS of the request message. Note that for non-TLOs, the WSCollaborations property is used for business object resolution.
The advantage to using non-TLOs is that you need not develop new, TLO-structured business objects for use with your web services solution. TLOs, however, allow a more precise and economical exposure of data--customer, company, or otherwise. TLO business objects also lend themselves to more customization than do non-TLOs.
For further information on requirements when using non-TLOs as input to the WSDL Configuration Wizard, see Identifying or developing Business Objects.
For request processing the connector allows two kinds of TLOs--synchronous and asynchronous. This section discusses synchronous request processing TLOs.
Figure 15 shows the TLO business object hierarchy for synchronous request processing. Request and Response objects are required, Fault objects are optional. Unlike event processing, a Protocol Config MO is required for the Request objects, and optional for the Response and Fault objects. For information on the header container and header child business objects, see Header container business objects.
Figure 15. Business object hierarchy for synchronous request processing
Object-level ASI provides important information about the nature of a TLO and the objects it contains. Figure 16 shows CLIENT_SYNCH_TLO_OrderStatus, a sample TLO for synchronous request processing.
Figure 16. Top-level business object for synchronous request processing
Table 15 describes the object-level ASI for a synchronous request
processing TLO. Unlike the ASI for synchronous event processing TLOs,
no ws_collab, ws_verb or ws_eventtlo ASI is
required at this level for request processing.
Table 15. Synchronous request processing TLO object ASI
Object-level ASI | Description |
---|---|
ws_mode=synch |
During request processing, the connector uses this ASI property to determine whether to invoke the web service synchronously (synch) or asynchronously (asynch). If synch is indicated, then the connector expects a response, and the TLO must include request and response business objects and, optionally, one or more fault objects. The default is asynch.
|
Figure 17 shows the attributes of the CLIENT_SYNCH_TLO_OrderStatus TLO as well as attribute-level ASI.
Figure 17. TLO attributes for synchronous request processing
Table 16 describes the attributes and ASI shown in Figure 17.
Table 16. Request processing TLO attributes
TLO attribute | Attribute-level ASI | Description |
---|---|---|
MimeType | None |
This attribute specifies the mime type of the data handler that the
connector invokes for transforming a Request business object into a request
message. This value may be used for transforming synchronous
response/fault messages into business objects, depending on the Message
Transformation Rules configuration.
|
BOPrefix | None | This attribute of type String is passed to the data handler. |
Handler | None | This attribute specifies the protocol handler to use to process the web
service request and is for request processing only. It takes one of the
following values:
The default is soap/http |
Charset | None | This optional parameter of type String specifies the charset to be set on the data handler when transforming the Request business object to a message. NOTE: the charset value specified in this attribute will not be propagated in the Content-Type protocol header of the request message. |
Request
| ws_botype=request |
This attribute corresponds to a web service request business object.
The connector uses this attribute ASI to determine whether this TLO attribute
is of type SOAP Request BO. This ASI, not the attribute name,
determines the attribute type. If there is more than one request
attribute, the connector uses the ASI of the first populated attribute.
|
Response
| ws_botype=response |
This attribute corresponds to the response returned to a collaboration and
is required for synchronous request processing. The connector uses this
attribute ASI to determine whether this TLO attribute is of type SOAP Response
BO. This ASI, not the attribute name, determines the attribute
type.
|
Fault
| ws_botype=fault
or ws_botype=defaultfault | This attribute, optional for synchronous request processing, corresponds
to a fault message returned by a web service when it cannot successfully
populate a response.
The connector uses this ASI to determine if the attribute of TLO is of type SOAP Fault BO. This ASI, not the attribute name, determines the attribute type. A defaultfault business object is returned if the fault message is a detail element. defaultfault is used in default business object resolution. For further information, see SOAP data handler. |
A Request business object is a child of a TLO and is required for synchronous request processing. A Request business object has object-level ASI.
For example, if you open CLIENT_SYNCH_OrderStatus_Request and click the General tab, the object-level ASI is displayed as shown in Figure 18.
Figure 18. Request object ASI for synchronous request processing
Table 17 describes the object-level ASI for a Request business object for synchronous request processing.
Table 17. Synchronous request processing: object-level ASI for Request business objects
Object-level ASI | Description |
---|---|
cw_mo_soap=SOAPCfgMO | The value of this ASI must match the name of the attribute that
corresponds to the SOAP Config MO. This is the SOAP Config MO that
defines the data handler transformation for the Request business
object. For further information, see SOAP Config MO.
|
cw_mo_jms=SOAPJMSCfgMO | The value of this ASI must match the name of the attribute that corresponds to the Protocol Config MO. This is the Protocol Config MO that specifies the destination web service for the JMS protocol handler. For further information, see JMS Protocol Config MO of request business object for request processing. |
cw_mo_http=SOAPHTTPCfgMO | The value of this optional ASI must match the name of the attribute that corresponds to the Protocol Config MO. This is a separate Protocol Config MO that specifies the destination for the SOAP/HTTP-HTTPS protocol handler. This ASI is used by the SOAP/HTTP and SOAP/HTTPS Protocol Handler. Note that the TLO request attribute must have either a JMS or an HTTP Protocol Config MO for request processing, depending on the type of web service protocol you are using. For further information, see HTTP Protocol Config MO for request processing. |
SOAPAction=SOAPActionURI | The connector uses this ASI to determine whether to set a SOAPAction header on the request message. Specify this ASI only if the target web service requires a SOAPAction header. Note that this ASI is used for request processing but not for event notification. |
A Response business object is a child of a TLO and is required for
synchronous request processing. The object-level ASI for a Response
business object for synchronous request processing is described in Table 18.
Table 18. Synchronous request processing: object-level ASI for response business objects
Object-level ASI | Description |
---|---|
cw_mo_soap=SOAPCfgMO | The value of this ASI must match the name of the attribute that corresponds to the SOAP Protocol Config MO. This is the SOAP Config MO that defines the data handler transformation for the Response business object. For further information, see SOAP Config MO. |
cw_mo_jms=SOAPJMSCfg MO
or cw_mo_http=SOAPHTTPCfgMO | The value of this ASI must match the name of the attribute that corresponds to the Protocol Config MO. This is the Protocol Config MO, optional for a Response business object, that specifies the headers in the response SOAP message for the JMS or HTTP(s) protocol handler. For further information, see Protocol Config MO |
You can specify a default verb for the Response business object. You do so by specifying:
DefaultVerb=true;
in the ASI field for the verb in the Supported Verbs list at the top-level of the Response business object. If DefaultVerb ASI is not specified and the data handler processes a business object with no verb set, the Response business object is returned without a verb.
A Fault business object is a child of a TLO and is optional for synchronous
request processing. The object-level ASI for a Fault business object
for synchronous request processing is described in Table 8.
Table 19. Synchronous request processing: object-level ASI for Fault business objects
Object-level ASI | Description |
---|---|
cw_mo_soap=SOAPCfgMO | The value of this ASI must match the name of the attribute that corresponds to the SOAP Protocol Config MO. This is the SOAP Config MO that defines the data handler transformation for the Fault business object. For further information, see SOAP Config MO. |
cw_mo_jms=SOAPJMSCfg MO
or cw_mo_http=SOAPHTTPCfgMO | The value of this ASI must match the name of the attribute that corresponds to the Protocol Config MO. This is the Protocol Config MO, optional for a Fault business object, that specifies the headers in the response SOAP message for the JMS protocol handler. For further information, see Protocol Config MO |
The SOAP Config MO (SOAPCfgMO) has the same attributes as those for the event processing SOAP Config MO. For further information, see SOAP Config MO.as well as SOAP configuration meta-object: child of every SOAP business object.
The JMS Protocol Config MO is required in a Request business object when
you are using JMS web services, and optional for Response and Fault
objects. Table 20 describes the request processing JMS Protocol Config
MO--Destination is the most important and only required attribute.
The JMS protocol handler uses this attribute to locate the requested web
service. In addition, all the attributes described for the JMS Config
MO in Protocol Config MO are optional.
Table 20. JMS Protocol Config MO Attributes for Request Processing
Attribute | Required | Type | Description |
---|---|---|---|
Destination | Yes | String | The destination queue name of the target web service. The JMS Protocol Handler uses this attribute to determine the destination of the web service. If the connector-specific JNDI property LookupQueuesUsingJNDI is set to true, the JMS Protocol Handler looks up this queue using JNDI. Make sure that this attribute gives the JNDI name of the destination queue. |
During request processing, the SOAP/HTTP-HTTPS protocol handlers use the
HTTP Protocol Config MO to determine the destination of the target web
service. This Protocol Config MO is required for a Request business
object. The SOAP/HTTP-HTTPS protocol handlers support HTTP 1.0
POST request only. As shown in Table 21 the sole required attribute (Destination) is the full URL of
the target web service. The optional authorization attributes are
described in the sections below.
Table 21. HTTP Protocol Config MO Attributes for Request Processing
Attribute | Required | Type | Description |
---|---|---|---|
Destination | Yes | String | The destination URL of the target web service. The SOAP/HTTP-HTTPS protocol handler uses this attribute to determine the destination of the web service. |
Content-Type | Required for the Request business object, otherwise optional. | String | The value of this attribute defines the Content-Type header of the outgoing message (which includes message ContentType and optionally charset for the outgoing message). The syntax is the same as that for the Content-Type header in the HTTP Protocol, for example: text/html; charset=ISO-8859-4. If there is no Content-Type attribute defined, the connector uses text/xml as the ContentType of the message. |
Authorization_UserID | No | String | This attribute corresponds to the userID of the HTTP basic authentication. For further information, see HTTP credential propagation for request processing |
Authorization_Password | No | String | This attribute corresponds to the password of the HTTP basic authentication. For further information, see HTTP credential propagation for request processing |
One or more HTTP headers | No | String | This attribute allows the handler to pass or retrieve the value for the specified HTTP header. |
UserDefinedProperties | No | Business object | This attribute holds the user-defined protocol properties business object. For further information, see User-defined properties for request processing. |
MessageTransformationMap | No | Single cardinality business object | This is the attribute that points to business object holding 0 or more message transformation rules. The rules hold information regarding the mime type and charset to apply to the incoming message that is specified in the rule. For further information, see Message transformation maps. |
Figure 19 shows some of the HTTP Protocol Config MO attributes in Business Object Designer.
Figure 19. HTTP Protocol Config MO attributes for request processing
The HTTP Protocol Config MO attributes are described in:
You can optionally specify custom properties in the HTTP Protocol Config MO. You do so by including the UserDefinedProperties attribute. This attribute corresponds to a business object that has one or more child attributes with property values. Every attribute in this business object must define a single property to be read (or, for synchronous responses, written) in the variable portion of the message header as follows:
Table 22 summarizes the application-specific information for these
attributes.
Name | Value | Description |
---|---|---|
ws_prop_name (case-insensitive; if not specified the attribute name will be used as the property name | Any valid protocol property name | This is the name of the protocol property. Some vendors reserve certain properties to provide extended functionality. In general, you should not define custom properties that begin with JMS (for JMS protocol) unless you are seeking access to these vendor-specific features. |
ws_prop_type (case insensitive, optional for JMS - if not specified String is assumed; irrelevant for HTTP(S) since only String types make sense) | String, Integer, Boolean, Float, Double, Long, Short | The type of the protocol property. For JMS protocol, the JMS API provides a number of methods for setting property values in the JMS Message: setIntProperty, setLongProperty, setStringProperty, etc. The type of the JMS property specified here dictates which of these methods will be used for setting the property value in the message. |
If the given custom property ASI (either the ws_prop_name or ws_prop_type) is invalid and there is no logical way to process this header (such as ignoring the property type for HTTP processing), the connector logs a warning and ignores this property. If the value of the custom property can neither be set nor retrieved after the necessary check against ws_prop_name or ws_prop_type has been performed, the connector logs the error and fails the event.
If the UserDefinedProperties attribute is specified and its business object is instantiated, the connector processes each attribute of this child business object and sets the message properties values accordingly.
For synchronous request processing, upon receipt of a response message from the web service/url, if the UserDefinedProperties attribute is specified, the connector creates an instance of a UserDefinedProperties business object and attempts to extract property values from the message and then stores them in the new business object. If at least one property value was successfully retrieved, the connector will set modified UserDefinedProperties business object in the Protocol Config MO.
The Message Transformation Map (MTM) feature is supported for request processing HTTP(S) protocol handlers only. MessageTransformationMap is an optional attribute in the Protocol Config MO that points to a business object. The business object contains rules for transforming messages with mime types and charsets that are specified in the rules. If it finds the (case-sensitive) attribute name MessageTransformationMap and this attribute is of the business object type (see Figure 19), the connector uses the rules in that object to transform a message.
As shown inFigure 19, the MTM attribute must have one cardinality N child business object attribute that is named TransformationRule. When trying to find TransformationRule for a message, the SOAP/HTTP(s) Protocol Handler first attempts to match the message exactly by the ContentType specified in all TransFormationRules. If unsuccessful, the connector attempts to find the rule that applies to multiple types of messages. For further information on protocol handler processing, see SOAP/HTTP-HTTPS protocol handler processing.
Each instance of a TransformationRule business object must have attributes
specified as shown in Table 23.
Table 23. TransformationRule attributes for MessageTransformationMaps in HTTP Protocol Config MO
Attribute name | Required | Type | Default value | Description |
---|---|---|---|---|
TransformationRule | No | Business object, cardinality N | None | This is the attribute that holds 1 rule for message transformation. There can be 0 or more instances of this attribute under the MessageTranformationMap attribute. |
+ContentType | Yes | String | */* | The value of this property specifies the HTTP ContentType of the message for which this transformation rule applies. The default value */* for this attribute enables the connector to apply this rule to any ContentType. For further information on protocol handler processing, see SOAP/HTTP-HTTPS protocol handler processing.Note that if Protocol Handler finds more than one rule that has the same ContentType as the other rule, Protocol Handler will log the warning and ignore all duplicate rules, but will use unique rules |
+MimeType | No | String | None | The mime type to use when calling a data handler while processing messages of the ContentType specified in this business object. |
+Charset | No | String | None | The charset to use when transforming a request of the ContentType specified in this business object. |
For the purpose of credential propagation, the connector supports the Authorization_UserID and Authorization_Password attributes in the HTTP Protocol Config MO. The support is limited to the propagation of these credentials as part of the HTTP Basic authentication scheme.
If credential propagation is desired during request processing, you must manually add the Authorization_UserID and Authorization_Password attributes to the Protocol Config MO generated by the WSDL ODA. You do this in Business Object Designer after generating the business object and meta-object definitions. (For further information on the WSDL ODA, see Enabling collaborations for request processing.)
The collaboration sets the values of the Authorization_UserID and Authorization_Password attributes in the Protocol Config MO. If these attributes are neither null nor empty, the connector creates an authorization header on the request its sends to the to the target web service. The SOAP HTTP/HTTPS protocol handler follows HTTP Authentication: Basic and Digest Access Authentication (RFC 2617) when creating the authorization header.
Figure 20 shows the business object hierarchy for asynchronous request processing. A request object only is required, and this object contains a SOAP Config MO for the SOAP data handler as well as two Protocol Config MOs, one each for the SOAP/JMS and SOAP/HTTP/HTTPS protocol handlers. These are described in the sections below.
Figure 20. Business object hierarchy for asynchronous request processing
The TLO contains object-level ASI as well as attributes with attribute-level ASI. Both kinds of ASI are discussed below. For information on the header container and header child business objects, see Header container business objects.
Figure 21 shows CLIENT_ASYNCH_Order_TLO, a sample TLO for asynchronous request processing.
Figure 21. Top-level business object for asynchronous request processing
Table 24 below describes the object-level ASI for an asynchronous
request processing TLO.
Table 24. Asynchronous request processing TLO object ASI
Object-level ASI | Description |
---|---|
ws_mode=asynch |
During request processing, the connector uses this ASI property to determine whether to invoke the collaboration synchronously (synch) or asynchronously (asynch). For asynchronous request processing, this ASI must be set to asynch. The default is asynch.
|
Figure 22 shows the attributes of the CLIENT_ASYNCH_TLO_Order, a sample request processing TLO.
Figure 22. TLO attributes for asynchronous request processing
Table 25 summarizes the attribute-level ASI for the request attribute
of an asynchronous request processing TLO.
Table 25. Asynchronous request processing TLO attributes
TLO attribute | Attribute-level ASI | Description |
---|---|---|
MimeType | None |
This attribute specifies the mime type of the data handler that the
connector invokes. Note that this attribute is used only for Request
Processing. (For event processing, protocol listeners use the
SOAPDHMimeType connector-specific configuration property.) The default
is xml/soap.
|
BOPrefix | None | This attribute of type String is reserved for future development and not required. |
Handler | None | This attribute specifies the protocol handler to use to process the web
service request and is for request processing only. It takes one of the
following values:
The default is soap/http |
Request
| ws_botype=request |
This attribute corresponds to a web service request business object.
The connector uses this attribute ASI to determine whether this TLO attribute
is of type SOAP Request BO. This ASI, not the attribute name,
determines the attribute type. If there is more than one request
attribute, the connector uses the ASI of the first one.
|
A Request business object is a child of a TLO and is required for asynchronous request processing. The object-level ASI for a Request business object for asynchronous request processing is described inTable 26.
Table 26. Asynchronous request processing: object-level ASI for Request business objects
Object-level ASI | Description |
---|---|
cw_mo_soap=SOAPCfgMO | The value of this ASI must match the name of the attribute that
corresponds to the SOAP Config MO. This is the SOAP Config MO that
defines the data handler transformation for the Request business
object. For further information, see SOAP Config MO.
|
cw_mo_jms=SOAPJMSCfgMO | The value of this ASI must match the name of the attribute that corresponds to the Protocol Config MO. This is the Protocol Config MO that specifies the destination web service for the JMS protocol handler. For further information, see JMS Protocol Config MO of request business object for request processing. |
cw_mo_http=SOAPHTTPCfgMO | The value of this ASI must match the name of the attribute that corresponds to the Protocol Config MO. This is a separate Protocol Config MO that specifies the destination for the SOAP/HTTP-HTTPS protocol handler. This ASI is used by the SOAP/HTTP-HTTPS Protocol Handler. Note that the TLO request attribute must have both JMS and HTTP Protocol Config MOs for request processing. For further information, see HTTP Protocol Config MO for request processing. |
SOAPAction=SOAPActionURI | The connector uses this ASI to determine whether to set a SOAPAction header on the request message. Specify this ASI only if the target web service requires a SOAPAction header. Note that this ASI is used for request processing but not for event notification. |
In the sample shown in Figure 14, the Request attribute contains a SOAP Config MO and header container (OrderHeader), as well as a content-related attribute (OrderLineItems). The requirements and characteristics of the SOAP Config MO, Protocol Config MO, SOAP header container, and header child business objects are the same for asynchronous request processing as they are for synchronous request processing. For further information, see these topics above in Synchronous request processing TLOs..
Figure 23. Request attributes for asynchronous event processing
The SOAP Config MO (SOAPCfgMO) has the same attributes as those for the event processing SOAP Config MO. For further information, see SOAP Config MO. as well as SOAP configuration meta-object: child of every SOAP business object.
The JMS Protocol Config MO is required in a Request business object when you are using JMS web services. For further information, see JMS Protocol Config MO of request business object for request processing.
During request processing, the SOAP/HTTP-HTTPS protocol handlers use the HTTP Protocol Config MO to determine the destination of the target web service. This Protocol Config MO is required for a Request business object. For further information, see HTTP Protocol Config MO for request processing.