Using Site Deployment Manager

Site Deployment Manager is a utility that ships as a part of CMS. SDM is used to import and export CMS-based assets. Exported assets are placed in a Site Deployment Object file, also referred to as a "package." When you are importing, the SDO file is processed by SDM, and the objects contained in the package are placed in the destination repository.

The interactive user interface for SDM is contained within Site Manager. This interface allows channel managers to export content and administrators to import or export content. Figure 21-1 shows the user interface for the import operation, and Figure 21-2 shows the export user interface.

Figure 21-1. The SDM import interface

Figure 21-2. The SDM export interface

Keep in mind that SDM is meant for CMS-based assets. SDM packages cannot include assets that are stored external to CMS. For example, all the template ASPX files are stored externally to CMS. As a result, when you deploy a CMS site, you'll have to create an SDO file for the CMS-based assets and then move the non-CMS based assets, placing them both on the destination server. Microsoft recommends using Application Center Server to handle moving the file-based assets. However, you may choose to use other methods perhaps a scripted FTP or other such method. There are no specific requirements for moving non-CMS based files, so the choice is yours.

NOTE: When moving a CMS application from one server to another for the first time, you must create a virtual directory on the destination server. When you create a new project through VS.NET, a virtual directory in your solution called CMS is automatically created. When moving your application to a new server, you must manually create this virtual directory under your application directory. The new virtual directory should be mapped to X:\program files\Microsoft Content Management Server\Server\IIS_CMS. This virtual directory contains the JavaScript code and certain assemblies for the Word Authoring Connector and the edit console. Also, you must remove the new application created for the new virtual directory; this virtual directory should inherit the application settings from your CMS application.

Creating Packages

There are two methodologies for processing packages in SDM: manual and scripted. If you choose to manually process packages, you will be using the interactive Site Manager interface. If you choose to use scripts, you'll end up using VBScript (VBS), which uses a COM-based API (yes, COM). Either methodology will work, and it's likely you'll use a combination, depending on the situation.

In the following sections, we'll discuss both the creation and the consumption of SDO files. We'll first start by showing you how you can create and consume SDO files using the interactive interface. After that, we'll walk you through the process of creating script files to allow you to incrementally deploy content from CMS.

NOTE: It's not possible to perform a full deployment through a script, and it's not possible to perform an incremental deployment through the interactive interface. In most cases, you'll end up using both methods at different times, based on the operation you need to perform. In addition, there may be some cases where it's simply easiest to back up and restore the entire SQL database. The drawback to this method is that you also carry the CMS settings specific to the source environment. We would recommend using an SQL backup/restore if you're moving a very large CMS database from one environment to another, similar environment. Use Site Deployment Manager for ongoing deployments.

Manually through Site Manager

Once of the easiest ways to process SDO files is using the manual interface in Site Manager. This interface will allow you to both export and import. The only restriction to processing SDO files is that only administrators can import content. However, channel managers have the ability to export content from their channels.

Export

To begin, you have to start Site Manager. Click the File menu in Site Manager. Now, choose Package and then Export. In Figure 21-3 you can see how this is done.

Figure 21-3. Starting SDM from Site Manager

Once you've started SDM, you'll be provided with an interface that allows you to choose which objects you'd like to export (shown in Figure 21-4). You'll immediately notice on the left side of the dialog box a complete listing of all containers in the system. To choose an item for export, simply click it and then click Include. This will place the object in the export list, just below the All Containers element. For our example, we've decided to export the BOTS Consulting site. So, we've chosen the botsconsulting channel and clicked Include to add it to the list of objects to be exported. When you chose a container, SDM will export that container and all its children. Since we picked the botsconsulting channel, SDM will export all channels and postings contained in the hierarchy of that channel. However, if you want to export a single posting object, you can simply select that single object. In our example, for each category of object (channels, templates, and resources), we've selected all the relevant containers for BOTS Consulting. In addition, we've supplied a file name in the Export to File field. In Figure 21-4, you can see what our export interface looks like now that we've added all the containers we want.

Figure 21-4. SDM set to export the BOTS Consulting site

