In this article

Process for moving to the latest update of Finance and Operations

In this article

This topic explains the process of updating or upgrading to the latest release of Microsoft Dynamics 365 for Finance and Operations. It describes the overall process and supported scenarios, but it doesn't provide detailed instructions for every step of the process.

Definitions

Public Preview – A feature that has been made generally available to everyone, and the functionality is supported. There might be additional functionality improvements, or known issues, that must be resolved before the preview phase can end.

Deprecation – A feature or process that won't be supported in the long term. The date when support for the feature or process will end should be stated.

Upgrade – The process of moving from one official release of Finance and Operations to the next release, for source environments prior to version 8.0. Some examples are the move from 7.1 to 7.3, or from 7.3 to 8.0. The process involves setup of a free sandbox environment, code upgrade, and data upgrade.

Update – The process of applying a binary package to an environment to move it from one official release of Finance and Operations to the next release, for source environments starting with version 8.0. This process has lower downtime requirements and doesn't involve data upgrade.

Scenario 3: Upgrade to the latest application release

Use this scenario to move to the latest release of Finance and Operations.

By using the process that is defined later in this topic, you can set up a free sandbox environment. You will be in full control of the downtime window in both your pre-production and production environments.

Scenario 4: Upgrade to the latest platform only

Use this scenario to update to the latest release of the platform when no application updates are required. Platform updates are always cumulative. Here are some examples of platform updates:

In Microsoft Dynamics AX with platform update 1 (May 2016) and Platform update 2, platform-level X++ code could be overlayered. In later platform updates, the platform-level X++ code is locked for overlayering. If you're upgrading from Platform update 1 or Platform update 2, your developers must refactor the overlayering as extensions before you can upgrade. If you're upgrading from Microsoft Dynamics 365 for Operations with platform update 3 (November 2016) or later to a later platform update, you don't have to refactor your X++ code.

This scenario will be deprecated by April 2019, when all customers should be on version 8.1 or later. Version 8.1 no longer releases or supports individual X++ hotfixes.

Use this scenario when one or more small hotfixes are required in order to address a specific issue, but business factors such as time or cost limitations currently prevent you from doing a complete major application update.

To incorporate new features of the application, you don't have to do a complete upgrade of your application. All features in the current update of the application are available individually on Microsoft Dynamics Lifecycle Services (LCS). For more information about how to download hotfixes from LCS, see Get updates from Lifecycle Services (LCS).

Scenario 2: Upgrade your custom code

This scenario describes the process for upgrading code from an earlier release to the current release. This process is required before you can use scenario 3. A developer must complete this process before other activities can begin. A code upgrade is required when you deploy new environments as part of the process of upgrading your application to a new major or cumulative release. A code upgrade isn't required for platform updates.

Source environment

Expected content of the AX7.version file for the source

Target environment

Is the code upgrade service required?

Application 7.3

7.3.11971.56116

Application release 8.x

Yes

July 2017 release (Application 7.2)

7.2.11792.56024

Application release 8.x or 7.3

Yes

Release 1611 (Application 7.1)

7.1.1541.3036

Application release 8.x, 7.3, or July 2017 (7.2)

Yes

August 2016 release (Application 7.0.1 with Platform update 2)

7.0.1265.27075

Application release 8.x, 7.3, July 2017 (7.2) or 1611 (7.1)

Yes

May 2016 release (Application 7.0.1)

7.0.1265.23014

Application release 8.x, 7.3, July 2017 (7.2) or 1611 (7.1)

Yes

February 2016 release (Application 7.0)

7.0.1265.3015

Application release 8.x, 7.3, July 2017 (7.2) or 1611 (7.1)

Yes

Microsoft Dynamics AX 2012

Not applicable

Application release 7.3 or July 2017 (7.2)

Yes

Application release 7.3

Not applicable

Newer version of the platform

No

July 2017 release (Application 7.2)

Not applicable

Newer version of the platform

No

Release 1611 (application 7.1)

Not applicable

Newer version of the platform

No

May 2016 release (Platform update 1, application 7.0.1)

Not applicable

August 2016 release (Platform update 2, application 7.0.1)

No

Regardless of whether you're a live customer or are still in the implementation phase of your project, follow these steps to upgrade your code to the latest platform and application updates.

The Code upgrade service also removes any old Microsoft X++ hotfixes that you've installed. Because the removal of old Microsoft X++ hotfixes is a required step, we recommend that you use the Code upgrade service even if you don't have custom code.

Deploy a new development environment that runs the new version that you're upgrading to. You will use this environment to merge code and refactor your custom code. Submit a request for a new development/test environment that runs the latest update.

You might have to delete your existing development/test environment if your subscription doesn't allow for a new development/test environment.

Depending on your project type, you might have these other options for deploying a developer virtual machine (VM):

