24 Migrating System Configurations

This chapter provides information on using the Configuration Migration utility with the Archiver utility to migrate content and export configuration and customization metadata.

This chapter covers the following topics:

24.1 Understanding the Configuration Migration Utility

The Configuration Migration utility is used with the Archiver to export one Content Server instance configuration to another Content Server instance. While the Archiver is used to migrate content, the Configuration Migration utility exports the configuration and customization of the Content Server instance.

This section describes the structure of the Configuration Migration utility and how it uses templates and bundles. For an overview of this utility and how it compares to other archiving tools, see Section 23.1.

24.1.1 Migration Structure

A bundle is a set of configuration information that is packaged into a single zipped file and made ready for exporting to another Content Server instance.

Information is stored in the DomainHome/ucm/cs/cmu/instance/ directory.

Figure 24-1 Migration Directory Structure

Description of Figure 24-1 follows
Description of "Figure 24-1 Migration Directory Structure"

The bundles subdirectory contains specific bundles and associated information. The templates subdirectory contains configuration templates which can be used for new export files.

Information is stored in the DomainHome/ucm/cs/cmu/instance/bundles/ directory.

Figure 24-2 The Bundles Subdirectory

Description of Figure 24-2 follows
Description of "Figure 24-2 The Bundles Subdirectory"

Each configuration bundle is in a separate subdirectory and contains all the relevant files needed to export that bundle.

Information is stored in the DomainHome/ucm/cs/cmu/instance/bundles/UserBundle/ directory.

Figure 24-3 Files in Configuration Bundle

Description of Figure 24-3 follows
Description of "Figure 24-3 Files in Configuration Bundle"

Within the specific directories, any customization that is unique to the instance in that export (such as customized metadata fields, schemas, and so on) are included in a separate subdirectory.

Information is stored in the DomainHome/ucm/cs/cmu/instance/bundles/UserBundle/usermetadef/ directory.

Figure 24-4 Customization Stored in Directory

Description of Figure 24-4 follows
Description of "Figure 24-4 Customization Stored in Directory"

The following files are included in these different subdirectories:

File or Directory Description

bundle directory

Each bundle has a subdirectory in the bundles/ directory. The subdirectory is given the name assigned to the bundle when the configuration export was created.

templates directory

Contains export rules created from bundles. When a configuration export is created and saved, a name is given to that export and the configuration is stored as a template in the templates directory

hda files

Contains definitions and details of customization and other elements of the exported instance. Depending on how the export was defined, information can be bundled into one HDA file or into several.


24.1.2 About Migration Templates and Bundles

A migration template is a set of configuration options which specify what Content Server items will be exported. For example, a template named FullCSExport may contain all Content Server items (schema, custom metadata, workflows, and so on). Another template named UserCSExport may only contain options that pertain directly to users (security groups, roles, and so on).

These templates are used to create configuration bundles. A bundle uses the template to determine what to export and to create the necessary definition files which will be exported with the Content Server items. The bundle name is used to identify the finished result of an import or an export. The bundled information is put into a zipped file, containing all the necessary definition files.

24.2 Managing Configuration Migration

Migration consists of tasks such as creating migration templates, creating migration bundles, and exporting or importing the configuration.

24.2.1 Creating a Configuration Migration Template

