Connector business object structure

The connector processes two kinds of business objects:

Note:
SOAP header container and header business objects, which are included in Request, Response, and Fault business objects, are not discussed in this chapter. For information on SOAP header container and header business objects, see SOAP data handler.

Synchronous event processing TLOs

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 for synchronous event processing TLOs

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.

Attribute-level ASI for synchronous event processing TLOs

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
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
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.

Request business object for synchronous event 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.

Response business object for synchronous event processing

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.

Note:
You can optionally include a Protocol Config MO object-level ASI for the Response BO.

Fault business object for synchronous event processing

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.

Note:
You can optionally include a Protocol Config MO object-level ASI for the Fault BO.

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.

Protocol Config MO

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.

Note:
It is the responsibility of the collaboration to ensure that the header values passed to the JMS Protocol Config MO are logically correct in the context of a request-response event.

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).

User-defined properties for event processing

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.

Table 11. Application-specific information for user-defined protocol property attributes: name=value pair content

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.

HTTP credential propagation for event processing

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.

Header container business objects

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.

Header child business objects

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.

Asynchronous event processing TLOs

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 for asynchronous event processing TLOs

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.

Note:
Unlike synchronous event processing, no collaboration name ASI is required at the TLO level for asynchronous event processing. Instead the integration broker assures that application events reach all subscribing collaborations.

Attribute-level ASI for asynchronous event processing TLOs

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.

Request business object for asynchronous event processing

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


Event processing non-TLOs

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.

Synchronous request processing TLOs

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 for synchronous request processing TLOs

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.

Attribute-level ASI for synchronous request processing TLOs

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:
  • soap/jms The connector uses the SOAP/JMS protocol handler to process the request
  • soap/http The connector uses the SOAP/HTTP, SOAP/HTTPS protocol handler to process this web service request.

The default is soap/http

Charset
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.

Request business object for synchronous request processing

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.

Response business object for synchronous request processing

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.

Fault business object for synchronous request processing

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

SOAP 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.

JMS Protocol Config MO of request business object for request processing

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.

HTTP Protocol Config MO 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. 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:

User-defined properties for request processing

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 22summarizes the application-specific information for these attributes.

Table 22. Application-specific information for user-defined protocol property attributes: name=value pair content

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.

Message transformation maps

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
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

The mime type to use when calling a data handler while processing messages of the ContentType specified in this business object.
+Charset No

The charset to use when transforming a request of the ContentType specified in this business object.

HTTP credential propagation for request processing

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.

Note:
The digest authentication scheme is not be supported, nor is the optional challenge-response mechanism for HTTP authentication defined in Rfc2617. If the HTTP(s) protocol handler is invoking a server that requires a credential, the connector does not wait for the challenge response from the server. Instead, it sends the credentials continuously.

Asynchronous request processing TLOs

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.

Object-level ASI for asynchronous event processing TLOs

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.

Attribute-level ASI for asynchronous request processing TLOs

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:
  • soap/jms The connector uses the SOAP/JMS protocol handler to process the request
  • soap/http The connector uses the SOAP/HTTP-HTTPS protocol handler to process this web service request.

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.

Request business object for asynchronous request processing

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


Config MOs for asynchronous request 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.

Copyright IBM Corp. 1997, 2004