Import a database

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 will be 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:

  1. Go to your target sandbox Environment Details page, and select the Maintain > Move database menu option.
  2. Select Import database and choose your source database backup (.bacpac format) file from the Asset Library.
  3. Note the warnings. Review the list of data elements that are cleaned up from the backup file.
  4. 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.

Import operation failure

If the import operation isn't successful, you can do a rollback. If you select the Rollback option after the initial failure of the operation, 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 often required if a customization that is present in the target sandbox can't complete a database synchronization with the newly imported data.

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 required.
  • Make sure that dual-write is relinked if required. To setup 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 will be, 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 will be 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 be 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 will not be fully functional until you perform the following additional steps.

Initialize Commerce Scale Units

If you are moving a database to a sandbox 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 will not copy over to the destination environment.

Synchronize Commerce self-service installers

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

Important

The Environment re-provisioning step has now been fully automated as part of database movement operations, and no longer needs to be run manually. The Environment re-provisioning tool is still available in the Asset Library and is only required for restoring a database to a development environment.

To run the Environment re-provisioning tool on the destination environment, run the following steps:

  1. In your project's Asset Library, in the Software deployable packages section, select Import.
  2. From the list of shared assets, select the Environment Reprovisioning Tool.
  3. On the Environment details page for your destination environment, select Maintain > Apply updates.
  4. Select the Environment Reprovisioning tool that you uploaded earlier, and then select Apply to apply the package.
  5. 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.

Re-activate 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.