Once you're ready to export your objects, just click Export. SDM will prompt you either to continue or to run a preexport report. If you choose to run a preexport report, SDM will simulate the export process to determine what will be exported and if any errors will occur. This same report can also be generated after the actual export process if you so choose. In our case, we've checked the option box that disables this prompt, and our export occurs immediately.

When you export objects, SDM will dutifully export all the objects you've specified, in addition to all dependent objects. For example, if a posting links to a resource that's in the resource gallery, the resource gallery item will automatically be moved, even though you didn't specifically include it in the export; in this way CMS prevents objects from "breaking" in the new environment. The only downside to this behavior occurs when you're moving content "backward" from production to development for testing. Since a posting needs a template to run, SDM will drag the templates for each posting along with the postings themselves. When you import the SDO in your development environment, the development templates will be overwritten with the ones from production. To avoid this problem, you should export your templates in development first, import your SDO from production, and then reimport your original development templates.

The length of time SDM takes to run depends entirely on the number and size of the objects it has to export. If your site is mostly HTML, is relatively flat, and doesn't have too many postings and/or resources, SDM could be done in a matter of seconds. If your site is very large, has a complex channel structure, and/or has lots of binary files, SDM may take longer to run. Once SDM finishes, you'll end up with one SDO file, which you can transfer to the other implementation of CMS to import. In Figure 21-5, we've provided a screen shot of one portion of the export report for our BOTS export exercise. As you can see, the report shows not only the channels, but the postings it exported.

Figure 21-5. The SDM export report

Now, let's go back to our export process and explore a few of the options available to you. The following is a list of options and functions in SDM and a brief explanation of each.

• Exclude: As its name suggests, it's the opposite of the Include option. Exclude allows you to specify particular objects to be excluded from the SDO. This is useful if you want to grab most of the objects in a given container but not all of them.

• Export Containers Only: Use this option if you simply want to export the selected containers but not the objects within them. For example, if you just wanted to transfer a channel structure, resource galleries, or template galleries to a destination CMS server, you could use this option to quickly move an existing structure. This is most commonly used when you are moving containers from a development server to a staging or production server, where the developers want to move a new navigation or gallery structure, but don't want to move any of the objects inside the containers (like test postings or resources).

• Report/Export Preview: This allows you to run an export preview report manually. This report will tell you exactly what will and won't be moved during an export process. It will also alert you to any potential errors.

• Report/Dependency: This allows you to run a dependency report on any object in the repository. For a given object, this report tells you what other objects may depend on it. For example, a template may have many postings that use it.

• File/Save Export Profile: This allows you to create an export profile. We'll learn more about profiles later in this chapter.

• Rights Options: If you want to back up and restore the groups and/or users associated with an object, you can use this option to create an SDO that includes this information. Backing up the user groups and rights is especially useful if you need to back up and restore the entire CMS database from one environment to another. You would first back up the rights groups from the destination, restore a database from a development source, and then import the rights groups back in to restore permissions.

Import

Now that you've walked through a manual export process, let's look at the import process. The import interface is started in a similar way to the export interface. First, start Site Manager, and pick the File menu and then Package. From the submenu choose Import. This will start SDM in import mode. Figure 21-6 shows this choice on the File menu.

Figure 21-6. Choosing Import from the Package menu

Once you've started SDM in import mode, let's open the SDO we created earlier and perform an import. Click the File menu and choose Open Package. Once you've done that, your SDO package will be listed at the bottom of the interface, in the Import from File (.sdo) field. Figure 21-7 shows the import interface with our BOTSConsultingSite. SDO chosen.

Figure 21-7. The SDM import interface with our SDO selected

As you can see, the import interface has a few more choices. In a lot of cases, it's likely you can simply perform the import with the default settings. However, let's review each of the options in the interface, described in the following list, before we proceed. When Adding Containers:

• Inherit destination parent rights: This will reset the permissions that may be stored in the SDO and replace them with the destination container parent's rights. For example, if you were importing a channel into the root channel (Channels) and the root channel allowed anonymous access, the new channel would also allow anonymous access.

