Store publish process

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. In order to publish a store, you must have Site Administrator authority. Site Administrators can initiate the publish process by using either of the following methods: Publish wizard, publishstore utility.

For information about how to publish a store, see one of the following topics:

The following information explains the actions that are automatically completed when you publish a store.

Important:

Only one store archive at a time can be published. Concurrent publishing is not supported and might cause the publication of both store archives to fail.
The following scenarios might overwrite data that was previously published:
- If you publish more than one type of composite store archive or organization structure store archive in the same instance
- If you publish the same composite store archive or organization structure store archive more than once
For more information, see Publishing multiple store archives of one type per instance.
Store archives can be published to a single clone only.
In a clustered environment, you must synchronize all cluster members after you publish any store archive.

The following diagram outlines the steps in the publishing process.

Publish process diagram

1 Unpack the assets from the store archive

After you click 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 that is in the SAR-INF directory in the store archive.

The following sample code is the unpack.xml file from the Aurora.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="xml/*"/>
		<exclude file="meta-inf/Manifest.mf"/>
		<rename-store-dir target-name="StoreAssetsDir">
			<store-dir path="WEB-INF/stores/StoreAssetsDir/data/AOP/tools/StoreAssetsDir" />
			<store-dir path="WEB-INF/stores/StoreAssetsDir" />
			<store-dir path="StoreAssetsDir" />
			<store-dir path="WEB-INF/classes/StoreAssetsDir" />
			<store-dir path="WEB-INF/xml/tools/stores/StoreAssetsDir" />
			<store-dir path="WEB-INF/xml/seo/stores/StoreAssetsDir" />
			<store-dir path="WEB-INF/src/xml/commerce/store/propertiesViews/StoreAssetsDir" />
			<store-dir path="tools/stores/StoreAssetsDir" />
			<store-dir path="WEB-INF/classes/com/ibm/stores/resources/StoreAssetsDir" />
		</rename-store-dir>
	</unpack>
	<unpack dest="${wc:ToolsStoresPropertiesPath}">
		<include file="SAR-INF/devtools/flow/ui/*.properties"/>
		<rename-store-dir target-name="SAR-INF">
			<store-dir path="SAR-INF" />
		</rename-store-dir>
	</unpack>
	
	<unpack dest="${wc:instanceDir}">
		<include file="xml/member/MemberRegistrationAttributes.xml"/>
		<include file="SAR-INF/unpack.xml"/>
	</unpack>
	
	<unpack>
	<ear-exclude file="WEB-INF/stores/"/>
	<ear-exclude file="unpack.xml"/>
	<ear-include file="ibm-wc-load.xml"/>
	<ear-include file="ForeignKeys.dtd"/>
	</unpack>
</ibm-wc-unpack>

The unpack.xml file determines which files to unpack (by using the include and exclude elements), where to unpack the files (by using the <unpack dest> entity), and also renames directories (by using the <rename-store-dir> entity).

By default, all files of the store archive are unpacked. However, the unpack process can also unpack certain files within the store archive, if specified. Also, by default, the files are unpacked to the path that is 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 preceding example, <unpack dest="${wc:ToolsStoresPropertiesPath}">, the files are unpacked to another location.

Note: Unpack accepts variables. In this case the "${wc:ToolsStoresPropertiesPath}" in the ToolsStoresPropertiesPath variable is an attribute of the devtools element in the instance.xml.

2 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">.

3 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 the Publish wizard page.

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

Loads store data from the XML in the store archive to the database
Reconciles store data
Updates the registry components
Calls the commands to publish business accounts and contracts
Configures payment
Creates parameters.jsp file

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.

Example: ibm-wc-load.xml

The ibm-wc-load.xml file determines what tasks are completed in the publish job and the sequence of these tasks. The following code 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:

base-dir: The directory of the information that is to be published. "." indicated that the information is in the same directory as the ibm-wc-load.xml file.
default-target: The ID of a target that is to be executed. Only one target is executed during publish.
asset id: The ID assigned to the assets to be published. Assets are assigned IDs as more than one task might act upon them during the publish process.
location: The location of the asset assigned the ID, relative to the base directory (base-dir).
deploy-task-cmd name: The short name that is assigned to task commands used within the publish process.
deploy-task-cmd class: The full name of task commands that are used within the publish process.
target id: A name that is given to a sequence of tasks that are executed as a group. Multiple targets can be defined but only the one referred to by default target is executed during publish.
task name: The name of the task to be completed. In this sample, the short name of the task is used. You can add new tasks to the ibm-wc-load.xml file, but any new task must extend the following command: com.ibm.commerce.tools.devtools.publish.tasks.DeployTaskCmd.
param name: The name of the parameter for the task. Input parameters are passed to the task as name-value pair strings.
value: The value for the parameter. Values can be variables. These variables are resolved when the task is run.

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 idresgen utility to resolve IDs

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

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

For more information about the idresgen utility and the other components of the loading utilities, see Overview of loading store data.

When the publish calls the idresgen utility, it must specify which idresgen utility method to use. The idresgen utility 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. By default, the publish process uses the mixed method. For more information about the idresgen utility methods, see idresgen utility command.

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 sample is a portion of the store-data-asset.xml file for the ConsumerDirect.sar to illustrate 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 that are identified with placeholders in the store-data-asset.xml file are consolidated into one large document. The idresgen utility resolves the IDs that are found in the document. After the IDs are resolved, the idresgen utility creates the following file, store-data-asset.resolved.xml, which contains unique IDs. If an error occurs during the ID resolving process, the loading utilities add an entry to the messages.txt file.

Calls the loading utilities to load the resolved master XML file into the database

The loading utilities load the resolved store-data-asset.resolved.xml into the database. If an error occurs during the loading process, the loading utilities add an entry to the messages.txt file.

For more information about the loading utilities, see Overview of loading store data.

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

SQL import (default)
Import
Load

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

Reconciles the store languages

The starter store archives contain data for all languages that are supported by WebSphere Commerce. As a result, when the loading utilities loads the store data, all language information is loaded for the store. However, a store can support the languages that are supported by the instance the store resides in. The reconcile store language task ensures that only the languages that are supported in the instance are enabled in the store.

Updates registry components

The publish process also updates the registry components. Publish updates all of the registries in WebSphere Commerce by calling the command: 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 loading utilities. Therefore, the publish process also calls the corresponding commands to publish store database 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.

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 in the following directory WC_eardir/Stores.war/ storedir/include