Business Object Document Message Architecture

Overview:

In order to Achieve Interoperability between Disparate systems, Disparate companies and Disparate supply chains, there must be a common Horizontal Message architecture that provides a common understanding for All.Once a horizontal messaging architecture has been agreed upon these messages can be sequenced together to form scenarios. Scenario can provide the detail step-by-step exchange of information needed to perform specific tasks. These tasks can be simple or complex. As such, the scenario describing them may be simple or complex. Complex scenarios may reuse one or more simple scenarios.

The Open Applications Group Integration Specification (OAGIS) provides example scenarios that can be used as a starting point for integration. By identifying a scenario that most closely matches your needs, it is possible to identify the messages needed to achieve your needs.

OAGIS messages -- to leverage the reuse. Once the initial OAGIS BOD can be read or produced, much of the code can then be used to read or produce the next message.

What is OAGIS?

Open Applications Group Integration Specification ( practical use of XML to enable integration )

The Open Applications Group Integration Specification (OAGIS) is an effort to provide a canonical business language for information integration. It uses XML as the common alphabet for defining business messages, and for identifying business processes (scenarios) that allow businesses and business applications to communicate. Not only is OAGIS the most complete set of XML business messages currently available, but it also accommodates the additional requirements of specific industries by partnering with various vertical industry groups.

The Open Applications Group (OAGi) -- the organization that oversees the OAGIS -- was formed in November 1994 in an effort to dramatically ease everywhere-to-everywhere integration (inside and outside of the enterprise, as well as across the supply chain). OAGi has done this by crafting standards where necessary and by recommending standards where they already exist.

OAGIS provides the definition of business messages in the form of Business Object Documents (BODs) and example business scenarios that provide example usages of the BODs. The business scenarios identify the business applications and components being integrated and the BODs that are used. The current release, OAGIS 8.0, includes 200 business messages and 61 business scenarios that can be used to integrate business applications.

OAGi recognizes that it is important for OAGIS to be technology-sensitive but not technology-specific. Because of this, OAGIS works well with Web services, ebXML(OASIS), or any other framework that your organization chooses to use to transport information, including FTP, SMTP -- or even none at all.

-OAGi members include individuals and small, medium, and large companies companies like Irista Software, MRO, IBM, Oracle, Sun Microsystems, Lockheed Martin, Lucent, Ford, and Agilent to name just a few.(http://www.ibm.com/developerworks/xml/library/x-oagis/)

These business scenarios provided by OAGIS were used to define OAGIS and are provided as examples to help the user understand how to work with OAGIS. They identify the business applications and components that are being integrated along with the BODs used to pass information. The business scenarios also capture the sequence in which the messages are intended to occur, the dependencies, the scope, and the error handling that has been addressed. OAGi provides these example scenarios as a starting point for any new implementation.

* The following figure illustrates an example of one such scenario. Notice that this scenario has call-outs to other scenarios to display more detail -- specifically, the integration of Manufacturing to Purchasing scenarios and the Manufacturing to Order Management scenario.

THE SUPPLY CHAIN INTEGRATION (Manufacturing to Purchasing, Order Management, Billing, Shipping, and Financials)

The BOD is a Common Horizontal Message Architecture. BODs are thebusiness messages or business documents that are exchanged between software applications or components;between companies; across supply chains; and between supply chains.

In order to do this the BOD must be able to inform the receiving system what kind of message to expect in the data area. Often there is a two-way interaction between a sender and receiver, for this reason, the BOD needs to be able to communicate status and error conditions. It is also necessary to provide for multiple actions on a Common Business Object (Noun). For this reason the OAGIS BODs have been designed to make use of a common Nouns that a given Action (Verb) may be applied. As different industries have different needs OAGIS must be extensible in order to allow industry verticals to plug in information that is needed in their industry. For this reason the BODs have been designed to be extensible, while providing a common architecture and content for integration.

The BOD Message Architecture is independent of the communication mechanism. It can be used with simple transport protocols such as HTTP and SMTP but it also can be used in more complex transport protocols such as SOAP, ebXML Transport and Routing, or any other Enterprise Application integration system.

A BOD graphically consists of the following:

* The outermost layer of the BOD identifies the Verb, Noun, revision and runtime environment (Test or Production in which the BOD instance is to be used.)

* Application Area Application Area communicates information that can be used by the infrastructure to communicate the message.

* Data Area The Data Area carries the business specific payload or data being communicated by the BOD.

* Verbs Verb identifies the action being performed on the specific Noun of the BOD.

* Nouns Nouns identify the business specific data that is being communicated (i.e.) PurchaseOrder, SalesOrder, Quote, Route, Shipment, etc.) They are comprised of Components, which are described below. Nouns are extensible in order to support the needs of specific vertical industries.

* Components Components are extensible building blocks of a Noun (i.e.) PurchaseOrder Header, PurchaseOrder Line, Address, etc.). They are comprised of compounds and fields, which are described below.

* Compounds Compounds are basic, shared building blocks that are used by all BODs (i.e.Quantity, Amount, etc.). They are extensible through contextual use but Not with additional fields (i.e. OrderedQuantity, ShippedQuantity, BackOrdered Quantity).

* Fields Fields are the lowest level elements defined in OAGIS. Fields are fundamental elements that are used to create Compounds and Components. (i.e. Description, Name, etc.)

The Verb identifies the action that the Sender application wants the Receiver application to perform on the Noun. OAGIS defines a standard list of Verbs and Nouns that are needed in mostsupply chain and manufacturing integration scenarios.

The general structure for all of Business Object Documents is shown in the following figure:

For a given Business Object Document, the generic names (BusinessObjectDocument, Verb,Noun) are replaced by specific names (ProcessPurchaseOrder, Process, and PurchaseOrder):

