OAGIS document processing

During OAGIS document processing, the developer developing the client library and the component facade needs to be aware of the following concepts:

  • Using the BusinessContext data area
  • Using control parameters
  • Returning error information
  • Correlating the request and the response when using asynchronous messaging

Using the BusinessContext data area

As part of the WebSphere Commerce transition to OAGIS interactions, a substitution group for the ApplicationArea of the OAGIS BusinessObjectDocumentType has been created for the purpose of adding business context information as part of the message. The purpose of this extended ApplicationArea is to provide a common definition of how language, currency, store, and other common business context information are passed into WebSphere Commerce.

Business context data is distinct from the user's security context. It is assumed that the security context is managed by the runtime environment (either the WebSphere Commerce runtime environment or the WebSphere runtime environment). In the case of WebSphere Commerce, the security context is established by the solution controller for local requests and based on the security token in the SOAP header for Web service requests.

Note: Business context data is optional. There are many integration scenarios where context data is not passed in or out. Context data can be specified in the service command, either overriding what was passed in or providing a default value for scenarios where the value was not passed in.
Supported context data:
Context Attribute Description Example
locale The locale under which the request should be implemented. "en_US"
storeId The WebSphere Commerce store identifier. 10001
langId The language identifier -1
forUser The logonId of the user to switch to for this request. wcsadmin
forUserId The userId of the user to switch to for this request. 12345
forStoreId The store to switch to for this request. 10001
catalogID The catalog identifier. 10001

BusinessContext data format:

The purpose of the business context data is to allow the client to specify the context of the request. The client should maintain the set of context data required for each BOD request and include it when issuing the request. The business context data is in clear text and is not considered sensitive data. By using externally identifiable context data, this data can be used by mediation when integrating with other systems.

Context data is passed in the clear to enable messages to be transformed from OAGIS to another message style for an enterprise service bus (ESB) type integration. If the business context data is encrypted, it becomes impossible to map the context data, and to use ESB technology for integration.

The schema is depicted graphically in the following diagram:

ApplicationArea

The following Java code sample shows how to specify the storeId in the BusinessContext element of the ApplicationArea of the request:


aBusinessContext =
CommerceFoundationFactory.eINSTANCE.createBusinessContextType();
ContextDataType cStoreId =
CommerceFoundationFactory.eINSTANCE.createContextDataType();
cStoreId.setName("storeId");
cStoreId.setValue("10001");
aBusinessContext.getContextData().add(cStoreId);

Using control parameters

There are cases where the caller of a service interface needs to pass extra parameters (which are not part of the noun) so that the correct business logic can be performed on the WebSphere Commerce Server. For example, merge, reverse, allocate, and check are ATP parameters in the OrderItemAddCmd command to control the inventory behavior when adding an order item.

These types of parameters should be specified in the WebSphere Commerce XPath (stored in the ActionExpression or SelectionExpression of the verb). All the parameters should start with a special prefix which is the same as the component schema prefix (for example, _ord). The following sample shows how to pass the "allocate " and "reverse" parameters for all OrderItems (signified by the *) in the ChangeOrder BOD for OrderItemAddCmd:


{_ord.reverse='*';_ord.allocate='*'}/Order[1]/OrderItem[1]

Correlating the request and the response when using asynchronous messaging

From the perspective of a component, it does not know if the protocol used is Web services, native JMS, SMTP or any other protocol. This binding information is all controlled by the configuration of the communication service layer for that particular component. However, the client does know whether the communication is synchronous or asynchronous.

OAGIS messages are designed to be delivered synchronously or asynchronously. To support asynchronous communication, there must be a way to correlate request and response messages.

The OAGIS message structure provides a BODID in the Application Area. The WebSphere Commerce runtime environment (and client library for client communication) generates a GUID and set it in the BODID on every request. Because the client code does not know the transport type, a BODID is generated for every request.

"Sync" requests are typically delivered by Asynchronous messaging with guaranteed delivery. This is appropriate because "Sync" operations are designed to be broadcast to all interested parties. This means that a synchronous point-to-point interaction is not required because the system of record does not need to wait for a response to the request.