• Use package container rights: This option will import the rights group assigned to the imported containers. Essentially, you're going to retain whatever rights were assigned to the containers in the source system.

• Leave container rights list empty: This option imports the containers in the SDO with no rights assigned.

When Replacing Containers:

• Inherit destination parent rights: This option specifies that replaced containers are to inherit the users assigned to the parent container on the destination server.

• Replace with package container rights: Choose this option if you want to use the source container permissions.

• Keep destination container rights: This option replaces the imported container's permissions with the permissions specified on the corresponding container in the destination server; essentially, you're leaving the destination server's permissions on replaced containers intact.

• Combine package and destination rights: This option will combine the rights from the source and destination servers.

• Change container hierarchy on destination to match the package hierarchy: This option will restructure the destination container to match the SDO package.

  Delete all existing container contents when replacing a container: When you select the "Change container hierarchy..." option, you can also select an option for SDM to delete containers in the destination machine that don't have a corresponding object in the SDO. This option is useful for "resetting" a destination server to match the source (such as moving a site from staging to production for the first time).

• Reports/Import Preview: This generates a report similar to the report we saw in the export process. The report will show you what objects were imported, replaced, and/or deleted. Further, should there be any potential problems, the report will show you those as well.

NOTE: Templates will not be deleted if pages based on the template still exist in the destination server.

At this point, we should be set up for a basic import. To begin the import process, simply click the Import button. Once the import completes, SDM will give you a success or failure message and the opportunity to see the import report. In Figure 21-8, you can see a portion of our import report. If you refer back to Figure 21-5, you will see the corresponding section of the export report; the two should match.

Figure 21-8. A portion of the import result report

So, now you should be familiar with the basics of importing and exporting objects. The interactive interface of SDM is a pretty easy tool to use and is quite handy. However, manually importing and exporting objects is not the best methodology if you have to continually move content between environments. As a result, Microsoft provides a COM-based interface to allow you to script an incremental import and export process. This COM-based interface can completely automate the process of importing and exporting content so that you can perform scheduled updates between, say, a development and staging environment or an authoring and production environment with little or no human interaction. In the next section, we'll show you how to create these incremental deployment scripts.

Deploying Content through the COM Interface

Although the interactive interface of SDM is convenient for the ad hoc movement of CMS objects from one environment to another, any regularly scheduled incremental import/export should be automated. Microsoft provides a COM-based interface that allows you to create scripts that can be used to export and import objects on some regularly scheduled basis.

NOTE: The COM interface will only export content that's changed. However, it will import anything in the source SDO file.

The COM interface is broken into two parts client and server and then two subcomponents import and export. Both the client and the server interfaces are the same from a functionality standpoint. The server object set is used to act on a local machine, and the client object is used for performing import or export tasks remotely. For example, if you were creating an export package on a source server, you'd use the server components. Once you've created the SDO package on the source server using the server component, you would transfer the SDO to the destination and use the client component on the source server to start a remote import process on the destination. In our examples, we're going to use the server object to export a package and then use the client object to perform the import. Both the server and the client deployment objects have virtually the same properties and methods.

Export

To begin, we're going to create an incremental export script to perform an incremental export of our BOTS Consulting site. In our example, we're going to use a VBS file. However, the COM objects can be used from within an ASP page or a .NET script (using the COM Interop). We chose a VBS file because it was convenient and it allowed us to easily create a task in the Task Scheduler (covered at the end of this chapter).

In our VBS file, we start by creating an export object from the CmsDeployServer library. The export object will handle all aspects of the export process on the server. To create the CmsServerExport object, use the following code:

 Set myCmsServerDeployment = Wscript.CreateObject("CmsDeployServer.CmsDeployExport.1") 

Next, you'll need to authenticate on the server. Remember, you can export content as a channel manager or an administrator. In our example we've embedded the user ID and password of our administrator for demonstration purposes. You could also pass in the credentials as parameters to the VBS file. The object model also provides an Authenticate AsCurrentUser method, which will use the current Windows user credentials, or the "run as" credentials if you use the Task Scheduler; choose the option that's appropriate for your environment.

 Call myDeployObject. AuthenticateAsUser("WinNT://CMSSERVER/admin","password") 

