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. If basic authentication is used, a value of 1 is needed. If ShopSite Login is used (implementing Oauth), a value of 2 is needed. 1, 2

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

download_shopsite_version Optional. Request the version of ShopSite the store is running, in the format major.minor (for example, 8.3). This allows you to check for version compatibility and make any adjustments based on that. This command was introduced in ShopSite version 8.3. 1

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. 11.0, 10.2, 10.1, 10.0, 9.0, 8.3 (default), 8.2, 8.1, 8.0, 7.1

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. If basic authentication is used, a value of 1 is needed. If ShopSite Login is used (implementing Oauth), a value of 2 is needed.	1, 2
dbname	Required. The name of the database that is being accessed.	pages products
download_shopsite_version	Optional. Request the version of ShopSite the store is running, in the format major.minor (for example, 8.3). This allows you to check for version compatibility and make any adjustments based on that. This command was introduced in ShopSite version 8.3.	1
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.	11.0, 10.2, 10.1, 10.0, 9.0, 8.3 (default), 8.2, 8.1, 8.0, 7.1
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. If basic authentication is used, a value of 1 is needed. If ShopSite Login is used (implementing Oauth), a value of 2 is needed. 1, 2

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)

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

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. If basic authentication is used, a value of 1 is needed. If ShopSite Login is used (implementing Oauth), a value of 2 is needed.	1, 2
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)
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
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. If basic authentication is used, a value of 1 is needed. If ShopSite Login is used (implementing Oauth), a value of 2 is needed. 1, 2

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

sitemap Optional. If included, a Google-type XML sitemap will be generated. 1

Option	Description	Values
clientApp	Required. Identifies the client application interface version. If basic authentication is used, a value of 1 is needed. If ShopSite Login is used (implementing Oauth), a value of 2 is needed.	1, 2
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
sitemap	Optional. If included, a Google-type XML sitemap will be generated.	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: August 30, 2011
Give Feedback

ShopSite Shopping Cart Software