The child elements of a BusinessObjectDocument are:

ApplicationArea. (application-specific information common to all BODs)

DataArea. (information that is specific to each BOD)

In addition to these child elements, each BOD contains four attributes, the BOD's releaseID,versionID, systemEnvironmentCode, and languageCode.

Release ID:Release ID is used to identify the release of OAGIS that the BOD belongs. For the BODs from OAGIS 9.0 the value of this attribute will be 9.0. The release ID is a required attribute of the BOD.

Version ID:Version ID is used to identify the version of the Business Object Document. Each BOD has its own revision number to specifically identify the level of that BOD, not just the release ID of OAGIS. The specific BOD version number is documented in each chapter of OAGIS. The outermost element name no longer includes the version number; it is instead now carried as an attribute of the BOD. The version ID attribute is an optional attribute of the BOD.

System Environment Code:The System Environment Code is used to identify whether this particular BOD is being sent as a result of a test or as production level integration. Often times as new systems are brought online testing must be performed in a production environment in order to ensure integration with existing systems. This attribute allows the integrator to flag these test messages as such. The environment attribute is an optional attribute of the BOD.

Language CodeThe languageCode attributes indicates the language of the data being carried in the BOD message. It is possible to override the BOD level language for fields that may need to carry multi-lingual information. Examples of this are Notes and Description.XML supports only one encoding for an XML message as such the languages carried within a BOD are limited to the set that the XML encoding can support.

Application Area

The ApplicationArea carries information that an application may need to know in order to -communicate in an integration of two or more business applications. The ApplicationArea is used at the applications layer of communication. While the integration frameworks web services and middleware provide the communication layer that OAGIS operates on top of.

As indicated in the graphic below each BOD contains one unique ApplicationArea

Sender

senderThe Sender identifies characteristics and control identifiers that relate to the application that created the Business Object Document. The sender area can indicate the logical location ofthe application and/or database server, the application, and the task that was processing tocreate the BOD.

The Sender area also provides the ability to create an audit trail to allow users to drill down from their Receiving business application to the information used to complete the business transaction being communicated in the BOD.In todays business environments and advanced technology - frameworks a single BOD may be routed to multiple destinations or receivers. For this reason,it is not feasible for the sending system to know all of the possible destinations of a BOD.For this - reason the Open Applications Group has made a conscious decision NOT to include a Receiver in the ApplicationArea. This is left to the middleware or infrastructure framework to ensure delivery to all locations that are interested in the content of the BOD.

The Sender is comprised of the following information:

- LogicalID - ComponentID - TaskID - ReferenceID - ConfirmationCode - AuthorizationID

Logical ID:The Logical Identifier element provides the logical location of the server and application from which the Business Object Document originated. It can be used to establish a logical to physical mapping ,however its use is optional.Each system or combination of systems should maintain an external central reference table containing the logical names or logical addresses of the application systems in the integration configuration. This enables the logical names to be mapped to the physical network addresses of the resources needed on the network.

Note: The technical implementation of this Domain Naming Service is not dictated by this specification.

This logical to physical mapping may be done at execution time by the application itself or by a middleware transport mechanism, depending on the integration architecture used.

This provides for a simple but effective directory access capability while maintaining application independence from the physical location of those resources on the network.

Component ID:The Component ID provides a finer level of control than Logical Identifier and represents the business application that issued the Business Object document. Its use is optional.

The Open Applications Group has not constructed the list of valid Component names. Example Components may be INVENTORY, or PAYROLL.

TaskID

The Task ID describes the business event that initiated the need for the Business Object Document to be created. Its use is optional. Although the Task may differ depending on the specific implementation, it is important to enable drill back capability. Example Tasks may be RECEIPT or ADJUSTMENT.

Reference ID:

Reference ID enables the sending application to indicate the instance identifier of the event or task that caused the BOD to be created. This allows drill back from the BOD message into the sending application. The may be required in environments where an audit trail must be maintained for all transactions.

Confirmation Code:

The Confirmation Code request is an option controlled by the Sender business application. It is a request to the receiving application to send back a confirmation BOD to the sender. The confirmation Business Object Document may indicate the successful processing of the original Business Object Document or return error conditions if the original Business Object Document was unsuccessful.* The confirmation request has the following valid values:

Never -No confirmation Business Object Document requestedOnError -OnError send back a confirmation Business Object Document only if an error has occurredAlways-Always send a confirmation Business Object Document regardless

Authorization ID:

The Authorization Identifier describes the point of entry, such as the machine or device the user uses to perform the task that caused the creation of the Business Object Document.

The Authorization Identifier is used as a return routing mechanism for a subsequent BOD or for diagnostic or auditing purposes. Valid Authorization Identifiers are implementation specific. The Authorization Identifier might be used for authentication in the business process. As an example, in the case of Plant Data Collection, the Authorization Identifier is used to fully define the path between the user of a hand held terminal, any intermediate controller and the receiving application.

In returning a BOD, the receiving application would pass the Authorization Identifier back to the controller to allow the message to be routed back to the hand held terminal.

CreationDateTime:

CreationDateTime is the date time stamp that the given instance of the Business Object Document was created. This date must not be modified during the life of the Business Object Document.

OAGIS Date time type supports ISO Date Time format.

Signature:

-If the BOD is to be signed the signature element is included, otherwise it is not.

-Signature will support any digital signature that maybe used by an implementation of OAGIS. The qualifyingAgency identifies the agency that provided the format for the signature.

-This is accomplished by not actually defining the content but by allowing the implementation tospecify the digital signature to be used via an external XML Schema namespace declaration. The Signature element is defined to have any content from any other namespace.

BODID:

The BODID provides a place to carry a Globally Unique Identifier (GUID) that will make each Business Object Document uniquely identifiable. This is a critical success factor to enable softwaredevelopers to use the Globally Unique Identifier (GUID) to build the following services or capabilities

1. Legally binding transactions,

2. Transaction logging,

3. Exception handling,

4. Re-sending,

5. Reporting,

6. Confirmations,

7. Security.

* Suns iPlanet Application Server provides the ability to generate a GUID, see http://docs.iplanet.com/docs/manuals/ias/60/sp3/JavaProgGuide/jpgdeplo.htm

Data Area

The Data Area (DataArea) of the Business Object Document contains the instance(s) of data values for the business transaction. For example, to send a Purchase Order or Orders to a business partner, the Data Area will contain Verb (the action) and the Noun (the object) onwhich the action is to be performed.

The DataArea contains a single verb and one or more occurrences of a noun. This is shown in the examples above where the repeating PurchaseOrder element indicates that 1 or more instances of the PurchaseOrders are to be Processed.

Verb

The Verb is the action to be applied to the object (the Noun). Examples of Verbs include Cancel,Add, Process, and Synchronize. Any additional information that is exclusively related to the actionis also stored with the Verb.For example a Process verb indicates that it is acknowledgeable and confirmable.

Noun

Noun is the object or document that is being acted upon. Examples includePurchaseOrder, RequestForQuote, and Invoice. Nouns are extensible within OAGIS,meaning that they can include content that was not originally designed by OAGI.

There are different types of verbs or actions that can be performed on a PurchaseOrder; as such the base Noun (e.g. PurchaseOrder) contains all of the information that might be present on a PurchaseOrder. The instantiation of each of the possible verb and noun combinations then further defines what must be provided to perform the intended transaction. For example in a ProcessPurchaseOrder transaction business partners and line item data must be provided, whereas in a CancelPurchaseOrder only the order identifier needs to be provided.

Nouns are extensible within OAGIS meaning that additional content (fields, compounds and components can be added to an existing Noun). This additional content can be defined external to OAGIS and added through the use of In-Line extensions. In-Line extensions will be discussed later in this document.

Components:

-Components are the large-grained building blocks of a Noun. Components are extensible within OAGIS. Components consist of other Components, Compounds, and Fields examples of Components include: PurchaseOrder Header, Party, and Address.-Components are extensible within OAGIS meaning that additional content (fields, compounds and components can be added to an existing Component). This additional content can be defined external to OAGIS and added through the use of In-Line extensions.-The instantiation of the Component identifies the OAGI recognized fields, compounds, and other components that must be present to support the intended business transaction on a BOD-by-BOD basis.

Compounds

Compounds are a logical grouping of fields (low level elements) that are used across all BODs.

Examples include Amount, Quantity, DateTime, and Temperature. Unlike Components, Compounds cannot be extended to include new data content.

Fields

Fields are the lowest level elements used in OAGIS Components and Compounds. These fields maybe based on either an OAGIS-defined type or a user-defined type.

Fields vs. Compounds

In the instantiation of OAGIS in XML Schema the distinction between fields and compounds become less defined. This is due to the fact that XML Schema provides a richer type system than that offered by DTDs, in fact a type system did not exist prior to the approval of the W3C XML Schema Recommendation (May, 2001). This allows the expression of dates and quantities in lower-level elements. With the XML Schema type system the need for Fields and Compounds is replaced by the combination of:

* Built-in datatypes, based on ISO standards, e.g. for dates, times, and decimal numbers.

* Simple User-definable types, are user-constrained versions of the standard types* Complex User-definable types, which are user-defined structures built up from other simple and complex type.

Since OAGIS is independent from the language used to instantiate it, the concepts of Compounds and Fields remain constant. However, they are both derived from Types in XML Schema. The XML Schema instantiation of OAGIS defines both compounds and fields as types. For this reason they are both defined in a single file Types.xsd, whereas the XML DTD instantiation defines them in separate files.

Extensions

While it is important to clearly define the messages to be passed between business partners and between business applications, it is not possible to identify all of the possible information that may be needed in every given situation. It is also not possible to completely identify the unique characteristics that may provide value for a given customers implementation.-In other words there are always going to be extension needed such that a company can communicate its unique needs. These may be in the form of additional fields or in the form of additional values for a given field(s).

For this reason OAGIS is designed to be extended.

OAGIS can be extended in the following ways:

UserArea Extensions UserArea extensions provide an optional element within each OAGIS defined component that may be used by an implementer to carry any necessary additional information. For example, it may be necessary to carry field XYZ in the Header of a ProcessPurchaseOrder BOD in order to meet the unique customer demands. This can easily be accomplished by defining the field XYZ in a XML Schema file and reference this file via a namespace in the XML instance of the BOD and carrying the extended field in the UserArea of the ProcessPurchaseOrders Header. As long as this additional XML Schema file is reference able, the extension can be validated.

The optional UserArea is specified in all Components. It always appears after any OAGIS-defined Components, Compounds, or Fields in a Component. The only things that will appear after the UserArea are Overlay extensions. XML Schema requires that any extensions be appended to the end of the currently defined type.

Overlay Extensions

In order to provide the additional functionality required by vertical industries, the XML Schema instantiation of the OAGIS Message Architecture supports In-Line extension of OAGIS. This is accomplished through the use of the XML Schema ability for types to extend other types and through the use of Substitution Groups.

It is possible to extend, the content of any OAGIS Noun or Component. Doing so appends new element content to an existing Noun or Component. The following example shows how a ProcessPurchaseOrder BOD maybe extended by a fictions vertical industry, IndustryA, to include additional fields that maybe needed within the its vertical.

