Migrating document templates in Dynamics 365 Dataverse is straightforward for system entities — but when custom entities are involved, a hidden pitfall can render migrated templates completely unusable. KingswaySoft’s SSIS Integration Toolkit addresses this directly with a purpose-built field called associatedentitytypecode.old, which is used to automatically correct entity code mismatches between source and target instances during migration.

 

Key Highlights

• Document templates in Dynamics 365 Dataverse are Word and Excel files tied to specific entity records, used to generate branded business documents at the click of a button.
• Migrating templates for system entities is simple: map the required metadata fields in KingswaySoft’s SSIS toolkit and write to the target instance.
• Custom entity templates require extra handling because entity codes are not consistent across Dataverse instances.
• KingswaySoft’s old field automatically rewrites the embedded entity code inside the template file to match the target instance.
• A three-step SSIS data flow — read, lookup, write — handles the full migration reliably, even when working across dozens of templates and multiple custom entities.

What Are Document Templates in Dynamics 365 Dataverse?

Document templates in Dynamics 365 Dataverse are standardized Microsoft Word and Excel files that users can generate directly from a CRM record. Rather than manually assembling contracts, reports, or client documents, a user clicks a button, and the system produces a fully populated, professionally formatted file. Because templates enforce consistent formatting and pull live record data, they save meaningful time and ensure brand consistency across the organization.

Each document template is associated with a specific entity — for example, a contract template tied to the Account entity, or a client summary tied to a custom entity. That association is stored as an entity type code, which is how Dataverse knows which records a given template applies to.

Why Are Document Templates with a Custom Entity Harder to Migrate?

For out-of-the-box Dataverse entities, document template migration is simple. You connect to the source instance, read from the documenttemplate entity, map the required metadata — the primary GUID, the associated entity type code, and the template name — and write to the target. The whole process typically takes only a few minutes.

Custom entities introduce a complication: the entity code assigned to a custom entity is not guaranteed to be the same across two different Dataverse instances. The associatedentitytypecode field in the source might reference entity code 10042 for a custom entity called cust_client, but in the target instance, that same custom entity may carry a completely different code. If you perform a direct write without accounting for this, the migrated template ends up associated with the wrong entity — or no valid entity at all.

The target entity code is embedded inside the template file itself, not just stored as external metadata. An incorrect code embedded in the file makes the migrated template completely unusable in the target environment, regardless of how the rest of the metadata looks.

How Does the SSIS Integration Toolkit Resolve the Entity Code Mismatch?

KingswaySoft’s SSIS Integration Toolkit addresses this with an artificial destination field called associatedentitytypecode.old. This is not a native Dataverse field — it was added specifically to the Dynamics 365 Dataverse/CRM destination component to handle entity code translation during migration.

When you map the original source entity type code to associatedentitytypecode.old, the toolkit automatically locates every occurrence of that old code inside the template file and replaces it with the correct code from the target instance. This rewriting happens internally within the software before the template is saved to the destination. No manual file editing is required, and the result is a fully functional, correctly associated template in the target environment.

How to Migrate Dynamics 365 Dataverse Document Templates Using the KingswaySoft SSIS Integration Toolkit

The migration is built as a three-step SSIS data flow, using two connection managers — one for the source Dataverse/CRM instance and one for the target. KingswaySoft’s Dynamics 365 Dataverse/CRM connection managers are valid for both on-premises and online Dataverse connections.

Step 1 — Read the DocumentTemplate Entity from the Source

The first step uses a KingswaySoft Dataverse/CRM Source component pointed at the documenttemplate entity on the source instance. This step is straightforward: pull the records you need, either by reading the full entity or by filtering to specific templates using a FetchXML query. This source becomes the primary data flow for the rest of the package.

Step 2 — Look Up ObjectTypeCodes from the Source EntityMetadata