To create a configuration migration template:

  1. Choose Administration, then Config Migration Admin, then Configuration Templates.

  2. On the Configuration Templates page, choose Create New Template from the Actions menu.

  3. On the Config Migration Admin page, choose one of the items in the Action Options list for the export.

    • To create an export template that will continue the export process even if an error is encountered, select Continue on Error.

      The export will proceed but errors will be reported on the Action History page.

    • To have email sent to the person initiating the export, select Email Results.

      Email will be sent to the person who performs the export, not the person who created the export template.

    • To have known dependencies added to the export or import bundle, leave the Add Dependencies option selected.

      If this is deselected, dependencies are checked and noted with an error flag in the log file but the bundle action continues.

    • To ignore all dependencies during export or import, select Ignore Dependencies. Ignoring dependencies may avoid errors during the export process, but may cause errors when an import is done.

      If you are certain that all the necessary fields are present in the Content Server instance, you can deselect Add Dependencies and select Ignore Dependencies to import a field without dependencies being added.

  4. You can create a custom name for this bundle. Custom names should be used sparingly to avoid possible name collisions. If a custom name is not selected, the system creates a name based on the bundle name given when you save the template. Custom names cannot contain spaces or special characters (#, $, % and so on).

  5. Choose one or more of the Content Server sections from the Content Server Sections list to be included:

    • To use all sections, choose Select All from the page Actions menu.

      Note:

      Some Content Server sections are not displayed; not all are supported on all versions of Content Server and some cannot be safely migrated.

    • To use only specific Content Server items, click Content Server Sections, then click the individual section name to include.

      To include all items in that section, choose Select All from the page Actions menu.

      To use only a subset in the section, select the individual items by putting a check in the selection box on the item's row. Some sections may have action options that are specific to that section. Select the option for the section by checking the selection box.

      Tip:

      If you want to use the majority of the metadata, choose the Select All menu option, then click the individual sections that you do not want to use.

  6. Preview the selections you made by choosing Preview from the page Actions menu.

  7. On the Preview page, continue editing and adding selections by choosing Edit from the page Actions menu.

    Click Preview to view your changes.

  8. When the template is complete, choose Save from the page Actions menu.

    Note:

    If you do not elect to save the template, your configuration changes will be lost.

  9. On the Edit Export Rule page, enter a name for the template. Names cannot contain spaces or special characters (#, $, %, and so on). A name can include details of the date of the export (for example, Nov10FullExport) or describe the contents (FullExportNoDependencies) or can be meaningful in any way that is appropriate for your use.

    Click Save when finished entering the name.

  10. When the Config Migration Admin page opens again:

    • To create another template using the current template, choose Save As from the page Actions menu.

      The Edit Export Rule window opens again where you can create a new name.

    • To alter the selections for exporting, make any changes then choose Save from the page Actions menu to change the selections and retain the name entered in step 9, or choose Save As from the page Actions menu to give it a new name on the Edit Export Rule page.

    • To export the configuration, choose Export from the page Actions menu. For more information, see Section 24.2.5.

After creating the configuration, you can export it and create a bundle for use on another system. For more information, see Section 24.2.5.

24.2.2 Editing a Configuration Template

To edit a configuration template:

  1. Choose Administration, then Config Migration Admin, then Configuration Templates.

  2. Choose a template to be edited. Use one of the following methods to choose a template from the Configuration Templates page:

    • Select the template name.

    • Choose Edit from the individual template Actions menu.

  3. Using the Config Migration Admin page, follow the steps detailed in Section 24.2.1 to select the items you want in the revised template:

    • Choose one of the Action Options for the template.

    • Choose the sections to be included from the Content Server Sections part of the page.

  4. Preview the selections you made by choosing Preview from the page Actions menu.

  5. On the Preview page, continue editing and adding selections by choosing Edit from the page Actions menu.

    Click Preview to view your selections.

  6. When the template is complete, choose Save from the page Actions menu to save the template under its current name, or choose Save As to give it a new name.

    Note:

    If you do not choose to save the template, your configuration changes will be lost.

  7. Enter a new template name on the Edit Export Rule page.

24.2.3 Importing a Template

To import a template from another system for use on the current instance.

  1. Choose Administration, then Config Migration Admin, then Upload Bundle.

  2. On the Upload Configuration Bundle page, use the Browse button to find the bundle that contains the template you want to use.

  3. Select Create Export Template.

  4. Click Upload.

    The bundle appears on the Configuration Bundles page. To use the template associated with that bundle, see Section 24.2.2.

    If you import a template to use for exporting and if the importing system does not have the same metadata fields, you must upload the template, import the configuration then use it for exporting. You cannot use the template for exporting unless the metadata fields are in place on the system that imported the template.

24.2.4 Creating a One-Time Export

To create an export template and immediately export the Content Server configuration:

  1. Choose Administration, then Config Migration Admin, then Configuration Templates.

  2. On the Configuration Templates page, choose Create New Template from the page Actions menu.

  3. Using the Config Migration Admin page, follow the steps detailed in Section 24.2.1 to select the items you want in the configuration:

    • Choose one of the Action Options.

    • Choose the sections to be included from the Content Server Sections part of the page.

  4. Preview the selections you made by choosing Preview from the page Actions menu.

  5. On the Preview page, continue editing and adding selections by choosing Edit from the page Actions menu.

    Click Preview to view your changes.

  6. When the template is complete, choose Export from the page Actions menu.

    The configuration is immediately exported and the name of the exported bundle appears in the Latest Action page with a unique identifier similar to the following:

    bundle-idcm1-25-20131110T135912
    

    The initial portion of the name (bundle-idcm1) indicates the default bundle name (bundle) and the instance name (idcm). The next portion indicates the sequence number (25). The date follows (20131110 for November 11, 2013). Finally a unique control number is used to identify the exported bundle.

24.2.5 Exporting a Configuration

To export a configuration:

  1. Choose Administration, then Config Migration Admin, then Configuration Templates.

  2. Use one of the following methods to choose an export configuration template from the Configuration Templates page.

    • Click the configuration name.

    • If you want to view the items that will be exported, choose Preview from the individual Actions menu.

  3. On the Preview page, choose Export from the page Actions menu.

    If you choose Export without previewing the bundle first, you are prompted to confirm that you want to perform the export.

    The Latest Action page refreshes automatically to show the most recent activities and their status.

  4. To view details of the migration action, click the message in the Status column. For more information, see Section 24.2.9.

After exporting, the bundle name appears on the Configuration Bundles page, indicating that it has been bundled. A date and time indicator is appended to the configuration name, as in the following example:

Nov23Bundle-idcm-1-20131123T122436

The initial portion of the name is the original bundle name. The instance name follows (idcm), followed by the date (20131123 for November 23, 2004) and the time (122436 to indicate 12:24:36). From this Import page, you can download the bundle to a new location so it can be uploaded onto another system.

The original template name (Nov23Bundle) continues to appear on the Configuration Templates page, where it can be re-exported at another time.

24.2.6 Uploading a Bundle

Before a configuration can be imported it must be first uploaded.

To upload a bundle from another Content Server instance:

  1. Choose Administration, then Config Migration Admin, then Upload Bundle.

  2. On the Upload Configuration Bundle page, use the Browse button to find and select the zipped bundle file you want to use.

  3. If you want to use the template included with the bundle, select Create Export Template.

  4. If you want the new bundle information to overwrite existing Content Server configuration information, select Force Overwrite.

  5. Click Upload to load the bundle.

    Tip:

    If you are uncertain about the contents of a bundle, it is always safe to upload the bundle and preview the configuration contents. The bundle configuration is not applied to the importing system until you choose to import it.

24.2.7 Importing a Bundle

After a bundle is uploaded and resides on the importing system, it can be imported for use.

To import a bundle:

  1. Choose Administration, then Config Migration Admin, then Configuration Bundles.

  2. On the Configuration Bundles page, choose Configuration Bundles from the Configuration Migration Administration page or from the top menu of any Migration page.

  3. Select the name of the bundle you want to import.

    The Config Migration Admin page opens with Overwrite Duplicates in place of the Custom Name field. Selecting this field will permit the importing bundle to overwrite any duplicate fields. If not selected, the import will error on duplicates and stop. It will continue if Continue on Error was checked but a status of fail appears on the Latest Action page.

  4. Select an action from the page Actions menu:

    • To preview the import configuration, click Preview.

      On the Preview page you can either choose Edit from the page Actions menu to edit the configuration options, or you can choose Import to import the selections as is.

    • To import the configuration without previewing, choose Import from the Configuration Bundles page Actions menu.

      You are prompted to confirm that you want to import the configuration without previewing it first.

      Important:

      You should verify that you want to import the settings in the Server Config portion of the Content Server sections. These settings determine configurations such as the type of web server used, the mail server, and other system-specific items. You may not want to import those configuration settings on a new Content Server instance.

  5. After you choose Import from either the Preview Page or the Configuration Bundles Page, the Latest Action page opens showing the status of the import.

    This page refreshes automatically to show the most recent history and status.

  6. To view details of the action, click the message in the Status column of the Latest Action page. For more information, see Section 24.2.9.

24.2.8 Downloading a Bundle

A bundle can be downloaded and stored in an easily accessible location for other Content Server instances to use.

To download a bundle:

  1. Choose Administration, then Config Migration Admin, then Configuration Bundles.

  2. On the Configuration Bundles page, choose Download from the bundle Actions menu of the bundle to be downloaded.

    A prompt appears for the bundle location.

  3. Enter the appropriate bundle location and click Save.

24.2.9 Viewing Action Status

To view status information for any import or export actions:

  1. Choose Administration, then Config Migration Admin, then Latest Action.

    The Latest Action page opens with information on action Time, Section, and Message.

  2. You can use the Page Refresh (In Seconds) menu to select a different number of seconds for the refresh (from 5 seconds to 300 seconds).

    Note:

    The Action History page automatically appears after an export or an import.

24.2.10 Viewing Action History

To view the history of migration actions:

  1. Choose Administration, then Config Migration Admin, then Action History.

  2. On the Action History page, for each action you can view the name, source, action, start time, and status.

  3. Using the Actions menu, you can select a specific action history or clear the Action History.

24.3 Migration Tips

It is important to remember that migration entails the bundling and copying of information about the Content Server instance. It does not include any of the actual content that is in the Content Server instance. The Archiver utility is used to export content. You should take care that if you archive specific content and plan to export it to another system, the metadata information for that content is also migrated using the Configuration Migration utility.

When migrating information from one Content Server instance to another, there is not a merging of information. Migration is an additive process. The exporting configuration bundle of metadata information is added to the metadata that currently exists in the importing Content Server instance. If metadata information currently exists that matches the metadata being imported, and if the Force Overwrite rule has been selected during import, then duplicate bundles are replaced. For information about the Force Overwrite option, see Section 24.2.6.

Configuration Migration administration tasks must be performed using a specific node of a cluster. If you do not use a specific node, then an error might occur because the job number assigned to an action is known only to the node that started the action.

You cannot import a configuration on a 6.2 version of the Content Server instance. The Edit, Preview, and History options will not appear on the bundle's options on the Configuration Bundles page on a 6.2 version Content Server instance.

If you import a template to use on another Content Server instance and if the importing system does not have the same metadata fields, you will not be able to use that template for export later. You must upload the template, import the configuration, and then use it for exporting. For details about the import process, see Section 24.2.3.

24.3.1 Limitations

Keep the following limitations in mind when using the Configuration Migration utility:

  • When exporting workflow configuration information, only the workflow definition is exported. The state of the workflow is not exported.

  • If importing and overwriting existing workflows, ensure that you have the same step names for each workflow.

  • If you import a workflow to a new Content Server instance, the workflow will not retain the same state information as that of the exporting Content Server instance. For this reason, you should not plan to export active workflows.

  • This utility is not a cloner. It does not synchronize information with another system, it only copies and moves information.

  • This utility cannot be set up to migrate automatically.

  • Errors may arise when migrating docmeta information from earlier versions of the Content Server instance because of the use of schemas in later versions of the Content Server instance.

  • You cannot import users from a 6.2 or 7.0 version of Content Server to a later version due to Archiver limitations.

  • Migrating the config.cfg file may have errors because some values are not migrated for safety reasons (for example, IDC_Name). Others values, such as that for AutoNumberPrefix, are migrated.

  • Migrating components can be difficult because no preference prompts (for example, in Folders or RMA) and no database tables can be migrated.

  • No support is provided for bundles in components.

24.3.2 Migration Logs

You can track activity during migration events by examining migration trace logs.

To enable Content Server migration trace logs, choose Administration, then System Audit Information. In the Tracing Section Information portion of the page, choose Active Sections, then cmu. Configuration Migration utility logs will be included in the trace files that are run.

To access the logs, click View Server Output from the Actions menu on the page. The Configuration Migration utility log information is included with other tracing logs that are generated.