5.3 Embedding Canvas Apps in Model-Driven Forms

Embedding Canvas Apps in Model-Driven Forms

While model-driven applications excel at structured data entry and automated business process flows, specific operational scenarios demand rich, composite user interfaces that connect to external line-of-business systems, display complex graphical components, or incorporate interactive calculations. Prior to the introduction of Custom Pages, Embedded Canvas Apps established the architectural pattern for bringing canvas capabilities directly onto model-driven forms.

For the PL-200 exam, functional consultants must thoroughly understand how embedded canvas apps operate, how the specialized ModelDrivenFormIntegration control bridges host context, how to handle data refresh lifecycles, and how embedded canvas apps compare to modern Custom Pages.

---

1. Embedded Canvas Apps Architecture & Integration Mechanism

An Embedded Canvas App is hosted within an isolated <iframe> element inside a section or tab of a model-driven form. It communicates with the host Dataverse form through a specialized client-side integration channel.

+-----------------------------------------------------------------------------------+
|                    EMBEDDED CANVAS APP INTEGRATION ARCHITECTURE                   |
|                                                                                   |
|  [MODEL-DRIVEN FORM SHELL]                                                        |
|  +------------------------------------------------------------------------------+ |
|  | Account Name: Contoso Corp | Account Number: AC-9021                         | |
|  |                                                                              | |
|  |  +-- [IFRAME: EMBEDDED CANVAS APP] --------------------------------------+   | |
|  |  |                                                                      |   | |
|  |  |   [ModelDrivenFormIntegration Control]                               |   | |
|  |  |         |                                                            |   | |
|  |  |         +---> [@ModelDrivenFormIntegration].Item                     |   | |
|  |  |         |     (Exposes Account Name, Number, GUID, etc.)             |   | |
|  |  |         v                                                            |   | |
|  |  |   +-------------------+       +------------------------------------+ |   | |
|  |  |   | External SQL Data |       | Power Automate / REST API Services | |   | |
|  |  |   +-------------------+       +------------------------------------+ |   | |
|  |  +----------------------------------------------------------------------+   | |
|  +------------------------------------------------------------------------------+ |
+-----------------------------------------------------------------------------------+

Configuration Mechanics

1. Column Binding Requirement: An embedded canvas app must be bound to a column on the host form—typically a Single Line of Text column (such as the primary name column name or a dedicated custom placeholder text column).
2. Adding the Control: In the form designer, the consultant selects the column, adds the Canvas App component, and selects Customize to launch the Canvas Studio.
3. App ID Parameter: Dataverse automatically generates a unique Canvas App definition linked to the form XML via its App Name and App ID (GUID).

---

2. The ModelDrivenFormIntegration Control & Context Passing

When a canvas app is created through the model-driven form designer, Dataverse automatically inserts a specialized root control named ModelDrivenFormIntegration. This control acts as the bi-directional communication bridge between the Dataverse form shell and the canvas app engine.

+-----------------------------------------------------------------------------------+
|                    MODELDRIVENFORMINTEGRATION DATA FLOW                           |
|                                                                                   |
|   [Host Record Form: Account "Northwind Traders" (ID: 8a9b...)]                   |
|        |                                                                          |
|        v                                                                          |
|   [ModelDrivenFormIntegration Control]                                            |
|        |                                                                          |
|        +---> [@ModelDrivenFormIntegration].Item                                   |
|        |     - Returns typed record object of "Northwind Traders"                 |
|        |     - Direct access: [@ModelDrivenFormIntegration].Item.Telephone1       |
|        |                                                                          |
|        +---> OnDataRefresh Event                                                  |
|              - Triggers when Host Form is Saved or Refreshed                      |
|              - Power Fx: Refresh(Accounts); Refresh(SQLExternalOrders)            |
+-----------------------------------------------------------------------------------+

Context Properties

1. [@ModelDrivenFormIntegration].Item:

   • Returns the active record currently displayed on the model-driven form as a strongly typed Dataverse record object.
   • Used directly in canvas formulas to filter related data, set default values, or display header details:

     // Gallery Items property querying external SQL orders matching current Account Number
     Filter(
         'External ERP Orders',
         CustomerAccountNumber = [@ModelDrivenFormIntegration].Item.accountnumber
     )
     

2. [@ModelDrivenFormIntegration].SelectedRecord:

   • Legacy property referencing the active row. In modern implementations, [@ModelDrivenFormIntegration].Item is the recommended syntax.

The OnDataRefresh Event Handler

When a user edits fields on the parent model-driven form and clicks Save, or clicks the form's Refresh button, the host form notifies the embedded canvas app by firing the OnDataRefresh event.

• Formula Execution: The consultant authors Power Fx formulas in ModelDrivenFormIntegration.OnDataRefresh to synchronize local collections and external data sources with the updated host record:

// ModelDrivenFormIntegration.OnDataRefresh Formula
Refresh(Accounts);
Set(varCurrentAccount, [@ModelDrivenFormIntegration].Item);
ClearCollect(
    colLiveSensorData,
    IoTDeviceConnector.GetTelemetry(varCurrentAccount.cr123_deviceguid)
);
Notify("Embedded sensor telemetry synchronized with host record.", NotificationType.Information)

---

3. Embedded Canvas Apps vs. Standalone Custom Pages

With the release of Custom Pages, Microsoft established a modern standard for embedding canvas-like flexibility into model-driven apps. Understanding when to use Custom Pages versus Embedded Canvas Apps is a frequent focus on the PL-200 exam.

+-----------------------------------------------------------------------------------+
|                 CUSTOM PAGES VS. EMBEDDED CANVAS APPS COMPARISON                  |
|                                                                                   |
|  [CUSTOM PAGES (MODERN STANDARD)]         [EMBEDDED CANVAS APPS (LEGACY PATTERN)] |
|  - Native React/Fluent UI shell           - Hosted in nested <iframe>             |
|  - Full page, Center Dialog, Side Pane    - Embedded only inside form tab/section |
|  - Responsive auto-layout by default      - Fixed aspect ratio (Phone/Tablet)     |
|  - Solution component page type           - Bound to single text column XML       |
|  - High performance, fast rendering       - Slower iframe initialization          |
|  - Param("recordId") context passing      - ModelDrivenFormIntegration.Item       |
+-----------------------------------------------------------------------------------+

Detailed Architectural Comparison

[!TIP] Exam Guidance: When a question describes creating a new responsive UI extension, modal dialog wizard, or docked side pane, Custom Pages is the correct architectural choice. Embedded Canvas Apps are primarily utilized when maintaining legacy forms or embedding canvas UIs strictly within a single form tab.

---

4. ALM, Solution Packaging & Security Governance

Deploying embedded canvas apps across development, test, and production environments requires strict adherence to Application Lifecycle Management (ALM) principles.

+-----------------------------------------------------------------------------------+
|                    EMBEDDED CANVAS APP ALM & SHARING PIPELINE                     |
|                                                                                   |
|  [DEVELOPMENT ENVIRONMENT]                                                        |
|  - Add Table + Form XML + Canvas App to Same Solution                              |
|  - Use Connection References & Environment Variables                              |
|                             |                                                     |
|                             v [Export as Managed Solution]                        |
|  [TEST / PRODUCTION ENVIRONMENT]                                                  |
|  - Import Managed Solution                                                        |
|  - Canvas App ID & Form XML bindings resolved automatically                       |
|                             |                                                     |
|                             v                                                     |
|  [SECURITY SHARING GOVERNANCE]                                                    |
|  - Model-Driven App: Assigned to Security Role (e.g., Sales Rep)                  |
|  - Embedded Canvas App: MUST ALSO BE SHARED with same Security Role / AAD Group!   |
+-----------------------------------------------------------------------------------+

Key ALM Best Practices

1. Unified Solution Packaging: Always add the host Table, the Model-Driven Form, and the Canvas App component into the same Dataverse Solution. This ensures relative component dependencies are preserved when exporting and importing managed solutions.
2. Connection References: Any connectors used inside the embedded canvas app (e.g., SQL Server, Office 365, SharePoint) must use Connection References and Environment Variables rather than hardcoded connection strings.
3. Dual Security Role Sharing:
   • Granting a user a Dataverse Security Role that allows access to the Model-Driven App does NOT automatically grant access to the embedded canvas app.
   • Administrators must explicitly Share the embedded canvas app with the corresponding Dataverse Security Roles or Microsoft Entra ID (Azure AD) security groups. If not shared, users will see a permissions error ("You don't have permission to view this app") inside the form iframe.