Once you've authenticated on the server, you can stipulate your export options by setting the ExportOptions properties in the CmsDeploy Export object. There are only two options when exporting and they're both related to the export of security information. The IncludeRightsGroups property allows you to determine whether you're going to export the rights groups in the SDO, and the IncludeCreatedBy property determines whether you're going to export the CreatedBy information (see Listing 21-1).

Listing 21-1 Setting the export options in our VBS file

 Set myExportOptions = myDeployObject.Options If ( Err.Number <> 0 ) Then             Call Msgbox(Err.Description, vbCritical, "Export Problem Authenticating User")       Set myDeployObject = Nothing       Set myExportOptions = Nothing       Exit Sub End If ' Include Rights groups and their members. ' ' IncludeRightGroups:   (1) Do not export rights groups or users (default) '                                               (2) Export rights groups without members '                                               (3) Export rights groups with members ' ' IncludeCreatedBy:     (1) Do not include created by information '                                               (2) Include created by information (default) ' myExportOptions.IncludeRightsGroups = 3 myExportOptions.IncludeCreatedBy = 2 

Once you've set the export options, you can start the export. In our example, we added some additional code for stipulating the export package we wanted to create. The export returns a URL to an export report. In a noninteractive mode, you may want to simply redirect the output to a file for review later. In our example, we're starting a browser session to show the report immediately. Listing 21-2 shows our code.

Listing 21-2 Setting the SDO file name and beginning the export process

 Dim strPackageFileName, sdoDateQualifier Dim strReportUrl ' Create a date qualifier for creating unique export names sdoDateQualifier =  day(now()) & month(now()) & _ year(now()) & hour(now()) & minute(now()) & second(now()) ' Set a string with the name and path of the SDO file strPackageFileName = "C:\BOTSConsultingSite" & sdoDateQualifier & ".sdo" ' Start the deployment ' The first option specifies the name of the export file ' The second option specifies the time interval.  A value ' of 0 specifies to export all objects that have changed since ' the last export regardless of time.  A value of 1 or greater ' specifies the age of objects to be exported.  For example, ' a value of 200 stipulates that all objects that have changed in ' the last 200 minutes should be exported. ' The last option specifies the channel to export.  If no value ' is provided, the entire repository will be evaluated.  All objects ' from the specified channel and below will be evaluated if a value ' is provided. strReportUrl = myDeployObject.Export(strPackageFileName,0,"/Channels/botsconsulting") If ( Err.Number <> 0 ) Then       Call Msgbox(Err.Description, vbCritical, "Export Problem creating SDO File")       Set myDeployObject = Nothing       Set myExportOptions = Nothing       Exit Sub End If 

Now, to finish out our script, we've included some basic messages back to the administrator. Again, we're using the Msgbox object to indicate the status. However, in a noninteractive mode, you'll want to remove these references. In Listing 21-3, we've provided the complete script from beginning to end.

Listing 21-3 The complete export script

