You're viewing help content for version:

The Correspondence Management migration utility converts the Correspondence Management assets from the format used in the earlier versions to the format used in AEM 6.2 Forms.

For more information on Correspondence Management, see Correspondence Management Overview.

Approaches to migration

You can upgrade to the latest version of AEM 6.2 Forms from your previous AEM Forms version or perform a fresh installation. Depending on whether you upgraded your previous installation or performed a fresh install, you need to do one of the following:

In-place upgrade

You can upgrade from a previous AEM Forms version to AEM 6.2 Forms on the same server instance. If you performed an in-place upgrade, the upgraded instance already has the Correspondence Management assets. However, before you can use the assets, you will need to update the assets by running the Migration utility. For more information on upgrading from a previous AEM Forms version to AEM 6.2 on JEE, see the appropriate document on AEM Forms Help and tutorial page.

Fresh installation

If it is a fresh installation, you need to run the Pre-Migration utility on the previous AEM Forms system, then export your assets from the previous AEM Forms system, import them into AEM 6.2 Forms, and then run the Migration utility on the AEM 6.2 Forms system. 

Note:

While importing old Correspondence Management assets for migration, log in using an Admin account.

Approaches to migration using the Migration utility

Prerequisites

Before you run the migration utility, take care of the following important tasks:

  • Ensure that you are running the relevant AEM Forms add-on package. Download the AEM Forms 6.2 CM Migration Package from AEM package share. For more information about obtaining and installing the package, see Installing and configuring AEM Forms.
  • For in-place upgrade, take a backup of the repository (the crx-repository folder), which includes the assets and customization.
  • For fresh installations, if you are exporting the assets from ADEP, apply the patch M03 P10 to the ADEP server before you export the Correspondence Management assets. Without this patch, importing assets into AEM 6.2 Forms fails. Contact Customer Support to get the ADEP patch.
  • For fresh installations, you need to first run the Pre-Migration utility on the setup from which you are exporting the assets. 

Running the Pre-Migration Utility

In case of fresh installation (When you directly export assets from a previous setup and import them to a new AEM forms version), before exporting the assets run the Pre-Migration utility on the existing setup from which assets are to be exported. 

The Pre-Migration utility makes required changes to Correspondence Management assets on the existing system to ensure import-assets process on fresh installation succeeds even if test data is missing in letters or localization data is missing in data dictionaries.

Note:

The state of the assets that get modified by running the Pre-Migration utility changes to "Modified." To make sure that all assets are exported, set their state to Ready To Publish or Published before running the Pre-Migration utility.

  1. Download and install the Pre-Migration utility

    Note:

    For instructions on installing an AEM package, see Downloading and installing packages from package share

  2. Go to the following URL and log in as Admin:

    http://[hostname]:[port]/[context path]/content/changeType.html

  3. Click Change Folder Type.

    The Pre-Migration utility runs. On successful completion, the browser displays "Complete." If you get an exception or error, ensure that you have logged in as Admin. 

Installing the Migration utility

Perform the following steps to install the Migration utility package on the AEM Forms 6.2 setup:

Note:

Alternatively, you can also directly download the migration utility package from AEM-Forms-6.2-CM-Migration-PKG and install it. For instructions on intalling the package, see Downloading And Installing Packages From Package Share

  1. Log on to your AEM portal in the Author instance.
  2. Choose Tools > Operations > Packaging > Package Share. You may be prompted to sign in with your Adobe ID.
  3. Search for CM Migration Pkg and download it. 
  4. After the download is complete, go to package manager: https://[server]:[port]/crx/packmgr/
  5. Search for CM Migration Pkg.
  6. Click Install next to the CM Migration Package.

Using the Migration utility

  1. Log in to Adobe Experience Manager Web ConsoleLog Support at http://[hostname]:[port]/system/console/slinglog.
  2. Click Add New Logger (located under the list of loggers) and add the following parameters for the new logger:
    1. Log Level: INFO
    2. Log File: logs\migration.log (or any other name and location according to your preferences)
    3. Logger: com.adobe.livecycle.icc.migration
  3. Click Save.

Running the Migration utility

After you complete the prerequisites, on the Author instance run the Migration utility in a browser from any machine that has access to the AEM 6.2 Forms server. Following are the steps to run the Migration utility:

Note:

Make sure that the Correspondence Management Assets user interface is not open while the migration process is running.

Do not close the browser session while the migration process is running. Otherwise, migration will not get completed.

