Step 3: Importing and exporting a contract using XML files

In this step of the tutorial, you will learn how to import and export contracts using the XML files that define those contracts, as well as some simple utilities supplied with WebSphere Commerce.

Export a contract

The ContractExport command is used to export a contract. The following parameters are required:

• contractId
  • The primary key from the CONTRACT table in the database of the contract to export. This uniquely defines which contract should be exported.
• fileName
  • The name of the file to create when exporting the contract. This can be a file name, or a fully qualified file name. If an existing file is specified, the contents will be overwritten.
• langId
  • National language-specific data, such as a contract description, will be exported in the language specified by the langId identifier. For example, en_US is -1. See the LANGUAGE table for all the language identifiers.
• xsdName
  • The XSD file that defines the root element of the XML definition. Unless you have customized the contract XSD files, specify Package.xsd.
• URL
  • The Web address to call when the command is finished. If you specify ContractDisplay, then the WebSphere Commerce Accelerator Contract Summary page will be displayed.

The following parameters are optional:

• all
  • Specifies whether every attribute should be included in the exported XML. If all is true, then attributes such as reference numbers, create times, and update times are included. If you intend to edit this file, and import it, then this parameter should be false because the reference numbers and create times are automatically generated and should not be included in the XML.
• xmlfileEncoding
  • Identifies which encoding should be used when exporting the file. If this is not specified, then UTF-8 is used.
• contractTagName
  • This should only be specified if you have customized the contract XML definition and defined your own contract type. For example, if you have defined a new type of contract named MyBuyerContract (instead of the standard BuyerContract), then this parameter will allow the correct contract tag name to be created in the exported XML.

Similarly, business accounts can be exported by using the AccountExport command. The only different parameter is that acccountId is used instead of contractId.

Follow these steps to export a contract using the ContractExport command:

1. Start WebSphere Commerce Test Server.
2. Open a SQL session to your database and type the following SQL command:

       SELECT * FROM CONTRACT;
   

   If you are using Cloudscape, follow these steps:
   1. Start the WebSphere Commerce Test Server.
   2. Open a browser and type the following URL: http://localhost/webapp/wcs/admin/servlet/db.jsp.
   3. In the SQL window, paste the sql above
3. Find the contractID of the contract you are trying to export
4. Start the WebSphere Commerce Accelerator:
   1. Open a Web browser
   2. Type the following link into the Web browser:
      • https://host_name/webapp/wcs/tools/servlet/ToolsLogon?XMLFile=common.mcLogon where host_name is the fully-qualified WebSphere Commerce development environment Web server host name. The host name may be a virtual host name on the Web server.
   3. Enter your WebSphere Commerce user name and password. The default user name and password are both wcsadmin
5. When the Select Store and Language page appears enter the following URL into the same window:

   https://host_name:8000/webapp/wcs/tools/servlet/ContractExport?fileName=AFileNameofYourChoice.xml&contractId=TheIDoftheContract&all=false&langId=-1&xsdName=Package.xsd&URL=ContractDisplay

6. On your computer, browse to the directory you specified the contract to be export to. You should see an XML file with the name you specified.

You have now exported a contract using the XML file that defines that contract.

Import a contract





There are two versions of the contract import command. ContractImportApprovedVersion is used to import contracts in the Active or Approved state. If the contract is in the Active state, then it is immediately deployed after the contract is imported. ContractImportDraftVersion is used for contracts in the Draft state. You can continue making changes to the Draft contract until it is ready to be submitted and deployed.
The following mandatory parameters are required for both commands:

• fileName
  • The name of the contract definition XML file to import. This can be a file name, or a fully qualified file name.
• URL
  • The Web address to call when the command is finished. If you specify ContractDisplay, then the WebSphere Commerce Accelerator Contract Summary page will be displayed.

The following parameters can also be specified:

• targetStoreId
  • (Required only for Active contracts; otherwise, optional) Identifies the store to which this contract should be deployed after it has been imported.
• xsd
  • (Optional) Specifies whether this XML file is based on the XSD or DTD format.
• validate
  • (Optional) Specifies whether the contract should be validated against the DTD/XSD. This should usually be left as true.

To re-import a contract, some small modifications need to be made. If you are modifying a contract, you should increase the majorVersionNumber or minorVersionNumber, or both, while keeping the contract name, owner, and origin the same. The name, owner, and origin of a contract define a set of the same contract (referred to as a family). If the family is the same, but the version numbers are different, then, when the new contract is deployed and becomes Active, the old version of the contract is automatically moved to the Closed state. If you want to have a completely new contract, then change the name of the contract.

Additionally, some terms and conditions contain unique names that need to be modified when you re-import a contract. The name of custom price lists and custom product sets must be unique, and they need to be changed when you re-import a contract.

Similarly, business accounts can be imported by using the AccountImport command. There is only one version of the account import command because business accounts do not have different states.

Follow these steps to import a contract using either the ContractImportApprovedVersion or ContractImportDraftVersion commands:

1. Start WebSphere Commerce Test Server.
2. Open a SQL session to your database and type the following SQL command:

   SELECT * FROM STORE;
   

   If you are using Cloudscape, follow these steps:
   1. Start the WebSphere Commerce Test Server.
   2. Open a browser and type the following URL: http://localhost/webapp/wcs/admin/servlet/db.jsp.
   3. In the SQL window, paste the sql above
3. Find the store ID of the store into which you want to import the contract.
4. Start the WebSphere Commerce Accelerator
   1. Open a Web browser
   2. Type the following link into the Web browser:
      • https://host_name/webapp/wcs/tools/servlet/ToolsLogon?XMLFile=common.mcLogon where host_name is the fully-qualified WebSphere Commerce development environment Web server host name. The host name may be a virtual host name on the Web server.
   3. Enter your WebSphere Commerce user name and password. The default user name and password are both wcsadmin
5. When the Select Store and Language window opens type the following URL into the same window:

https://host_name:8000/webapp/wcs/tools/servlet/ContractImportApprovedVersion?fileName=AfileNameyouChoose.xml&targetStoreId=theIDyouFoundInStep3&xsd=true&validate=true&URL=ContractDisplay

Note: If you want to import a contract in the Draft state, then replace the ContractImportApprovedVersion part of the URL above with ContractIMportDraftVersion.

You have now imported a contract using the ContractImportApprovedVersion or ContractImportDraftVersion commands.

Summary

In this tutorial you learned that there are two methods to import and export contracts: Using the WebSphere Commerce Accelerator, and using the XML files that define the contract. In the first step you learned that contracts are based on the XSD format, and that the import utilities described in step 3 can import both DTD and XSD formatted contracts although the Commerce Accelerator can only import contracts formatted as XSD. You also learned that the default location for the XML files was WC_eardir\xml\trading\xml. Finally, you learned in the first step that the content of the XML files contains a root called Package, and that nodes that end in Ref are references to already existing commerce objects. In the second step you learned that you can import and export contracts using the Commerce Accelerator. Finally, in the third step you learned that the ContractImportApprovedVersion ContractImportDraftVersion, and ContractExport commands can be used to import and export the XML files that define contracts.

The final topic in this tutorial, explores an optional HTML utility you can use to simplify importing and exporting contracts.

---



(C) Copyright IBM Corporation 1996, 2006. All Rights Reserved.