Database Automated XML Upload/Download

Screen: ShopSite > Utilities > Database > Upload/Download

Database Automated XML Upload/Download

ShopSite's programmatic XML interface allows merchants the ability to write their own applications to automatically upload or download their store information.

Note:

The information on this page applies to Products and Pages only. For information on automated XML downloads of Orders, see Automated XML Orders Download.

There are three CGI programs used for the different tasks of downloading, uploading, and publishing the store. Each of these CGIs can be called from an automated script or manually, using a standard HTTP POST function. The following example demonstrates a typical URL used to invoke one of the scripts:

http://mystore.domain/cgi-path/db_xml.cgi?clientApp=1&dbname=products&fieldmap=inventory

In the example above, mystore.domain represents the domain name of the store, and cgi-path is the path to the ShopSite back-office CGI directory. In this example, we are using the db_xml.cgi program, and we are passing the following options: clientApp=1, dbname=products, and fieldmap=inventory. The meaning and use of the options is explained below.

Note:

Any spaces in values for any options should be replaced with a plus sign (+) when included in a URL. For example, the value Field Name would be represented as Field+Name:

. . ./dbupload.cgi?clientApp=1&dbname=products&uniqueName=File+Name

Developers interested in building client applications to use the automated XML Upload/Download utilities may want to check out the Automated XML Upload/Download SDK.

Downloading Data

The database download program allows you to export all or part of a database in XML format. The available options allow you to specify which database to export, what format to use, and which data you want.

Program Name:

db_xml.cgi

Options

Option Description Values

clientApp Required. Identifies the client application interface version. 1

dbname Required. The name of the database that is being accessed. pages
products

version Optional. The XML format version (based on ShopSite implementation). Using this option will ensure that your application downloads a compatible version of the database, in case future ShopSite versions require changes to the XML format. 7.1 (default)
7.0
6.3

fields Optional. A list of fields to download, delimited by the pipe (|) character. For example: fields=|fieldname_1|fieldname_2|fieldname_3| All (default)
any valid field from specified database

fieldmap Optional. A fieldmap lists field number and ID pairs that associate the data in the XML output file with the store data. You can create fieldmaps using the tool provided in the Database Download area in the ShopSite back office (click on Utilities > Database > Upload/Download, then select the database you want to create a fieldmap for, and click Download. In the Download fields section, find the Use field map option, select <New> from the pull-down menu, then click on Change.) any existing fieldmap name

Option	Description	Values
clientApp	Required. Identifies the client application interface version.	1
dbname	Required. The name of the database that is being accessed.	pages products
version	Optional. The XML format version (based on ShopSite implementation). Using this option will ensure that your application downloads a compatible version of the database, in case future ShopSite versions require changes to the XML format.	7.1 (default) 7.0 6.3
fields	Optional. A list of fields to download, delimited by the pipe (\|) character. For example: fields=\|fieldname_1\|fieldname_2\|fieldname_3\|	All (default) any valid field from specified database
fieldmap	Optional. A fieldmap lists field number and ID pairs that associate the data in the XML output file with the store data. You can create fieldmaps using the tool provided in the Database Download area in the ShopSite back office (click on Utilities > Database > Upload/Download, then select the database you want to create a fieldmap for, and click Download. In the Download fields section, find the Use field map option, select <New> from the pull-down menu, then click on Change.)	any existing fieldmap name

Uploading Data

The upload program can be used to upload MIME encoded XML files or to import an XML file that has already been uploaded to ShopSite's HTML output directory. For very large databases (usually over 10,000 records), you can break up the upload into several files and upload them in batches.

Program Name:

dbupload.cgi

Options

Option Description Values

clientApp Required. Identifies the client application interface version. 1

dbname Required. The name of the database that you are uploading. pages
products

filename Optional. Used if the XML file was previously uploaded to the ShopSite HTML Output directory, to indicate the name of the file to import. filename

uniqueName Optional. The unique database key field name. This value is used to match records in the uploaded XML data to records in an existing ShopSite database. The (none) option turns off record matching, which allows duplicate entries in your database (new records with the same name as an existing record will be uploaded as a separate record, rather than updating the existing record). Name
SKU (Products)
File+Name (Pages)
(none)

checkpoint Optional. For large databases, specify the interval between record checkpoints. 500 (default)
any number

newRecords Optional. If the XML upload contains new products or pages, setting this to "no" will ignore those rows during the import process. yes (default)
no

use_optimizer Optional. Setting this option to yes will run the link optimizer during the upload process. The optimizer will slow down the upload, but on very large databases (more than 100,000 records) the decreased time required to link records in the database makes the trade-off worth while. no (default)
yes

defer_linking Optional. When uploading large databases in batches, setting this to "yes" for all but the last file in the batch will postpone record linking until the full database has been uploaded. no (default)
yes

restart Optional. If an upload times-out or is interrupted, use the restart option to start the upload again from where it left off. 1

Option	Description	Values
clientApp	Required. Identifies the client application interface version.	1
dbname	Required. The name of the database that you are uploading.	pages products
filename	Optional. Used if the XML file was previously uploaded to the ShopSite HTML Output directory, to indicate the name of the file to import.	filename
uniqueName	Optional. The unique database key field name. This value is used to match records in the uploaded XML data to records in an existing ShopSite database. The (none) option turns off record matching, which allows duplicate entries in your database (new records with the same name as an existing record will be uploaded as a separate record, rather than updating the existing record).	Name SKU (Products) File+Name (Pages) (none)
checkpoint	Optional. For large databases, specify the interval between record checkpoints.	500 (default) any number
newRecords	Optional. If the XML upload contains new products or pages, setting this to "no" will ignore those rows during the import process.	yes (default) no
use_optimizer	Optional. Setting this option to yes will run the link optimizer during the upload process. The optimizer will slow down the upload, but on very large databases (more than 100,000 records) the decreased time required to link records in the database makes the trade-off worth while.	no (default) yes
defer_linking	Optional. When uploading large databases in batches, setting this to "yes" for all but the last file in the batch will postpone record linking until the full database has been uploaded.	no (default) yes
restart	Optional. If an upload times-out or is interrupted, use the restart option to start the upload again from where it left off.	1

Publishing Data

After new store data has been imported into ShopSite, it is necessary to regenerate the store pages with the new information. The same options available from the Back Office Publish tool can be included in an automated publish.

Program Name:

generate.cgi

Options

Option Description Values

clientApp Required. Identifies the client application interface version. 1

htmlpages Optional. If included, HTML pages will be generated. 1

custompages Optional. If included, Custom pages will be generated. 1

index Optional. If included, the search index will be updated. 1

regen Optional. If included, all store content will be regenerated. If left out, only the content that has changed since the last publish will be regenerated. 1

Option	Description	Values
clientApp	Required. Identifies the client application interface version.	1
htmlpages	Optional. If included, HTML pages will be generated.	1
custompages	Optional. If included, Custom pages will be generated.	1
index	Optional. If included, the search index will be updated.	1
regen	Optional. If included, all store content will be regenerated. If left out, only the content that has changed since the last publish will be regenerated.	1

If a publish times out before completing, you can call generate.cgi with the same options as before, and the publish will restart from where it left off.

ShopSite Help and Resource Center
Last updated: January 13, 2005
Give Feedback