When using SharePoint document management with Dataverse, the right configuration depends on where you want users to see and manage the files. A model-driven app and a Power Pages site may both use Dataverse and SharePoint, but the document display pattern is not the same.
The key difference is this: model-driven apps use the SharePoint document experience through sharepointdocument, while Power Pages uses a form subgrid based on Document Locations. Mixing these patterns can lead to confusing configuration and broken document behavior.
1) Three Common Scenarios
There are three common ways to show SharePoint documents related to Dataverse records:
- Model-driven app: out-of-the-box Documents tab
- Model-driven app: custom tab with a document subgrid
- Power Pages: form or multistep form with a Document Locations subgrid
These scenarios are related because they all depend on Dataverse SharePoint integration, but they should not be configured the same way.
2) Model-Driven App: OOB Documents Tab
For a model-driven app, the standard approach is to use the built-in Documents tab. This is the native SharePoint document experience inside model-driven apps, and it shows SharePoint files related to the current Dataverse record.
Use this pattern for internal users working in Dynamics 365 or model-driven Power Apps.
| Item | Value |
|---|---|
| App type | Model-driven app |
| Recommended UI | OOB Documents tab |
| Target table used by the document control | sharepointdocument |
| Best for | Internal document management on Dataverse records |
Microsoft’s model-driven app guidance shows that the Documents tab uses the relationship to SharePointDocument. In the FormXML sample, the target entity type is sharepointdocument, and the relationship name follows a pattern such as Account_SharePointDocument.
Recommended pattern:
Model-driven app form → OOB Documents tab → sharepointdocument → SharePoint files
3) Model-Driven App: Custom Tab with Subgrid
You can also create a custom tab on a model-driven app form and place a subgrid there to show SharePoint documents. This is still a model-driven app pattern, so the subgrid should use sharepointdocument.
| Setting | Value |
|---|---|
| Table | sharepointdocument |
| Relationship | <ParentTable>_SharePointDocument |
| Example relationship | Account_SharePointDocument |
| Purpose | Show SharePoint files related to the current Dataverse record |
For example, if the parent table is Account, the relationship is commonly shown as:
Account_SharePointDocument
For another table, use that table’s actual one-to-many relationship where the related table is SharePointDocument. Microsoft’s documentation says to find the table relationship where the related table type is SharePointDocument.
Recommended pattern:
Model-driven app form → custom tab → subgrid using sharepointdocument → SharePoint files
4) Power Pages: Form with Document Locations Subgrid
Power Pages is different. For Power Pages, do not use the model-driven app sharepointdocument grid as the document-management pattern.
Instead, the Dataverse form used by Power Pages should include a subgrid based on Document Locations.
| Setting | Value |
|---|---|
| Table | Document Locations |
| Default view | Active Document Locations |
| Purpose | Enable Power Pages document display and document actions through the portal form experience |
Microsoft’s Power Pages documentation specifically says to add a subgrid component, choose Document Locations as the table, and select Active Document Locations as the default view.
Recommended pattern:
Power Pages form → Document Locations subgrid → Power Pages document UI → SharePoint files
5) Simple Rule
The simplest way to remember the configuration is this: model-driven apps use sharepointdocument, while Power Pages uses Document Locations.
| App Type | Scenario | Table to Use |
|---|---|---|
| Model-driven app | OOB Documents tab | sharepointdocument |
| Model-driven app | Custom tab with document subgrid | sharepointdocument |
| Power Pages | Form or multistep form document list | Document Locations |
| Power Pages | Upload, download, or delete documents | Document Locations plus table permissions |
6) Important Power Pages Notes
For Power Pages, the parent Dataverse record must already exist before users can upload documents. That means the Power Pages form should normally be an update or edit form, not a create form, when document upload is required.
Microsoft states that file upload will not work on a create form because the parent record is not created until after the form is submitted.
Power Pages also requires table permissions. The user must have permission to the parent Dataverse record, and the site must also be configured with the required child permission on Document Location.
| Permission | Purpose |
|---|---|
| Parent table permission | Allows access to the main Dataverse record |
| Child permission on Document Location | Allows access to the related document location and files |
Microsoft states that a child table permission on Document Location is required for each parent table permission where documents need to be shown.
Recommended Guidance for Project Teams
- Use the OOB Documents tab for the standard model-driven app document experience.
- Use a custom subgrid with
sharepointdocumentonly when the model-driven app form needs a custom layout. - Use Document Locations for Power Pages forms and multistep forms.
- Do not treat the model-driven app
sharepointdocumentgrid as the Power Pages document-management pattern. - For Power Pages uploads, make sure the parent record already exists before users try to upload documents.
- Configure both the parent table permission and the required child permission on Document Location for Power Pages document access.
Quick Summary
| Area | Use | Key Point |
|---|---|---|
| Model-driven app OOB Documents tab | sharepointdocument |
Best default option for internal users working in Dynamics 365 or model-driven Power Apps. |
| Model-driven app custom tab | sharepointdocument |
Use the parent table’s SharePointDocument relationship, such as Account_SharePointDocument. |
| Power Pages form | Document Locations | Add a Document Locations subgrid using the Active Document Locations view. |
| Power Pages upload | Existing parent record plus permissions | Uploads require an existing parent record and correct table permissions. |
Final Recommendation
For model-driven apps, use sharepointdocument. This applies to both the standard OOB Documents tab and a custom model-driven app tab with a document subgrid.
For Power Pages, use Document Locations. Configure the form or multistep form with a Document Locations subgrid, use the Active Document Locations view, and set up the required table permissions.
Do not use the model-driven sharepointdocument grid as the Power Pages document-management pattern. It is correct for model-driven apps, but Power Pages expects the Document Locations configuration.
No comments:
Post a Comment