Understanding CMA

The Content Migration Assistant (CMA) provides implementers with a flexible, extensible facility for migrating data from one environment to another (e.g., from a development environment to a production environment). Data is exported from the source system to a file. The file can then be checked in to a version control system for reuse, or can be immediately imported into the target system and applied.

Note: As used in this chapter, source systems are those on which export-related activities are conducted and target systems are those on which migration updates are to occur.

The following points highlight some common use cases for using this tool:

  • Seeding a newly created environment with configuration data. For example, if you are creating test environments, you can import configuration data from a development environment. In this case, you will probably set up a "copy all configuration" type of migration. Another use case is if you want to troubleshoot an issue in production, you may want to copy all production configuration to a test environment.

  • Updating an existing test environment with new configuration or updates to configuration from a development environment. In this case your set of objects will be more targeted and you are doing more of an incremental migration.

  • Promoting tested configuration to your production environment.

  • Migrating selected master and transaction entities from one environment to another for testing purposes.

Here are key aspects of the import process that apply to all cases:

  • When records exist in both the target and the source, the CMA tool will fully replace the object with the version from the source. Special consideration should therefore be given to records whose primary key is system generated to ensure the correct entity is being replaced.

  • While typically the source version of an object is applied directly onto the target environment, CMA does provide a way to Adjust Imported Data.

  • The import process does not handle deletion of records in the target environment. When importing records from a source environment to a target environment, the import process for the migrated records is able to identify objects to add and objects to change. There is no mechanism for indicating that records in the target environment should be deleted. The absence of those records in the import is not enough because the migration may be only importing a subset to add or update. If data on the target system must be deleted, users must delete the records in the target accordingly. Note that CMA does orchestrate the deletion of child rows of an object as a result of a comparison. This is only applicable to child records that are owned by the implementation.

Configuration steps are mainly used to define the data to migrate at the source system but also involve tasks to be performed at the target environment. Note that the products provide base delivered configuration that may be used as is or used as a template for building more specific configuration for a given implementation. At a high level, configuration tasks involve the following entities:

  • System wide settings are defined in the Migration Assistant Configuration master configuration record.
  • Each type of record that may be copied requires a Migration Plan. The migration plan is used to identify the maintenance object (MO) for the record (using a business object) and allows for instructions to specify related records that may be included in the migration.

  • A Migration Request is used to define the data to include in a given migration export.

Once you have a migration request defined to include desired data to export, the next steps are to export from the current environment and import to the target.

  • The Export process includes all the steps needed to select records to be exported from the source environment and create the export file. For more information, refer to Exporting a Migration.
  • The file created by the export, which is a BINARY file, needs to be transferred from the export directory to the import directory. The transfer needs to be done in such a way as to preserve the file structure. Refer to Additional Migration Considerations for more information.

  • The Import processes include all the steps needed to read an imported file, compare the data in the file to the data in the target, review the proposed changes and apply the updates. For more information, refer to Importing and Applying a Migration.

The topics in this section provide a general understanding of the Content Migration Assistant (CMA) tool.