Run the Migration utility before making any changes in the assets or creating assets. We recommend that you do not run the utility after making any changes or creating assets. 

  1. In a browser session, log in to AEM portal as Admin in the Author instance.

  2. Open one of the following URLs to run the utility:

    • In-place upgrade: http://<hostname>:<port>/lc/aem/cm_migration.html
    • Importing assets in a fresh installation of AEM 6.2 or performing in-place upgrade from AEM 6.1 to 6.2: http://<hostname>:<port>/aem/cm_migration.html

    The browser window displays the following as the migration process takes place:

    • When migration starts: Correspondence Management Migration started. Please refer to logs for further information...(You can move the migration-related logs to a separate log file by setting up a logger. For more information, see the steps for setting up a logger under Prerequisites.)
    • When the assets are updated: Assets successfully updated.
    • When the thumbnail generation is started: Generating thumbnail for Assets...
    • Once migration is complete: Migration completed.

    When executed, the Migration utility does the following:

    • Adds the tags to the assets: Adds the tag “Correspondence Management : Migrated Assets” to the migrated assets, so that the users can identify migrated assets. When you run the Migration utility, all the existing assets in the system are marked as Migrated. 
    • Generates tags: Categories and subcategories present in the previous system are created as tags, and then these tags are associated with the relevant Correspondence Management assets in AEM. For example, a Category (Claims) and a Subcategory (Claims) of a letter template are generated as tags in the following screenshot:
    • Moves the images and content to DAM: The image modules and content modules are available as DAM assets after the migration. 
    • Moves layouts and layout fragments to AEM 6.2 Forms user interface: The layout templates and layout fragments are added as forms in the AEM 6.2 Forms user interface section.
    • Dumps sample data of letters into the temp folder: Dumps sample data of letters into SampleData folder in the temp location (<temp folder>/SampleData/). The temp location is configured using the crx config manager for asset composer. Earlier, every individual letter had sample data in it. Now the sample data is associated with a Data Dictionary. For information on how to configure the Temp Folder property, see Correspondence Management Configuration Properties
    • Prefixes the names of processes: AEM 6.2 Forms supports both Forms and AEM workflows. The process names are prefixed for identification. Forms workflows are prefixed with "Forms Workflow ->" and AEM workflows are prefixed "AEM Workflow ->". For example, the following screenshot displays a letter template's properties, in which the associated post process's name is prefixed with "Forms Workflow ->."
  3. After the Migration utility finishes running, proceed to the housekeeping tasks.

Housekeeping tasks after running the migration utility

After running the Migration utility, take care of the following housekeeping tasks:

  1. Take a backup of repository (the crx-repository folder). You should take backups at every important milestone. Proceed with creation of new assets or modification of assets only after validation of migrated assets. 
  2. Ensure that XFA version of layouts and fragment layouts is 3.3 or later. If you are using layouts and fragment layouts of an older version, then there could be issues in rendering the letter. To update version of an older XFA to the latest version, complete the following steps: 
    1. Download the XFA as a zip file from the Forms user interface. 
    2. Extract the file.
    3. Open the XFA file in the latest Designer and save it. The version of the XFA gets updated to the latest one.
    4. Upload the XFA in the Forms user interface.
  3. Associate Data Dictionaries with the dumped sample data for the old assets that are migrated. Earlier, sample data was associated with letters. Now, sample data is associated with a data dictionary. For more information on creating a letter, see Create Letter.
  4. Publish all the assets that were published in the previous system before migration. The migration utility updates the assets only on the author instance and to update the assets on the publish instance (s) you need to publish the assets.
  5. In case of export/import, you need to replicate the configurations set on the old system (export system) to the new system (import system). This is to make sure that the appearance and other settings such as audit enabled/disabled, cache, reload enabled/disabled remain the same in the latest version of AEM Forms as they were in the previous version. For more information on the configuration properties, see Correspondence Management Configuration Properties
  6. For fresh install of AEM 6.2 Forms, create new users and assign forms-users group (for AEM Forms on OSGI) or Forms Manager Administrator role (for AEM Forms on JEE setup). For in-place upgrade, assign the new group\role to the existing users (forms-users group for OSGI and Forms Manager Administrator role for JEE).

Changes in Correspondence Management due to migration

  • Since AEM 6.1 forms, comments are not available out of the box. The comments that were added previously are available in the assets but are not visible on the interface automatically. You need to customize the extendedProperties property in the AEM Forms user interface to make the comments visible. 
  • In some of the previous versions such as LiveCycle ES4, text was edited using Flex RichTextEditor, but since AEM 6.1 forms, HTML editor is used. Due to this rendering and appearance of the fonts, font sizes, and font margins may be different from the previous versions in the Author user interface. However, the letters look the same when rendered. 
  • Lists in text modules are improved and now render differently. There may be visual differences. We recommend that you render and see the letters where you are using lists in text modules.
  • Since image content modules are converted to DAM assets and layouts and fragments are added to forms during migration, the Updated By property for these modules changes to admin. 
  • The version history of the assets is not migrated and is not available after migration. The subsequent version history post migration is maintained. 
  • The Ready to Publish state is deprecated since AEM 6.1 forms, so all the assets in the Ready to Publish state is changed to Modified state.
  • Since the user interface is updated in the latest version of AEM Forms, the steps to perform the customizations are also different. You need to redo the customization. 

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy