Data Entities in Microsoft Dynamics 365 F&O – Practical Configuration Guide

In our previous post, we talked about what data entities are and why they matter; now it’s time to roll up our sleeves and configure them. This guide will walk you through setting up standard data entities for import/export, finding and using the out-of-the-box entities, extending them when you need extra fields, and even creating brand-new custom entities in Visual Studio. We’ll also cover best practices on performance tuning, enabling change tracking for incremental loads, and keeping your data entities secure. Let’s dive in!

Setting Up Data Entities for Import/Export

Setting up a data entity in the Data Management Framework (DMF) is usually the first step for any import or export project. This process is largely point-and-click, and it handles the heavy lifting of moving data in or out of F&O.

When you need to import or export data in Dynamics 365 F&O, the Data Management Framework is your best friend. Here’s a quick overview of how to use DMF with data entities:

1️⃣ Data Management Workspace: In F&O, navigate to the Data Management workspace. Here you can create a Data Project by clicking Import or Export tile. Think of data project as a container for one or more entities you want to import or export. Give your project a name (e.g. “Customer data export”).

2️⃣ Add Entities to the Project: Once your data project is created, you can add an entity to it. Click Add entity and select the data entity you need (for example, Customer V3 for customer records), and pick the target data format (Excel, CSV, XML, etc.).

3️⃣ Field Mapping: After adding the entity, F&O will auto-map the columns for you if you used the template. However, you can always click View map to review or adjust the field mappings. This is where you match fields from your source file to the entity’s fields. In most cases the default mapping is fine, but if your source file column names differ or you want to set default values, you can configure that here.

4️⃣ Staging vs. Direct: By default, imports/exports use a two-step approach. When you run the project, DMF will first load data into a staging table for that entity, then move it into the actual target tables. The staging table has the same fields as the entity and acts as a buffer where business logic and validation are applied. This design is super helpful – it catches errors and lets you fix data in the staging area without corrupting live records. (You can choose to skip staging for performance, which pushes data directly to target tables – useful for final runs once you’re confident the data is clean, but generally not recommended for initial imports.)

5️⃣ Execute and Monitor: Run the import or export. The DMF execution engine will process each entity sequentially (or in parallel if configured) – parsing the file, pushing data into staging, running validations, and then importing into F&O. You can monitor progress in the Execution summary, which shows each entity as a tile with status. If any records fail validation, they will be flagged. You can click View staging data to inspect records that failed and see error messages. A handy trick: fix the data directly in the staging table (or your source file) and re-run the import for just the failed records, rather than starting over.

6️⃣ Data Packages (Optional): If you have multiple entities in one project, you can export or import them together as a data package – essentially a zip file containing all the data files and a manifest. This is great for moving configuration sets between environments. F&O can generate this package for you, and you can also load a package to import multiple entities in one go.

A big convenience of using data entities via DMF is that one entity can represent data from many tables. So instead of juggling 5 different spreadsheets to import a customer and their addresses, you fill in one template for the Customer entity and DMF distributes the data to the right places. And remember – always verify the results after an import or export. Use the application UI or Excel add-in to spot-check that records landed correctly. The DMF job history and execution log are your go-to for any troubleshooting (it will tell you if, say, a required field was missing, or a value was invalid).

For large imports, break the data into batches (e.g. files of 10k records) instead of one giant file, to improve performance and error isolation.

Finding & Using Standard Data Entities

One of the great things about F&O is that Microsoft provides thousands of standard data entities out-of-the-box (over 1,700 by recent count). Here’s how to locate and use these standard entities:

• Data Entities List: In the Data Management workspace, there’s a Data entities page. This is a searchable list of all entities available in your system. You can filter by name or category. For example, search “Customer” to see all customer-related entities. The naming can be a bit technical (e.g. CustCustomerV3Entity is a customer entity). Microsoft Learn documentation provides lists of common entities per module (Accounts receivable, Accounts payable, etc.) if you’re unsure.

• Using Entities in Excel or Power BI: Besides DMF, you can use standard entities in other ways. For instance, the Excel Add-in allows you to open an entity in Excel and refresh data or publish changes. Similarly, Power BI or other tools can pull data via the OData feed of an entity. No additional setup is needed beyond security privileges – if you have access and the entity is public, you’re good to go.

Using standard entities is generally straightforward – find the entity, include it in your data project or integration, and let it work its magic. Make sure to use the right entity for the right job (e.g. use the Customers V3 entity for customer master data, not a transactions entity). And don’t reinvent the wheel – before creating a custom entity, always search this list; Microsoft likely already built it for you!

Extending an Existing Data Entity (Adding Fields)

Sometimes the standard entity is almost perfect but missing one little field you need. Don’t worry – you don’t have to start from scratch. You can extend Microsoft’s entities to add your custom fields or tweak mappings, all while staying within supported customization.