The below example shows how a ProcessPurchaseOrder BOD maybe extended by a fictions vertical industry, IndustryA, to include additional fields that maybe needed within the its vertical.

String String String String 0 String 2001-12-17T09:30:47-05:00 String

Note: These extensions, while providing new elements in OAGIS, are distinguished from core OAGIS content by the presence of a namespace identifier. In this case, the default namespace is used to identify Industry A extensions prefix. OAGIS defined elements are identified by the oa: namespace.

A detailed explanation of how to accomplish this and how it works can be found in the OAGIS XML Schema Extension white paper.

While it is possible to carry externally defined element within the UserArea, OAGI recommends using Overlay extensions to add additional information to OAGIS.

Constraints

While XML Schema provides a view powerful mechanism for validating types and structures. It does not provide a good mechanism for applying rules and constraints that may differ from implementation to implementation. For this reason the decision was made to separate the type and structure validation from the rules and constraint validation. With the structure and type being provided by XML Schema and the rules and constraints being provided by XSL. More specifically XPath but since there are many different XSL processors available and no simple XPath processors and XPath is a part of XSL.

This allows OAGI to define the required fields that our constituency agrees must be present but a given implementation can also apply their own requirements fields, compounds, or components by simply populating an XSL and applying the additional constraints.

Error Handling

OAGIS facilitates error handling at the application layer through the Confirm BOD.

If an error occurs in the processing of a BOD in the receiving application and the Sender set the Confirmation to either OnError or Always. The receiving application must provide a ConfirmBOD that references the original BODs BODId. This ConfirmBOD indicates that there was an error in the original BOD and carries the error messages from the receiving system.

Once the original sending system receives the ConfirmBOD indicating an error occurred in the original BOD. OAGIS leaves what happens next up to the integrator.

While it is possible for the sending system to resend the BOD or to attempt to correct any missing information through advanced error correction mechanisms. It is important to consider the affect of the time that has lapsed on the information that is being communicated.

The OAGIS ConfirmBOD is in addition to any communication layer error handling that may be provided by the infrastructure framework, web service, or middleware.

Business Object Document In Commerce (Command Framework For Business Logic Layer)

//Starting in WebSphere Commerce Version 6 Feature Pack 3.0.1, WebSphere Commerce introduces the Business Object Document (BOD) command framework..//

USE:The WebSphere Commerce BOD command framework architecture uses well defined interfaces to decouple the implementation of the presentation layer, business logic layer and persistence layer.

-Over the years, OAGi has been and continues to be more interested in real solutions than in academic exercises. OAGi works and acts more like a development organization than a traditional standards organization. By doing this, it is able to deliver a solution that works and can be implemented quickly.

-From the business logic layer perspective, OAGIS messages are used as the interface for making requests to retrieve business data or invoke business logic. The BOD command framework provides the capability to process these BOD requests and responses.

The interaction between the business objects(BOD requests and responses) and persistence layer is isolated in an object called the Business Object Mediator.

WebSphere Commerce BOD command framework

Presentation layer:Retrieving business data or executing any business logic must be done through the OAGIS defined services of a service module.

Business logic layer:The business logic layer provides services to return data or run business logic.

-NameVAluePair Command Framework shows an approach in which services transform the OAGIS messages (BODs) to name-value pairs for processing by name-value pair commands. This makes for easy integration with existing WebSphere Commerce or customized commands. This approach is known as Service-Oriented Integration (SOI). It is appropriate to use this approach when the business logic you want to run is already written as a name-value pair command.

- BOD Command Framework approach in which services transform the OAGIS messages (BODs) to Java objects called service data objects (SDOs). The BOD commands use these objects as their interface to represent the BOD. The command then uses an object called the Business Object Mediator to accept service data objects and handle the mapping between these objects and how they are persisted. The business logic never needs to deal with the technology used to interact with how the data is persisted . The business logic layer passes SDOs to the persistence mechanism without binding itself to the persistence technology.Service data objects are part of the IBM SOA(Service Oriented Architecture) programming model.

Persistence layer:

The business logic layer interacts with the persistence layer to retrieve and store data. The persistence layer has two different implementations: EJB 1.1, and the data service layer.

Note: A mixed model (for example, name-value pairs using the data service layer, or BOD processing commands using EJB 1.1) is not supported.

Tutorial:Extending a BOD service to manage UserData with The 'Data Service layer'

REQUIREMENT : Customizing the Catalog service to support warranty information and care instructions for Catalog Entries.

NEED : This customization includes updating the WebSphere Commerce schema so that it will store the new information and customizing the Catalog service to include the new information as user data in the CatalogEntry noun.

FRAMEWORK : WebSphere Commerce BOD programming model, the CatalogEntry noun, and the CatalogEntryDescription noun

JOB :You will configure the business object mediator to populate warranty information as UserData in the CatalogEntry noun and care instruction information as attributes to the CatalogDescription noun part and you will create a custom query template file to map an XPath expression and access profile to SQL.(The template file defines a SQL template statement that fetches data from the new tables, associates a new access profile to the new SQL template statement, and associates a XPath expression to the new SQL template statement.)

USE OF BOD programming model :Separates processing into the business logic layer and the persistence layer .

-The business logic layer works with logical service data objects (SDOs), which are the Java representation of nouns. The persistence layer creates, reads, updates, or deletes business objects in the WebSphere Commerce database. This separation allows adding new data to impact only the persistence layer.

Things to know:

(1)What is Business Object Document(BOD)?(2)what is OAGIS?(3)what is business object mediator(BOM)?(4)what is service data objects(SDO)?(5)what is Data Service Layer?(6)what are CatalogEntry noun and CatalogEntryDescription noun?(7)what is Custom Query Template file ?(8)what were XPath expression and access profile to SQL?

Difference between NAME-VALUE PAIRS & BOD Frameworks:

* BOD commands deal with service data objects(SDO) instead of name-value pairs* BODs can represent a complex request, that performs multiple actions instead of just one * BOD commands deal with a persistence interface called the Data Service Layer using an object called the Business Object Mediator, and are independent of the Persistence technology.

CatalogEntry noun :

The CatalogEntry noun uses the UserData element as a data extension point to add new data without changing the logical model. In this tutorial, warranty information is added to the CatalogEntry noun UserData element to demonstrate the addition of language dependent properties. For this tutorial, a warranty applies to a specific catalog entry and consists of a term or number of days the warranty applies and a warranty type: either limited or comprehensive.

Catalog description noun :

The Catalog description noun part supports the Attributes element as a data extension point. Attributes provides the same functions as the UserData element. Product care instructions is added to the CatalogEntryDescription noun part attributes element to show the addition of language independent properties. In this tutorial, a care instruction applies to a specific catalog entry and language and consists of a text description of the instruction.

The following example CatalogEntry noun shows the customization of the CatalogEntry UserData element and CatalogEntryDescription attributes element :

10251 FULO-01 White Fabric Roll Arm Chaise images/catalog/FULO_01_sm.jpg images/catalog/FULO_01.jpg Plumply padded for your ultimate comfort. 10251 -1 Warranty description for the chaise. 30 LIMITED

The persistence layer is customized according to the following diagram:

Learning objectives

After completing this tutorial you should be familiar with the following concepts:

* Understanding the WebSphere Commerce Data Service Layer* Overview of simple extension and customization tasks.

After completing this tutorial, you should be able to perform the following tasks:

* Updating the WebSphere Commerce database with new tables and relationships.* Generating custom object-relational metadata that describe new tables and relationships.* Generating static service data objects (SDO) that provide a Java representation of the newly added tables.* Configuring the logical data object to physical data object mapping.* Creating a custom query template file to map an XPath expression and access profile to SQL.

Skill level

This tutorial is intended for advanced WebSphere Commerce developers responsible for creating and customizing WebSphere Commerce BOD services. To complete this tutorial you should be familiar with the following terms and concepts:

* Web services* XML* WebSphere Commerce services* Relational databases* SQL

System requirements:

Before beginning this tutorial ensure that you have completed the following tasks:

- Install WebSphere Commerce Developer.- Publish the Madisons sample store.

Note: Workspaces are not supported when completing this tutorial.

Lessons in this tutorial:

(1)Customizing the WebSphere Commerce schema.

(2)Customizing the physical layer to include the new information.

(3)Adding query templates to include the new information.

(4)Creating an access control policy to secure the new information

(5)Validating the Catalog customization with JUnit

(1) Customizing the WebSphere Commerce schema:

In this step you will customize the physical layer by adding tables to contain store warranty and care instruction information to the WebSphere Commerce schema.

The following diagram outlines the changes to the WebSphere Commerce schema:

The above diagram shows the new XWARRANTY and XCAREINSTRUCTION tables, and how they have been related to the existing WebSphere Commerce tables, CATENTRY and CATENTDESC.

The XWARRANTY table has a foreign key to the CATENTRY table. This allows the Data Service Layer (DSL) to populate data from the XWARRANTY table in the user data element of the CatalogEntry noun.

The XCAREINSTRUCTION table has a foreign key to the CATENTDESC table to allow DSL to populate data in the attribute element of the CatalogEntryDescription noun part.

The XCAREINSTRUCTION table has a foreign key to the CATENTRY table to provide support to the DSL search function.

To take advantage of the Data Service Layer's user data (and attribute) support, the following restrictions apply when adding custom database tables:

The custom tables must have a foreign key to the base table for the noun or noun part that will contain the data. A base table is a table that contains the unique key for the noun or noun part. For example, the CATENTRY table is the base table for the CatalogEntry noun. These relationships are used when fetching or updating a noun or noun part to access the custom data.

The relationship between the custom table and the base table must be a one-to-one relationship. User data is essentially a map of name-value pairs, where each name represents a database column name and each value is the value in that database column. One-to-many relationships are not supported as each name in the map would collide.

To take advantage of the Data Service Layer's parameter search support, foreign key should also be created to the base table for the noun, when adding a custom table for a noun part. This relationship provides support to the DSL search function and this relationship does not have to be one-to-one

NOTE:All foreign key relationships in the custom tables should specify ON DELETE CASCADE

(2)Customizing the physical layer to include the new information:

In this step you will customize the physical layer by;

Modifying the WebSphere Commerce schema

Generating object-relational metadata

& Generating physical service data objects (SDOs). To do so, you will use a tool called the Data Service Layer wizard.

Physical SDOs are service data objects that represent tables in the WebSphere Commerce schema. Each data object type corresponds to a table definition in the schema, and each data object property corresponds to a table column or a reference to another data object type; these references correspond to the foreign key relationships between the database tables.

For each service module, there is object-relational metadata that contains the information to relate the physical data object to a database table. Custom object-relational metadata is stored in the component configuration extension directories and custom physical SDOs are stored inside the WebSphereCommerceServerExtensionsLogic project.

This wizard performs the following tasks:

(a)Creates an extension configuration folder for the Catalog service module if one does not already exist. The directory path is: WC_eardir\xml\config\com.ibm.commerce.catalog-ext.

(b)Generates a custom object-relational metadata file that describes the new custom tables and relationships. In this tutorial, the metadata file will describe the two new tables, XWARRANTY and XCAREINSTRUCTION, along with the three new relationships between tables:

XWARRANTY and CATENTRY

XCAREINSTRUCTION and CATENTRY

XCAREINSTRUCTION and CATENTDESC

