Publishing a complete store

In order to create a functioning store, the storefront Web assets must be published to the WebSphere Commerce server, and the store data must be published to the WebSphere Commerce database. This topic discusses publishing an entire store (storefront and store data assets), if the store is in the form of a store archive, using either the Publish wizard, or the PublishStore utility.

Note: If you prefer not to package your store as a store archive, you can publish the assets individually. For more information, see Publishing your store.

The Publish wizard and the PublishStore utility publish a complete store (storefront and store data assets) all at once. In order to use this option, your store assets must be packaged in the form of a store archive.

The following diagram outlines the steps in the publishing process.

Publish process diagram

Start publish

In order to publish a store, you must have Site Administrator authority. Site Administrators can initiate the publish process using either of the following methods:

Both methods of publishing require you to specify the store archive you want to publish.

Note: In order to publish a store archive using the Publish wizard, it must be in the right location or registered.

You may then change values for selected parameters, if available, including the store identifier (the name that uniquely identifies the store), store directory (the unique location to which the JSP files and the images will be published) and organization (the organization to which you publish the store archive).

Publish wizard publish parameters

The publish parameters used by the Publish wizard are defined by the store-refs.xml file in each store archive.

Look at the following example of a store-refs.xml file from the ConsumerDirectStore.sar file.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE store-refs SYSTEM "store-refs.dtd">
<store-refs
    target-dtd="WEB-INF/stores/FashionFlow/data/ForeignKeys.dtd"
    deploy-descriptor="WEB-INF/stores/FashionFlow/data/ibm-wc-load.xml"
 resource-bundle="/SAR-INF/properties/publishNLS">
ref id="storeDir" entity="STORE_DIR" >
        <input type="text"/>
</ref>
<ref id="storeIdent" entity="STORE_IDENTIFIER" >
        input type="text"/>
</ref>
<ref id = "parentOrg" entity="ORGANIZATION_DN">
 <input type="member" />
</ref> 
</store-refs>

This file defines three publish parameters for the ConsumerDirectStore.sar file:

where

The values that a user enters for these parameters are stored in the file identified in the target-dtd file. The target dtd is defined in the following code:

target-dtd="WEB-INF/stores/ConsumerDirect/data/ForeignKeys.dtd

This file is also part of the store archive and is unpacked with the store data assets. The entity value corresponding to each parameter is updated in the unpacked file. The DTD inside the store archive is not updated. The values for the parameters are stored in this file (in this case ForeignKeys.dtd) until publish is instantiated.

Finally, if a store may be published in several languages, as the starter stores are, the publish parameters and their accompanying descriptions are found in locale specific files. The field label and description for each publish parameter are located in the properties file defined in the resource-bundle attribute of the store-refs.xml. During publish, publish looks for the specific locale for the language used in the Publish wizard. The stores-ref.xml file also defines these files:

Note: Publishing parameters are only available through the Publish wizard. If you publish a store archive through the command line, you cannot specify parameter values. The default values contained in the store archive will be used.

The deploy descriptor specifies the location of the file ( ibm-wc-load.xml) that controls the publish data portion of the publishing process. For example,deploy-descriptor="WEB-INF/stores/FashionFlow/data/ibm-wc-load.xml

After selecting your parameters, you click Finish to initiate the publish. After you have initiated the publish process using either the Publish wizard or the PublishStore utility, you do not have to do anything else. All other steps listed in the preceding diagram, and in this chapter are completed by the WebSphere Commerce system.

Unpack the assets from the store archive

After you have clicked Finish in the Publish wizard, or run the PublishStore utility, WebSphere Commerce unpacks the assets from the store archive to the WebSphere Commerce Server. Unpacking the assets is controlled by the unpack.xml file, located in the SAR-INF directory in the store archive.

The following example of an unpack.xml file is from the ConsumerDirect.sar file:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ibm-wc-unpack SYSTEM "unpack.dtd">
<ibm-wc-unpack>
 <unpack>
  <include file="*"/>
  <exclude file="SAR-INF/*"/>
  <exclude file="*.zip"/>
  <exclude file="*.war"/>
  <exclude file="FashionFlow/devtools/flow/ui/*.properties"/>
  <exclude file="xml/*"/>
  <rename-store-dir target-name="FashionFlow">
   <store-dir path="WEB-INF/stores/FashionFlow" />
   <store-dir path="FashionFlow" />
   <store-dir path="WEB-INF/classes/FashionFlow" />
   <store-dir path="WEB-INF/xml/tools/stores/FashionFlow" />
  </rename-store-dir> 
 </unpack>
 <unpack dest="${wc:ToolsStoresPropertiesPath}">
  <include file="FashionFlow/devtools/flow/ui/*.properties"/>
  <rename-store-dir target-name="FashionFlow">   
   <store-dir path="FashionFlow" />   
  </rename-store-dir> 
 </unpack>
 <unpack dest="${wc:instanceDir}">
  <include file="xml/member/MemberRegistrationAttributes.xml"/>
 </unpack>