Data entities are extensible, meaning you can include additional fields that you have created or customized. For example, you might have introduced a custom field such as Loyalty Level on your Customers table to better categorize customers based on their purchase history and rewards status. Here’s a realistic scenario on how you can extend a data entity to include this field:

1️⃣ Add the Custom Field to the Table: First, ensure your custom field, Loyalty Level, is added to the standard customer table (CustTable). You can do this via table extensions in Visual Studio:

Build your project and synchronize it with the database.

2️⃣ Create an Entity Extension in Visual Studio:

• In Application Explorer search for CustCustomerV3Entity.

• Right-click on entity and select Create Extension.

3️⃣ Include the New Field in the Entity:

• In the data entity extension designer, identify your custom field Loyalty Level from the primary data source (CustTable).

• Drag this field from the data source into the entity’s fields list. This inclusion ensures that your custom field becomes available for integrations and data management tasks.

4️⃣ Extend the Staging Table:

• If the entity supports Data Management Framework (DMF), you’ll also need to extend its staging table (CustCustomerV3Staging) by adding the Loyalty Level field. This step prevents import/export errors due to missing fields.

After your modifications, build your Visual Studio project and synchronize your database. Confirm that there are no errors to ensure your changes have successfully applied.

5️⃣ Refresh Entity List:

• Within the Data Management workspace in F&O, navigate to System administration > Workspaces > Data management > Framework parameters > Entity settings, and click Refresh entity list. This step is crucial to update the entity metadata with your recent changes.

6️⃣ Regenerate Mapping:

• If existing data import or export projects involve the modified entity, regenerate the data mapping to integrate your new Loyalty Level field. This ensures the field will be available in future data operations.

Following these steps allows your new custom field, such as Loyalty Level, to seamlessly integrate into your data entities, enhancing your ability to manage and leverage custom data effectively.

That’s it! You’ve extended a standard entity. From the end-user perspective, it behaves just like any other field. If you open the entity in Excel or export it, the new field comes along.

Things to keep in mind:

• You can also use this technique to add whole new data sources to an entity (for example, link an additional related table). This is more advanced – you’d add the new table as a data source in the entity extension and join it appropriately. It may sometimes require a little X++ code if the relationship isn’t straightforward.

• If you need to change or override business logic of the entity (say the way it validates data), you might use X++ Chain of Command on the entity’s methods. For instance, you could override the postLoad method to manipulate data after it’s read, or the validateWrite method to add custom validation on import. Use these carefully – they run for every record during data import/export.

• Testing: Always test your extended entity with a small data file to ensure the new fields export and import correctly. If something isn’t working, double-check that you extended both the entity and its staging table, and that security settings (privileges) are updated if needed.

By extending standard entities, you’re effectively telling the system “treat my custom field just like it was always part of standard data.” This is a powerful way to adapt the system’s data model to your business without a lot of reinventing.

Creating a New Custom Data Entity

What if you’ve created a completely new table in Dynamics 365 F&O, such as an Asset Registry, that Microsoft doesn’t provide by default? No worries — you can create your own data entity. This allows you to seamlessly import, export, and integrate your custom table data just like any standard entity.

Sometimes you’ll create new tables in F&O to manage specific business needs, like tracking assets. Here’s how to create a custom data entity step-by-step:

1️⃣ Use the Wizard: In Visual Studio, right-click your project and choose Add > New item. Select Data Model > Data Entity to launch the Data Entity Wizard. Name your entity clearly (e.g., “AssetRegistryEntity”):

2️⃣ Set Properties (Very Important): During setup, configure these essential properties based on your custom entity:

• Primary datasource: Select your main table (AssetRegistry) as the data source for the entity.

• Entity category: Choose “Master” to reflect the nature of your Asset Registry entity, impacting security and template behaviors.

• Enable public API: Check this option to expose your entity for external integrations via OData and Excel.

• Public entity name & collection name: Define how your entity appears externally; use singular (“Registry”) and plural (“Registries”) names.

• Enable data management capabilities: Check to allow import/export operations via the Data Management Framework (DMF), automatically creating the staging table (e.g., “AssetRegistryStaging”).

• Security privileges: Review auto-generated privileges (e.g., “AssetRegistryEntityView” and “AssetRegistryEntityMaintain”) to manage user access.

3️⃣ Select Fields (and Related Data): The wizard will prompt you to choose fields from your primary table. Typically, you’ll select all fields initially and later remove any unnecessary ones. You can also add fields from related tables if needed. For example, if your “AssetRegistry” table links to an “AssetType” table via a foreign key, you can easily pull relevant fields like “AssetTypeDescription” into your entity.

4️⃣ Finish Wizard & Review: Completing the wizard generates your entity and associated staging table (if DMF is enabled), and security privileges for view and maintain purpose. Review the generated entity in the AOT, ensuring fields, data sources, and keys are accurately represented. Adjust labels or add computed fields as necessary.

5️⃣ Build and Synchronize: Build your project to compile the new entity and its staging table. Synchronize the database afterward to physically create the staging table in SQL. Resolve any compilation or synchronization issues promptly.

6️⃣ Refresh Entity List in F&O: In Dynamics 365 F&O, go to Data management workspace > Framework parameters > Entity settings and click Refresh entity list. Your custom entity “AssetRegistryEntity” should now appear in the entity list. If it doesn’t, verify your build, sync, and environment.

7️⃣ Test Your Entity: Confirm functionality by performing quick tests. Create an export project to generate an Excel template — ensure all desired fields appear correctly. Also, test importing data using a small dataset.

Clear Naming Conventions

• Use Meaningful Names: Follow Microsoft’s naming conventions—entities should be intuitively named to reflect their purpose, ending with “Entity” (e.g. AssetRegistryEntity).

• Field Names and Labels: Align field names with their corresponding labels in the UI. For clarity, suffix foreign keys with “ID” or “Number,” and avoid using abbreviations or underscores in naming.

• Unique Labels: Assign distinct labels and descriptions for every data entity and field to avoid conflicts or confusion during system refreshes or migrations.

• Use prefix for custom objects: While deeper architectural topics were intentionally left out of this blog post for simplicity, it’s worth emphasizing the importance of using a consistent prefix for all custom objects (usually 3 letter prefix). Adopting a unique prefix across your custom entities, tables, classes, and fields provides immediate clarity by distinguishing custom components from Microsoft’s standard ones, and it significantly reduces the risk of naming conflicts. This approach also supports long-term maintainability in enterprise-scale solutions, ensuring that your custom artifacts remain distinct and manageable as the system evolves.

By creating custom entities, you ensure your unique data smoothly integrates with Dynamics 365 F&O’s robust Data Management Framework, simplifying migration, integration, and consistent data handling.

Time to Talk Results

When working with Data Entities in Dynamics 365 Finance & Operations, following best practices will significantly enhance your integrations, maintainability, and overall system performance. Here are some key technical recommendations:

Performance Tuning

• Optimize for Bulk Operations: Utilize set-based processing and parallel imports to handle large datasets efficiently. Configure your import/export parameters carefully—consider batch mode execution to distribute the load effectively.

• Minimize Complexity: Keep entity designs simple, avoiding unnecessary joins or extensive computed columns. Limit data sources within entities (ideally to 3 or fewer joins) and select only essential fields.

• Database Optimization: Ensure that underlying tables have appropriate indexes for frequently used filter or join fields to accelerate query performance.

• Incremental Exports: Enable change tracking selectively, excluding large or rarely modified tables to ensure incremental exports run quickly and efficiently.

• Staging Tables: Only utilize staging tables when truly necessary; avoid excessive custom logic in staging operations to maintain optimal throughput.

Maintainability and Extensibility

• Extend: Add custom fields via table and data entity extensions, and implement business logic using event handlers or chain of command.

• Logical Organization: Maintain clear organization in the AOT by adhering to consistent naming conventions and using structured project layouts. This approach simplifies debugging, enhancements, and future upgrades.

• Centralize Reusable Logic: Create and use shared methods or global classes for frequently used logic, validation rules, or transformations rather than duplicating code across multiple entities.

• Label and Enum Consistency: Utilize labels, enumerations, and configuration keys consistently to avoid hard-coded values, ensuring changes propagate cleanly across entities.

Robust Security Practices

• Least Privilege Access: Assign the minimum required permissions to users or roles. Define entity-specific privileges clearly separated by functional scenarios (import, export, view, maintain).

• Distinct Entry Points: Leverage built-in entry-point security to differentiate permissions clearly between Data Management (file import/export) and Data Services (OData/Excel integrations).

• Regular Security Reviews: Continuously audit which entities are publicly exposed through APIs and Excel integrations. Test security configurations with realistic user roles rather than admin-level privileges to verify that permissions behave as intended.

By following these best practices, you’ll build robust, efficient, and maintainable data management solutions in Dynamics 365 F&O. This careful planning upfront saves significant effort in maintenance and troubleshooting down the road, ensuring that your data entity strategy scales seamlessly alongside your business needs.

Links

https://dynlab365.com/2025/04/30/data-entities-in-microsoft-dynamics-365-fo-practical-configuration-guide/

https://learn.microsoft.com/en-us/dynamics365/fin-ops-core/dev-itpro/data-entities/data-entities

https://learn.microsoft.com/en-us/dynamics365/fin-ops-core/dev-itpro/data-entities/build-consuming-data-entities

https://learn.microsoft.com/en-us/dynamics365/fin-ops-core/dev-itpro/data-entities/entity-change-track

https://learn.microsoft.com/en-us/dynamics365/fin-ops-core/dev-itpro/dev-tools/design-best-practices

https://learn.microsoft.com/en-us/dynamics365/fin-ops-core/dev-itpro/data-entities/security-data-entities