This is where the migration handles the custom entity challenge. Each document template’s associatedentitytypecode identifies which entity the template is tied to, but you also need the corresponding ObjectTypeCode — a source-assigned integer value — to pass into the associatedentitytypecode.old field in Step 3.

Hardcoding these integer values is not practical when you’re migrating a large number of templates across multiple entities. Instead, use a lookup against the EntityMetadata entity, which KingswaySoft’s source component supports natively. EntityMetadata contains each entity’s logical name and its assigned ObjectTypeCode, making it the right source for this information. Using KingswaySoft’s Premium Lookup component, you join the document template source data with the EntityMetadata source on the entity name field, pulling the correct ObjectTypeCode for each template dynamically. This approach scales cleanly regardless of how many templates and custom entities are involved.

Step 3 — Write to the Target Instance with Correct Entity Associations

The final step uses the KingswaySoft Dataverse/CRM Destination component pointed at the target instance, writing to the documenttemplate entity with a Create action — or an Upsert action if that fits your scenario better.

On the column mapping page, you map the standard metadata fields (GUID, template name, associated entity type code) alongside the associatedentitytypecode.old field. For that field, you supply the ObjectTypeCode value retrieved from the EntityMetadata lookup in Step 2. With this mapping in place, the toolkit translates the old entity code to the correct target-side code automatically, and each template is created in the target instance correctly associated with the intended custom entity.

Verifying the Migration in the Target Dynamics 365 Instance

Once the SSIS package executes, the migrated document templates appear in the target Dataverse environment and can be reviewed directly from the Dynamics 365 interface. Confirming that each template is associated with the correct custom entity — and that it opens and functions as expected — validates that the associatedentitytypecode.old translation worked correctly. A template that renders properly and pulls the right record data is the clearest sign that the migration succeeded.

Frequently Asked Questions

Q: What happens if I migrate a custom entity document template without using the associatedentitytypecode.old field?

A: The migrated template will likely be associated with the wrong entity in the target instance, or no valid entity at all. Because the entity code is embedded inside the template file itself, an incorrect value makes the template unusable until the association is manually corrected.

Q: Does KingswaySoft’s SSIS Integration Toolkit support migration between on-premises and online Dataverse instances?

A: Yes. KingswaySoft supports both on-premises and online Dataverse/CRM connections, and the same migration approach — including the associatedentitytypecode.old field — applies to on-premises-to-online migrations.

Q: What is the EntityMetadata entity, and why is it used in this process?

A: EntityMetadata is a Dataverse entity that stores metadata about all entities in the environment, including each entity’s logical name and its assigned ObjectTypeCode. KingswaySoft’s source component can query it directly, making it the right tool for dynamically retrieving entity codes rather than hardcoding them.

Q: Can this process handle migrations involving multiple custom entities at once?

A: Yes. The EntityMetadata lookup retrieves ObjectTypeCodes dynamically at runtime, so the data flow scales to any number of document templates and associated entities without requiring hardcoded values for each one.

Q: Is the associatedentitytypecode.old field part of the standard Dataverse schema?

A: No. It is a field introduced by KingswaySoft within our Dataverse/CRM destination component specifically to handle entity type code translation during document template migration. It does not exist in the native Dataverse entity model.

Ready to Migrate Your Dynamics 365 Document Templates?

If your Dynamics 365 migration project includes document templates tied to custom entities, understanding the entity code mismatch problem before you start will save you from a confusing failure mid-migration. KingswaySoft’s SSIS Integration Toolkit is built to handle exactly this kind of scenario — the kind that isn’t obvious until the template you just migrated refuses to work.

For more details on configuring the Dataverse/CRM source and destination components, working with the EntityMetadata entity, or handling other migration edge cases, contact us at KingswaySoft today.

 

By KingswaySoft | www.kingswaysoft.com

The post How to Migrate Dynamics 365 Dataverse Document Templates with Custom Entities Using KingswaySoft appeared first on CRM Software Blog | Dynamics 365.