Administer > Deploy > Publish a store archive
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.
To publish a store, have Site Administrator authority. Site Administrators can initiate the publish process using either of the following methods:
- Publish wizard
- publishstore utility
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.
It is not recommended that you publish the same store archive more than once, as doing so may overwrite data previously published.
IBM recommends that you do NOT publish more than one type of composite or organization structure store archive in the same instance. For example, do not publish a ConsumerDirect.sar and DemandChain.sar in the same instance. Do not publish the same composite store archive or organization structure store archive more than once, as doing so may overwrite data previously published.
Store archives can only be published to a single clone.
For Developer, you can use the Publish wizard to create a store in the development environment.
In a clustered environment, synchronize all cluster members after publishing any store archive.
The following diagram outlines the steps in the publishing process.
1. 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.
Example: unpack.xml file 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 preceding 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.
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 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:
- base-dir
- The directory of the information that is to be published. "." indicated that the information is located 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 may 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 assigned to task commands used within the publish process.
- deploy-task-cmd class
- The full name of task commands used within the publish process.
- target id
- A name 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. Note that in this sample the short name of the task is used. You may 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. Note that values can be variables. These variables will be resolved when the task is run.
3a. 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 utilities utility, generates unique identifiers for XML elements in the store archive XML files. For example, the idresgen utility 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 Use internal-alias ID resolution.
Note: The idresgen utility 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, 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, publish 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 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 idresgen utility resolves the IDs found in the document. After the IDs are resolved, 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 adds an entry to the messages.txt file.
Calls the loading utilities to load the resolved master XML file into the database
The loading utilities loads the resolved store-data-asset.resolved.xml into the database. If an error occurs during the loading process, the loading utilities adds 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
By default the Publish wizard uses the SQL import method.
3b. Reconciles the store languages
The starter store archives contain data for all languages 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 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.
3c. 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.
3d. 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, so publish also calls the corresponding commands to publish those assets to the WebSphere Commerce Server. These commands are...
- 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.
3e. Configures payment
The publishing process also includes a step to configure payment. If a payment XML file is included in the store archive being published, WebSphere Commerce will complete the following payment configuration during publish:
- Create the merchant.
- Create the account (for offline cassettes only).
- Create the brands specified in paymentinfo.xml (for
offline cassettes only).
- Assign user authority.
This step is required only if you are using commerce payments. The new payments does not need this section.
3f. 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...