</ibm-wc-unpack>

The unpack.xml file determines which files to unpack (using the include and exclude elements), to which directories the files will be unpacked (using the unpack dest entity), and also renames directories (using the rename-store-dir entity).

By default, unpack unpacks all of the files of the store archive that it is located in. However, unpack can also unpack just certain files within the store archive, if specified. Also by default, unpack unpacks the files to the path obtained by combining the StoreDocRoot and StoreWebPath paths from the DevTools element in the instance XML. This path points to the document root of the Stores Web module. However, if specified, as in the above example, <unpack dest="${wc:ToolsStoresPropertiesPath}">, unpack will unpack the files in another location. Note unpack accepts variables. In this case the "${wc:ToolsStoresPropertiesPath}" the ToolsStoresPropertiesPath variable is an attribute of the devtools element in the instance.xml.

Updates publish parameters

After the assets are unpacked from the store archive, WebSphere Commerce updates the DTD file (in the starter stores, ForeignKeys.dtd) with the publishing parameter values created or selected in the publish wizard. For example, if the original file contained <!ENTITY STORE_IDENTIFIER "FashionFlow">, the updated file contains <!ENTITY STORE_IDENTIFIER "MyFashion">.

Note: Publishing parameters are only available through the Publish wizard. If you publish a store archive through the command line you can not select publishing parameters

Publish data

After the files are unpacked and the publish parameters are updated, a scheduled job is created for the publish process. The scheduled job number for publishing the store archive is displayed on a Publish wizard page.

When the scheduler runs the publish job, WebSphere Commerce typically completes the following actions:

The publish job is controlled by the ibm-wc-load.xml file, contained in each store archive.This file is specified by the deploy-descriptor attribute in the stores-refs.xml file.

ibm-wc-load.xml

The ibm-wc-load.xml file determines what tasks will be completed in the publish job and the sequence of these tasks. The following is an example of an ibm-wc-load.xml file:

<data-deploy base-dir="." default-target="all">
    <asset id="master" location="store-data-assets.xml"/>
    <asset id="resolved.master" location="store-data-assets.resolved.xml"/>
    <asset id="foreignKeys" location="ForeignKeys.dtd" type="dtd"/>
    <asset id="pmconfigfile" location="paymentinfo.xml"/>
    <deploy-task-cmd name="configPM" class="com.ibm.commerce.tools.devtools.publish.tasks.payment.ConfigurePaymentTaskCmd"/>
    <target id="all">
     <task name="idresolve">
              param name="infile" value="${asset:master}" />
              param name="outfile" value="${asset:resolved.master}" />
     </task>
     <task name="massload">
              param name="infile" value="${asset:resolved.master}" />
     param name="maxerror" value="1" /> 
              param name="noprimary" value="error" />
    </task>
    <task name="configPM">
              param name="paymentConfigFilename" value="${asset:pmconfigfile}" />
              param name="storeIdentifier" value="${asset:foreignKeys#STORE_IDENTIFIER}" />
              param name="organizationDN" value="${asset:foreignKeys#ORGANIZATION_DN}" />
        </task>
   </target>
</data-deploy>

where

Loads store data from the XML files in the store archive to the database

While loading the store data from the XML files in the store archive to the database, WebSphere Commerce does the following:

Calls the ID Resolver to resolve IDs

The ID Resolver, which is a Loader package utility, generates unique identifiers for XML elements in the store archive XML files. For example, the ID Resolver replaces the @ alias used in the starter store XML files with a unique value. For an example of internal-alias resolution used in the starter stores, see Using internal-alias ID resolution.

Note: The ID Resolver can also resolve identifiers for already published stores, when you republish. For example if you have published the store archive once, and you need to republish the store archive or portions of it, ID Resolver retrieves the unique identifiers from the database and uses those during the republishing process.

For more information on the ID Resolver and the other components of the Loader package, see Overview of loading store data.

When the publish calls the ID Resolver, it must specify which ID Resolver method to use. The ID Resolver has several methods, which can be used to process the ID Resolver input; specifically, whether to treat the data as if identifiers exist in the original data (update method) or do not (load method). Mixed method is used when some identifiers exist and others do not. You can specify which method the publish will use in the WebSphere Commerce Configuration File, instance_name.xml. By default, publish uses the mixed method. For more information on the ID Resolver methods, see ID Resolver command.

Publish must also specify a customizer file to be used with the ID Resolver. The default customizer files are the following: DB2ConnectionCustomizer.properties or OracleConnectionCustomizer.properties.

Note: To specify your own customizer file, change the value of the following attribute in the DevTools section of the instance_name.xml file to the name of your customizer file without the extension:

store-data-asset.xml

