Commerce Server Command Line Tools

Commerce Server 2009 R2 includes a number of tools that are located in the Commerce Server 2009 R2/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 R2 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 Web site 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 can be one of the following:

OrderMapping /w <configfile> /t <groupname> [options] 
OrderMapping /channelconfig <channelconfigfile> [/sitename <name>] /t <groupname> [options]

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 /channelconfig option specifies the ChannelConfiguration.config file to use. The /sitename option is only used when there is more than one site specified in the ChannelConfiguration.config file.

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.

/f

Specifies the mapping schema file to use. Uses the entry in the Web.config file by default.

/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. The /t option must be specified otherwise the XSD will not be generated.

/o or /output

Specifies the output file for SQL stored procedures. Defaults to OrdersStorage.sql.

/s[qltables]

Generate SQL table definitions. If you do not specify this command line argument, the Order Mapping tool only generates SQL stored procedures.

Dd327897.alert_caution(en-us,CS.95).gifImportant Note:
If you specify the /s[qltables] argument, the Order Mapping tool generates DROP statements in the output SQL file, which will delete data in the database tables if the tables already exist. If you use this option and your database tables already exist, edit the output SQL file so that it does not delete data.

/x or /xsd

Specifies the output file for the XML schema. Defaults to groupnameXSD.xsd.

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 /channelconfig ChannelConfig.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

Commerce Server uses keys to encrypt credit card information in user profiles, and other uses. You use the ProfileKeyManager tool to create, modify and manage profile encryption keys. Key pairs (a public and a private key) can be stored in either an XML file or the Windows registry. 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).

You can use the ProfileKeyManager tool to perform the following tasks:

  • Creating new profile keys

  • Encrypting existing keys into the registry

  • Updating existing keys (rolling keys)

  • Validating a User Name and Password Pair

This section also contains information about:

  • Key File Formats

  • Service Connection String File

Creating New Profile Keys

You can use the ProfileKeyManager to create a new key using the following syntax:

ProfileKeyManager /kn [/l {keylength}] [/o [{file}] [/pe {numpasswords} [/pswd {username} {password}] [/pswd.]] [/f] [/facl {user} [/facl...]]] [/reg [regkey] [/racl {user} [/racl...]]]
ProfileKeyManager /ke [/pswd {username} {password}] [/pswd.] /kf {keyfile} [/reg regkey] [/f] [/racl {user} [/racl...]] [/o [{file}] [/facl {user} [/facl...]]]
ProfileKeyManager /kc [/kfo {OldKeyFile}] {/kfn {NewKeyFile}} {/i {1 | 2}} {/config {ConfigFile}} [/wc [ProfileName1 WhereClause1] ... [ProfileNameN WhereClauseN] [/p {PropertyToBeEncrypted1} ... [PropertyToBeEncryptedN]]
ProfileKeyManager /auth /pswd {username} {password} /kf {keyfile} 

The following table lists the options that are available when using ProfileKeyManager to create a new key.

/kn

(Key new). Generates a new key pair (public/private).  The following arguments may be specified with the /kn option:

/l <length>

(Key length) The key length to use for the public / private key pair generated. The default is 2048.

/o <file>

(Write to file). The new key pair is written to the {file} specified. If {file} is not provided, the file name used is "NewKeyPair_timestamp.xml" where timestamp is the current timestamp.

Access Control Logs (ACLs) are assigned so that only the user running the tool and local administrators can access it. Can be specified only with the /kn or /ke option

/pe <numpswds>

(Password Encrypt). Specifies that the public/private key pair generated should be encrypted using one or more user-provided passwords. The {numpasswords} parameter specifies the number of passwords that will be used to encrypt the public / private key pair generated. The /pe flag cannot be combined with the /reg flag.

/pswd <username> <password>

(user name and password). Specifies a pair of user name and password, where the password is to be used to encrypt the public/private key pair, and the user name is to be stored in the key file for reference purpose. /pswd flag must be used in conjunction with /pe flag, whose {numpasswords} parameter determines the total number of /pswd flags that must be present.

Important   Passwords provided to /pswd flag from the command line are not masked and can be observed. Be cautious with /pswd flag.

/f

(Force overwrite). Specifies that the file specified in the /o parameter, and the registry key specified in the /reg parameter should be overwritten if they already exist. If not specified, key generation will fail if either the registry key or file already exist.

/facl <user>

(File access control list). Specifies a user that should be granted read-only access to the file generated by the /o parameter. /facl can only be used when /o is specified. Multiple /facl flags may be specified.

/reg <regkey>

(Registry key). The keys generated are encrypted using DPAPI with the local machine key, and then placed into the registry key specified.

The public key will be named "PublicKey", and the private key will be named "PrivateKey". If the /o parameter is specified, the properly formatted registry key paths will be written to the output file, rather than the clear-text encryption keys.

/racl <user>

(Registry access control list). Specifies a user that should be granted read-only access to the registry key generated by the /reg parameter.  /racl can only be used when /reg is specified. Multiple /racl flags may be specified.

Example

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\9.0 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 RSA Key Pair Using Passwords Supplied by Users

To prompt users for multiple passwords to be used to encrypt the generated RSA key pair and store it to an XML file using the ProfileKeyManager, use the following syntax:

Profilekeymanager /kn /[/pswd <username> /pe <number> /o <file>

The /pe parameter is used with the /kn parameter in order to generate a new password encrypted key. <number> is mandatory and specifies the number of passwords to be entered. There can be a maximum of ten (10) passwords.

If /pe is absent, the generated RSA key pair will not be encrypted.

Note

The /pe flag cannot be combined with the /reg flag.

To ensure that users do not enter insecure passwords, password policy required by PCI DSS is supported, which means that the password must be at least 7 characters in length, and consist of both alphabetical and numeric charactersThe following example demonstrates the generation of a key pair, saved as the xml file keypair.xml and the encryption of the key pair using two passwords:

C:>ProfileKeyManager.exe /kn /pe 2 /o keypair.xml 
Please enter 2 passwords to encrypt key pairs to be generated!
Password must contain at least 7 characters, both numeric and alphabetic!

Please enter the NAME of the person owning password 1: alice
alice, please enter your password    : *******
alice, please re-enter your password : *******

Please enter the NAME of the person owning password 2: bob
bob, please enter your password    : *******
bob, please re-enter your password : *******

Encrypting Existing Keys into the Registry

You can use the ProfileKeyManager tool to encrypt existing keys and then store them into the registry. The syntax for the command is:

ProfileKeyManager /ke [/pswd <username> <password> [/pswd…]] /kf <keyfile> [/reg <regkey>] [/f] [/racl <user> [/racl…]]] [/o <file> [/facl <user> [/facl…]]] 

When deploying a key file that contains a password encrypted public/private key pair (see the /pe option of the /kn command), all passwords used to encrypt the key pair must be specified.

The following table lists the options available when using ProfileKeyManager to encrypt existing keys.

/ke <user>

(Encrypt existing keys). Takes an existing key file, encrypts the keys using DPAPI with the local machine account, and adds them to the system registry. This mode of operation should be used to deploy the same encryption keys to multiple servers in a web farm in a secure fashion.

When deploying a key file that contains a password encrypted public /private key pair (see the /pe option of the /kn command), all passwords used to encrypt the key pair must be specified. The following arguments may be specified with the /ke option:

/pswd <username> <password>

(user name and password). Specifies a pair of user name and password, where the password is to be used to encrypt the public/private key pair, and the user name is to be stored in the key file for reference purpose. /pswd flag must be used in conjunction with /pe flag, whose {numpasswords} parameter determines the total number of /pswd flags that must be present.

Important Passwords provided to /pswd flag from the command line are not masked and can be observed. Be cautious with /pswd flag.

/kf <user>

(Key file). The already existing key file containing the encryption keys that should be added to the system registry. The key file should have the following format:

<?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>

Or when the key file contains a password encrypted public / private key pair:

<?xml version="1.0"?>

<Keys xmlns="https://schemas.microsoft.com/CommerceServer/2006/08/ProfilesKeyFile">

<PublicKey>"base64 encoded string"</PublicKey>

<PrivateKey>"base64 encoded string"</PrivateKey>

<Password>

<PasswordOwner>User1</PasswordOwner>

<PasswordSalt>"base64 encoded string"</PasswordSalt>

<PasswordHash>"base64 encoded string"</PasswordHash>

</Password>

<PBKDF2Parameters>

<Salt>"base64 encoded string"</Salt>

</PBKDF2Parameters>

</Keys>

When a password protected key file is specified, all passwords used to encrypt the key file must be provided before the encryption keys can be deployed.

If a "registry key path" is provided, it will have the format "registry:{hive}[\{subkey}],[{valuename}]". {hive} is the key hive name (i.e. HKLM, HKEY_CURRENT_USER, etc.).  {subkey} is an optional subkey name.  {valuename} is an optional name of the value in the registry key. If {valuename} is not specified, the (default) value is used.

Example: registry:HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\CommerceServer\9.0\Encryption Keys,PublicKey

/reg <regkey>

(Registry key). The keys generated are encrypted using DPAPI with the local machine key, and then placed into the registry key specified.

The public key will be named "PublicKey", and the private key will be named "PrivateKey". If the /o parameter is specified, the properly formatted registry key paths will be written to the output file, rather than the clear-text encryption keys.

/o <file>

(Write to file). The new key pair is written to the {file} specified. If {file} is not provided, the file name used is "NewKeyPair_timestamp.xml" where timestamp is the current timestamp.

Access Control Logs (ACLs) are assigned so that only the user running the tool and local administrators can access it. Can be specified only with the /kn or /ke option

/racl <user>

(Registry access control list). Specifies a user that should be granted read-only access to the registry key generated by the /reg parameter. /racl can only be used when /reg is specified.  Multiple /racl flags may be specified.

/f

(Force overwrite). Specifies that the file specified in the /o parameter, and the registry key specified in the /reg parameter should be overwritten if they already exist. If not specified, key generation will fail if either the registry key or file already exist.

/wc

(Where clause). Specifies a profile name and a CSOLEDB WHERE clause that can be used to restrict the profiles that will be rolled to the new public / private key pair.  You must make sure that the WHERE clause is enclosed in quotation marks so that the tool treats it as a single token.  For example:

/wc CreditCard "WHERE GeneralInfo.expiration_month = 1"

Updating Existing Keys (Rolling Keys)

To roll data (that is, re-encrypt profile data using a new key pair or encrypt previously decrypted profile data using a key pair) using the ProfileKeyManager, use the /kc (key change) option with the following syntax:

ProfileKeyManager /kc [/kfo <oldFile>] /kfn <newFile>] /i <1|2>][/config <configFile> [/wc <profile1 WhereClause1> … <profileN WhereClauseN>] [/p <property1> … <propertyN>]

If either of the key files contains a password-encrypted public/private key pair, it is recommended that you first use the /ke command to add these keys to the system registry and produce a key file where key pairs are specified using the registry path. This allows the tool to run multiple change-key batches without requiring manual password entry for each batch, and is more secure than using a key file with plain-text key pairs.

The following table lists the options available when using ProfileKeyManager to update existing keys.

/kc

(Key change). Rolls the data by encrypting it with the new keys supplied. If either of the key files contains a password-encrypted public / private key pair, it is recommended that you first add these keys to the system registry using the /ke command. This is more secure and allows the tool to run multiple change-key batches without requiring manual password entry for each batch. The following arguments may be specified with the /kc option:

/kfo

(Old key file name). An XML file that contains the old key pair used for encrypting the data. See the /kf parameter for the file format.

/kfn

(New Key File Name). An XML file that contains the new key pair used for encrypting the data. The file is similar to the /kfo file.

/i

(New key index). The new global key index. Valid values are 1 and 2.

The key index property is extremely important, and must be aligned correctly with the global key index value. That is, if the current global key index value is 1, then the New key index must be 2 and vice versa. Incorrect key specification can result in data loss. It is the responsibility of the site administrator to verify the correctness of the value supplied at runtime; the tool is unable to check this value.

/wc

(Where clause). Specifies a profile name and a CSOLEDB WHERE clause that can be used to restrict the profiles that will be rolled to the new public / private key pair.  You must make sure that the WHERE clause is enclosed in quotation marks so that the tool treats it as a single token.  For example:

/wc CreditCard "WHERE GeneralInfo.expiration_month = 1"

/p

(Properties to be encrypted). This option is followed by a list of properties that must be encrypted. The maximum length for property names is 128 characters; valid characters are alphanumeric, underscore (_) and dash (-). The properties should be prefixed by the name of the profile. For example, if you have a UserObject profile in which you want to encrypt the property MyProperty, which is nested under the group MyGroup, you would provide UserObject.MyGroup.MyProperty as an argument. Specifying properties that do not exist, that are primary keys, or that are already encrypted will produce errors.

/config

(configuration file name). Specifies the XML file that stores the BizData, BDAO and Profiles service connection strings. The name of the file can consist of only 260 alphanumeric characters. The following is a sample configuration file:

<?xml version="1.0"?>

<Configuration xmlns="https://schemas.microsoft.com/CommerceServer/2006/08/ProfileKeyManagerConfiguration">

<ProfileConnectionString>Provider=CSOLEDB;Data Source=MYSERVER;Initial Catalog=MYSITE_profiles;Integrated Security=SSPI;</ProfileConnectionString>

<ProviderConnectionString>Provider=Commerce.DSO;Data Source=mscop://InProcConnect/Server=MYSERVER:Database=MYSITE_profiles:Catalog=Profile Definitions:Trusted_Connection=true:</ProviderConnectionString>

<BDAOConnectionString>Provider=SQLOLEDB;Data Source=MYSERVER;Initial Catalog=MYSITE_profiles;Integrated Security=SSPI;Network Library=;</BDAOConnectionString>

</Configuration>

/auth

(Validate user name and password). Validates if a pair of user name and password has been used to encrypt a public / private key pair stored in an existing key file (see the /pe option of the /kn command). If the user name and password combination provided is valid, the exit code of the program will be 0. Otherwise, the exit code will be -1.  The following arguments must be specified with the /auth option:

/pswd <username> <password>

(user name and password). Specifies a pair of user name and password, where the password is to be used to encrypt the public/private key pair, and the user name is to be stored in the key file for reference purpose. /pswd flag must be used in conjunction with /pe flag, whose {numpasswords} parameter determines the total number of /pswd flags that must be present.

Important   Passwords provided to /pswd flag from the command line are not masked and can be observed. Be cautious with /pswd flag.

/kf <user>

(Key file). The already existing key file containing the public/private key pair encrypted with passwords. Please see the /kf option of the /ke command for a sample key file with password encrypted public / private key pair.

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"

Validating a User Name and Password Pair

You can use the ProfileKeyManager tool to validate whether a user name and password pair has been used to encrypt a public/private key pair stored in an existing key file. If the user name and password combination provided is valid, the exit code of the program is 0. Otherwise, the exit code is -1.

To validate a user name and password pair, use the following syntax with the ProfileKeyManager command:

ProfileKeyManager /auth /pswd <username> <password> /kf <keyfile> 

The following table lists the options available when using ProfileKeyManager to update existing keys.

/auth

Validates if the specified user name and password pair has been used to encrypt a public/private key pair in the specified key file.

/pswd <username> <password>

Specifies a pair of user name and password, where the password is used to encrypt the public/private key pair and the user name is stored in the key file for reference. Only one user name and password pair can be specified.

Dd327897.alert_caution(en-us,CS.95).gifImportant Note:
Passwords provided with the /pswd flag on the command line are not masked. For security reasons, use this option with caution.

/kf <keyfile>

Specifies the existing key file containing the public/private key pair encrypted with passwords.

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>

If the key file contains a password-encrypted public/private key pair, it will have the following format:

<?xml version="1.0"?>
<Keys xmlns="https://schemas.microsoft.com/CommerceServer/2006/08/ProfilesKeyFile"
 <PublicKey>"base64 encoded string"</PublicKey>
 <PrivateKey>"base64 encoded string"</PrivateKey>
 <Password>
   <PasswordOwner>User1</PasswordOwner>
   <PasswordSalt>"base64 encoded string"</PasswordSalt>
   <PasswordHash>"base64 encoded string"</PasswordHash>
  </Password>
 <PBKDF2Parameters>
   <Salt>"base64 encoded string"</Salt>
  </PBKDF2Parameters>
 </Keys>

When a password-protected key file is specified, all passwords used to encrypt the key file must be provided before the encryption keys can be deployed.

If a registry key path is provided, it will have the following format:

registry:<hive>[\<subkey>],[<valuename>]

where <hive> is the key hive name (for example, HKLM, HKEY_CURRETN_USER,), <subkey> is an optional subkey name, and <valuename> is an optional name for the value in the registry key.

For example:

Registry:HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\CommerceServer\9.0\Encryption Keys,PublicKey

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".

Using PurgeCommerceData with Customised Order Schemas

To use PurgeCommerceData.exe with customised order schemas, create a config file (PurgeCommerceData.exe.config) in the same directory as PurgeCommerceData.exe. This file specifies the location of the customized "OrderObjectMappings.xml" file.

 

An example PurgeCommerceData.exe.config:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
    <configSections>
  <sectionGroup name="CommerceServer">
   <section name="orders" type="Microsoft.CommerceServer.Runtime.Configuration.CommerceOrdersSectionHandler, Microsoft.CommerceServer.Runtime, Version=6.0.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
  </sectionGroup>
    </configSections>
 <CommerceServer>
  <orders honorStatus="true" newOrderStatus="NewOrder">
   <MappingFiles StorageMappingFilename="location to user customized file\OrderObjectMappings.xml"/>
  </orders>
 </CommerceServer>
</configuration>

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.

See Also

Other Resources

Commerce Server Command Line Tools