Share This Post

Dynamics AX Updates

Data Upgrade Scripts for AX 2012

The following topic provides information about AX upgrade scripts in the SYS or GLS layer that are implemented in Microsoft Dynamics AX 2012. AX Upgrade scripts are run as part of the data upgrade process to upgrade data from a source Microsoft Dynamics AX database to Microsoft Dynamics AX 2012.

The following table provides the terms and definitions related to the upgrade framework:

Term Definition
Source environment or source system  The MS Dynamics AX system that is to be upgraded.

The supported source systems for the direct upgrade to Microsoft Dynamics AX 2012 are as follows:

  • Microsoft Dynamics AX 4.0
  • Microsoft Dynamics AX 2009

 Note

The upgrade starts and the source environment is still live, but there is the minimal effect to the live system.

Target environment or the target system  Microsoft Dynamics AX 2012
Transformation  Data is transformed between the source and the target environment by using field mapping and joins between  necessary tables.

Examples include the conversion of the CustTable table to the DirParty* tables.

Shadow table  Auxiliary table created in source environment. The shadow tables will contain all the fields from the source  tables which have to be upgraded.
The Dictionary table  New target Microsoft Dynamics AX 2012 tables. Dictionary tables are imported into the source environment  for the application pre-upgrade checklist, and AX upgrade scripts execution as needed. The definition of the table  must match target system. Dictionary tables will be copied to the targets as they are. Dictionary  tables  are also named upgrade staging tables.

The data upgrade framework runs the data upgrade scripts that transform the earlier version of the Microsoft Dynamics AX database to the current version. There are two categories of AX upgrade scripts:

  • Preprocessing upgrade scripts: The X++ method is implemented by using the upgrade framework APIs to run on the source system (Microsoft Dynamics AX 4.0 or Microsoft Dynamics AX 2009). Preprocessing upgrade scripts prepare the data within the staging tables in preparation for the final data upgrade. The Preprocessing upgrade scripts are installed when you import the preprocessing upgrade XPO from the installation media in the source environment. These upgrade scripts are run by using preprocessing upgrade framework.
  • Target upgrade scripts: X++ methods are implemented by using the attribute based upgrade framework to run on the target system (Microsoft Dynamics AX 2012). Target upgrade scripts are run to do the final transformation to the data before the Microsoft Dynamics AX system is available to users. Target upgrade scripts are installed on the Microsoft Dynamics AX 2012 system as a part of the installation for the upgrade.

Preprocessing Upgrade Scripts

Preprocessing upgrade checklist is the navigation pane that guides you through the preprocessing of the data upgrade steps in the source environment.

The Preprocessing upgrade scripts are derived from the class ReleaseUpdateTransformDB. The Preprocessing upgrade script classes have the following naming convention: ReleaseUpdateTransformDBxx_<module name>. DBxx corresponds to which source version of the Microsoft Dynamics AX that the script applies to. For example, the ReleaseUpdateTransformDB40_Bank upgrade script applies to the Microsoft Dynamics AX 4.0 as indicated by the DB40 in the name. When an upgrade script has the DB50 in the name, the script corresponds to both Microsoft Dynamics AX 4.0 and Microsoft Dynamics Axapta 2009.

The following list describes the types of the preprocessing upgrade scripts:

  • Live preprocessing script that is implemented to run on the live source system. The MS Dynamics AX system is available to the user and the upgrade occurs in the background. Live preprocessing scripts write the prepared data into the shadow and dictionary tables that were created by importing the preprocessing XPOs. These scripts must be implemented by using the row-by-row operations, and commit after a predetermined number of transactions. To schedule the live preprocessing scripts, in the preprocessing upgrade checklist, click Run live preprocessing scripts. The scripts that run are specified in the initTransformationJobs method with a definition of the SetLivePreProcessingScript in ReleaseUpdateTransformDB40_ and ReleaseUpdateTransformDB50_ classes.
  • The Delta preprocessing scripts are implemented to check for changes to the production data that have occurred since you started running the live preprocessing scripts. Similar to the live preprocessing scripts, the delta scripts processes the updated data into the shadow and the dictionary tables. The Delta scripts are designed to run multiple times before entering into the single-user mode. To schedule the Delta preprocessing scripts, in the preprocessing upgrade checklist, click Run delta preprocessing scripts. The scripts that run are specified in the initTransformationJobs method with a definition of the SetDeltaPreProcessingScript in the ReleaseUpdateTransformDB40_ and ReleaseUpdateTransformDB50_ classes.
  • Single-User preprocessing scripts are implemented to run on the source system during the single-user mode. Single-user mode occurs on the source system to make sure that the system is unavailable for the business use. In the single-user mode, only an upgrade user who has administrative permissions is connected. No other users can start a client session when the source system is in final preprocessing and source data is being bulk copied to the Microsoft Dynamics AX 2012 target system. Single-user preprocessing scripts must be written as the set-based operations. To schedule the single-user preprocessing scripts, in the preprocessing upgrade checklist, click Run single-user mode preprocessing scripts. The scripts that run are specified in the initTransformationJobs method with a definition of the SetSingleuserPreProcessingScript in ReleaseUpdateTransformDB40_ and ReleaseUpdateTransformDB50_ classes.
  • The Upgrade Readiness scripts are implemented to help identify the issues that cause an upgrade to fail. These scripts read the AOT metadata or data and then categorize the results into an error or advisory in the upgrade validation result. The Errors must be fixed before you continue with the upgrade. Advisory are designed to improve the upgrade experience by pointing out the issues which may improve the efficiency of upgrade, or issues which require manual actions. To schedule the upgrade readiness scripts, in the preprocessing upgrade checklist, click on the Upgrade Readiness check. The AX upgrade scripts that run are specified in the initTransformationJobs method with a definition of SetValidatePreProcessingScript in ReleaseUpdateTransformDB40_ and ReleaseUpdateTransformDB50_ classes.

Target Upgrade Scripts

Upgrade script methods that upgrade data from Microsoft Dynamics AX 4.0 or Microsoft Dynamics AX 2009 to Microsoft Dynamics AX 2012 are in the ReleaseUpdateDB60_<module name> class. These classes are derived from ReleaseUpdateDB base class.

The following list describes the types of target AX upgrade scripts:

  • Presynchronize upgrade scripts are implemented to make the metadata changes before the step to create tables. For example, the presynchronize scripts are used to map the database table or fields on the source Microsoft Dynamics AX system to the database table or fields on the target system. This table-to-table and the column-to-column mapping prepares the source-to-target upgrade model for data copy from source to target. Other kinds of presynchronize scripts disable the unique index in preparation for data upgrade and avoid duplicate key error. This action is undone during the postsynchronize step. The scripts that run are the methods with an UpgradeScriptStageAttribute of PreSync. They are specified in ReleaseUpdateDB401_, ReleaseUpdateDB41_ and ReleaseUpdateDB60_ classes.
  • The Postsynchronization upgrade scripts contain the bulk of the data upgrade. Company-specific business data is upgraded in the postsynchronization upgrade scripts. The Postsynchronization also reverses the metadata changes that were made during the presynchronize step. During postsynchronization, the upgrade scripts run to update existing data when it is required and populate new tables and columns. Running the upgrade scripts and any inter-dependencies are controlled by the upgrade framework. The Upgrade scripts are implemented for any major version change. If you upgrade from Microsoft Dynamics AX 4.0 with a supported service pack to Microsoft Dynamics AX 2012, the upgrade framework will execute the following three sets of upgrade scripts:
    • Upgrade scripts associated with the Microsoft Dynamics AX 4.0 to Microsoft Dynamics AX 4.0 SP1 that is represented by version 4.01 or v401.
    • Upgrading scripts associated with Microsoft Dynamics AX 4.01 to Microsoft Dynamics AX 2009 that is represented by version 4.1 or v41.
    • Upgrade scripts associated with the Microsoft Dynamics AX 2009 to Microsoft Dynamics AX 2012 that is represented by version 6.0 or v60.

    The AX upgrade scripts that run are methods with an UpgradeScriptStageAttribute of PostSync, the ones specified in the in ReleaseUpdateDB401_, ReleaseUpdateDB41_ and ReleaseUpdateDB60_ classes.

  • The Additional upgrade scripts are implemented to run outside the core data upgrade. Thus reduces the upgrade downtime for core data upgrade. An example is upgrading the metadata that is related to AIF endpoints. The scripts that run are the methods with an UpgradeScriptStageAttribute of Additional, the scripts are specified in the ReleaseUpdateDB401_, ReleaseUpdateDB41_ and ReleaseUpdateDB60_ classes.

Reasons for Data Upgrade Scripts

AX upgrade scripts

Data Upgrade Scripts

AX Upgrade scripts are implemented for the following operations:

  • Deleting a table and saving data
  • Deleting a field and saving data
  • Adding or changing unique indexes
  • Changing a non-unique index into a unique index
  • Restructuring where data is stored. For example, moving the data from one field to another
  • Correcting old data inconsistencies
  • Populating the new tables with existing data
  • Populating the new fields with existing data or a default value that differs from the default value for the data type

Finding Upgrade Script Documentation

There are several ways that the upgrade scripts are documented in the Help file. You can view them in the following ways:

  • Tables Affected, Listed by Table: If you want to see how a particular table is affected by the upgrade, use this topic. It lists the affected tables and scripts that affect them.
  • Tables Affected, Listed by Script: If you want to see which tables the particular script affects, use this topic. It lists the each script and the tables they affect.
  • Modules Affected, Listed by Module: If you want to see how the particular module is affected by upgrade, use this topic. It lists the affected modules and scripts that affect them.
  • Modules Affected, Listed by Script: If you want to see which modules the particular script affects, use this topic. It lists the each script and the modules they affect.
  • Preprocessing Data Upgrade Scripts: If you want to see which scripts are run before upgrade to prepare the data, use this topic. It lists all the scripts that belong to the preprocessing category.
  • Script detail: Each script is also documented and sorted under the topic that has same name as the class name of the script. These topics are useful if you want to see the actions that the script performs.

Share This Post

Leave a Reply

avatar
  Subscribe  
Notify of
Skip to toolbar