deploy: 81ffc9da10
This commit is contained in:
JesperSchulz
parent
158b902b20
commit
cb4e8e2194
131 changed files with 3191 additions and 3076 deletions
|
|
@ -2,19 +2,19 @@
|
|||
<head>
|
||||
<meta charset=utf-8>
|
||||
<meta name=viewport content="width=device-width,initial-scale=1">
|
||||
<meta name=generator content="Hugo 0.89.0">
|
||||
<meta name=generator content="Hugo 0.89.1">
|
||||
<meta name=description content>
|
||||
<title>Data Migration Facade :: BC AL Help</title>
|
||||
<link href=/css/nucleus.css?1636104707 rel=stylesheet>
|
||||
<link href=/css/fontawesome-all.min.css?1636104707 rel=stylesheet>
|
||||
<link href=/css/featherlight.min.css?1636104707 rel=stylesheet>
|
||||
<link href=/css/perfect-scrollbar.min.css?1636104707 rel=stylesheet>
|
||||
<link href=/css/auto-complete.css?1636104707 rel=stylesheet>
|
||||
<link href=/css/theme.css?1636104707 rel=stylesheet>
|
||||
<link href=/css/theme-blue.css?1636104707 rel=stylesheet>
|
||||
<link href=/css/variant.css?1636104707 rel=stylesheet>
|
||||
<link href=/css/print.css?1636104707 rel=stylesheet media=print>
|
||||
<script src=/js/jquery.min.js?1636104707></script>
|
||||
<link href=/css/nucleus.css?1636386789 rel=stylesheet>
|
||||
<link href=/css/fontawesome-all.min.css?1636386789 rel=stylesheet>
|
||||
<link href=/css/featherlight.min.css?1636386789 rel=stylesheet>
|
||||
<link href=/css/perfect-scrollbar.min.css?1636386789 rel=stylesheet>
|
||||
<link href=/css/auto-complete.css?1636386789 rel=stylesheet>
|
||||
<link href=/css/theme.css?1636386789 rel=stylesheet>
|
||||
<link href=/css/theme-blue.css?1636386789 rel=stylesheet>
|
||||
<link href=/css/variant.css?1636386789 rel=stylesheet>
|
||||
<link href=/css/print.css?1636386789 rel=stylesheet media=print>
|
||||
<script src=/js/jquery.min.js?1636386789></script>
|
||||
<style>:root #header+#content>#left>#rlblock_left{display:none!important}</style>
|
||||
</head>
|
||||
<body data-url=/navpatterns/1-patterns/data-migration-facade/>
|
||||
|
|
@ -32,9 +32,9 @@ BC AL Help . dev
|
|||
<input data-search-input id=search-by type=search placeholder=Search...>
|
||||
<span data-search-clear><i class="fas fa-times"></i></span>
|
||||
</div>
|
||||
<script src=/js/lunr.min.js?1636104707></script>
|
||||
<script src=/js/auto-complete.js?1636104707></script>
|
||||
<script src=/js/search.js?1636104707></script>
|
||||
<script src=/js/lunr.min.js?1636386789></script>
|
||||
<script src=/js/auto-complete.js?1636386789></script>
|
||||
<script src=/js/search.js?1636386789></script>
|
||||
</div>
|
||||
<div class=highlightable>
|
||||
<ul class=topics>
|
||||
|
|
@ -200,20 +200,20 @@ BC AL Help . dev
|
|||
<div class=wrapper>
|
||||
<nav id=TableOfContents>
|
||||
<ul>
|
||||
<li><a href=#context><strong>Context:</strong></a></li>
|
||||
<li><a href=#problem><strong>Problem:</strong></a></li>
|
||||
<li><a href=#solution><strong>Solution:</strong></a></li>
|
||||
<li><a href=#usage><strong>Usage:</strong></a>
|
||||
<li><a href=#context>Context:</a></li>
|
||||
<li><a href=#problem>Problem:</a></li>
|
||||
<li><a href=#solution>Solution:</a></li>
|
||||
<li><a href=#usage>Usage:</a>
|
||||
<ul>
|
||||
<li><a href=#usage-without-staging-tables><strong>Usage without staging tables:</strong></a></li>
|
||||
<li><a href=#usage-with-staging-tables><strong>Usage with staging tables:</strong></a></li>
|
||||
<li><a href=#combining-both-approaches><strong>Combining both approaches:</strong></a></li>
|
||||
<li><a href=#usage-without-staging-tables>Usage without staging tables:</a></li>
|
||||
<li><a href=#usage-with-staging-tables>Usage with staging tables:</a></li>
|
||||
<li><a href=#combining-both-approaches>Combining both approaches:</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href=#error-handling-with-staging-tables><strong>Error handling with staging tables:</strong></a></li>
|
||||
<li><a href=#limitations><strong>Limitations:</strong></a></li>
|
||||
<li><a href=#usages-in-nav><strong>Usages in NAV:</strong></a></li>
|
||||
<li><a href=#references><strong>References:</strong></a></li>
|
||||
<li><a href=#error-handling-with-staging-tables>Error handling with staging tables:</a></li>
|
||||
<li><a href=#limitations>Limitations:</a></li>
|
||||
<li><a href=#usages-in-nav>Usages in NAV:</a></li>
|
||||
<li><a href=#references>References:</a></li>
|
||||
</ul>
|
||||
</nav>
|
||||
</div>
|
||||
|
|
@ -226,11 +226,11 @@ BC AL Help . dev
|
|||
<h1 id=data-migration-façade><strong>Data Migration Façade</strong></h1>
|
||||
<p><em>By David Bastide and Soumya Dutta at Microsoft Development Center Copenhagen</em></p>
|
||||
<p><a href=8308.logo.png><img src=8308.logo.png alt=" "></a></p>
|
||||
<h2 id=context><strong>Context:</strong></h2>
|
||||
<h2 id=context>Context:</h2>
|
||||
<p>This pattern is describing how you can migrate data using the Data Migration Façade.</p>
|
||||
<h2 id=problem><strong>Problem:</strong></h2>
|
||||
<h2 id=problem>Problem:</h2>
|
||||
<p>Writing migration code from an external source, such as a product from a competitor, can be time consuming, as you need to tackle the problems of what to migrate, in which order, exception handling… and can result in code that is fragile due to deep dependencies on the NAV data model (high coupling). Any change to the NAV data model can easily break this code. ****</p>
|
||||
<h2 id=solution><strong>Solution:</strong></h2>
|
||||
<h2 id=solution>Solution:</h2>
|
||||
<p>The idea of the Data Migration Façade is to provide an API that creates and updates master data and related entities (including transactions) without referencing NAV tables.</p>
|
||||
<p>Additionally, the framework around the Data Migration Façade provides tools for error handling, and a way to integrate the migration in the Data Migration Overview page (page 1799).</p>
|
||||
<p>The façade framework has the following components:</p>
|
||||
|
|
@ -261,7 +261,7 @@ BC AL Help . dev
|
|||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
<h2 id=usage><strong>Usage:</strong></h2>
|
||||
<h2 id=usage>Usage:</h2>
|
||||
<p>There are the following use cases:</p>
|
||||
<ul>
|
||||
<li>
|
||||
|
|
@ -278,7 +278,7 @@ This deletes existing status lines for migrating Items for ‘My Migration T
|
|||
</ul>
|
||||
<p>**“Data Migration Façade”.StartMigration(‘My Migration Type’,false) **<br>
|
||||
This starts the migration. False means this is not a retry. A re-try is when you migrate one or more records from the <strong>Show Errors</strong> page, which is described later in this document. Retry = true is only used by the <strong>Show Errors</strong> page and should not be used from extensions.</p>
|
||||
<h3 id=usage-without-staging-tables><strong>Usage without staging tables:</strong></h3>
|
||||
<h3 id=usage-without-staging-tables>Usage without staging tables:</h3>
|
||||
<p>The overall workflow is:</p>
|
||||
<ol>
|
||||
<li>Integrate your extension in the <strong>Data Migration Wizard</strong> by subscribing to the events exposed by the <strong>Data Migration Façade</strong>.</li>
|
||||
|
|
@ -295,55 +295,54 @@ This starts the migration. False means this is not a retry. A re-try is when you
|
|||
<p><a href=NoStagingTableNew2.png><img src=NoStagingTableNew2.png alt=" "></a></p>
|
||||
<p>_Figure 1: sequence diagram of the data migration without staging tables _</p>
|
||||
<p>The following example shows how to migrate items without staging tables:</p>
|
||||
<pre><code>trigger OnRun();
|
||||
var
|
||||
ItemDataMigrationFacade: Codeunit "Item Data Migration Facade";
|
||||
ItemNumber: Integer;
|
||||
ItemJson: Text;
|
||||
begin
|
||||
// loop on items retrieved through a web service for example
|
||||
for ItemNumber := 1 to ExternalWebService.GetItemCount do begin
|
||||
ExternalWebService.GetItem(ItemNumber,ItemJson);
|
||||
// create item using the facade
|
||||
if not ItemDataMigrationFacade.CreateItemIfNeeded(ItemJson.ItemNumber,ItemJson.ItemName1,
|
||||
ItemJson.ItemName2,ConvertItemType(ItemJson.ItemType)) then
|
||||
exit; // item already exists
|
||||
// set some fields using the facade
|
||||
ItemDataMigrationFacade.SetVendorItemNo(ItemJson.VendItemNumber);
|
||||
ItemDataMigrationFacade.SetUnitVolume(ItemJson.Volume);
|
||||
ItemDataMigrationFacade.SetAlternativeItemNo(ItemJson.AltItemNumber);
|
||||
if ItemJson.PrimaryVendor <\> '' then
|
||||
ItemDataMigrationFacade.SetVendorNo(ItemJson.PrimaryVendor);
|
||||
// migrate dependencies
|
||||
MigrateItemUnitOfMeasure(ItemDataMigrationFacade,ItemJson);
|
||||
// modify the item (+run trigger) to save the changes made by setters
|
||||
ItemDataMigrationFacade.ModifyItem(true);
|
||||
// update the status in the migration dashboard
|
||||
DataMigrationStatusFacade.IncrementMigratedRecordCount('My Migration Type',
|
||||
Database::Item,1);
|
||||
end;
|
||||
end;
|
||||
procedure MigrateItemUnitOfMeasure(ItemDataMigrationFacade : Codeunit "Item Data Migration Facade";
|
||||
ItemJson : Text);
|
||||
var
|
||||
MyUnitCodeStagingTable: Record "My Unit Code Staging Table";
|
||||
DataMigrationStatusFacade: Codeunit "Data Migration Status Facade";
|
||||
DescriptionToSet: Text\[10\];
|
||||
UnitCodeJson: Text;
|
||||
begin
|
||||
if ItemJson.UnitCode = '' then
|
||||
// log an error using the Data migration façade
|
||||
DataMigrationStatusFacade.RegisterErrorNoStagingTablesCase(
|
||||
'My Migration Type',Database::Item,'Unit of measure is empty.');
|
||||
if ExternalWebService.GetUnitCode(ItemJson.UnitCode,UnitCodeJson) then
|
||||
DescriptionToSet := UnitCodeJson.Description;
|
||||
ItemDataMigrationFacade.CreateUnitOfMeasureIfNeeded(ItemJson.UnitCode, DescriptionToSet);
|
||||
// set the unit of measure on the item
|
||||
ItemDataMigrationFacade.SetBaseUnitOfMeasure(ItemJson.UnitCode);
|
||||
end;
|
||||
</code></pre>
|
||||
<p>_Figure 2: Example of Item and Item Unit of Measure migration without staging tables _</p>
|
||||
<h3 id=usage-with-staging-tables><strong>Usage with staging tables:</strong></h3>
|
||||
<div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-al data-lang=al> <span style=color:#66d9ef>trigger</span> OnRun<span style=color:#f92672>()</span>;
|
||||
<span style=color:#66d9ef>var</span>
|
||||
ItemDataMigrationFacade: <span style=color:#66d9ef>Codeunit</span> "Item Data Migration Facade";
|
||||
ItemNumber: <span style=color:#66d9ef>Integer</span>;
|
||||
ItemJson: <span style=color:#66d9ef>Text</span>;
|
||||
<span style=color:#66d9ef>begin</span>
|
||||
<span style=color:#75715e>// loop on items retrieved through a web service for example
|
||||
</span><span style=color:#75715e></span> <span style=color:#66d9ef>for</span> ItemNumber <span style=color:#f92672>:=</span> <span style=color:#ae81ff>1</span> <span style=color:#66d9ef>to</span> ExternalWebService<span style=color:#f92672>.</span>GetItemCount <span style=color:#66d9ef>do</span> <span style=color:#66d9ef>begin</span>
|
||||
ExternalWebService<span style=color:#f92672>.</span>GetItem<span style=color:#f92672>(</span>ItemNumber,ItemJson<span style=color:#f92672>)</span>;
|
||||
<span style=color:#75715e>// create item using the facade
|
||||
</span><span style=color:#75715e></span> <span style=color:#66d9ef>if</span> <span style=color:#f92672>not</span> ItemDataMigrationFacade<span style=color:#f92672>.</span>CreateItemIfNeeded<span style=color:#f92672>(</span>ItemJson<span style=color:#f92672>.</span>ItemNumber,ItemJson<span style=color:#f92672>.</span>ItemName1,
|
||||
ItemJson<span style=color:#f92672>.</span>ItemName2,ConvertItemType<span style=color:#f92672>(</span>ItemJson<span style=color:#f92672>.</span>ItemType<span style=color:#f92672>)) </span><span style=color:#66d9ef>then</span>
|
||||
<span style=color:#66d9ef>exit</span>; <span style=color:#75715e>// item already exists
|
||||
</span><span style=color:#75715e></span> <span style=color:#75715e>// set some fields using the facade
|
||||
</span><span style=color:#75715e></span> ItemDataMigrationFacade<span style=color:#f92672>.</span>SetVendorItemNo<span style=color:#f92672>(</span>ItemJson<span style=color:#f92672>.</span>VendItemNumber<span style=color:#f92672>)</span>;
|
||||
ItemDataMigrationFacade<span style=color:#f92672>.</span>SetUnitVolume<span style=color:#f92672>(</span>ItemJson<span style=color:#f92672>.</span>Volume<span style=color:#f92672>)</span>;
|
||||
ItemDataMigrationFacade<span style=color:#f92672>.</span>SetAlternativeItemNo<span style=color:#f92672>(</span>ItemJson<span style=color:#f92672>.</span>AltItemNumber<span style=color:#f92672>)</span>;
|
||||
<span style=color:#66d9ef>if</span> ItemJson<span style=color:#f92672>.</span>PrimaryVendor <\> <span style=color:#e6db74>''</span> <span style=color:#66d9ef>then</span>
|
||||
ItemDataMigrationFacade<span style=color:#f92672>.</span>SetVendorNo<span style=color:#f92672>(</span>ItemJson<span style=color:#f92672>.</span>PrimaryVendor<span style=color:#f92672>)</span>;
|
||||
<span style=color:#75715e>// migrate dependencies
|
||||
</span><span style=color:#75715e></span> MigrateItemUnitOfMeasure<span style=color:#f92672>(</span>ItemDataMigrationFacade,ItemJson<span style=color:#f92672>)</span>;
|
||||
<span style=color:#75715e>// modify the item (+run trigger) to save the changes made by setters
|
||||
</span><span style=color:#75715e></span> ItemDataMigrationFacade<span style=color:#f92672>.</span>ModifyItem<span style=color:#f92672>(</span>true<span style=color:#f92672>)</span>;
|
||||
<span style=color:#75715e>// update the status in the migration dashboard
|
||||
</span><span style=color:#75715e></span> DataMigrationStatusFacade<span style=color:#f92672>.</span>IncrementMigratedRecordCount<span style=color:#f92672>(</span><span style=color:#e6db74>'My Migration Type'</span>,
|
||||
<span style=color:#66d9ef>Database</span>::Item,<span style=color:#ae81ff>1</span><span style=color:#f92672>)</span>;
|
||||
<span style=color:#66d9ef>end</span>;
|
||||
<span style=color:#66d9ef>end</span>;
|
||||
<span style=color:#66d9ef>procedure</span> MigrateItemUnitOfMeasure<span style=color:#f92672>(</span>ItemDataMigrationFacade : <span style=color:#66d9ef>Codeunit</span> "Item Data Migration Facade";
|
||||
ItemJson : <span style=color:#66d9ef>Text</span><span style=color:#f92672>)</span>;
|
||||
<span style=color:#66d9ef>var</span>
|
||||
MyUnitCodeStagingTable: <span style=color:#66d9ef>Record</span> "My Unit Code Staging Table";
|
||||
DataMigrationStatusFacade: <span style=color:#66d9ef>Codeunit</span> "Data Migration Status Facade";
|
||||
DescriptionToSet: <span style=color:#66d9ef>Text</span>\[<span style=color:#ae81ff>10</span>\];
|
||||
UnitCodeJson: <span style=color:#66d9ef>Text</span>;
|
||||
<span style=color:#66d9ef>begin</span>
|
||||
<span style=color:#66d9ef>if</span> ItemJson<span style=color:#f92672>.</span>UnitCode = <span style=color:#e6db74>''</span> <span style=color:#66d9ef>then</span>
|
||||
<span style=color:#75715e>// log an error using the Data migration façade
|
||||
</span><span style=color:#75715e></span> DataMigrationStatusFacade<span style=color:#f92672>.</span>RegisterErrorNoStagingTablesCase<span style=color:#f92672>(
|
||||
</span><span style=color:#f92672> </span><span style=color:#e6db74>'My Migration Type'</span>,<span style=color:#66d9ef>Database</span>::Item,<span style=color:#e6db74>'Unit of measure is empty.'</span><span style=color:#f92672>)</span>;
|
||||
<span style=color:#66d9ef>if</span> ExternalWebService<span style=color:#f92672>.</span>GetUnitCode<span style=color:#f92672>(</span>ItemJson<span style=color:#f92672>.</span>UnitCode,UnitCodeJson<span style=color:#f92672>) </span><span style=color:#66d9ef>then</span>
|
||||
DescriptionToSet <span style=color:#f92672>:=</span> UnitCodeJson<span style=color:#f92672>.</span>Description;
|
||||
ItemDataMigrationFacade<span style=color:#f92672>.</span>CreateUnitOfMeasureIfNeeded<span style=color:#f92672>(</span>ItemJson<span style=color:#f92672>.</span>UnitCode, DescriptionToSet<span style=color:#f92672>)</span>;
|
||||
<span style=color:#75715e>// set the unit of measure on the item
|
||||
</span><span style=color:#75715e></span> ItemDataMigrationFacade<span style=color:#f92672>.</span>SetBaseUnitOfMeasure<span style=color:#f92672>(</span>ItemJson<span style=color:#f92672>.</span>UnitCode<span style=color:#f92672>)</span>;
|
||||
<span style=color:#66d9ef>end</span>;
|
||||
</code></pre></div><p>_Figure 2: Example of Item and Item Unit of Measure migration without staging tables _</p>
|
||||
<h3 id=usage-with-staging-tables>Usage with staging tables:</h3>
|
||||
<p>The overall workflow is:</p>
|
||||
<ul>
|
||||
<li>
|
||||
|
|
@ -373,76 +372,73 @@ end;
|
|||
<li></li>
|
||||
</ul>
|
||||
<p><a href=StagingTableNew2.png><img src=StagingTableNew2.png alt=" "></a></p>
|
||||
<p>_Figure 3: Simplified sequence diagram of the data migration with staging tables _</p>
|
||||
<p><em>Figure 3: Simplified sequence diagram of the data migration with staging tables</em></p>
|
||||
<p>Below is a simplified example showing how to create an item:</p>
|
||||
<pre><code>\[EventSubscriber(ObjectType::Codeunit, Codeunit::"Item Data Migration Facade", 'OnMigrateItem', '', true, true)\]
|
||||
procedure OnMigrateItem(VAR Sender : Codeunit "Item Data Migration Facade";RecordIdToMigrate : RecordId);
|
||||
var
|
||||
MyItemStagingTable : Record "My Item Staging Table";
|
||||
begin
|
||||
// handle the event if it targets this extension's staging table
|
||||
if RecordIdToMigrate.TableNo <\> Database::"My Item Staging Table" then
|
||||
exit;
|
||||
MyItemStagingTable.Get(RecordIdToMigrate);
|
||||
// create item using the facade
|
||||
if not Sender.CreateItemIfNeeded(MyItemStagingTable.ItemNumber,MyItemStagingTable.ItemName1,
|
||||
MyItemStagingTable.ItemName2,ConvertItemType(MyItemStagingTable.ItemType)) then
|
||||
exit; // item already exists
|
||||
// set some fields using the facade
|
||||
Sender.SetVendorItemNo(MyItemStagingTable.VendItemNumber);
|
||||
Sender.SetUnitVolume(MyItemStagingTable.Volume);
|
||||
Sender.SetAlternativeItemNo(MyItemStagingTable.AltItemNumber);
|
||||
if MyItemStagingTable.PrimaryVendor <\> '' then
|
||||
Sender.SetVendorNo(MyItemStagingTable.PrimaryVendor);
|
||||
// modify the item (+run trigger) to save the changes made by setters
|
||||
Sender.ModifyItem(true);
|
||||
end;
|
||||
</code></pre>
|
||||
<p>_Figure 4: Example of event subscriber for Item migration _</p>
|
||||
<p>__</p>
|
||||
<div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-al data-lang=al> [EventSubscriber<span style=color:#f92672>(</span><span style=color:#66d9ef>ObjectType</span>::<span style=color:#66d9ef>Codeunit</span>, <span style=color:#66d9ef>Codeunit</span>::"Item Data Migration Facade", <span style=color:#e6db74>'OnMigrateItem'</span>, <span style=color:#e6db74>''</span>, true, true<span style=color:#f92672>)</span>]
|
||||
<span style=color:#66d9ef>procedure</span> OnMigrateItem<span style=color:#f92672>(</span><span style=color:#66d9ef>VAR</span> Sender : <span style=color:#66d9ef>Codeunit</span> "Item Data Migration Facade";RecordIdToMigrate : <span style=color:#66d9ef>RecordId</span><span style=color:#f92672>)</span>;
|
||||
<span style=color:#66d9ef>var</span>
|
||||
MyItemStagingTable : <span style=color:#66d9ef>Record</span> "My Item Staging Table";
|
||||
<span style=color:#66d9ef>begin</span>
|
||||
<span style=color:#75715e>// handle the event if it targets this extension's staging table
|
||||
</span><span style=color:#75715e></span> <span style=color:#66d9ef>if</span> RecordIdToMigrate<span style=color:#f92672>.</span>TableNo <\> <span style=color:#66d9ef>Database</span>::"My Item Staging Table" <span style=color:#66d9ef>then</span>
|
||||
<span style=color:#66d9ef>exit</span>;
|
||||
MyItemStagingTable<span style=color:#f92672>.</span>Get<span style=color:#f92672>(</span>RecordIdToMigrate<span style=color:#f92672>)</span>;
|
||||
<span style=color:#75715e>// create item using the facade
|
||||
</span><span style=color:#75715e></span> <span style=color:#66d9ef>if</span> <span style=color:#f92672>not</span> Sender<span style=color:#f92672>.</span>CreateItemIfNeeded<span style=color:#f92672>(</span>MyItemStagingTable<span style=color:#f92672>.</span>ItemNumber,MyItemStagingTable<span style=color:#f92672>.</span>ItemName1,
|
||||
MyItemStagingTable<span style=color:#f92672>.</span>ItemName2,ConvertItemType<span style=color:#f92672>(</span>MyItemStagingTable<span style=color:#f92672>.</span>ItemType<span style=color:#f92672>)) </span><span style=color:#66d9ef>then</span>
|
||||
<span style=color:#66d9ef>exit</span>; <span style=color:#75715e>// item already exists
|
||||
</span><span style=color:#75715e></span> <span style=color:#75715e>// set some fields using the facade
|
||||
</span><span style=color:#75715e></span> Sender<span style=color:#f92672>.</span>SetVendorItemNo<span style=color:#f92672>(</span>MyItemStagingTable<span style=color:#f92672>.</span>VendItemNumber<span style=color:#f92672>)</span>;
|
||||
Sender<span style=color:#f92672>.</span>SetUnitVolume<span style=color:#f92672>(</span>MyItemStagingTable<span style=color:#f92672>.</span>Volume<span style=color:#f92672>)</span>;
|
||||
Sender<span style=color:#f92672>.</span>SetAlternativeItemNo<span style=color:#f92672>(</span>MyItemStagingTable<span style=color:#f92672>.</span>AltItemNumber<span style=color:#f92672>)</span>;
|
||||
<span style=color:#66d9ef>if</span> MyItemStagingTable<span style=color:#f92672>.</span>PrimaryVendor <\> <span style=color:#e6db74>''</span> <span style=color:#66d9ef>then</span>
|
||||
Sender<span style=color:#f92672>.</span>SetVendorNo<span style=color:#f92672>(</span>MyItemStagingTable<span style=color:#f92672>.</span>PrimaryVendor<span style=color:#f92672>)</span>;
|
||||
<span style=color:#75715e>// modify the item (+run trigger) to save the changes made by setters
|
||||
</span><span style=color:#75715e></span> Sender<span style=color:#f92672>.</span>ModifyItem<span style=color:#f92672>(</span>true<span style=color:#f92672>)</span>;
|
||||
<span style=color:#66d9ef>end</span>;
|
||||
</code></pre></div><p><em>Figure 4: Example of event subscriber for Item migration</em></p>
|
||||
<p>Below is another example showing how to use additional events to set fields that reference other tables, here the unit of measure:</p>
|
||||
<pre><code>\[EventSubscriber(ObjectType::Codeunit, Codeunit::"Item Data Migration Facade", 'OnMigrateItemUnitOfMeasure', '', true, true)\]
|
||||
procedure OnMigrateItemUnitOfMeasure(VAR Sender : Codeunit "Item Data Migration Facade";RecordIdToMigrate : RecordId);
|
||||
var
|
||||
MyItemStagingTable : Record "My Item Staging Table";
|
||||
MyUnitCodeStagingTable : Record "My Unit Code Staging Table";
|
||||
DescriptionToSet: Text\[10\];
|
||||
begin
|
||||
// handle the event if it targets this extension's staging table
|
||||
if RecordIdToMigrate.TableNo <\> Database::"My Item Staging Table" then
|
||||
exit;
|
||||
MyItemStagingTable.Get(RecordIdToMigrate);
|
||||
if MyItemStagingTable.UnitCode = '' then
|
||||
error('Unit of measure is empty.');
|
||||
MyUnitCodeStagingTable.SetRange(UnitCode,MyItemStagingTable.UnitCode);
|
||||
if MyUnitCodeStagingTable.FindFirst then
|
||||
DescriptionToSet := MyUnitCodeStagingTable.Description;
|
||||
// create the unit of measure through the facade
|
||||
Sender.CreateUnitOfMeasureIfNeeded(MyItemStagingTable.UnitCode, DescriptionToSet);
|
||||
// set the unit of measure on the item
|
||||
Sender.SetBaseUnitOfMeasure(MyItemStagingTable.UnitCode);
|
||||
// modify the item to save the changes made by setter
|
||||
Sender.ModifyItem(false);
|
||||
end;
|
||||
</code></pre>
|
||||
<p>_Figure 5: Example of event subscriber for Item Unit of Measure migration _</p>
|
||||
<h3 id=combining-both-approaches><strong>Combining both approaches:</strong></h3>
|
||||
<div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-al data-lang=al> [EventSubscriber<span style=color:#f92672>(</span><span style=color:#66d9ef>ObjectType</span>::<span style=color:#66d9ef>Codeunit</span>, <span style=color:#66d9ef>Codeunit</span>::"Item Data Migration Facade", <span style=color:#e6db74>'OnMigrateItemUnitOfMeasure'</span>, <span style=color:#e6db74>''</span>, true, true<span style=color:#f92672>)</span>]
|
||||
<span style=color:#66d9ef>procedure</span> OnMigrateItemUnitOfMeasure<span style=color:#f92672>(</span><span style=color:#66d9ef>VAR</span> Sender : <span style=color:#66d9ef>Codeunit</span> "Item Data Migration Facade";RecordIdToMigrate : <span style=color:#66d9ef>RecordId</span><span style=color:#f92672>)</span>;
|
||||
<span style=color:#66d9ef>var</span>
|
||||
MyItemStagingTable : <span style=color:#66d9ef>Record</span> "My Item Staging Table";
|
||||
MyUnitCodeStagingTable : <span style=color:#66d9ef>Record</span> "My Unit Code Staging Table";
|
||||
DescriptionToSet: <span style=color:#66d9ef>Text</span>[<span style=color:#ae81ff>10</span>];
|
||||
<span style=color:#66d9ef>begin</span>
|
||||
<span style=color:#75715e>// handle the event if it targets this extension's staging table
|
||||
</span><span style=color:#75715e></span> <span style=color:#66d9ef>if</span> RecordIdToMigrate<span style=color:#f92672>.</span>TableNo <\> <span style=color:#66d9ef>Database</span>::"My Item Staging Table" <span style=color:#66d9ef>then</span>
|
||||
<span style=color:#66d9ef>exit</span>;
|
||||
MyItemStagingTable<span style=color:#f92672>.</span>Get<span style=color:#f92672>(</span>RecordIdToMigrate<span style=color:#f92672>)</span>;
|
||||
<span style=color:#66d9ef>if</span> MyItemStagingTable<span style=color:#f92672>.</span>UnitCode = <span style=color:#e6db74>''</span> <span style=color:#66d9ef>then</span>
|
||||
error<span style=color:#f92672>(</span><span style=color:#e6db74>'Unit of measure is empty.'</span><span style=color:#f92672>)</span>;
|
||||
MyUnitCodeStagingTable<span style=color:#f92672>.</span>SetRange<span style=color:#f92672>(</span>UnitCode,MyItemStagingTable<span style=color:#f92672>.</span>UnitCode<span style=color:#f92672>)</span>;
|
||||
<span style=color:#66d9ef>if</span> MyUnitCodeStagingTable<span style=color:#f92672>.</span>FindFirst <span style=color:#66d9ef>then</span>
|
||||
DescriptionToSet <span style=color:#f92672>:=</span> MyUnitCodeStagingTable<span style=color:#f92672>.</span>Description;
|
||||
<span style=color:#75715e>// create the unit of measure through the facade
|
||||
</span><span style=color:#75715e></span> Sender<span style=color:#f92672>.</span>CreateUnitOfMeasureIfNeeded<span style=color:#f92672>(</span>MyItemStagingTable<span style=color:#f92672>.</span>UnitCode, DescriptionToSet<span style=color:#f92672>)</span>;
|
||||
<span style=color:#75715e>// set the unit of measure on the item
|
||||
</span><span style=color:#75715e></span> Sender<span style=color:#f92672>.</span>SetBaseUnitOfMeasure<span style=color:#f92672>(</span>MyItemStagingTable<span style=color:#f92672>.</span>UnitCode<span style=color:#f92672>)</span>;
|
||||
<span style=color:#75715e>// modify the item to save the changes made by setter
|
||||
</span><span style=color:#75715e></span> Sender<span style=color:#f92672>.</span>ModifyItem<span style=color:#f92672>(</span>false<span style=color:#f92672>)</span>;
|
||||
<span style=color:#66d9ef>end</span>;
|
||||
</code></pre></div><p><em>Figure 5: Example of event subscriber for Item Unit of Measure migration</em></p>
|
||||
<h3 id=combining-both-approaches>Combining both approaches:</h3>
|
||||
<p>If you want to migrate additional entities, the **Data Migration **framework lets you initialize the migration with entities other than master data. In this case, the <strong>Data Migration Overview</strong> page will show additional lines. Item, vendor, customer, an general ledger accounts are migrated with an event driven approach, and the additional entities are migrated by calling an extension codeunit <strong>OnRun</strong> method.</p>
|
||||
<h2 id=error-handling-with-staging-tables><strong>Error handling with staging tables:</strong></h2>
|
||||
<h2 id=error-handling-with-staging-tables>Error handling with staging tables:</h2>
|
||||
<p>The migration starts by calling <strong>RUN</strong> on the façade codeunit. Errors thrown during the call are captured by <strong>GETLASTERRORTEXT</strong> and displayed when you choose the <strong>Show Errors</strong> action on the <strong>Data Migration Overview</strong> page.</p>
|
||||
<p><a href=errorhandling1.png><img src=errorhandling1.png alt=" "></a></p>
|
||||
<p>_Figure 6: List of errors shown when clicking <strong>Show Errors</strong> on the <strong>Data Migration Overview</strong> page _</p>
|
||||
<p><em>Figure 6: List of errors shown when clicking <strong>Show Errors</strong> on the <strong>Data Migration Overview</strong> page</em></p>
|
||||
<p>__</p>
|
||||
<p>The <strong>Edit Record</strong> action opens a view of the staging table, where you can edit fields to fix errors. Figure 4 shows an example of a page for the vendor staging table in a migration from C5.</p>
|
||||
<p><a href=errorhandling2.png><img src=errorhandling2.png alt=" "></a></p>
|
||||
<p>_Figure 7: Edit a staging table record _</p>
|
||||
<p><em>Figure 7: Edit a staging table record</em></p>
|
||||
<p>__</p>
|
||||
<p>The <strong>Staging Table ID</strong> determines the page to open, so it is important that the page ID is equal to the <strong>Staging Table ID</strong>, at least for the master data staging tables, for example, for<strong>G/L Accounts, Items, Customers</strong> and <strong>Vendor</strong>. You should ensure that pages to edit related entities are linked on this page by means of new actions. For example, Figure 4 uses the <strong>C5 Purchaser</strong> action.</p>
|
||||
<p>After you fix the staging table record, you can choose the <strong>Migrate</strong> action to mark the selected records as records to retry, and then run <strong>StartMigration</strong> with the <strong>Retry</strong> flag set to true. This is the only place where the retry flag should be set to true in the <strong>StartMigration</strong> procedure.</p>
|
||||
<p>Error handling without staging tables</p>
|
||||
<p>When migrating data without staging tables, errors can be registered manually by the extension using <strong>DataMigrationStatusFacade.RegisterErrorNoStagingTablesCase</strong>. Otherwise they can be registered automatically if the codeunits fail when called on their <strong>OnRun</strong> procedure.</p>
|
||||
<p>Errors will be displayed in the error list, but you cannot open and edit records because there is no staging table. The Edit action will not be available.</p>
|
||||
<h2 id=limitations><strong>Limitations:</strong></h2>
|
||||
<h2 id=limitations>Limitations:</h2>
|
||||
<ul>
|
||||
<li>
|
||||
<p>Data migration will fail if there are customers, vendors, items in the database and if these entities are selected for migration. For example, if you choose to migrate items and your company already contains items, you will get an error. This should not be an issue if you migrate your data from another tool to NAV, in which case you will most likely start on a fresh empty company. However, if you just want to import additional items to a company with existing items, then it is not supported by the framework. however, you can still use the different functions provided by the different codeunits (such as <strong>Item Data Migration Facade</strong>) to create the entities without strong coupling on the NAV data model.</p>
|
||||
|
|
@ -454,7 +450,7 @@ end;
|
|||
<p>There is no automated rollback in case of failure: data that is successfully migrated will be commited, and data that is not successfully migrated with be shown in the errors list. The retry feature (in case of staging tables) then makes it possible for you to retry individual entities or ignore them.</p>
|
||||
</li>
|
||||
</ul>
|
||||
<h2 id=usages-in-nav><strong>Usages in NAV:</strong></h2>
|
||||
<h2 id=usages-in-nav>Usages in NAV:</h2>
|
||||
<p>The Data Migration Façade is available starting from version 2018.</p>
|
||||
<p>The following Façade codeunits for data migration management are available:</p>
|
||||
<ul>
|
||||
|
|
@ -483,7 +479,7 @@ end;
|
|||
<p>COD6114 (<strong>Ex. Rate Data Migration Facade</strong>)</p>
|
||||
</li>
|
||||
</ul>
|
||||
<h2 id=references><strong>References:</strong></h2>
|
||||
<h2 id=references>References:</h2>
|
||||
<p>Façade pattern on Wikipedia: <a href=https://en.wikipedia.org/wiki/Facade>https://en.wikipedia.org/wiki/Facade</a>_pattern</p>
|
||||
<footer class=footline>
|
||||
</footer>
|
||||
|
|
@ -497,12 +493,12 @@ end;
|
|||
<div style=left:-1000px;overflow:scroll;position:absolute;top:-1000px;border:none;box-sizing:content-box;height:200px;margin:0;padding:0;width:200px>
|
||||
<div style=border:none;box-sizing:content-box;height:200px;margin:0;padding:0;width:200px></div>
|
||||
</div>
|
||||
<script src=/js/clipboard.min.js?1636104707></script>
|
||||
<script src=/js/perfect-scrollbar.min.js?1636104707></script>
|
||||
<script src=/js/perfect-scrollbar.jquery.min.js?1636104707></script>
|
||||
<script src=/js/jquery.svg.pan.zoom.js?1636104707></script>
|
||||
<script src=/js/featherlight.min.js?1636104707></script>
|
||||
<script src=/js/modernizr.custom-3.6.0.js?1636104707></script>
|
||||
<script src=/js/relearn.js?1636104707></script>
|
||||
<script src=/js/clipboard.min.js?1636386789></script>
|
||||
<script src=/js/perfect-scrollbar.min.js?1636386789></script>
|
||||
<script src=/js/perfect-scrollbar.jquery.min.js?1636386789></script>
|
||||
<script src=/js/jquery.svg.pan.zoom.js?1636386789></script>
|
||||
<script src=/js/featherlight.min.js?1636386789></script>
|
||||
<script src=/js/modernizr.custom-3.6.0.js?1636386789></script>
|
||||
<script src=/js/relearn.js?1636386789></script>
|
||||
</body>
|
||||
</html>
|
||||
Loading…
Add table
Add a link
Reference in a new issue