Moving Tables and Fields to Extensions Down the Dependency Graph

INTRODUCED IN: Business Central 2019 Release Wave 2, update 15.3, for on-premises only

This article explains how to move tables and fields from an extension to another extension that is down the dependency graph.

Tip

For more information about the general concepts for moving tables and fields between extensions, see Migrating Tables and Fields Between Extensions. This article explains the the difference between moving up and down the dependency graph.

Overview

The steps in this article are based on the example illustrated in the following figure. Although your scenario is different, the concept and process are much the same.

In the example, TableB and Field C-2 are customizations. You'll keep these elements in the original extension, but create a new version without TableA and TableC. You'll move TableA and TableC down the dependency chain to a new, separate extension.

Prerequisite

If you're moving enum type fields, then your solution must be running on Business Central 2020 release wave 1, version 16.5 or later. For more information, see Known Issues.

Create receiving extension (Ext Y)

The receiving extension will contain the table and fields that you want to move. In this example, these objects include TableA and TableC.

1. Create an AL project for the receiving extension.

2. Add a table object definition for TableA.

   The table definition (schema) must include the full schema of the releasing extension Ext X, with the same field definitions. You can add new fields.

3. Add a table object definition for TableC.

   The table definition (schema) must include the full schema of the releasing extension Ext X, with the same field definitions, except don't include field C-2. You can add new fields.

4. Make a note of the ID of the new extension. You'll use this ID in the next task.

   For purposes of the example, the ID is 00001111-aaaa-2222-bbbb-3333cccc4444.

5. Compile the extension package.

Create new version of releasing extension (Ext X v2)

1. In the releasing extension AL project, add a migration.json file that points to the ID of the target extension.

   { 
   "apprules": [ 
       { 
           "id": "00001111-aaaa-2222-bbbb-3333cccc4444"
       } 
   ] 
   } 
   

   For more information, see The Migration.json File.

2. Modify the app.json file as follows:

   • Ensure that "target": "OnPrem".
   • Increase the "version" value.
   • In the "dependencies" parameter, set up a dependency on the new receiving extension Ext Y.

   For more information, see App.json file.

3. Complete the following steps for TableC.

   1. Add a table extension object TableExtC.
   2. In table extension object TableExtC, add a field definition for field C-2 that matches its definition in the original TableC object.
   3. Delete the original TableC object.

4. Delete the entire table object for TableA.

5. Compile a new version of the extension package.

Deploy extensions

1. Uninstall the old version of the releasing extension Ext X.

2. Publish the new receiving extension Ext Y and releasing extension version Ext X v2.

3. Synchronize the receiving extension Ext Y.

   This step creates empty database tables for TableA and TableC that are owned by the receiving extension Ext Y.

   Important

   The receiving extension must always be synchronized first.

4. Synchronize the new version of the releasing extension Ext X v2.

   This step first reads rules in the migration.json file of the extension, then does the following operations in the database:

   • Creates a companion table for field C-2 of the table extension object TableExtC.
   • Copies data from column C-2 in the original TableC to new companion table TableExtC.
   • Temporarily renames the new empty tables TableA and TableC made by receiving extension Ext Y.
   • Renames the original tables TableA and TableC that include the data. Instead of including the ID of the releasing extension Ext X, the names are changed to include the ID of the receiving extension Ext Y. This step essentially transfers ownership from Ext X to Ext Y.
   • Deletes the unused column for C-2 in the original table TableC.
   • Deletes the empty, renamed tables of Ext Y.

5. Install the receiving extension Ext Y.

6. Run Start-NAVAppDataUpgrade cmdlet on the new releasing extension version Ext X v2.

   This step basically installs the new extension version. You run a data upgrade because an earlier version has been installed and is still published.

See Also

Migrating Tables and Fields Between Extensions
Moving Tables and Fields to Extension Up the Dependency Graph
Upgrading Extensions
Publishing and Installing an Extension
JSON Files