Projects

Article
01/18/2011

You create Commerce Server 2009 Staging (CSS) projects to define the specific Web site assets that you want to update on other servers, to schedule when to move the content, and to specify a source and destination for the deployment. A project is a container for maintaining the properties for and definition of an actual deployment. Projects contain the location of the assets to deploy and other project parameters, such as the source directory, destination server, and destination directory.

You use the CReplicationProject object to administer projects on a server. The following sections summarize how this object is used to manage staging projects:

Project Types
Project Destinations
Project Properties
Project Replication Flags
Project Access Rights
Defining Staging Project
Starting and Stopping Projects
Retrieving Project Information

Project Types

There are three types of staging projects:

Web content. Used to replicate Web sites, individual files, and directories.

Note

Web content projects can be used to replicate any files from one server to another. Web content projects are not restricted to replication of Commerce Server 2009 site files.
IIS Metabase. Used to replicate the Internet Information Server (IIS) metabase associated with a Web site.
Business data. Used to update catalog data, marketing data, orders configuration, and site terms associated with a Commerce Server 2009 site.

The CSS system determines the project type based on the assignment of two properties:

For business data projects, the BusinessDataProject property is set to True. If it is set to False, the project is used to replicate Web content or IIS metabase.
For IIS metabase projects, the MetabaseReplication parameter is set to Yes.

If neither of these two properties is defined, the project is determined to be a Web content project. For a summary of project properties that can be set, see Project Properties.

Web content projects are also used to provide the context for replicating individual files by using the CReplicationClient object. For more information about how to replicate individual files, see Individual File Replications.

Project Destinations

You replicate projects from one server to another by specifying one or more destinations. The destinations you define for a project depend on where the server sits in the staging topology and whether one or more domains exist between the servers. For information about which staging topologies are supported for each project type, see What Network Topologies does Staging Support?

For each server in the staging topology, you define the project destinations for that server so that the data to be replicated is transmitted to the next server in the topology. A destination can be a server name, a route name, or a directory. For content or data to be staged, at least one destination must be specified for a project defined on the source staging server.

You use the CReplication.AddDestination and CReplication.RemoveDestination methods to add and remove a destination to/from a project. You use the CReplicationServer.AddRoute method to add a route to a server.

Project Properties

Project properties define the data to be replicated and how the data is to be replicated. The project properties that you can set vary depending on the project type. For a comprehensive overview of all the staging options available for each project type, see What are the Staging Project Options?

The following table summarizes the required project properties based on project type. These are in addition to the project name and destinations.

Project type	Required properties
Web content	LocalDirectory. Specifies the source directory whose files are to be replicated and the endpoint directory where files are transmitted.
IIS metabase	LocalDirectory. Specifies the name of the Web site who's IIS metabase is to be replicated. MetabaseReplication. Specifies the project is defined to update the IIS metabase (YES).
Business data	LocalDirectory. Specifies the absolute directory path of the directory to use to temporarily store data that is staged. BusinessDataProject. Specifies the project is defined to replicate Commerce Server 2009 business data (True). BusinessDataProjectXml. Specifies the absolute directory path and file name of the business data XML configuration file. This file selects the business data to be staged and how it is to be staged. For information about the contents of this file, see CSS Business Data XML Configuration File Syntax Elements.

You use the Put method to define or modify additional project properties. Optional properties that you can set for all project types are as follows:

AfterReceiveScript, AfterSendScript, BeforeReceiveScript, and BeforeSendScript. Specifies the path and file name of pre and post processing scripts.
MailTo, MailToFail, MailToSuccess. Specifies where to send e-mail messages when a project succeeds or fails.

For Web content projects, the following optional properties can also be set:

Filter options:
- ExcludeDir. Specifies a directory to exclude from replication.
- Filter. Specifies one or more filters that can be used to include or exclude a file or directory, apply a filter to a directory, apply a filter to all subdirectories. A file or directory filter can use wildcard characters.
- For additional filter options and file management options, see Web Content Project Replication Flags.
MapUrl. Specifies the URL to which the destination maps.
SkipLockedFiles. Specifies whether CSS will skip the replication of files locked on the source or overwrite a file on the target if it is locked or currently being used.
TransactionMethod. Specifies whether to enable transactional staging.
IIS virtual directory:
- CreateVirtualRoot. Specifies whether the Web content project is to stage to a virtual root directory.
- VRootWebSiteName. Specifies the relative path of the physical directory to be mapped for the virtual directory of the Web site defined for the project.
- VRootAttributes. Specifies the user rights that are set on the virtual directory:
When you specify a virtual directory, CSS creates the virtual directory on both the source and endpoint servers. This virtual directory will map to a logical directory and can be used by client browsers to access the project content. The virtual directories that CSS creates are not Web applications.

Project Replication Flags

Project replication flags are used to enable and disable options that determine how the replication should run. You use the Flags property to set which flags are active. These flags are only valid for Web content projects. They support the following staging options:

Automatic/NoAutomatic. Enable/disable monitoring of the Web content project directory for changes and stage change files immediately.
Delete/NoDelete. Enable/disable file deletion on the endpoint servers for files that were deleted on the source staging server.
DirsOnly/NoDirsOnly. Enable/disable replication of directories only, skipping the replication of Web content project files.
ExcludeAll. Exclude all subdirectories from the replication. Replicate only the current directory.
Force/NoForce. Enable/disable replication of all Web content project files, regardless of whether they have changed since the last time that a project replication was run.
Incremental/NoIncremental. Enable/disable checking of last modified date on Web content project files and only replicate those that have changed since the last time that a project replication was run. Default is Incremental.
Route/NoRoute. Enable/disable reference of the route table. Default is Route.

Note

This flag is the only flag that is valid for all project types. We recommend that you leave it set to the default assignment which is to enable route table reference.

For more information about replication flags, see CSS API Flags.

Project Access Rights

To create a project or modify its properties, you must have CSS administrator rights or CSS project rights to administer the project. You use the GrantAccess and RemoveAccess methods to grant or remove administrator rights on a project-by-project basis.

For more information about how to assign CSS user rights, see How Are CSS Authentication Accounts Defined and Managed?

Defining Staging Projects

You create a same-named project on each server in the staging topology. The properties that are defined for a project differ depending on the role played by the server. For the source server, the project properties specify the data to be staged, how the data should be staged, and the destinations to transmit the replicated data files. For each destination server, the project properties primarily define a project container that specifies a directory for the replicated data.

Note

You need CSS administrator rights to create and modify projects.

For each project that you want to stage, you perform the following sequence of tasks:

Determine the staging credentials that you will use to stage the project and create these credentials on each server in the staging topology. For information about staging credentials, see How Are CSS Authentication Accounts Defined and Managed?

Important Note:
To create staging projects, you must log into the staging server where you call the CReplicationServer.OpenProject method with an account that is a member of the CSS Administrators group. Also, the accounts you use to connect to remote host servers must also be members of the CSS Administrators group on the host server.

For business data projects:
1. Configure the required database permissions on the source staging server that is running SQL Server for the required accounts or groups. For more information about these requirements, see How to Stage Business Data.
2. Create a temporary storage directory on the source staging server. This directory corresponds to the LocalDirectory for the business data project.
3. Create a business data XML configuration file and set the business data project properties. Copy this file to the %COMMERCE_SERVER_ROOT%/Staging/Projects directory on each source and destination server in the staging topology.
  
  Note
  
  We recommend that you first create a business data XML configuration file by using the CSS Microsoft Management Console (MMC). You can then copy and modify the XML configuration file to support programmatic staging of business data. For information about the syntax of the business data XML file, see CSS Business Data XML Configuration File Syntax Elements.
For Web content projects:
1. Configure the security permissions on the destination folder on each endpoint server to provide full access to the staging authentication account for that server. For information about how to set folder permissions, see How to Set Folder Permissions for Staging Accounts.
2. Optional. If you select to create a virtual directory when staging the Web content, you must provide the CSS_SG security group on the source and destination CSS servers full access control permissions to the IIS metabase. For information about how to configure access to the Internet Information Services (IIS) metabase, see How to Configure Access to the IIS Metabase.
For IIS metabase projects:
- For each endpoint in the staging topology, configure the required IIS metabase permissions for the CSS service account and CSS users. The CSS service account must have permissions to update the IIS metabase. CSS users must have permissions to view the Web sites in the project properties dialog boxes accessed from the CSS MMC. For information about how to grant these permissions, see How to Configure Access to the IIS Metabase.
Optional. Create one or more routes as they are required to support the staging topology. Routes must be defined for each server referenced in the route. For information about routes, see Routes and How to Manage Routes.
Create the same named project on each server in the staging topology. For each project you create:
1. Add only those destinations to the project that represent the next hop in the staging topology.
2. Specify the LocalDirectory based on the project type.
3. Define all remaining required properties based on project type as summarized in Project Properties.
4. Optional. Set one or more optional project properties. You must define most optional project properties only on the source staging server.
5. Optional. For Web content projects, set one or more flags that define how to replicate the content files. For information about how to set these flags, see CSS API Flags. Set the flags on the project defined for the source staging server.
For more information about how to create a project, see How to Create and Modify a Staging Project.
Optional. Add and configure one or more schedules to a project depending on your staging automation requirements.
1. For a source staging server, add a replication schedule to its project.
2. For an endpoint server, add an apply schedule to its project if you want to use the timed release. This step is only valid for Web content projects.
For more information about how to work with schedules, see Schedules and How to Manage Staging Schedules.

Starting and Stopping Projects

As soon as projects are created, you can initiate replication immediately or according to a schedule defined for the project.

Note

You need CSS administrator or operator rights to start and stop projects.

Use the CReplicationProject.Start method to start project replication. You always initiate replication on the source staging server. By using this method, project replication starts immediately and returns a CReplicationInstance object. When you start a Web content project, you can also decide to specify a bitmask flag to set parameters for the replication. These are the same flags described in Project Replication Flags.

You can stop project replication on any server in the staging topology as needed by using the CReplicationProject.Cancel method. When you cancel a project that is running, the replication instance for the project is stopped and all content at each destination server will remain in its current state.

However, as soon as the project finishes and all files have been replicated, you cannot cancel the project. However, for Web content projects, you may revert files to their previously staged version by using the CReplicationProject.Rollback method. This method requires that you have enabled transactional processing for the project or on the server. For more information about rollback, see Web Content Staging Options.

Retrieving Project Information

You use one of the CReplicationProject enumeration methods to retrieve information for a project. You can retrieve the following types of information:

The properties that are defined for a project.
The set of users who have CSS administrator or operator rights to administer a project.
The set of files in a directory that have been replicated for a Web content or IIS metabase project.
The replication instances that are in a specific state that are running for a project.
The schedules that are defined for a project.

For information about how to retrieve project information, see How to Retrieve Project Information.

You can also access the CSS Microsoft Management Console (MMC) to monitor the status of projects that are run. For more information about how to monitor staging events, see Monitoring Commerce Server Staging.