Commerce Server Command Line Tools
Commerce Server 2009 includes a number of tools that are located in the Commerce Server 2009/Tools directory. These are command-line tools designed for specific purposes. The tools include:
CatalogCycleCop. Checks for cyclical references in the catalog.
CreateCatalogAuthorizationStore. Updates catalog authorization policies.
CreateProfilesAuthorizationStore. Updates profile authorization policies.
ExpirePromoCodeReservations. Reclaims abandoned promotion codes.
ExportCatalog. Exports catalogs in XML format. Can also generate an XSD file of the catalog schema and data (used by the BizTalk adapters).
ExportProfileXsd. Generates an XSD schema for the Profiles System for use by the BizTalk adapters.
ImportCatalog. Uses an XML file to create a catalog.
InventoryConsistencyChecker. Checks the consistency of the inventory files.
OrderMapping. Generates an XSD schema of the current Orders System.
PipeReg. Registers a new pipeline component.
ProfileKeyManager. Lets you create or regenerate profile encryption keys.
PurgeCommerceData. Purges deleted data from a site database.
RCXml2Resx. Converts RC.xml files to .resx format.
ReportInstaller. Installs data warehouse reports.
Note Most of the command line tools accept options preceded by a "/", although most also allow a hyphen "-" to be used instead. For consistency, the "/" is used in the syntax below.
CatalogCycleCop
The CatalogCycleCop tool checks catalogs for cyclical references. The syntax for CatalogCycleCop is:
CatalogCycleCop <sitename> [/c <catalogname>]
here sitename is the Web site that you want to check. The /c option lets you specify a catalog to check, otherwise Commerce Server checks all catalogs for circular references.
When CatalogCycleCop runs, a status message "CSCatalogCycleCop is detecting cycles" is displayed followed by the results. If no cyclical references are detected, the message "No catalog cycles were detected" is displayed.
CreateCatalogAuthorizationStore
The CreateCatalogAuthorizationStore tool provides a command line utility to update catalog authorization policies. The catalog authorization policy contains definitions (scopes) for catalogs, properties, and languages used in the catalog. The authorization policy is used by the Catalog Web service.
The CreateCatalogAuthorizationStore tool synchronizes the catalog authorization policy on the target Web site with the site's Catalog System by creating missing scopes.
You usually use the CreateCatalogAuthorizationStore tool in two circumstances:
When upgrading from an earlier version of Commerce Server, the scope of some of these entries is missing. The CreateCatalogAuthorizationStore.exe tool updates these entries automatically to the scopes that Commerce Server 2009 uses.
When staging business data from one Commerce Server site to another site, the staging site's authorization settings will overwrite those on the destination site. Depending on the catalog scope of the destination site, this may cause problems since the Catalog System on the destination may not be synchronized with the authorization scopes. The CreateCatalogAuthorizationStore.exe tool will update the scopes to reflect the catalogs.
To use the CreateCatalogAuthorizationStore.exe tool, open a command prompt window, and use the following syntax:
CreateCatalogAuthorizationStore <sitename> <filename.xml>
where sitename is the Web site name that you want to update and filename.xml is the catalog authorization store file name.
CreateProfilesAuthorizationStore
The CreateProfilesAuthorizationStore tool synchronizes profile authorization policy with the profile definitions that a site uses. The Commerce Server Profiles System uses an Authorization Manager file (in XML format) to define access control for profiles. The authorization policy is used by the Profiles Web service.
Typically, there are scopes defined in the file for each built-in profile definition. CreateProfilesAuthorizationStore makes sure that the definitions in the file are synchronized with the profile role assignments.
The syntax for the CreateProfilesAuthorizationStore is:
CreateProfilesAuthorizationStore <sitename> <filename.xml>
where sitename is the Web site that you want to synchronize and filename.xml is the profile file. If the XML file already exists, missing scopes are added without removing any scopes. If the XML file does not exist, it is created.
ExpirePromoCodeReservations
The ExpirePromoCodeReservations command-line tool lets you reclaim unused and abandoned promotion codes. Promotion codes are added to a shopper's basket and sometimes are not used (the customer decides not to proceed to checkout). Commerce Server keeps the promotion code in a reserved state, prohibiting its use by others. While most promotion codes are set to expire automatically, some do not or you need to reclaim unused codes for reuse before the expiry event. The ExpirePromoCodeReservations.exe tool lets you reclaim these unused codes either for reuse or cancellation.
When called, ExpirePromoCodeReservations examines the configuration settings for the site and updates the promotion code history and transaction tables with reclaimable promotion codes.
The syntax for the ExpirePromoCodeReservations is:
ExpirePromoCodeReservations <sitename>
where sitename is the Web site to examine for reclaimable promotional codes.
You can schedule the ExpirePromoCodeReservations task to run automatically by using the Windows Task Scheduler service. You should schedule the task to run at intervals shorter than the promotion code expiration time. By default, promotion code reservations expire after 30 minutes, so you can set ExpirePromoCodeReservations to run every 20 minutes.
ExportCatalog
The ExportCatalog tool creates a file containing an XML representation of the Commerce Server Catalog System. It can also generate an XSD representation for use by BizTalk adapters.
There are a number of options for ExportCatalog that let you control what is included in the created file.
The simplest syntax for the ExportCatalog tool is:
ExportCatalog /Site:sitename [options] <filename.xml>
where sitename is the name of the Website to use for the catalog schema and filename.xml is the name of the file to create (in XML format).
Instead of exporting the XML for a named Commerce Server site, you can use the Catalog Web service with this syntax:
ExportCatalog /WebService:URL [options] <filename.xml>
where URL is the URL of the Catalog Web service that you want to use for the export.
If you specify a Commerce Server site (as opposed to a Web service) you can optionally specify an authorization policy file that will be used to verify the current user is authorized to perform the export:
ExportCatalog /AzMan:filename [options] <filename.xml>
where filename is the Authorization Manager XML file.
There are a number of options that you can use with ExportCatalog to control how the XML is output. The same options apply for both options (Commerce Server site and Web service). The following table lists and describes these options.
/xsd |
Indicates to create an XSD representation of the schema. |
/Schema: All |
Exports all schemas. |
/Schema: Relevant |
Exports only the schemas of catalogs included in the export. |
/Schema: None |
Exports no schema. This is the default value. |
The following table lists and describes several filtering options that you can use to control the output.
/Catalogs:catalogname |
A comma-separated list of the catalogs to export. If not specified, all catalogs are exported. |
/PropertiesToExport:propertyname |
A comma-separated list of the properties to export. If not specified, all properties are exported. |
/ProductsAndCategories:clause |
Specifies the query clause used to select the products and categories included in the export. |
/Descendants:All |
Specifies to export all descendants. |
/Descendants:ImmediateChildren |
Specifies to export immediate children only. |
/Descendants:None |
Specifies that no descendants should be exported. This is the default value. |
/FilterDescendants:clause |
Specifies the SQL query clause used to select the descendants included in the export. |
/CatalogSetsToExport:catalogsets |
A comma-separated list of the catalog sets to include in the export. |
/Language:language |
Specifies the language for the export. |
/EmptyValues |
Specifies to export only empty values. |
The following table lists and describes two additional options that you can use to control the export.
/VCasBC |
Specifies to export virtual catalogs as base catalogs. |
/Namespace:namespace |
Specifies the namespace to use in the exported catalog XML. |
The command:
ExportCatalog /Site:ABC cschema.xml
will export all catalogs in the Commerce Server site ABC to a file called cschema.xml. This exported XML file will have no XML namespace specified.
The command:
ExportCatalog /Site:ABC /namespace:myname /xsd myfile.xml
will generate a file called myfile.xml from the site ABC and include the namespace specifier myname in the root node of the exported XML file.
ExportProfileXsd
The ExportProfileXsd tool generates an XSD version of the profiles schema for use with the profiles BizTalk adapter. The syntax for the ExportProfileXsd tool is:
ExportProfileXsd [-o filename] [-tn namespace] <-s sitename> <-c connectionstring> <profiletypes>
The -s option specifies either the name of the Commerce Server used as the source for the generated Profile XSD file. Instead of using the -s option, you can use the -c option to specify a connection string to the profiles database. The profiletypes are one or more profile types (multiple entries are separated by spaces) that you want to include in the XSD output.
The -o option is followed by the output XSD file name. If you do not use this option, the output is sent to the console.
The -t option is followed by a namespace to be used as the target namespace in the schema generated.
An example of using ExportProfileXsd is:
ExportProfileXsd /s MySite /o MySchema.xsd Address Organization
This generates an XSD file called MySchema based on the content from MySite. The output will contain only the Address and Organization profiles.
ImportCatalog
The ImportCatalog tool uses an XML file to create a catalog. There are a number of options for ImportCatalog that let you control the creation of the catalog.
The simplest syntax for the ImportCatalog tool is:
ImportCatalog /Site:sitename [options] <filename>
where sitename is the name of the Commerce Server site the catalogs will be created for, and filename is the name of the file to be read.
For example, the command:
ImportCatalog /Site:ABC cschema.xml
reads a file called cschema.xml to create a catalog for the Commerce Server site ABC.
If you specify a site (as opposed to a Web service) you can optionally specify an authorization policy file that will be used to verify the current user is authorized to perform the import by using this syntax:
ImportCatalog /WebService:URL [options] <filename>
where URL is the URL of the Web service that is the target.
Alternatively, you can give an Authorization Manager policy file (XML format) as the source by using this syntax:
ImportCatalog /AzMan:filename [options] <filename>
where filename is the Authorization Manager XML file.
There are a number of options that you can use with ImportCatalog to control how the catalogs are imported. The same options apply for both connection options (Commerce Server site and Web service). The following table lists and describes these options.
/ErrorThreshold:threshold |
Specifies the number of errors that are allowed to occur before the catalog import is aborted. The default is 100. |
/MergeRelationships |
Merges the imported relationships with the existing relationships. |
/Replace |
Specifies that the existing catalogs should be replaced with the imported catalogs. If this option is not specified, the catalogs are incrementally imported. |
/Transacted |
Enables transactional processing. |
/Validate |
Validates the schema before starting the import. |
/ValidateOnly |
Validates the schema, but does not import it. |
The following table lists and describes three filtering options for controlling the import.
/CatalogToImport |
Specifies the catalogs to import. |
/LastModified:date |
Specifies that only items modified after the provided date should be imported. This option is ignored if /Replace is specified. |
/PropertiesToImport:propertyname |
Specifies the properties to import. |
The following table lists and describes additional options that you can use to control the import.
/AllowSchema |
Allows schema changes to existing content. |
/Materialize |
Specifies that all imported virtual catalogs should be marked as materialized. |
/Namespace:namespace |
The import should be aborted if the namespace of the XML import file does not match the specified namespace. |
/SkipFullTextUpdate |
Specifies to not update the full text indices during import. |
/SkipExportReady |
Specifies to not set the export ready flag during import. |
/Unmaterialize |
Specifies that all imported virtual catalogs should be marked as not materialized. |
InventoryConsistencyChecker
The InventoryConsistencyChecker tool checks inventory files for consistency. The syntax for the InventoryConsistencychecker tool is:
InventoryConsistencyChecker -s <sitename> -l <logfile> [-f]
where sitename is the Web site to check and logfile is the file to use to capture the output.
If the optional -f flag is specified, the tool will attempt to fix any inconsistencies found.
OrderMapping
The OrderMapping tool generates a current XSD file of the Orders schema. The syntax for the OrderMapping tool is:
OrderMapping /w <configfile> /t <groupname> [options] <outputfile>
The /t or /type option specifies the root type for the generated XSD file. The groupname must be an Order-derived type (such as PurchaseOrder). The /w or /webconfig option specifies the Web.config file to use. The output file is the name of the file (in XSD format) that is the OrderMapping tool creates.
You can use options with the OrderMapping tool to further control its capabilities. The following table lists and describes these options.
/c or /collection |
Includes collections in the output. |
/i or /ignore |
Overwrites any existing output file. |
/nologo |
Suppresses display of start-up and copyright text. |
/n or /nosql |
Suppresses all SQL processing (output is only XSD). |
/tn <namespace> |
Specifies a namespace to be included. |
/p |
Generates only a partial XSD based on the /t option setting of a derived type. |
/x or /xsd |
Specifies the output file for the XML schema. |
Examples of using OrderMapping are:
OrderMapping /w Web.config /t PurchaseOrder /c /nosql /xsd MySchema.xsd
This command generates the file MySchema.xsd that can replace the schema in the default system schema file OrderGroupCollection.xsd.
OrderMapping /w Web.config /t Basket /nosql /xsd MySchema.xsd
This command generates MySchema.xsd that you can use to replace the default Basket.xsd schema file.
Note
To generate all possible schemas it is sometimes necessary to run the OrderMapping tool twice, both with and without the /c option.
PipeReg
The PipeReg tool opens a wizard that adds a new pipeline component. When opened at the command prompt, PipeReg displays the first wizard dialog box asking for the type of component to be added.
You can add components by using ProgID or by the component type library. After entering the ProgID or path to the library, click Next. This displays the Component section dialog box.
Select the categories that the new pipeline is to be available to, and move them to the Selected Categories pane by using the arrows. Click Next.
You can select to add only the components, only export the registration data, or do both actions, which is the default. Click Next.
The registration and export processes will begin. A confirmation dialog box appears. If the information is correct, click Close.
ProfileKeyManager
You use the ProfileKeyManager tool to create, modify and manage profile encryption keys. Key pairs (a public and a private key) are stored in an XML file. You can generate the XML file by using the ProfileKeyManager tool (creating a new key). If the XML file is lost, damaged, or needs replacing, ProfileKeyManager can generate a new key pair. The XML file generated by ProfileKeyManager is not compatible with other Commerce Server XML key files, so the new key must be manually pasted into the appropriate configuration location for each of the Commerce Server systems (such as ProfileWebService).
The ProfileKeyManager tool supports a number of options which depend on the task for which you are using the ProfileKeyManager tool. There are three typical situations:
Creating new profile keys
Encrypting existing keys
Updating existing keys (rolling keys)
Commerce Server uses keys to encrypt user passwords, credit card information in user profiles, and other uses.
This section also contains information about:
Key File Formats
Service Connection String File
Creating New Profile Keys
ProfileKeyManager can create a new key using the following syntax:
ProfileKeyManager /kn [options]
The /kn option generates a new public/private key. The following table lists and describes the options that are available when you create a new key.
/f |
Overwrites an existing key. If a key already exists, the command will fail without this option. |
/facl <user> |
Grants "user" read-only access to the file generated by the /o option. You can specify more than one /facl option on the command line, each with one user name. |
/l <length> |
Generates a key of length length. The default length is 1024. |
/o <file> |
Writes the output to file. If you do not use this option, the output is written to a file called NewKeyPair_time where time is the current timestamp. |
/racl <user> |
Grants "user" read-only access to the registry key that the /reg option creates. You can use multiple /racl options on the command line, each with one user name. |
/reg <key> |
Generates a key which is encrypted using the local machine key. The new key is placed into the registry key key. The keys are called "PublicKey" and "PrivateKey". When used with /o option, a specially formatted string that can be used in the web.config is written to the file. |
A simple example of using ProfileKeyManager to generate new keys is:
ProfileKeyManager.exe /kn /o NewKey.xml
This creates a new key pair XML file called NewKey.xml.
Another example of using ProfileKeyManager to generate new keys is:
ProfileKeyManager.exe /kn /reg "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Commerce Server 2007 Keys" /o /f
This generates new keys encrypted using the local machine key in the registry key "Keys" and puts pointers to the registry key (using a format compatible with web.config) in the file called "NewKeyPair_timestamp" where timestamp is the current system time stamp. Any existing file is overwritten in this example due to the /f option.
Encrypting Existing Keys
You can use the ProfileKeyManager tool to encrypt existing keys. The syntax for the command is:
ProfileKeyManager /ke /kf <key> /reg <key> [options]
where the /ke option encrypts the existing key file and adds the result to the registry. The /kf option specifies the existing file with encryption keys that is to be added to the registry. The /reg option is followed by the registry key into which the encrypted key pair is placed.
The following table lists and describes the options that are available to modify the behavior of the ProfileKeyManager tool when encrypting existing keys.
/facl <user> |
Grants "user" read-only access to the file that the /o option generates. You can specify multiple /facl options with a user for each. |
/o <file> |
Writes output to file. If you do not specify this option, the file name "NewKeyPair_timestamp" is used where timestamp is the current date and time. |
Updating Existing Keys (Rolling Keys)
To roll data (re-encrypt profile data using a new key pair or encrypt previously decrypted profile data using a key pair) using the ProfileKeyManager, use the following syntax:
ProfileKeyManager /kc /kfn <newfile> /i <1|2> [options]
where /kc encrypts the data with the new keys.
The /i parameter specifies the new global key index, which is either "1" or "2". If the existing key is "1", the new key must be "2" and vice versa. The /kfn parameter specifies the file containing the new key pairs.
The following table lists and describes the options available for use with the /kc option.
/config <configfile> |
Specifies the file containing the BizData, BDAO and profile service connection strings. See "Service Connection Strings File" below. |
/kfo <oldfile> |
Specifies the old key pair used for encryption. If you are re-encrypting with a new key pair this option is required. If encrypting previously decrypted data, this option must be omitted. |
/p <property1...> |
Specifies that any currently unencrypted properties are to be encrypted. Properties should be space-delimited and provided in the format profile.[group.]property. |
/wc <profile whereclause> |
Specifies the profile name with a clause that indicates the profiles to be rolled (see examples). The WHERE clause must be in quotation marks. |
The following example decrypts existing profile data using NewKey.xml and re-encrypts it using the keys specified in NewerKey.xml. This example does not generate a new key pair. The file ProfileStrings.config contains the profile resource connections:
ProfileKeyManager.exe /kc /kfo NewKey.xml /kfn NewerKey.xml /i 2 /config ProfileStrings.config
The following is an example of using the profile WHERE clause which only re-encrypts instances of profiles of type MyProfile1 whose property MyIntegerPrimaryKey is between 2 and 1000:
ProfileKeyManager … /wc MyProfile1 "WHERE MyIntegerPrimaryKey > 1 AND MyIntegerPrimaryKey <= 1000"
Key File Formats
The files that you use for encryption keys have a specific format, as shown in the following example:
<?xml version="1.0"?>
<Keys xmlns="https://schemas.microsoft.com/CommerceServer/2006/08/ProfilesKeyFile">
<PublicKey>"Hexadecimal_public_key" or "registry_key_path"</PublicKey>
<PrivateKey>"Hexadecimal_private_key" or "registry_key_path"</PrivateKey>
</Keys>
Service Connection String File
The service connection strings for BizData, BDAO, and the Profiles service are specified in an XML file. The connection string will only contain passwords if SQL authentication is used. If Windows authentication is used (the recommended approach) there are no passwords in the connection string. For security reasons, if this file contains passwords to the connections the file should be destroyed after use by the ProfileKeyManager tool. An example file is:
<?xml version="1.0"?>
<!-- This is a sample XML document. -->
<Configuration>
<ProfileConnectionString>Provider=CSOLEDB;Data Source=CommerceMachine;Initial Catalog=BlankSite_commerce;Integrated Security=SSPI; </ProfileConnectionString>
<ProviderConnectionString>provider=commerce.dso.1;data source=mscop://INPROCCONNECT/Server=CommerceMachine;Catalog=Profile Definitions;Database=BlankSite_Commerce:Trusted=True;</ProviderConnectionString>
<BDAOConnectionString>Provider=SQLOLEDB;Data Source=CommerceMachine;Initial Catalog=BlankSite_commerce;Integrated Security=SSPI;Network Library=;</BDAOConnectionString>
</Configuration>
PurgeCommerceData
The PurgeCommerceData tool lets you permanently remove four different types of information from Commerce Server databases:
Shopping baskets that have not been changed for a specified number of days (abandoned baskets)
All deleted products, categories, and inventory SKUs
Marketing System customers, campaigns, campaign items, and promotion codes that have been deleted for a specific number of days
Purchase orders that have not been changed for a specified number of days
The syntax for the PurgeCommerceData command is:
PurgeCommerceData <site_name> flag [options]
where site_name is the name of the Commerce Server site, and flag is one of the following depending on the data that you want to purge:
-b: purges baskets
-c: purges products, categories, and inventory SKUs
-m: purges marketing data
-p: purges purchase orders
options specifies options needed for the flag
The following table lists and describes the options that the PurgeCommerceData tool supports.
Option |
Works with these flags |
Description |
|---|---|---|
-d <days> |
-b, -m, -p |
Purges baskets that have been unchanged in the last specified number of days. |
-n <name> |
-b |
Purges baskets only with the specified name. |
-o |
-m |
Purges promotion codes for old discounts (used with the -d option; deletes codes that expired at least a set number of days ago). |
-s <status> |
-p |
Purges only purchase orders with the specified status. |
Purging Baskets
To purge shopping baskets, use the -b" flag with the "-d" parameter to purge baskets that have been unchanged for a specific number of days. You can narrow the purge to baskets unchanged for a specific number of days with a specified name using the "-n" option as well.
Syntax examples are:
PurgeCommerceData site_name -b -d 14
This command purges all baskets that have been unchanged in 14 days
PurgeCommerceData site_name -b -d 14 -n adwork
This command purges all baskets that have the name "adwork" that have been unchanged in 14 days
Purging Products, Categories, and Inventory SKUs
To purge all deleted products, categories, and inventory SKUs use the -c flag. There are no parameters with this flag. A syntax example is:
PurgeCommerceData site_name -c: purges all deleted products, categories, and inventory SKUs
Purging Marketing Entities
To purge all marketing entities (customers, campaigns, campaign items, and promotion codes) use the -m flag. The -d option purges entities that have been unchanged for a specific number of days. The -o option purges promotion codes for discounts that expired over the specified number of days. Syntax examples are:
PurgeCommerceData site_name -m -d 14
This command purges all marketing entities that have been deleted at least 14 days.
PurgeCommerceData site_name -m -d 14 -o
This command purges all marketing entities and all promotion codes that have been deleted or expired (in the case of promotion codes) at least 14 days.
Purging Purchase Orders
To purge all purchase orders use the -p flag. The -d option purges purchase orders that have been unchanged for a specific number of days. The -s option purges purchase orders with the specified order status that have been unchanged for a specific number of days. Syntax examples are:
PurgeCommerceData site_name -p -d 14
This command purges all purchase orders that have been unchanged at least 14 days.
PurgeCommerceData site_name -p -d 14 -s open
This command purges all purchase orders that have been unchanged at least 14 days and that have the status "open".
RCXml2Resx
You use the RCXml2Resx tool to convert RC.xml files to .resx format. This is useful is you are using the Message Manager to manage localized message handling with RC.xml files and need to convert the files to .resx files for use as satellite assemblies. Satellite assemblies are language-independent string resources. The syntax for RCXml2Resx is:
RCXml2Resx xmlfile [output]
where xmlfile is the name of the XML file to be converted and the optional output file will be the converted to .resx format. If no output file name is specified, the input file name is used with the .resx extension.
The following shows example code to use with the RCXml2Resx tool:
RCXml2Resx c:\inetpub\wwwroot\mywebapp\rc.xml
The example code converts the RC.xml file to an RC.resx file.
ReportInstaller
The ReportInstaller tool installs Data Warehouse reports. These reports should have an .rdl extension. The syntax of ReportInstaller is:
ReportInstaller /r <targeturl> /i <reportfile> [options]
where targeturl is the URL of the reporting server, and reportfile is the path to the Data Warehouse reports to be installed.
The following table lists and describes the options that you can use with the ReportInstaller tool.
/b |
Brands the reporting server as the analytics server. |
/d |
Specifies the Data Warehouse if there is more than one. |
/t |
Specifies the analytics folder name on the reporting server. |
The following is example code that you can use with the ReportInstaller tool:
ReportInstaller /r https://localhost/MyServer /i "C:\Reports"
This example code installs the reports in "C:\Reports" into the MyServer Web site.