This file is located at : WC_eardir\xml\config\com.ibm.commerce.catalog-ext\wc-object-relational-metadata.xml.

Note: The wc-object-relational-metadata.xml file maps the database tables and columns to physical SDOs.

For example, the following snippet of the XWARRANTY configuration as generated by the DSL wizard in this tutorial:

-Where the column CATENTRY_ID is mapped to the field catentry_id in the XWarranty Java class.

(c)Generates an SDO Java class and places it in the WebSphereCommerceServerExtensionsLogic project for:

Each new custom table (XWARRANTY and XCAREINSTRUCTION).

Each modified WebSphere Commerce table (CATENTRY and CATENTDESC were modified by adding new relationships to the custom tables).

Physical SDOs are service data objects that represent tables in WebSphere Commerce. For each table there is one data object that represents the tables, columns, and relationships.

(d)Creates a utility Java class to return the physical SDO root class (and its package) for the service module. This root class ensures that all WebSphere Commerce physical SDOs for the Service Module, and any additional physical SDOs for the customization, are available at runtime.

(e)Creates an extension service module configuration file that instructs WebSphere Commerce to use the newly created catalog physical SDO class inWC_eardir\xml\config\com.ibm.commerce.catalog-ext\wc-component.xml

(f)Creates an extension business object mediator configuration file that configures the business object mediator to include data from the XWARRANTY and XCAREINSTRUCTION tables in the user data of a CatalogEntry noun. This file is located at WC_eardir\xml\config\com.ibm.commerce.catalog-ext\wc-business-object-mediator.xml

(3)Adding query templates to include the new information :

The Catalog Service Module needs to be configured to update warranty and care instruction user data. In this step you will add query template files that will help retrieve our custom warranty information. Query template files store the SQL (XPath key)and access profile definitions for a service module, isolating it from the business logic layer completely.

A query template relates an XPath key and an access profile of a logical object to a template SQL query to select the data. Custom query templates may reuse existing XPath keys but must always define a new access profile because a different view of the data is returned. You can read more about query template files and how they are used in the Query template file topic.

Our query template file will consist of the following:

