Tutorials > Contracts > Import and exporting contracts

< Previous | Next >


Understand contract XML files

In this section of the tutorial we will learn what XML formats are supported, where the XML files are located by default, and about the contents of the XML files.

In order to import or export contracts using their defining XML files, it is important to understand some aspects of those files.


Supported XML formats

When contracts were introduced in WebSphere Commerce 5.4, the XML files were based on a DTD format. In WebSphere Commerce 5.5 and 5.6, contracts can be based on a new XSD format. The DTD format is still supported when importing contracts; however, when a contract is exported, it will be in the XSD format. The import utility described in the last step of the tutorial can import contracts in both formats but the import function in the WebSphere Commerce Accelerator described in step 2 will only support importing contracts written in the XSD format.

To understand the details of the different formats, then see the files in the WC_EAR\xml\trading\xsd and WC_EAR\xml\trading\dtd directories for the XSD and DTD formats, respectively.


XML file locations

When a contract XML file is exported, by default, it will be placed in the WC_EAR\xml\trading\xml directory if a fully qualified path is not specified. Similarly, files are imported from the same directory. Optionally, you may specify a fully qualified path for the location of the file. The default locations of the XML, DTD, and XSD files are defined in the instance XML file. 

<Trading
        DTDFileName="B2BTrading.dtd"
        DTDPath="/trading/dtd"
        XMLPath="/trading/xml"
        XSDPath="/trading/xsd" />

Edit the instance file to define the own preferred locations for these files.


XML file contents

XML files can be used to create several types of commerce objects including:

One schema is used to define all of these objects, so a root element called <Package> is used to contain the different elements. Use the attributes in the <Package> element as specified in the example below. They do not need to be modified.

The convention used in the XSD format is that if an element is used to identify an existing commerce object, then the element name is XxxxxRef. For example <CatalogRef> refers to an existing catalog in the database. If the element name does not end with Ref, then the meaning of the element is to create a new object in the database. For example, the element <Catalog> defines the data to create a new catalog in the database.

In the example below, the <OrganizationRef> element refers to the existing SampleStoreOrganization to identify that organization as the owner of the contract. Since we are creating a new contract, the element tag is <BuyerContract>, as opposed to referring to an existing contract. 

<Package xmlns="http://www.ibm.com/WebSphereCommerce"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://www.ibm.com/WebSphereCommerce
Package.xsd">

       
<!-- create a draft base contract -->
       
<BuyerContract state="Draft"
contractUsage="OrganizationBuyer" 
        comment="Some remarks about the contract"
creditAllowed="false">

       
<!-- the contract name and owner -->
       
<ContractUniqueKey name="Base Contract for
SampleCustomer" 
        majorVersionNumber="1" minorVersionNumber="0" 
        origin="Deployment">
               
<ContractOwner>
                       
<OrganizationRef
distinguishName="o=SampleStoreOrganization,o=Root
Organization"/>
               
</ContractOwner>
       
</ContractUniqueKey>

       
</BuyerContract>
</Package>

Most objects are referred to by their unique database index. Contracts are referred to by their name, owner, and origin, and business accounts are referred to by their name and owner. Members, such as organizations and users, are referred to by their unique distinguished name (DN). Primary keys are mostly not used because they can change between systems (such as between staging and production servers). However, some elements can be referred to by their primary key to improve performance. For example, categories and catalog entries may be referred to by their primary key if that is more convenient, and if improved import performance is desired. They can also be referred to by their unique index composed of category identifier/part number and owner.

Several contract elements have descriptions that can be translated into multiple national languages. A separate XML file can be created to contain these translatable elements. A separate file makes the translation more convenient, and supports the setting of different encodings.

In the next step, we will learn how to import and export contracts using the WebSphere Commerce Accelerator.

< Previous | Next >


+

Search Tips   |   Advanced Search