When you want to use a Web Service that accesses RepositoryItems, you can create a mechanism for translating foreign content into different formats:
A serializer will convert content from a native format into XML that will eventually undergo another conversion into a
RepositoryItem. You need to create a serializer for “set” operations in which the client sends content to the Web Service in the context of the callA deserializer constructs XML content that was originally formatted as
RepositoryItemsinto a native content format. You need to create a deserializer for “get” operations in which a Web call returns content that represents aRepositoryItem
Both a serializer and a deserializer will need to understand the RepositoryItem schema. When you create the XML schema and a mapping file, you need information about the Web Service itself. You can find that information in the sections that describe the Web Service:
For
getProfile, see the Personalization Programming GuideFor
getOrderAsXML,getOrdersAsXML,getProductXMLById,getProductXMLByDescription,getProductXMLByRQL,getProductSkusXML,getPromotionAsXML, see the Commerce Programming GuideFor Repository Web Services , see the Repository Guide
Two Repository Web Services, getRepositoryItem and performRQLQuery, require a serializer and deserializer, but they can apply to any RepositoryItems you choose, which is different from the other Web Services that are only available to specific RepositorityItems and item descriptors.
The serializers and deserializers you create require a Repository schema, which you can create by following these steps:
Create a Mapping file that determines which
RepositoryItemproperties will be captured by the Web Service and returned by the call. See Creating a Mapping File.Use the
generateXMLSchematool to convert theRepositoryItemclass into a standard XML schema. See Generating an XML Schema.Insert a reference to the XML schema in your instance document, which is a document that represents an instance of the Web Service call. You complete this step when you configure the client stub; see Creating and Compiling a Client Stub for instructions.
Creating a Mapping File
If you were to create an XML schema that included all RepositoryItem properties, some content may not be understood by standard deserializers and some may not conform to the XML 1.0 specification. Instead, you create a mapping file that determines which properties, from the RepositoryItem's item descriptor, to include or exclude from your XML schema. For instructions on how to create a mapping file, see Mapping Files.
To create a mapping file, you need to know the properties defined by your item descriptor so you can decide which of them ought to be represented in the XML schema. You can find the location of a Repository’s item descriptor in the Oracle ATG Web Commerce platform Dynamo Administration UI:
In Dynamo Server Admin, click the Component Browser link.
Navigate to the Repository component that correlates to your Web Service as indicated in the documentation for your Oracle ATG Web Commerce Web Service.
Click the See Property Descriptions link beside the item descriptor name. For the item descriptor name, see the documentation for your Oracle ATG Web Commerce Web Service.
This list that displays includes all properties that are available to the item descriptor based on the modules that are currently running.
To make this XML schema compatible with the expectations of the resources that will use it, exclude the following items from your XML schema:
RepositoryItemproperties that accept primitive data types and may be nullRepositoryItemproperties that accept Maps, Lists, or Sets
Generating an XML Schema
The generateXMLSchema is a script that takes a given Repository component and item descriptor as arguments and produces an XML schema. For instructions on using this tools, see XML Schemas.
When you create an XML schema in support of a Web Service, make sure that the same modules in the Oracle ATG Web Commerce platform are running now as those that will be running when the client calls the Web Service.
For a list of Web Services, associated Repository components and items descriptors, see the documentation for your Oracle ATG Web Commerce Web Service.
You may find these two optional arguments helpful:
outputDirectorycopies the resultant XML schema to the directory of your choosingmappingFilespecifies a file that describes theRepositoryItemproperties to include in the resultant XML schema
Other Required Schemas
When a client deserializes a RepositoryItem, it uses the schema derived from the item descriptor to reconstruct each repository object and its properties in the appropriate data types. Depending on the makeup of the item descriptor, you may need to also generate a schema for related item descriptors.
Consider the Profile repository that uses the user item descriptor. There are two item descriptors, broker and investor, that are subtypes of user. If you were to use the updateProfile Web Service call while the Relationship Management platform is running, user and all subtypes of it that are part of Relationship Management are accessible. When you call updateProfile, it’s unclear which version of user you want to call: user, investor or broker. In this case, you need to generate XML schemes for all three item descriptors.
In short, you need to generate an XML schema for all item descriptors used by RepositoryItems that are accessed by a Web Service call and for any related (parent or child) item descriptors that are running when the call is made.
It is difficult to supply a general list of all item descriptors for which this added step applies because the contents of that list depend on many factors. When deciding if you need to create supplemental XML schemas for an item descriptor, consider the following:
The Web Service you are calling
The modules running when you call that Web Service
The contents of your Oracle ATG Web Commerce module stack
The custom Oracle ATG Web Commerce components you have created that may extend existing components accessed by the Web Service
Note: The previous discussion addresses item descriptors and their subtypes, meaning item descriptors that inherit from the parent class. This relationship should not be confused with that which item descriptors share with extensions of themselves, which are added by other modules. For example, the order item descriptor has one set of properties provided by the Consumer Commerce module. A second order item descriptor is supplied by Business Commerce and, when both modules are running, the order item descriptors are concatenated so that Business Commerce properties take precedence. Because all versions of order for the running module are combined into one, you need only one XML schema for the order item descriptor. When you create that XML schema for order, remember to do so while the same modules are running as will run when your Web Service calls that item descriptor.