Each starter store archive contains a store-data-asset.xml file. The store-data-asset.xml file includes placeholders for all of the data asset files in the store archive that will be included during publish.

The following is a portion of the store-data-asset.xml file for the ConsumerDirect.sar, illustrating the placeholders:

<?xml version="1.0"?>
<!DOCTYPE import SYSTEM "store-data-assets.dtd">

<import>
 &modelorg.xml;
 &modelorgrole.xml;
 &storeorg.xml;
 &storeorgrole.xml;
 &fulfillment.xml;
 &store.xml;
 &en_US_store.xml;
 &en_US_fulfillment.xml;
 &catalog.xml;
 &en_US_catalog.xml;
 &tax.xml;

During publish, all the data assets identified with placeholders in the store-data-asset.xml file are consolidated into one large document. The ID Resolver resolves the IDs found in the document. After the IDs are resolved, ID Resolver creates the following file, store-data-asset.resolved.xml, which contains unique IDs. If an error occurs during the ID resolving process, the Loader package adds an entry to the messages.txt file. For more information, see Publish log files.

Calls the Loader package to load the resolved master XML file into the database

The Loader package loads the resolved store-data-asset.resolved.xml into the database. If an error occurs during the loading process, the Loader package adds an entry to the messages.txt file.

For more information on the Loader package, see Overview of loading store data.

When the Publish wizard or PublishStore utility calls the Loader package, it must specify which Loader method to use. The Publish wizard can use any of the following Loader methods:

Note: By default the Publish wizard uses the SQL import method.

You can specify which method the Publish wizard or the PublishStore will call in the WebSphere Commerce configuration file, instance_name.xml, using the LoaderMode attribute in the DevTools element:

sqlimport
This method uses Java Database Connectivity (JDBC) to insert and update data, providing the most flexible method of operation but also the slowest for importing large amounts of data into a small number of tables. It allows column-level update. It is recommended that you use SQL import.

Note: SQL import method is the safest method to use because it will not corrupt your database if the data is invalid. Before you can load using SQL import, the records must meet the database schema constraints. The other Loader methods are faster because they are bulk loaded into the database without much checking. As a result you must be certain of data correctness before using the other methods.

import
This method uses DB2 native import functions and allows cell-level update with medium speed and flexibility. This method is not available with Oracle.
load
This method uses the native facilities of the RDBMS (DB2 Load or SQLLoad) and is the fastest method for loading large amounts of data into a small number of tables.

For more information on the methods in the load command, see Load command.

The Publish wizard and PublishStore utility must also specify a customizer file to be used with the Loader. If you do not specify a customizer file in the WebSphere Commerce Configuration File, instance_name.xml, the publish code will use the default customizer file: MassLoadCustomizer.

Note: To specify your own customizer file, change the value of the following attribute in the DevTools section of the instance_name.xml file to the name of your customizer file without the extension:

By default the WebSphere Commerce Configuration File, instance_name.xml, does not specify a value for this attribute.

Reconciles the store languages

The starter store archives contain data for all languages supported by WebSphere Commerce. As a result, when the Loader package loads the store data, all language information is loaded for the store. However, a store can only support the languages that are supported by the instance the store resides in. The reconcile store language task ensures that only the languages supported in the instance are enabled in the store. If you want to add support to the instance for additional languages, do so by using the Configuration Manager.

Updates registry components

The publish process also updates the registry components. Publish updates all of the registries in WebSphere Commerce by calling the com.ibm.commerce.scheduler.commands.RefreshRegistryCmd.

Calls command to publish business accounts and contracts

Some of the store database assets, (contracts and business accounts) cannot be loaded by the Loader package, so publish also calls the corresponding commands to publish those assets to the WebSphere Commerce Server. These commands are as follows:

AccountImport
Creates a business account from the businessaccount.xml file in the store archive.
ContractImportApprovedVersion
Imports a contract from the contract.xml file in the store archive.
ProductSetPublish
Synchronizes the product set data in the database with the catalog before business accounts and contracts are created. The Publish wizard and the PublishStore utility call the ProductSetPublish command, which then calls the AccountImport and ContractImportApprovedVersion commands.

For more information on publishing business accounts and contracts, see Publishing business accounts and contracts.

Configures payment

The publishing process also includes a step to configure payment. WebSphere Commerce supports WebSphere Commerce Payments. If you plan to use WebSphere Commerce Payments as your method of processing payment, you should create a payment XML file as described in Creating payment assets using an XML file. If a payment XML file is included in the store archive being published, WebSphere Commerce will complete the following payment configuration during publish:

Creates parameters.jsp file

The publish process creates the file parameters.jsp. This file includes the storeId parameter. The index.jsp file in the starter stores uses this parameter to launch the store.

parameters.jsp is located in the following directory:

Error handling

If an error occurs during the publish assets phase of the publish process, you can view the error message either in the publish logs (see Publish log files) or through the Publish Summary page of the Publish wizard.

Feedback