WebSphere Commerce use of Open Applications Group (OAGIS) messaging
WebSphere Commerce service interfaces are defined using the OAGIS message structure, from The Open Applications Group. The OAGIS standard provides a consistent message structure and model for messaging using XML. The OAGIS standards describe Business Object Documents (BODs) as nouns and the services that interact with those nouns are called verbs.Business Object Documents
The Business Object Document (BOD) is an open standard for a common horizontal message architecture developed by the Open Applications Group ( http://www.openapplications.org). BODs are business messages exchanged between software applications or components.
A BOD is a message structure that contains an application area and a data area to operate on. The application area of the BOD describes the application context to associate with the processing. The application area will associate specific application context information to control the processing and indicate application context when returning the result. In the context of a WebSphere Commerce service, the application area is where store, language and other session type data will be found. This information is common across all component facades and will use this information during processing.
The data area contains the service operation (Verb) and the business object of the operation on (Noun). The verb will indicate what operation to perform or the response of the service operation. In the case of a request, it will contain details of the operation and in the case of a response, it will contain information pertaining to the response. The noun represents the data contained in the business object pertaining to the request or response.
The Business Object Document architecture is independent of the communication mechanism, and can be used with many transport mechanisms.
WebSphere Commerce use of OAGIS
Although the OAGIS style of interaction is used, only the OAGIS message envelope and verbs have been adopted by WebSphere Commerce. Simplified nouns which better represent the structure of how the business objects are modeled in WebSphere Commerce have been provided. Although OAGIS may provide a noun definition for the same business object, WebSphere Commerce only supports a small percentage of the structure OAGIS provides. Instead of reusing the OAGIS definition with limited support, WebSphere Commerce has defined business objects which better represent what is supported. The OAGIS verbs used include:
- Get Request and the Show Response
- Process Request and the Acknowledge Response
- Change Request and the Respond Response
- Sync Request and the ConfirmBOD Response
File structure
All extensions to the OAGIS schema are placed in the Overlays directory of the OAGIS directory. The WebSphere Commerce extensions are found in the IBM/Commerce sub directory of the Overlays directory. If we are performing additional customizations, place them in the Company Name/Commerce sub directory of the Overlays directory (for example MyCompany/Commerce). This will clearly indicate where the definition originated from.
Note: All new WebSphere Commerce services are installed in the component-services subdirectory of the WebServicesRouter project. These services are optional and are placed in a separate directory to avoid conflict with existing services. The directory structure for overlays is described in this table:
| WebSphere Commerce assets | |
|---|---|
| Customized assets | |
| Business Object Documents | /OAGIS/9.0/Overlays/IBM/Commerce/BODs |
| Nouns | /OAGIS/9.0/Overlays/IBM/Commerce/Resources/Nouns |
| Data types | /OAGIS/9.0/Overlays/IBM/Commerce/Resources/Components |
| Business Object Documents | /OAGIS/9.0/Overlays/ MyCompany/BODs |
| Nouns | /OAGIS/9.0/Overlays/ MyCompany/Resources/Nouns |
| Data types | /OAGIS/9.0/Overlays/ MyCompany/Resources/Components |
All WebSphere Commerce nouns, regardless of namespace, are in the IBM/Commercedirectory.
Logical schema customization
There are two ways to add more data to a current request and response document. One way is to take advantage of the UserData hooks within the existing types to pass unstructured information. The other way is to use the Overlay methodology.
The overlay methodology can be compared to extending a class in Java. An overlay is an XML type that extends another XML type and contains more attributes and elements. This new type is then declared as a substitution of the type and can be used when creating a service request and returning a service response.
Do not modify a WebSphere Commerce schema directly. Schema customizations should be done either using the UserData element, or using the OAGIS recommended customization practices using schema overlays.
More detail on logical schema customization can be found in the Extending a noun topic.
- 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: - Nouns
A logical model definition is required for services that are fronted by an XML schema. In WebSphere Commerce, the logical model definition is represented as a noun. WebSphere Commerce uses its own simplified nouns, defined types, and primitive XML schema types. WebSphere Commerce does not use nouns and base types provided by OAGIS. - Verbs
A verb represents an operation that can be performed on a noun. For example, an "Order" noun has a specified operation that is performed in response to the verb "Get" (in this case, providing details to the client about the Order). Although OAGIS messaging defines a number of verbs; WebSphere Commerce uses a subset.
Related concepts
Change Request / Respond Response
Get Request and the Show Response
Verbs
Nouns
Process request and the acknowledge response
Sync request and the ConfirmBOD response
Related tasks
Customizing the Web service client invocation XML file
Enable WebSphere Commerce as a service consumer