[View full width]

 Call ExportCMSObjects() Sub ExportCMSObjects       Dim myDeployObject       Dim myExportOptions       On Error Resume Next       Set myDeployObject = Wscript.CreateObject("CmsDeployServer.CmsDeployExport.1")       If ( Err.Number <> 0 ) Then             Call Msgbox(Err.Description, vbCritical, "Export Problem Creating Deployment  Object")             Set myDeployObject = Nothing             Exit Sub       End If       ' Server side call to authenticate as current user.       Call myDeployObject.AuthenticateAsUser("WinNT://DOMAIN/cmsadmin","password")       'Call myDeployObject.AuthenticateAsCurrentUser()       If ( Err.Number <> 0 ) Then             Call Msgbox(Err.Description, vbCritical, "Export Problem Authenticating the  Admin User")             Set myDeployObject = Nothing             Exit Sub       End If       Set myExportOptions = myDeployObject.Options       If ( Err.Number <> 0 ) Then             Call Msgbox(Err.Description, vbCritical, "Export Problem Authenticating User")             Set myDeployObject = Nothing             Set myExportOptions = Nothing             Exit Sub       End If       ' Include Rights groups and their members.       '       ' IncludeRightGroups:   (1) Do not export rights groups or users (default)       '                                         (2) Export rights groups without members       '                                         (3) Export rights groups with members       '       ' IncludeCreatedBy:     (1) Do not include created by information       '                                         (2) Include created by information (default)       '       myExportOptions.IncludeRightsGroups = 3       myExportOptions.IncludeCreatedBy = 2 Dim strPackageFileName, sdoDateQualifier Dim strReportUrl ' Create a date qualifier for creating unique export names sdoDateQualifier =  day(now()) & month(now()) & _       year(now()) & hour(now()) & minute(now()) & second(now()) ' Set a string with the name and path of the SDO file strPackageFileName = "C:\BOTSConsultingSite" & sdoDateQualifier & ".sdo" ' Start the deployment ' The first option specifies the name of the export file ' The second option specifies the time interval.  A value ' of 0 specifies to export all objects that have changed since ' the last export regardless of time.  A value of 1 or greater ' specifies the age of objects, in minutes, to be exported. ' For example, a value of 200 stipulates that all objects that ' have changed in the last 200 minutes should be exported. ' The last option specifies the channel to export.  If no value ' is provided, the entire repository will be evaluated.  All objects ' from the specified channel and below will be evaluated if a value ' is provided. strReportUrl = myDeployObject.Export(strPackageFileName,0,"/Channels/botsconsulting") If ( Err.Number <> 0 ) Then       Call Msgbox(Err.Description, vbCritical, "Export Problem creating SDO File")       Set myDeployObject = Nothing       Set myExportOptions = Nothing       Exit Sub End If       ' Create a scripting host shell to provide feedback to the user       ' and start a browser session for the export report.       dim winShell       Set winShell = Wscript.CreateObject("Wscript.Shell")       ' Show the export report in a web browser       Call Wscript.Echo("Export has completed successfully.")       Call Wscript.Echo("Starting browser session to display the export report.")       Call winShell.run("http://localhost" & strReportUrl)       ' Dispose of the objects       Set myDeployObject = Nothing       Set myExportOptions = Nothing       Set winShell = Nothing End Sub 

If you use the code we've provided, be sure to specify your domain name when authenticating as well as the appropriate export channel. Other than those two changes, the script should operate as described.

NOTE: One last mention automated scripting is meant for incremental exports only; it's not meant to provide a mechanism for moving the entire repository. If you want to export the entire repository, you can use a SQL backup and restore or use the interactive SDM interface in Site Manager.

Import

Once you've completed your export, it's time to import the content. As we mentioned in the export section, we're going to use the client object to perform the import. This will allow us to remotely connect to a CMS server to perform the import.

For the most part, the import process is very similar to the export. For the sake of brevity, we provide the following list of the general operations performed in the import process, and we share the script code in Listing 21-4.

• Create the client-side import object.

• Authenticate with the remote CMS server. As in the export example, we specify the credentials explicitly; you could authenticate as the current Windows user instead.

• Set the import options (the various settings are in the comments of our code example).

• Start the import process, pointing to the SDO file you want to process. The path has to be fully qualified.

• Show success and the import report.

Listing 21-4 The import code example

