You're viewing help content for version:

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

Approaches to migration

You can upgrade to the latest version of AEM 6.3 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.3 Forms on the same server instance. If you performed an in-place upgrade, the upgraded instance already has the assets and documents. However, before you can use the assets and documents, you will need to update the assets and documents by running the Migration utility. For more information on upgrading from a previous AEM Forms version to AEM 6.3 Forms on JEE as well as OSGi, see the appropriate document on AEM 6.3 Forms User Guide page.

Fresh installation

If it is a fresh installation, you need to run the Pre-Migration utility (applicable only for Correspondence Management assets and when you are migrating from a version prior to AEM 6.2 Forms) on the previous AEM Forms system, then export your assets from the previous AEM Forms system, import them into AEM 6.3 Forms, and then run the Migration utility on the AEM 6.3 Forms system. 


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


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

  • Ensure you have the relevant AEM 6.3 Forms add-on package installed. For more information about obtaining and installing the package, see Installing and configuring AEM Forms.
  • Ensure you have Admin privileges.
  • Review Changes in Correspondence Management and Adaptive Forms due to migration.
  • For in-place upgrade, take a backup of 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.3 Forms fails. Contact Customer Support to get the ADEP patch.
  • For fresh installations, you need to first run the Pre-Migration utility (applicable only for Correspondence Management assets and when you are migrating from a version prior to AEM Forms 6.2) on the setup from which you are exporting the assets. 

Running the Pre-Migration Utility for Correspondence Management assets

In case of fresh installation, when you directly export assets from a setup prior to AEM Forms 6.2 and import them to a new AEM Forms version, before exporting the assets run the Pre-Migration utility on the existing setup from which Correspondence Management 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.


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


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

  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. 

Using the Migration utility

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.3 Forms server. Following are the steps to run the Migration utility:


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

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.


    When you run the Migration Utility for the first time, a log is created with the following path and name: \\cq-quickstart\logs\aem-forms-migration.log. This log keeps getting updated Correspondence Management and Adaptive Forms migration info, such as moving of assets.

  2. Open the following URL in the browser:


    The browser displays three options:

    • AEM Forms Assets Migration
    • Adaptive Forms Custom Components Migration
    • Adaptive Forms Templates Migration
  3. Do the following to perform the migration:

    • To migrate assets, tap Adaptive Forms Assets Migration, and in the next screen, tap Start Migration. The following get migrated:
      • Adaptive forms and adaptive documents
      • Document fragments
      • Themes
      • Letters
      • Data dictionaries

    During assets migration, you may find warning messages such as “Conflict found for…”.  Such messages indicate that rules for some of the components in adaptive forms could not be migrated. For example, if the component had an event which had both rules and scripts, if rules occur after any script none of the rules for the component are migrated. However, such rules can be migrated by opening the rule editor in adaptive form authoring.

    These components can be migrated by opening them in Rule Editor in Adaptive Forms editor. 

    • To migrate rules and scripts in custom components, tap Adaptive Forms Custom Components Migration, and in the next screen, tap Start Migration. The following get migrated:
      • Rules and Scripts created using rule editor (6.1 FP1 and later)
      • Scripts created using the Script tab in the UI of 6.1 and earlier
    • To migrate templates, tap Adaptive Forms Template Migration, and in the next screen, tap Start Migration. The following get migrated:
      • Old templates – the adaptive forms templates created under /apps using AEM 6.1 Forms or earlier. This includes the scripts that were defined in the template components.
      • New templates – Adaptive forms templates created using template editor under /conf. This includes migration of rules and scripts created using the rule editor.
    The browser window displays the following as the migration process takes place:
    • When the assets are updated: Assets successfully updated.
    • Once migration is complete: Finished migration for assets.

    When executed, the Migration utility does the following:

    • Adds the tags to the assets: Adds the tag “Correspondence Management : Migrated Assets” / “Adaptive Forms : 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.3 Forms user interface: The layout templates and layout fragments are added as forms in the AEM 6.3 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 in Correspondence Management Configurations. 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.3 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 ->."


    For Correspondence Management, new folders may appear in the UI that include your assets. You may need to check these folders to locate your assets. 

  4. 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.3 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).
  7. In 6.3, some of the rights of the forms users groups are changed. If you want any of your users to be able to upload XDPs and Adaptive Forms containing scripts or use code editor, you need to add them to forms-power-users group. Similarly, template-authors can no longer use the code editor in Rule Editor. For users to be able to use code editor, add them to af-template-script-writers group. For instructions on adding users to groups, see Managing Users and User Groups.

Changes in Correspondence Management and Adaptive Forms 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. 
  • Layout Fragments move from /content/apps/cm/layouts/fragmentlayouts/1001 to /content/apps/cm/modules/fragmentlayouts. Data Dictionary reference  in assets displays path of the Data Dictionary instead of its name.
  • Any tab spaces being used for alignment in text modules need to be readjusted. For more information, see Correspondence Management - Using tab spacing for arranging text.
  • Asset composer configurations changes to Correspondence Management configurations. 
  • Correspondence Management assets are moved under folders with names such as Exisiting Text and Existing List.