Download a development virtual hard disk (VHD).

If you're running in your own Microsoft Azure subscription, deploy a new developer topology.

If you want to keep the development data from your old development environment, create a database backup, and keep the BAK file. Then, when you've completed the code upgrade, you can restore the database backup to your new development environment and do a data upgrade by following the steps in Upgrade data in development, demo, or sandbox environments.

Scenario 3: Upgrade to the latest application release

These steps apply to customers who are live on an earlier release, and who want to do a full upgrade to the most recent platform and application releases. The steps might also apply to customers who have already deployed and configured a production environment, even if they haven't yet gone live. If you aren't upgrading your application but just want to upgrade your platform, use scenario 4 instead.

Upgrade your code

First, upgrade your code as described in scenario 2. This step is a developer task. It's done in a developer environment that is running the new release that you're upgrading to.

Upgrade your data in a development environment

Run the data upgrade process on a copy of your source database. If your environment is already live in production, the source database is a copy of the production database. Otherwise, the source database is your most current database. Run this process in the development environment that is running the release that you're upgrading to. This step is a validation process that is done by a developer. It helps the developer verify that the data upgrade can be completed successfully by using the specific set of customizations in this environment.

Data upgrade in a development environment is a required step. It helps reduce the risk of extended downtime and upgrade errors later, when you upgrade sandbox user acceptance testing (UAT) and production environments.

Several application hotfixes might be required before you can upgrade data. Before you redeploy your existing development environment, verify whether these hotfixes are required. Install the required hotfixes, and check them in to Azure DevOps. This step can be completed only in the old version of your development environment. For a list of the hotfixes that are required in various situations, see Upgrade data in develop, demo, or sandbox environments.

Upgrade your Tier2+ Standard Acceptance Test sandbox environment

When you've completed the code upgrade and have been able to do an end-to-end data upgrade in your development environment, without having to manipulate data in Microsoft SQL Server, you can then begin the process in your sandbox environment.

Prerequisite

Before you begin your upgrade, we highly recommend that you make sure that your sandbox environment has the latest production data. If the data set is up to date, you can have more confidence that the upgrade will work in production. To complete this step, use the Database Refresh self-service action.

Begin the upgrade

In your sandbox environment, on the Maintain menu, select Upgrade.

A dialog box appears, where you can select the latest application and platform combination.

Important

If you receive an error that states that preparation failed, see the Known issues section later in this topic.

Preparation

The environment details page will be refreshed, and options for two sandbox environments will now appear in the upper-right corner. By selecting the options, you can switch between your old sandbox and your new upgrade-in-progress sandbox.

The preparation stage can take eight hours or longer, because it's similar to a full environment deployment. The upgrade-in-progress environment is connected to an empty Microsoft Azure SQL database to speed up deployment, and it's running on the newer version that you selected to deploy.

During this time, your original sandbox is left untouched, and there is no downtime impact at this stage.

Important

If you receive an error that states that staging deployment failed, the Microsoft Dynamics Service Engineering (DSE) team will be notified and will proactively resolve the issue for you. This issue can occur if Azure doesn't have the required resources available in your region. Microsoft DSE will work with the Azure engineers to allocate more resources. When staging deployment is successfully completed, you will receive an email.

Package application

After staging deployment is completed, go back to the environment details page, and switch to the Upgrade in progress view. In this view, you will now see an Upgrade menu.

The Upgrade menu will include an Apply updates option. You can select this option to apply your software deployable packages to the new environment. These packages include any binary package, whether it's from an independent software vendor (ISV) solution, your own customization packages, or platform binary update packages.

We highly recommend applying the latest platform update as your first step. If you are upgrading to version 8.1, we recommend getting the latest binary update package such as 8.1.3 for example, which will also include the latest platform update. This ensures you have the latest hotfixes available and will reduce errors further along in the process.

When you apply a new package to the environment, the process is the same as the process for regular environment servicing. When package application is completed, you must use the Sign Off button for that package before you can move on or apply another package.

If package deployment fails, you can use the Rollback button to reverse it. Note that this button is not the same as the Rollback option on the Upgrade menu.

Critical hotfixes

With increased use of the self-service upgrade process, we have found several hotfixes to be critical to success for various target versions. For example, if you're upgrading to version 7.3 a list of KBs that have consistently resolved issues with data upgrade, retail components, or performance will display.

The goal is to have this list empty before you start the Data Upgrade step of the process. These KBs need to be installed on your Upgrade-in-progress environment.

Upgrade Financial Reporting binaries

Database Refresh and other operations are blocked if your sandbox and production environments aren't on the same version of Financial Reporter. During upgrade, it is an opportune time to uptake the latest binaries for Financial Reporting.

Click the Import button and find the latest Microsoft Dynamics Financial Reporting binary update package and select this for import.

Apply this package to your upgrade-in-progress environment.

Deployment of packages typically lasts about one hour.

Data upgrade and environment swap

After all packages are applied to your upgrade-in-progress sandbox, and you've signed off on them, you can begin the data upgrade.

Important

This stage will begin the downtime for your original sandbox environment.

On the Upgrade menu, select Data upgrade. Your original sandbox environment will be turned off, and the database connection will be swapped so that your new environment is connected to the original database. This process can take up to one hour.

Next, the data upgrade package for your target version will be automatically applied. The time that is required to apply the data upgrade package varies, depending on the size of your database.

If the data upgrade fails, you need to select Rollback on the Upgrade menu to restore your database to the point that it was at before the data upgrade began. Before you do a rollback, we highly recommend that you download the logs to determine the root cause of the failure. This helps to ensure that your next Data Upgrade execution will go more smoothly.

Upgrade days remaining

Because the self-service upgrade process provides a parallel environment at no additional cost to you, there is a time limit on how long this environment can be used. Currently, this time limit is set to 10 calendar days and begins when you use the Maintain menu > Upgrade button to start the process.

What happens when the time runs out?

There are two possible outcomes when the timer reaches zero:

If you have not yet started the Data Upgrade step, then the new environment will be queued for deletion. In this scenario, the upgrade in the progress environment was provisioned, and optionally had customizations and packages applied but no data was upgraded and the original environment never incurred downtime.

If you have executed the Data Upgrade step but not yet committed the upgrade, then no actions will be performed and no environments will be deleted. You can remain here until you commit or rollback. If you decide to rollback and the timer is at zero, then the new environment will be deleted.

Only after you commit the upgrade as a success, is the original environment queued for deletion.

Commit or rollback

After the data upgrade package is applied, you can review the environment, and your users can perform business validation activities. If this validation is successful, you can mark the entire upgrade as a success by selecting Commit on the Upgrade menu. You must commit the upgrade before you can move on to your production environment. After you commit, the original environment is queued for deletion.

If the business validation fails, you can select Rollback on the Upgrade menu. This option will perform a point-in-time restore of the database, swap the database connection back to your original sandbox, and bring your original sandbox back online. The sandbox will then be back in its previous state.

Post upgrade actions

After you have signed off on your upgrade, there are a few actions which must be performed on the environment. These are listed below:

Aggregate Measurements - these must be refreshed after a major upgrade. To do this, go to System Administration > Setup > Entity Store and then click Refresh.

Note

These can be scheduled to run using Batch.

Upgrade production

When you reach this stage, you've finished the upgrade process. You can now begin the same process in your production environment. The steps that you follow are exactly the same.

If you encounter an issue that causes excessive downtime during your production upgrade, use the Report production outage process to alert Microsoft and get help.

Upgrade additional environments

You can upgrade additional sandbox environments in this same way. You also can deallocate and delete your other sandbox environments, and then redeploy on the newer version. By using the Database Refresh self-service action, you can copy in the upgraded database from another sandbox or production environment.

Known issues

Prepare operation could not start. Microsoft support has been notified. If the issue persists, please contact support with this ID.

This known issue involves environment certificates on the LCS back end. If it affects you, submit a support ticket, and include the activity ID from the error message. Microsoft will work to resolve the issue. Microsoft is compiling a list of affect environments and intends to proactively fix this issue in the future.

I want to cancel the upgrade and try again later.

To cancel an upgrade, you can select Cancel Upgrade on the Maintain menu. The Maintain menu is available in the Old view (for the original sandbox), not in the Upgrade in progress view (for the new sandbox).

This DVT error is intermittent and can be resolved by using the Resume button for your data upgrade package. When you select Resume, the process will resume at this step. Microsoft is trying to reliably reproduce this issue and intends to produce a fix in the future.

This TTSCOMMIT error is intermittent and can be resolved by using the Resume button for your data upgrade package. When you select Resume, the process will resume at this step. (This is fixed in Platform update 21.)

Upgrade was Committed but the environment remains in 'Upgrade cleanup in progress' state.

This is an issue we have noticed on some Sandbox and Production environments. We have created a bug to resolve this problem. In the meantime, we will be alerted proactively when this occurs and will clean up the environment state manually. When the bug is resolved, we will remove this issue from the Known Issues list.

Scenario 4: Upgrade to the most current platform only

If you're running an environment that doesn't have any customization of the platform Application Object Tree (AOT) models (Application Platform, Application Foundation, and Directory and Test Essentials), you can do an in-place update of your platform without upgrading to a new environment. For more information about this process, see Apply the latest platform update to environments. If you upgrade only your platform, you don't have to do a code upgrade (scenario 2 in this topic) or run data upgrade scripts.

Feedback

We'd love to hear your thoughts. Choose the type you'd like to provide: