Upgrade preprocessing scripts (form) [AX 2012]

Updated: June 6, 2011

Applies To: Microsoft Dynamics AX 2012 R3, Microsoft Dynamics AX 2012 R2, Microsoft Dynamics AX 2012 Feature Pack, Microsoft Dynamics AX 2012

This topic describes a form that is used multiple times during data upgrade preprocessing to manage the various stages of data upgrade preprocessing and different sets of scripts.

The upgrade preprocessing form is part of the upgrade framework that creates upgrade jobs and tasks and executes them in the correct order, which helps to ensure that appropriate dependencies are met. The form allows you start, stop, and pause data upgrade preprocessing jobs. You can also view runtime errors, which serve as a guide to changes that are needed in the data upgrade preprocessing scripts.

The form displays different labels and instructions based on the Preprocessing upgrade checklist task that called it, but the common functionality enables you to manage the running of upgrade scripts in a consistent manner.


While the data upgrade scripts are running, Infolog messages accumulate in the log file. The upgrade job may fail if the maximum size for the log file is reached. As a precaution, clear the log file every 48 hours. The log is a temporary file located in C:\Users\<user name>\AppData\Local\Temp\2\.

The following table displays the upgrade tasks that open this form and summarizes how each version of the form is used.




Check upgrade readiness

Upgrade readiness

The readiness check produces a report that identifies issues that could potentially affect data upgrade. Checks identify data that might cause failure of the data upgrade scripts and identify the scenarios that will need extra planning before the upgrade. For more information, see Check upgrade readiness

Run live preprocessing scripts

Upgrade live preprocessing

Run the live preprocessing scripts after completing the tasks in the Prepare application data for preprocessing section of the Preprocessing upgrade checklist. The live preprocessing scripts write the prepared data into the shadow and dictionary tables that were created during the Initialize preprocessing step. For more information see Run live preprocessing scripts.

Run delta preprocessing scripts

Upgrade delta preprocessing

Run the delta preprocessing scripts after completing the Run live preprocessing scripts task. The delta preprocessing scripts check for changes to the production data that have occurred since you started running the live preprocessing scripts. Then, like the live preprocessing scripts, the delta scripts process the updated data into the shadow and dictionary tables. For more information, see Run delta preprocessing scripts.

Run single-user mode preprocessing scripts

Upgrade single-user preprocessing

After a check to ensure that the source Microsoft Dynamics AX system is running in single-user mode, click Run on this form to launch the delta upgrade scripts a final time and then launch the upgrade scripts that prepare data to be bulk copied to the target system. For more information, see Run single-user mode preprocessing scripts.

The following tables provide descriptions for the controls in this form.




Select this check box to designate individual scripts to be rerun (Upgrade readiness only).

Status icon

A graphical indicator of the status of the upgrade task.


The status of the upgrade task: Waiting, Ready, Running, Finished, or Error.


A short description of the upgrade task.


The name of the company account being upgraded. An asterisk (*) indicates a task that will run for all company accounts.

Method name

The name of the upgrade script method.


The name of the Microsoft Dynamics AX module associated with the upgrade task.


The upgrade script version of Microsoft Dynamics AX.

Time running

The time that has elapsed since the upgrade task began running.

Start date

The date when the upgrade task began running.

Start time

The time when the upgrade task began running.

End date

The date when the upgrade task finished running.

Finish time

The time when the upgrade task finished running.

Session ID

The identifier for the client session that is processing the task. This is required by Microsoft Dynamics AX 4.0, where multiple-threaded processing is achieved by opening multiple instances of the client.

Computer name

The name of the Application Object Server (AOS) where the batch process is running.


The stage value, which is Standard, Shared, Start, or Final.




Submit data preprocessing jobs to the batch processing queue. This button can also be used to resume paused jobs.

Trial Run

Start the upgrade job in Trial Run mode, which ignores failures in upgrade scripts. A trial run helps you estimate the data upgrade effort by identifying prospective issues that you might encounter.


Use this option for testing purposes only.

Manage running tasks

Stop or restart upgrade scripts in order to manage the processing load on the live source system. This option is available only on Preprocessing live upgrade and Preprocessing delta upgrade versions of the form.

Pause job

Pause running of all upgrade tasks.

Rerun script

Reschedule the selected failed task.

Rerun all failed scripts

Reschedule all of the tasks that have failed in the proper sequence.


A dependency between failed tasks can cause an unknown failure. Rerun the tasks after resolving the dependency problem.

Reload scripts

Set scripts that have already been run to be run again.


Rerunning the upgrade scripts may cause data integrity issues. Use this option only for upgrade script development and for testing.

View job predecessors

View the predecessor tasks of the selected task. This function applies only on tasks that depend on the completion of another task.

View job errors

Display errors that occurred while the batch job was running.


Detailed SQL errors are logged in the Windows Application Event Viewer.

View batch task

Open the Batch tasks form to view details of the selected batch task.

View batch job

Open the Batch jobs form to view details about the batch job that contains the current upgrade task.


Refresh the job status information on the form.



Time started

The time when the form began running preprocessing jobs.

Last updated

The time when the job status information on the form was last updated.

Jobs succeeded

The number of jobs with a Finished status.

Jobs with errors

The number of jobs that stopped with an error.

Total number of jobs

The number of jobs that were attempted.

Auto refresh enabled

Select this check box to enable the system to update the displayed job statistics automatically.

Auto refresh time (sec)

Specify the number of seconds between automatic updates.

Announcements: To see known issues and recent fixes, use Issue search in Microsoft Dynamics Lifecycle Services (LCS).