Dynamics 365 Finance & Operations: Build Custom Archive Framework Scenarios with Dataverse LTR

First introduced in public preview on April 24, 2026, and reaching general availability on June 30, 2026, for Worldwide (Standard Multi-Tenant) cloud instances, this cross-app capability opens up the core Archive Framework orchestration engine to customer-built data models. While the roadmap entry flags the capability as enabled automatically for end users, ERP administrators and developers should read that label carefully: the platform hooks are live, but turning this into a working retention pipeline requires deliberate schema design, strict indexing, X++ contract coding, and Microsoft Dataverse configuration.

The "One Dynamics One Platform" Context and Architectural Boundaries​

Under Microsoft's One Dynamics One Platform initiative, the boundary between traditional Finance and Operations SQL storage and Microsoft Power Platform's Dataverse layer continues to converge. In the standard Dynamics 365 archival architecture, live application data that has aged out of daily operational relevance is replicated to Dataverse long-term retention (LTR) via virtual entities, reconciled, copied into reduced-index Finance and Operations history tables (*History), and finally purged from the live transactional tables.

Before writing a single line of X++ code, architects must understand the strictest rule in Microsoft Learn's archive customization documentation: a standalone custom archive scenario can only include custom tables. It cannot reference Microsoft-managed tables—not even as join conditions or lookup dependencies. The Archive Framework actively validates table graphs during job creation; if it detects a dependency on a first-party Microsoft table, the archive job fails validation immediately.

So how do you choose the right customization path? Microsoft Learn outlines three distinct options depending on how your custom data lives in the ERP:

The framework also polices first-party scenarios against unauthorized alterations, blocking jobs if extensions attempt to remove required Microsoft tables or slip unauthorized standard tables into an existing flow.

Step-by-Step Engineering Guide: Building a Standalone Custom Archive Scenario​

If your organization has a standalone custom transaction hierarchy—say, a custom workflow module consisting of CustomWorkflowHeader, CustomWorkflowLine, CustomWorkflowLineDetail, and CustomWorkflowComment—building a custom scenario lets you plug directly into the standard Archive Workspace scheduling, execution, and reversal flows.

According to Microsoft Learn's implementation documentation, all custom archive classes and objects must be placed in a customer-owned model, never inside Microsoft's locked BusinessIntelligence model.

1. Prerequisite Environment Setup​

Before deploying custom scenarios, ensure the base archival plumbing is active:

• Visual Studio & Roles: You need Visual Studio with Dynamics 365 Finance and Operations development tools and System Administrator rights in the environment.
• Power Platform Admin Center: Install or update the Dynamics 365 Archive with Dataverse long term retention application and verify that Dynamics 365 Finance and Operations Virtual Entities are enabled.
• Feature Management: In Finance and Operations, enable Archive with Dataverse long term retention.

2. Live Table Hierarchy and Mandatory Indexing​

Your table hierarchy starts with a single root table (which defines the overall archive scope) and cascades to related child tables using RecId foreign-key relationships with clear one-to-one or one-to-many cardinality and zero circular dependencies.

Every participating live root and child table requires three non-negotiable configurations in Visual Studio:

1. Enable Change Tracking: Set the table property ChangeTrackingEnabled to Yes.
2. Archive Criteria Index (ArchiveCriteriaIdx): This index optimizes the query that selects records ready for archiving. On the root table, place the primary segregation field (DataAreaId or Partition) first, followed by your WHERE clause criteria fields (such as workflow status and completion date). On child tables, index the foreign key used to join to the parent table. Both root and child criteria indexes must attach RecId (if not clustered), SysRowVersion, and SysDataStateCode as Included Columns.
3. Reconciliation Index (ArchiveSysVersionIdx): Required on every root and child table participating in Dataverse long-term retention. It must be a nonclustered index with the exact field sequence SysDataStateCode followed by SysRowVersion. Microsoft warns that omitting ArchiveSysVersionIdx causes severe performance degradation during LTR marking and reconciliation, leading to job timeouts or validation failures.

3. Mirror History Tables​

For each live table in your hierarchy, create a corresponding history table named with the History suffix (for example, CustomWorkflowHeaderHistory).