[View full width]

 Call ImportCMSObjects() Sub ImportCMSObjects()       Dim myDeployObject, myImportOptions       Dim winShell       On Error Resume Next       Set myDeployObject = WScript.CreateObject("CmsDeployClient.CmsDeployImport.1")       If ( Err.Number <> 0 ) Then             Call MsgBox(Err.Description, vbCritical, "Import Problem Creating Import Object")             Set myDeployObject = Nothing             Exit Sub       End If       ' Authenticate against the remote server, either by stipulating the credentials       ' or using the current Windows user credentials.  These calls are similar to the       ' authentication methods for the export process, except you must also provide       ' the URL to the remote system.  Both methods are shown below.       Call myDeployObject.AuthenticateasUser("http://localhost/","WinNT://cmsdemo1 /cmsadmin","password")       'Call myDeployObject.AuthenticateAsCurrentUser("http://localhost/")       If ( Err.Number <> 0 ) Then             Call MsgBox(Err.Description, vbCritical, "Import Problem Authenticating Admin  User")             Set myDeployObject = Nothing             Exit Sub       End If       Set myImportOptions = myDeployObject.Options       If ( Err.Number <> 0 ) Then             Call MsgBox(Err.Description, vbCritical, "Import Problem Creating Import Options")             Set myDeployObject = Nothing             Set myImportOptions = Nothing             Exit Sub       End If       ' Set the import options       ' IncludeCreatedBy            (1) This will set CreatedBy property of all imported  objects       '                                         as the user running the script (default)       '                                   (2) Retain the CreatedBy properties of the  origin objects.  If       '                                         the original user does not exist in the  destination, set the       '                                         CreateBy property to the user executing  the import.       '       ' RightsOnAdd                 (1) For objects that do not currently exist in the  destination       '                                         repository, leave all rights blank.       '                                   (2) Inherit rights from the parent container  (default)       '                                   (3) Use the rights specified in the SDO       '       ' RightsOnReplace       (1) Keep the existing destination container rights. (default)       '                                   (2) Use the rights in the SDO file.       '       ' IncludeRightsGroups   (1) Do not import any rights groups or users       '                                   (2) Import rights groups without users.  If the  group already       '                                         exists, keep the user list intact       '                                   (3) Import groups and users included in the SDO  file.  If the       '                                         rights group exists in the destination,  replace the user       '                                         list with the one supplied in the SDO file . (default)       myImportOptions.IncludeRightsGroups = 2       myImportOptions.RightsOnAdd = 3       myImportOptions.RightsOnReplace = 2       myImportOptions.IncludeCreatedBy = 1       Dim strReportUrl       ' Start the import operation       strReportUrl = myDeployObject.Import("c:\BOTSConsultingSite134200315235.sdo")       If ( Err.Number <> 0 ) Then             Call MsgBox(Err.Description, vbCritical, "Import Problem Importing SDO")             Set myDeployObject = Nothing             Set myImportOptions = Nothing             Exit Sub       End If       ' Provide message that operation completed successfully and open       ' a browser to display the report       Set winShell = WScript.CreateObject("WScript.Shell")       Wscript.Echo("Import operation completed successfully.")       Wscript.Echo("Start a web browser to display import report.")       Call winShell.Run("http://localhost" & strReportUrl, 7)       ' Dispose of the objects       Set myDeployObject = Nothing       Set myImportOptions = Nothing       Set winShell = Nothing End Sub 

Once you've completed your script, you should have a fully functional import process!

Creating Profiles

When using SDM in an interactive mode, you may want to preserve certain predetermined settings for a deployment. For example, if you periodically need to export a specific set of objects, like new templates from development to production, you may want to create a profile. A profile allows you to preset deployment options and save them in a file, which can be used over and over again to perform a predetermined deployment.

There are two types of profiles in SDM. An export profile stores all settings for a predetermined export process. Conversely, an import profile stores all the settings for a predetermined import process. Creating profiles for semiregular export/import operations will ultimately save you time. Since we've covered a lot of ground in this chapter with regard to deployment, we're combining the creation of an export and an import profile in a more generic description of creating a profile; both operations are similar enough that they don't require separate explanations.

The first step in creating a profile is to start SDM interactively through Site Manager. Be sure to start SDM in the appropriate mode for the profile you wish to create. For example, if you want to create an export profile, start SDM in export mode. If you're creating an export profile, select all the objects you wish to export. In an import profile, you simply have to set how the import process occurs. Once you've finished making all the setting changes and/or selecting the objects, click the File menu. Next, click Save Import/Export Profile (Import or Export based on the mode you're in). Now, just browse to the directory where you want to save the profile, provide the profile with a name, and click OK.

When you're ready to use your profile, begin by opening SDM in interactive mode through Site Manager. When SDM appears, click the File menu and choose Open Import/Export Profile. Once the profile has loaded, SDM will automatically configure itself based on the settings in the profile. Now, just click the Import/Export button.