O25DE1: Understanding and Creating Data Entities

<for my reference only: O25 = October 2025; DE1 = Data Entity Tag;>

What's a Data Entity (really)?

A Data Entity is a business‑friendly view over one or more normalized tables (e.g., CustTable, addresses, contacts), packaged so you can import/export, integrate, and evolve with less pain when the underlying schema changes. Think: one door, many rooms behind it. Entities can also be exposed as OData (for APIs) and used by the Data Management Framework (DMF) for bulk import/export.

Heads‑up: F&O does not allow direct T‑SQL against the prod DB. Entities (and BYOD) exist to keep you safe and supported.

---

When should I create my own entity?

• You need a clean shape for integration—not ten joins.
• You plan to expose an API (OData) for a specific business concept.
• You want DMF import/export (files, recurring jobs, mapping) without writing plumbing.

---

Step‑by‑step: Create an entity for Item Serial Numbers

Example scenario: Export/import item serial numbers from the InventSerial table (and related bits) via one entity.

1. Create a project in Visual Studio (F&O dev VM).
2. Add → New Item → Data Entity.
3. In the wizard: choose a category, then select the primary data source (InventSerial).
4. (Important) Choose capabilities — see the two checkboxes below (“Enable API” and “Enable Data management capabilities”).
5. Click Next, add/remove fields & data sources as needed, then Finish.
6. Build + Sync your model so SQL views / staging artifacts are created. (Entities compile to a view; DMF adds staging.)

---

The two checkboxes everyone asks about

1) Enable API — what it actually does (and when to use it)

• What it enables: Makes the entity OData‑exposable (public) so external apps can call it via REST (/data/<EntitySet>). Under the hood you’re opting the entity into the OData surface.
• What you still need: The entity must have a key, be public (IsPublic), and only use OData‑supported constructs. Not every entity shape is OData‑friendly (e.g., composite entities are not supported over OData).
• Good use cases: Near‑real‑time CRUD integrations, light automation, low‑volume “API first” scenarios.
• Not ideal for: Heavy bulk transfers (DMF is better), document‑style multi‑header/multi‑line imports (use composite entities via DMF instead).

Composite entities aren’t OData‑enabled and generally don’t play with Change Tracking either—so keep them for DMF XML/file imports.

Sanity checks before you tick it:

• Your entity has a stable key and predictable cardinality.
• No unsupported data sources for OData.
• Security/privileges are configured (exposing an API means access control matters).

---

2) Enable Data management capabilities — what you get (and why you want it)

• What it enables: Hooks the entity into DMF so you can use Data Management workspace to import/export, apply mappings, run recurring jobs, and use staging tables for validation. This is the backbone for BYOD full/incremental pushes.
• Artifacts created: A staging table and metadata for DMF pipelines; the runtime gives you target mappings, templates, packages, and file handling (CSV/Excel/XML).
• Good use cases: Bulk loads, cutovers, scheduled exports to analytics, and any scenario where you want mapping + validation + retry rather than row‑by‑row API calls.

If you’re planning BYOD later:

• Turn on Change Tracking (on the entity) so you can do incremental exports—not just “full push”. You can track primary table, entire entity, or a custom query (the latter is for classic CT; row version CT doesn’t allow custom query—details below).

---

Finishing the build (and proving it works)

1. Build → Build Solution.
2. Sync after adding entities so the SQL view and (if DMF enabled) the staging table exist.
3. Test DMF: open Data management → Data entities and verify your entity is listed; try an Export with a small filter.
4. Test API (if enabled): from a browser or client, call https://<env>.cloudax.dynamics.com/data/<EntitySet>?$top=1 with OAuth—confirm you get metadata/rows (and mind security).

---

A few pragmatic tips 

• Keys & indexes: Define a clear natural or surrogate key in the entity; shaky keys make OData and DMF unhappy.
• Keep it lean: Don’t over‑join. Flat, well‑scoped entities export faster and are easier to troubleshoot in DMF.
• Composite wisely: Great for document‑like imports (header+lines) via DMF; don’t try to OData them, and don’t rely on incremental CT.
• Change Tracking choices:
  • Primary table → fewer false positives, but misses secondary table updates.
  • Entire entity → more complete, potentially more churn - so slower.
  • Custom query → only for classic CT (not rowversion enabled). Pick what fits your ops.

---

Wrap‑up

Creating a Data Entity is still the safest, most future‑proof way to move data in/out of F&O.

• Tick Enable API when you want an OData endpoint for light, transactional integrations.
• Tick Enable Data management capabilities when you need DMF for robust import/export, BYOD, and scheduled workloads.
• And if analytics modernization is on your roadmap, keep an eye on row version change tracking prerequisites so you’re ready for BYOD/Synapse/Fabric later.

I hope this saves you a few build‑and‑sync loops. 

 
<Inspired from https://www.linkedin.com/pulse/d365fo-creating-data-entities-anshika-gupta-niduc>