• Copy every field from the live table except SysRowVersion and SysDataState, which the platform manages automatically during data movement. Field names, data types, extended data types (EDTs), and string lengths must match the live table identically.
• Do not copy unique indexes from the live table to the history table.
• Do add indexes on foreign keys and criteria fields on the history tables. If criteria indexes are missing on history tables, the framework will block you from scheduling reversal (restore) jobs.

4. Finance and Operations Data Entities (BiEntity) and Dataverse LTR​

To move data into Dataverse long-term retention with a minimal SQL Server footprint, every live table needs a dedicated Finance and Operations data entity following the [TableName]BiEntity naming convention (e.g., CustomWorkflowHeaderBiEntity). Set all fields to Public and configure these mandatory entity properties:

• IsPublic: Yes
• Is Read Only: Yes
• Auto Create: Yes (automatically publishes the virtual entity to Dataverse after entity sync, though Microsoft notes automatic publication can take 24 to 48 hours)
• Auto Refresh: Yes
• Allow Retention: Yes
• Allow Row Version Change Tracking: Yes
• ChangeTrackingEnabled: Yes

Once your package is deployed and entities are refreshed in the Data Management workspace (Framework parameters > Entity settings > Refresh entity list), open the Power Apps Maker Portal (or package an automated Dataverse solution via Customizations.xml). Locate each virtual entity (prefixed with mserp_, such as mserp_customworkflowheaderbientity) and enable both Track changes and Long-term retain this table. Skipping even one child entity in the hierarchy will cause LTR to fail for that table and break archive job validation.

5. X++ Job Contract Creator and Parallel Processing​

Next, build the job contract creator class in your customer-owned model using Microsoft.Dynamics.Archive.Contracts. Your createPostJobRequest method uses ArchiveServiceArchiveJobPostRequestBuilder and ArchiveServiceSourceTableConfiguration to wire together each live table (newForSourceTable for the root, newForChildSourceTable for children), its history table, and its BiEntity, along with exact foreign-key join conditions and DataAreaId / Partition filter conditions. Finally, implement ArchiveServiceIManagedArchiveType and export it via MEF so your custom scenario appears in the Archive Workspace UI.

Pro Tip for High-Volume Environments: By default, custom scenario archive jobs run sequentially one at a time. To unlock parallel processing, call setJobCriteriaKey() on the builder before adding source tables. Passing a logical partition identifier—most commonly the legal entity (DataAreaId)—tells the scheduler that two jobs with different keys do not overlap and can execute simultaneously, provided each job's WHERE clause strictly filters by that exact key.

Operational Realities and Troubleshooting Common Pitfalls​

Building the code is only half the battle; running it in production requires understanding what the Archive Framework actually does behind the scenes.

• Retention Rules Are Your Responsibility: While Microsoft's sample code illustrates archiving completed workflows older than 730 days (CompletedDate < (today() - 730)), that is purely a technical syntax example—not legal or regulatory advice. Organizations must define age, status, and volume criteria that align with their own industry and local compliance mandates.
• Verify Operational Constraints: Retained data in Dataverse is strictly read-only, and staging, reconciling, and moving records happens asynchronously in the background. Furthermore, admins should always test reversal jobs in a sandbox environment to confirm parent-child hierarchies restore cleanly to live tables before trusting a custom scenario in production.
• Quick Troubleshooting Checklist:
  • Job creation fails validation immediately: Check that every live table has both ArchiveCriteriaIdx and ArchiveSysVersionIdx, and verify that no table in your hierarchy references a Microsoft-managed table.
  • Child records aren't archiving: Confirm that the addJoinCondition field names in your X++ contract builder match the child table's foreign-key relation constraints exactly.
  • Reversal jobs are blocked: Ensure your *History tables have indexes covering foreign keys and criteria fields.

Summary​

Roadmap ID 576778 brings first-party archival discipline to custom X++ data domains in Dynamics 365 Finance and Operations. By enforcing strict index standards, isolated custom-table scopes, and unified Dataverse long-term retention entities, the Archive Framework gives enterprise teams a supported way to keep custom tables lean without writing brittle cleanup scripts.