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.
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:
- Publish wizard
- PublishStore utility
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:
<ref id="storeDir" entity="STORE_DIR" > <input type="text"/>
This entity creates the publish parameter store directory.<ref id="storeIdent" entity="STORE_IDENTIFIER" > < input type="text"/>
This entity creates the publish parameter store identifier.<ref id = "parentOrg" entity="ORGANIZATION_DN"> <input type="member" />
This entity creates the publish parameter organization.
where
- ref id is used as the key in the properties file specified by the store-refs resource-bundle attribute. It is used to obtain the translatable parameter name and the description that displays in the publish parameters page.
- entity is the name of the ENTITY in the target-dtd that is edited by this parameter.
- input type controls how the parameter is displayed on screen. If the input type is text, the parameter is displayed in an editable field. If the input type is member, all of the existing organizations display in a drop-down list. Read-only parameters cannot be edited.
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:
- resource-bundle="/SAR-INF/properties/publishNLS"
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:
- 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.
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 is 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 is the ID of a target that is to be executed. Only one target is executed during publish.
- asset id is 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 is the location of the asset assigned the ID, relative to the base directory (base-dir).
- deploy-task-cmd name is the short name assigned to task commands used within the publish process.
- deploy-task-cmd class is the full name of task commands used within the publish process.
- target id is 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 is 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 is the name of the parameter for the task. Input parameters are passed to the task as name-value pair strings.
- value is the value for the parameter. Note that values can be variables. These variables will be 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 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.
The OracleConnectionCustomizer.properties file is located in the following directory:
- WAS_installdir/installedApps/cell_name/WC_instance_name.ear/properties
The DB2ConnectionCustomizer.properties file is located in the following ZIP file:
- WAS_installdir/installedApps/cell_name/WC_instance_name.ear/lib/loader/IdResGen.zip
WAS_userdir/WAS_instance_name/installedApps/cell_name/WC_instance_name.ear/lib/loader/IdResGen.zip
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:
- IDResolverCustomizerFile="myIDResolverCustomizerFile"
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:
- SQL import
- Import
- Load
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:
- LoaderCustomizerFile="myLoaderCustomizerFile"
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:
- Create the merchant.
- Create the account (for offline cassettes only).
- Create the brands specified in paymentinfo.xml (for offline cassettes only).
- Assign user authority.
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:
- WAS_installdir/installedApps/cell_name/WC_instance_name.ear/Stores.war/storedir/include
WAS_userdir/WAS_instance_name/installedApps/cell_name/WC_instance_name.ear/Stores.war/storedir/include
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.