A symbol definition section that defines the tables our query template will use (CATENTRY, CATENTDESC, XWARRANTY, XCAREINSTRUCTION.

An XPath to SQL statement that maps the XPath key and access profile to a specific template SQL query.

A new access profile, 'MyCompany_All' that is used along with the XPath key to identify the SQL template query.

The default queries to fetch the data before updating the CatalogEntry noun, and CatalogEntryDescription noun part need to be changed to include the XWARRANTY and XCAREINSTRUCTION tables.

-The default SELECT queries for updating the CatalogEntry nouns and its parts is located inside the following file, WC_eardir\xml\config\com.ibm.commerce.catalog\wc-query-CatalogEntry-update.tpl. -The default SELECT query used to update the CatalogEntry noun is identified by the IBM_CatalogEntryUpdate access profile and the default SELECT query to update the CatalogEntryDescription noun part is identified by the IBM_CatalogEntryDescription_Update access profile.

To configure the Catalog service module to update the new user data, these two queries are copied and pasted into extension update query template files. The queries are modified to also select the new tables, and a new access profile to uniquely identify each query is added.

(4)Creating an access control policy to secure the new information :

The previous step created a new access profile, MyCompany_All. By default, only the users with a site administrator role will have access to this new data. In this step you will update the Catalog service access control policy to state that all users have access to view this data.

The new policy defines a new action for the MyCompany_All access profile and adds the new action to the CatalogEntry all users group. The access profiles for Change, Process, and Sync are only run after the access control check on the Change, Process, or Sync action.

Tip: Although the previous step of the tutorial also created the MyCompany_CatalogEntry_Update and MyCompany_CatalogEntryDescription_Update access profiles, only those access profiles used by Get commands need to be explicitly registered.

(5)Validating the Catalog customization with Junit :

This step demonstrates how to test your customization using JUnit. This unit tests assumes a starter store with a store ID of 10101 and a catalog ID of 10101 has been published to your WebSphere Commerce Development environment.

Verify the results :

This test performs a Get request to retrieve a CatalogEntry noun including the warranty and care instruction data.

The Get request uses the XPath key of /CatalogEntry[CatalogEntryIdentifier[(UniqueID=)]] and the MyCompany_All access profile defined in step three.

The data service layer uses the XPath key and access profile to identify the SQL query template to run against the database and populate physical data objects with the results.

The business object mediator transforms the physical data objects into logical nouns. This process populates warranty information into the CatalogEntry noun's UserData element and populates care instructions into the Catalog description noun part's attributes element.

To enable the customization you perform in this tutorial in workspaces you must complete the following tasks after completing this tutorial:

(1) Run the CM_updateWorkspacesSchema script to enable your modified database tables. See ANT target: CM_updateWorkspacesSchema for more information.(2) Run the following SQL statement to register the custom access profile in the cmdreg; this will return the locking information:insert into cmdreg (storeent_id, interfacename, classname) values (0, 'com.ibm.commerce.catalog.facade.server.commands.InsertMoreCatalogEntryDataCmd+MyCompany_All.0', 'com.ibm.commerce.foundation.server.command.bod.bom.InsertMoreNounChangeControlMetaDataCmdImpl');

(1)ANT target: CM_updateWorkspacesSchema:Use the CM_updateWorkspacesSchema script when you have made changes to your base schema, and need the workspaces schema updated to reflect those changes.Usage:Windows WC_installdir/bin/config_ant.bat -buildfile WC_installdir/components/Workspaces/xml/updateWorkspacesSchema.xml-DinstanceName=instance_name -DresourceXMLLocation=location_of_resource_XML_Files-DdbaPassword=administrative_password-DgenerateSQLStatementsOnly=true|false(optional)-DgenerateSQLStatementsOutputFile=outputFileDirectory(optional)-DdebugMode=true(optional)CM_updateWorkspacesSchema-logfile location_of_log_file (optional)

Parameters:

instance_nameThe WebSphere Commerce instance name.

resourceXMLLocationThis is the XML directory where the content-management/wc-resource-containers.xml and all the other resource manager XML files reside. The directory only needs to contain the resource manager XML file for this table if the table is content managed or operational. If there is no resource file for a table found in the content-management directory under the specified location, the tool assumes that there is no change to the resource type of the table, or the table is a non-managed type table if the table does not exist in the workspace yet. The tool looks for the a directory named "content-management" under the specified location first. If the tool cannot find the content-management directory under the specified location, it tries to locate the content-management directory under the tools classpath. If the tool still cannot find any content-management directory, it throws an exception. In summary, the content-management directory must exist even if it is empty.

dbaPasswordThe password for the database administrative user. This password is needed for schema creation and update.

generateSQLStatementsOnly (optional)A flag (true or false) to indicate that the Ant task should not actually update the workspaces but rather just report the SQL used to update the workspace pool. The default value is false, which means that the workspace pool will be updated.

generateSQLStatementsOutputFile (optional)The output file to print the SQL statements to if generateSQLStatementsOnly is set to true. If not specified then the SQL is output to standard output stream.

debugMode (optional)If true, trace and log information is enabled and prints to file: WC_installdir/logs/Application.messages.log

logfile (optional)If provided, the ANT script will create or overwrite a log file at this location.

To run the ANT task on a WebSphere Commerce Developer environment see,Running authoring server update scripts :

Before you begin:

Ensure that the development environment is configured for workspaces. See Configuring workspaces.

Configuring workspaces:

(a)Enabling Workspaces in the WebSphere Commerce development environment

(b)Enabling e-mail notification for workspaces

(c)Running authoring server update scripts

(a)Enabling Workspaces in the WebSphere Commerce development environment :

The development environment is not meant to be an authoring environment. Support is provided in the environment for customization purposes only. For example, to test changes to the content management functionality. The ability to propagate changes is not available. If you want to change the content management workspaces, you cannot publish the changes out to another database.

Before you begin:

* Before enabling Workspaces in the WebSphere Commerce development environment: Installed and configured WebSphere Commerce Developer.

* Verify that the development environment is configured to use DB2 Universal Database or Oracle Database. Workspaces are not supported when using Apache Derby. Workspaces do not work with Apache Derby.

Procedure:

1. Exit the development environment.

2.Issue the following command:

WCDE_installdir/bin/enableContentManagement.bat number_of_workspaces

Where:

number_of_workspaces:

Enter the maximum number of workspaces you want on the authoring server. Ensure that the number of workspaces allocated is sufficient to handle the number of concurrent workspace activities that might occur.

The maximum number of workspaces is the maximum number of simultaneous activities that require data isolation. Multiple stores managed by the same organization can share a workspace. For example, to work on two future events simultaneously while providing regular updates and providing a data-isolated area in which to complete emergency fixes, you need four workspaces per organization.

The maximum number of workspaces specifies the number of database schemas that are allocated for workspaces. The number of allocated database schemas remains fixed. If a Workspace Manager creates more workspaces than the number of workspace database schemas available, task groups in workspaces without an available database schema cannot be activated until another workspace is completed or canceled.

For more information, see Workspaces data model.

(b)Enabling e-mail notification for workspaces :

Enabling e-mail notification in workspaces allows e-mail to be sent automatically when the state of a task changes.Workspace Content Contributors will receive e-mail notification when a task they are assigned is part of a task group that has been activated.

Task Group Approvers will receive e-mail notification when a task group for which they are an approver is ready for approval.

Workspace Content Contributors will receive e-mail notification if a task group approval request is rejected and their assigned tasks are re-activated.

Procedure :

(1)Configure the e-mail transportation method for your authoring server: (Configuring a transport method for the site)

Open the Administration Console and select Site on the Administration Console Site/Store Selection page.

Click Configuration > Transports. The Transport Configuration page displays.

Select the check box beside the method you want to configure.

If the transport you want to configure is inactive:

Select the check box next to the inactive transport.

Click Change Status.

The transport status should change from Inactive to Active.

Select the transport again.

Click Configure. The Transport Configuration Parameters dialog opens. The name of the transport method you selected appears at the top-left of the parameter table.

-If the transport you would like to enable is not shown on the list use the Configuration Manager to add the transport. See, Enabling additional transports.

Type the values to be used by the transport method.

Click OK to accept the changes, or click Cancel to return to the Transport Configuration page.

(2)Assign the following message types to the e-mail transportation method:

RejectTaskNotification

ReadyToApproveTaskGroupNotification

ActivateTaskNotification

If you assign a message type to a particular transport, the transport must first be set active. By default, only the e-mail transport is active at the site-level. If the store does not have a message transport assignment, then the site assignment is used.Procedure:

Open the Administration Console

On the Administration Console Site/Store Selection page, select Site to assign a message type to a site, or Store to assign a message type to a store.

Click Configuration > Message Types. The Message Type Configuration page is displayed.

Click the check box next to the message type to which you want to assign a transport, and click Change. If the message type is not in the list, click New. The Message Transport Assignment page opens.

If this is a new transport assignment, select the message type to which a transport is to be assigned from the Message Type list.

Select the transport method. If the desired transport is not shown in the list, this desired transport is not activated. See Configuring a transport method for the site to configure the transport.

Type the transport configuration values in the appropriate fields. In general, a message severity of 0,0 and a Standard Device Format is recommended.

Click Next to configure the transport parameters for the specified message type.

Click Finish. The Message Type Configuration page displays, and the Transport Status Column should be Active.

If the transport status is not active, the transport has been deactivated or removed.

Important: After assigning a message type to a transport method for a site or store, the message profile that is created is based on the initial transport and has its own record in the database. If you make any changes to the initial transport, you must update the parameters for all the message types. For example, if you change the e-mail host in the Transport Configuration, all the message types using this e-mail transport must be updated with the new e-mail host.

-Open the following the file in a text editor: WC_eardir\xml\config\wc-workspace.xmlFind the following text :

Change the text :

Save your changes.

Stop and restart WebSphere Commerce.

(c)Running authoring server update scripts:

Procedure:

Recalibrating a table.

If you have changed a table in the base schema, run the following script to recalibrate the table:

UpdateWorkspacesTable.bat -debug tableName [tableResourceType outputFile]

Where:

tableNameThe name of the table you want to recalibrate.tableResourceType (optional)The table resource type. The valid input for this can be CONTENT_MANAGED, OPERATIONAL, and NON_MANAGED.outputFile (optional)Indicates that no database update should take place. The SQL statements are written to this output file.debug (optional)Indicates that trace and log information is enabled.

This script takes a single table from the base schema and updates the table in the workspaces.

Recalibrating the entire schema.

If you have made many changes in the base schema and want the workspaces schema to reflect those changes, run the following script to recalibrate the entire schema:

UpdateWorkspacesSchema.bat -debug [outputFile]

Where:

outputFile (optional)Indicates that no database update should take place. The SQL statements are written to this output file.debug (optional)Indicates that trace and log information is enabled.

This script scans through the base schema and adjusts the workspaces schema accordingly.

WORKSPACES DATA MODEL

Content management is achieved through the use of workspaces. Each workspace in WebSphere Commerce Version 7 is comprised of three database schemas. These schemas are identical whether you are using the WebSphere Commerce Accelerator or the Management Center.

The following schemas are used in workspaces:Base schema:Contains the current content.

Write schema:Stores the content changes.

Read schema:Presents how the current and changed content appears.

The data within these schemas is categorized as one of the following types of data:Content data:Data that is updated by business users.

Operational data:Runtime data associated with the content data.

Configuration data:Data similar to content data but is associated with the store and is not frequently updated. The base schema contains data that is identical to the production environments. All workspaces draw from this common repository of data but none of their working changes are reflected here. It is in the individual write schemas that any uncommitted changes are stored, thereby isolating workspace 1 from changes in workspace 2. However, when users preview their changes, the write and base schemas are hidden behind the read schema. The read schema first checks the write schema for the requested data and, if it is not found there, then goes to the base schema. Essentially, the read schema consolidates all the altered and unaltered data from the write and base schemas and packages it as a single entity.

Within a workspace context, updates to a resource are directed to the write schema, whereas retrieving data for a resource is directed to the read schema. Each table within the WebSphere Commerce data model is in one of the following classifications that determine the definition of the read and write schema:

Each of the assets defines a table within the Production-Ready schema:

Managed content assets:The attribute and its corresponding table are content that needs to be managed in the workspaces model. Content changed in a workspace is stored in a separate data area allocated into each workspace and participates through the actions within the workspace and its task groups and tasks. These assets define each workspace write schema as a physical table to store the data. Content is moved back to the production-ready area when the workspace components life cycle is completed. Extensions to product, marketing and pricing assets are managed content assets.

The following figure illustrates the workspace data model for a content managed resource:

This type of resource has a physical table allocated in the write schema to store changes from within a workspace. A database view of the same name is defined within the read schema that is a union of the write schema table overriding the production-ready schema table. The table within the write schema has nearly the same structure as the production-ready schema with the following exceptions:The table has additional columns as follows:CONTENT_STATUS - CHARACTER(1)The operation performed on this instance of the resource within this workspace. Possible values would be N - new resource, U - updated resource or D - deleted resource. This column is used to form the view within the read schema.CONTENT_TASK - CHARACTER(25)The task name that performed the operation on this instance of the resource.CONTENT_TASKGRP - CHARACTER(25)The task group name that performed the operation on this instance of the resource.

The constraints in the workspace write schema are relaxed.

Foreign keys to associated tables are dropped.

Unique indexes are relaxed to indexes. All non-unique indexes are restored.

Managed operational assets:

The attribute and its corresponding table represent data created during the operation of the store within preview while in a workspace. This data is specific to the particular workspace and is removed when the workspace component life cycle is completed. Transactional order data is an example of managed operational data in which data can be created in the workspace during preview.

The following figure illustrates the workspace data model for a managed operational resource. This type of resource has a corresponding table allocated in the workspace write schema to record changes within the workspace resulting from a preview. The read schema is defined as an alias to the write schema table so that the data is only viewable within the workspace.

The table within the workspaces has nearly the same structure as the production-ready schema with the following exceptions:

The table has additional columns as follows:

CONTENT_BASE INTEGER

*This identifier indicates whether the data within this table is bootstrapped (1) or not (0). The data is not cleared when the workspace task group is completed.

* The constraints in the workspace write schema are relaxed.- Foreign keys to associated tables are dropped.- Unique indexes are relaxed to indexes. All non-unique indexes are restored.

Unmanaged assets:

The attribute and its corresponding table represent content or operational data that is not managed under workspaces. The data is not associated to a workspace and is always referenced from the production-ready data area. By default all other resources that are not explicitly categorized otherwise are treated as unmanaged resources. User and store are examples of unmanaged data.

The following figure illustrates the workspace data model for an unmanaged resource.

This type of resource does not participate in a workspace. The data in the production-ready schema is always accessed directly from within a workspace and as such, both the read and write schemas are aliases to the production-ready schema table.