Import a database

Article
11/13/2023

You can use Microsoft Dynamics Lifecycle Services (LCS) to import a golden configuration database into a sandbox user acceptance testing (UAT) environment.

Prerequisites

Database import isn't applicable to LCS projects that are configured for a Dynamics AX 2012 upgrade. Therefore, import is blocked if the Legacy system field at Project Onboarding > Project overview is set to AX2012 Upgrade.

Self-service import database

To import a database that is prepared from a developer environment to a standard user acceptance test (UAT), or a database previously exported from a UAT environment, follow the steps outlined below:

Go to your target sandbox Environment Details page, and select the Maintain > Move database menu option.
Select Import database and choose your source database backup (.bacpac format) file from the Asset Library.
Note the warnings. Review the list of data elements that are cleaned up from the backup file.
The import operation will begin immediately.

Note

All users except the Admin user and other internal service user accounts will be unavailable after import. Therefore, the Admin user can delete or obfuscate data before other users are allowed back into the system.

To import a database to a developer environment after you've downloaded a database backup (.bacpac) file, you can begin the manual import operation on your Tier 1 environment. When you import the database, we recommend that you follow these guidelines:

Keep a copy of the existing AxDB database, so that you can revert to it later if needed.
Import the new database under a new name, such as AxDB_fromProd.

To ensure the best performance, copy the *.bacpac file to the local computer that you're importing from. Download sqlpackage .NET Core for Windows from Get sqlpackage .NET Core for Windows. Open a Command Prompt window, and run the following commands from the sqlpackage .NET Core folder.


SqlPackage.exe /a:import /sf:D:\Exportedbacpac\my.bacpac /tsn:localhost /tdn:<target database name> /p:CommandTimeout=1200

Here is an explanation of the parameters:

tsn (target server name) – The name of the Microsoft SQL Server instance to import into.
tdn (target database name) – The name of the database to import into. The database should not already exist.
sf (source file) – The path and name of the file to import from.

Note

During import, the user name and password aren't required. By default, SQL Server uses Microsoft Windows authentication for the user who is currently signed in.

For information about how to complete the manual import operations into a Tier 1 environment, see Import the database.

Long running operations

Import operation can take several hours and in extreme cases days to complete. This amount of time is due to the schema complexity of finance and operations apps, and limitations of Azure SQL provided tools to convert a cloud database to a flat file for use by traditional SQL Server. When the import operations takes too long and you want to stop the process, you can click the Cancel button from the environment details page.

Import operation failure

If the import operation isn't successful, it automatically rolls back. Your target sandbox environment is restored to the state that it was in before the import began. The rollback operation is made available by the Microsoft Azure SQL Database point-in-time restore capability for restoring the database. Rollback is required if a customization that is present in the target sandbox can't complete a database synchronization with the newly imported data.

To cancel an ongoing import operation, use the Cancel button.

To determine the root cause of the failure, use the Environment change history page to download the logs for the failed operation.

Data elements that require attention after import

Specific activities must be completed when you import a database backup into a sandbox UAT environment. Here are some examples:

Make sure that the source database contains only a single record in the Partitions table.
Make sure that email capabilities are correctly reconfigured or turned off, according to your requirements.
Make sure that integration settings are turned on or off, according to your requirements.
Make sure that Application Object Server (AOS) servers are added back to required batch groups.
Make sure that system Help and task guides are reconnected.
Make sure that batch jobs are set to a status of Waiting.
Make sure that users are re-enabled.
Make sure that dual-write is relinked if necessary.
Make sure that dual-write is relinked if necessary. To set up a new link on the target environment after this operation is successful, see Dual-write environment linking.

Environment admin

The system admin account in the target environment (Admin user ID) is reset to the value that is found in the web.config file in that environment. This account should be the same as the admin account from LCS. To preview which account this account is, visit the Environment details page for your target sandbox in LCS. The value that was selected in the Environment Administrator field when the environment was first deployed is updated to the system admin in the transactional database. Therefore, the tenant of the environment is the tenant of the environment admin.

If you've used the Admin User Provisioning Tool on your environment to change the web.config file, the value might not match the value in LCS. If you require that a different account is used, you must deallocate and delete the target sandbox, redeploy, and select another account. You can then do another database refresh action to restore the data.

Steps to complete after a database import for environments that use Commerce functionality

Important

When a Commerce headquarters database (previously called AOS database) is migrated, the associated Commerce Scale Units (CSUs) are not moved. In several cases, depending on the features that are in use, a CSU redeployment may be required. Redeployment must then be followed by a full synchronization of data to the CSU. In extreme scenarios where data discrepancies still exist, the final action is to delete the CSU, deploy a fresh CSU to replace it, and then perform a full synchronization of data to the new CSU.

Some environment-specific records are not included in automated database movement operations and require additional steps. These include the following:

Commerce self-service installer references.
Commerce Scale Unit channel database configuration records.

If you copy a database between environments, Commerce capabilities in the destination environment won't be fully functional until you perform the following additional steps.

Initialize Commerce Scale Units

If you're moving a database to a sandbox user acceptance testing (UAT) or production environment, you must Initialize Commerce Scale Unit after the database movement operation is complete. The Commerce Scale Unit's association from the source environment won't copy over to the destination environment.

Synchronize Commerce self-service installers

To be able to access Commerce self-service installers in headquarters, you must Synchronize self-service installers after the database movement operation is complete.

Important

The environment reprovisioning step has now been fully automated as part of database movement operations, and no longer needs to be run manually. The environment reprovisioning tool is still available in the asset library, but is only required for restoring a database to a development environment running Commerce version 10.0.37 or earlier. For development environments running Commerce version 10.0.38 and later, the environment reprovisioning tool doesn't apply because these environments use a sealed CSU.

To run the environment reprovisioning tool on the destination environment, run the following steps:

In your project's Asset Library, in the Software deployable packages section, select Import.
From the list of shared assets, select the Environment Reprovisioning Tool.
On the Environment details page for your destination environment, select Maintain > Apply updates.
Select the Environment Reprovisioning tool that you uploaded earlier, and then select Apply to apply the package.
Monitor the progress of the package deployment.

For more information about how to apply a deployable package, see Create deployable packages of models. For more information about how to manually apply a deployable package, see Install deployable packages from the command line.

Reactivate POS devices

If you use point of sale (POS) devices, you must activate the POS devices again after you import a database. Previously activated devices in the destination environment will no longer function. For more information, see Point of sale device activation.