pragmatic development blog RSS feed

Offline-Funktion in Model-Driven Apps: Effizienz ohne permanente Internetverbindung

Tue, 20 May 2025 00:00:00 GMT

In der heutigen digitalisierten Welt sind Unternehmen auf leistungsfähige Anwendungen angewiesen, die auch unterwegs problemlos funktionieren. Die Microsoft Power Platform ermöglicht es Nutzern durch die Offline-Funktionalität von Model-driven Apps auch ohne permanente Internet-Verbindung produktiv zu bleiben.

Warum ist die Offline-Funktion wichtig?

Cloud-Apps werden in vielen Unternehmen für tägliche Arbeitsvorgänge oder zur Datenerfassung genutzt. Ohne eine stabile Verbindung ist die Nutzung von cloudbasierten Anwendungen herausfordernd. Schlimmstenfalls müssen Daten manuell erfasst und später in das System übertragen werden, was einen vermeidbaren zusätzlichen Aufwand und verlangsamte Prozesse bedeutet.

Wie kann also Mitarbeitenden im Außendienst, in Lagerhallen oder an entfernten Standorten mit begrenztem Internetzugang die Nutzung ermöglicht werden? Die Offline-Funktion von Model-driven Apps stellt sicher, dass Nutzer weiterhin Daten erfassen, aktualisieren und bearbeiten können, ohne auf eine aktive Internetverbindung angewiesen zu sein.

Wie funktioniert die Offline-Fähigkeit in Model-driven Apps?

Microsoft Power Apps ermöglichen es, Model-driven Apps mit Offline-Funktionalität auszustatten.
Einige wesentliche Merkmale sind:

Automatische Synchronisation: Sobald die App erkennt, dass eine Internetverbindung besteht, synchronisiert sie automatisch die lokal gespeicherten Daten mit der Cloud.
Cachingsystem: Häufig genutzte Daten können zwischengespeichert werden, sodass Nutzer diese auch ohne Verbindung abrufen können.
Formulare und Datensätze offline nutzen: Nutzer können neue Datensätze anlegen und bestehende bearbeiten, während sie offline sind. Diese Änderungen werden später synchronisiert.
Benutzerfreundliche Einrichtung: Administratoren können Offline-Profile definieren, um festzulegen, welche Entitäten und Daten für die Offline-Nutzung verfügbar sein sollen.

Vorteile der Offline-Nutzung

Produktivität steigern: Mitarbeiter können ohne Unterbrechung arbeiten, selbst wenn das Internet nicht verfügbar ist.
Datenverluste vermeiden: Da Daten lokal gespeichert werden, gehen sie nicht verloren, wenn die Verbindung plötzlich abbricht.
Optimierte Performance: Durch den Zugriff auf lokal gespeicherte Daten kann die App schneller reagieren.

Beispiel aus der Praxis

Energieberater sind häufig bei Kunden vor Ort tätig, um Gebäude auf ihre Energieeffizienz zu prüfen. In vielen Fällen gibt es keinen oder nur eingeschränkten Internetzugang, was die digitale Erfassung von Daten erschwert. Mit einer offline-fähigen Model-driven App können Energieberater auch ohne Internetverbindung alle relevanten Daten direkt vor Ort erfassen und bearbeiten.

Vor dem Besuch synchronisiert der Energieberater die App mit der zentralen Datenbank. Dadurch stehen ihm bereits vorhandene Kundendaten, der Stand des Projekts oder projektbezogene Dokumente zur Verfügung. Vor Ort können vorher festgelegte Datensätze vearbeitet und bearbeitet werden, z.B.:

Eingabe von Gebäudedaten (z. B. Baujahr, Heizsystem, Materialien)
Dokumentation mit Fotos und Notizen
Stand des Projekts verfolgen

Alle eingegebenen Daten werden lokal gespeichert und automatisch synchronisiert, sobald wieder eine Internetverbindung besteht. Nach der Synchronisation stehen die Daten in der zentralen Datenbank zur Verfügung. Der Energieberater kann die Ergebnisse am PC weiterbearbeiten und Berichte erstellen.

Wie kann die Offline Funktion aktiviert werden?

Maker Portal der Power Platform öffnen
Gewünschte Umgebung wählen
Entsprechende Solution wählen
Tabellen/Entitäten offline zur Verfügung stellen
a. Jede Tabelle, die offline zur Verfügung stehen soll, muss für die Offline-Verfügbarkeit freigeschaltet werden.
b. Tabelle wählen > Eigenschaften der Tabelle öffnen > "Kann Offline geschaltet werden"

Die Model-driven App im Power Apps App Editor öffnen
"Einstellungen" öffnen

Den Reiter "Allgemein" wählen und bis zu “Kann offline verwendet werden” scrollen. Den Schalter auf "Ja" setzen und “Neues Profil mit aktuellen App-Daten” wählen.

Daraufhin öffnet sich ein Fenster. Hier können der Name des Offline-Profils eingegeben und die offline verfügbaren Tabellen hinzugefügt werden.

Wenn eine weitere Tabelle hinzugefügt werden soll, wird "+ Add Table" gewählt und es können alle für den Offline-Modus verfügbaren Tabellen ausgewählt werden. Wurde eine Tabelle ausgewählt, erscheint ein weiteres Fenster. Hier kann eine weitere Auswahl getroffen werden, beisielsweise welche Zeilen offline angezeigt werden sollen oder wie oft sich diese Tabelle bei verfügbarer Internetverbindung synchroniseren soll.

Im Anschluss speichern und schließen. Daraufhin die App speichern und veröffentlichen. Nun kann die Power Apps App offline verwendet werden.

Hilfreiche Hinweise

Es gibt zwei Möglichkeiten, wie die Offline Funktion ausgeführt werden kann. Zum einen gibt es den "Offline First Modus" und zum anderen den "Offline Classic Modus". Beim Offline First Modus sind die Daten immer gleich, unabhängig von der Internetverbindung. Außerdem gibt es keinen Schalter in dem die Benutzer zwischen Offline- und Online-Modus wechseln können. Ein Benutzer vergisst also nie, seine Änderungen mit dem Server zu synchronisieren, da die App dies automatisch tut.

Der Offline Classic Modus hingegen müssen die Nutzer manuell entscheiden, ob sie im Offline- oder Online-Modus arbeiten. Außerdem müssen Sie dort manuell die neuen Daten mit dem Server synchronisieren. Das ist sehr fehleranfällig. Unsere Empfehlung ist daher der Offline First Modus, da dieser weniger fehleranfällig ist. Um den Offline First Modus zu aktivieren sind folgende Schritte nötig:

Im Power Apps App Editor die Einstellungen öffnen.
Unter Funktionen zu "Enable Offline Classic" scrollen und dies auf "Nein" setzen

Fazit

Die Offline-Funktion in Model-driven Apps ist ein bedeutender Schritt zur Steigerung der Effizienz und Flexibilität in Unternehmen. Sie ermöglicht es Nutzern, unabhängig von ihrer Internetverbindung produktiv zu bleiben und sicherzustellen, dass alle relevanten Daten nahtlos synchronisiert werden, sobald eine Verbindung wiederhergestellt ist.

Change Visibility of Attributes on Visible Sections Only

Tue, 25 Mar 2025 00:00:00 GMT

When changing the visibility of attributes in Dynamics 365 or Power Apps, you might have noticed that this change also impacts hidden sections, where the attribute is located, i.e. these sections are set to visible by default. While this of course makes sense, it might not always be what you intended, especially if you used attributes with multiple instances within a form.

For instance, as you can see in the following illustration, the visibility of sections in our order form is determined by product selection (sand or bricks). The section “Product Details” is individual for each product, though in both cases it allows the user to choose a unit (kg or m³). Upon selecting kg as “Unit (Classic)” in “Sand Details” the visibility is set for the attribute “Weight” (resp. “Volume” if you chose m³), which then appears on our form.

But – lo and behold – what is this?! The section “Bricks Details” is also suddenly visible on our form. How did this happen?

See, as “Brick Details” contains the attribute “Weight” as well the whole section is set to visible by default. Of course you could override this by using unique control names, like “weight_2” etc., and set the visibility individually for each item. While this could work for a while, it is not the safest option development-wise (think reusability and clean coding) and will definitely cause problems as soon as changes are made to the controls or if attributes are used more than once.

Let me show you a better option.

As stated, our aim is to apply attribute visibility only to controls on already visible sections. We can achieve this by checking in the event handler beforehand, whether the control we want to set to visible is located on a visible section. If the section is visible, the control will appear. Any other invisible sections, which contain controls of the same name, will remain hidden. This way, section visibility will not be implicitly affected.

Let’s have a look at the code.

static setVisibilityOfAttributeOnVisibleSectionsOnly(fCtx: Xrm.FormContext, attributeName: string, isVisible: boolean) {
    // Get the names of all controls on visible sections
    var controlNames: string[] = [];
    fCtx.ui.tabs.forEach(t => t.sections.forEach(s => {
        if (s.getVisible()) {
            s.controls.forEach(c => controlNames.push(c.getName()));
        }
    }));

    // Change the visibility for the control of the attribute.
    fCtx.getAttribute(attributeName).controls.forEach(x => {
        // But only if the current control is on a visible section
        if (controlNames.includes(x.getName())) {
            x.setVisible(isVisible);
        }
    });
}

And this is what it looks like in our app. Note that now, when you select kg as unit on “Sand Details”, the attribute “Weight” will show on this section – while our alternative section “Brick Details” will remain hidden.

In a nutshell, if you aim to avoid problems in the long run, the proposed solution is a good way to go. You can use (and reuse) attributes of the same name/type without worrying that it might impact the intended functionality. Using this function will enable you to build forms with multiple sections and still control exactly which of your data will be presented.

Let me know, if you have already encountered this matter and if this solution helped you.

Automatisches Erstellen von Listen und Dokumenten-Bibliotheken in SharePoint mit Azure Automation

Thu, 20 Feb 2025 00:00:00 GMT

Azure Automation in der Kombination mit SharePoint bietet viele Möglichkeiten, um den unternehmerischen Alltag zu erleichtern. So können z.B. Routineaufgaben automatisiert und manuelle Aufwände für das Erstellen von SharePoint-Seiten, -Listen, -Dokumenten-Bibliotheken, -Ordnern etc. enorm reduziert werden. Dies führt nicht nur zu einer höheren Effizienz, sondern auch zu einer schnelleren Bereitstellung von Diensten und Ressourcen.

Anwendungsfälle von SharePoint und Azure Automation:

Genehmigungen (Approvals): Azure Automation in der Kombination mit SharePoint kann verwendet werden, um bestimmte Prozesse mit Genehmigungen zu versehen. Bevor ein Prozess ausgelöst wird, muss eine ausgewählte Person diesen Prozess bestätigen.
Automatisches Erstellen von Berechtigungsstufen: In Azure Automation wird ein Prozess ausgelöst, um einen Ordner zu einem Projekt im SharePoint anzulegen. Durch das Azure Automation-Skript werden die exakt vorgesehenen Berechtigungen auf diesen Ordner gesetzt.
Automatisches Erstellen von SharePoint-Seiten: SharePoint-Seiten können automatisch erstellt werden, sobald ein vorher festgelegter Auslöser dafür bestimmt wurde.

Im Folgenden zeige ich dir, wie du Azure Automation einrichtest und die benötigten Module und Runbooks hinzufügst. Des weiteren sehen wir uns zwei mögliche Anwendungsfälle von SharePoint-Automatisierungen mithilfe von Azure Automation im Detail an.

Inhalt:

Einrichtung Azure Automation, Runbooks und Webhooks
Anwendungsbeispiel: Verwendung in Power Automate zur automatischen Anlage von Dokumenten-Bibliotheken

Azure Automation einrichten

Azure Automation ermöglicht eine automatisierte Erstellung von Ordnern. Zum Ausführen der notwendigen Befehle nutzt Azure Automation die PowerShell.

Erstellen eines Azure Automation Accounts: Create a standalone Azure Automation account | Microsoft Learn

Module

Damit die PowerShell Befehle ausgeführt werden können, müssen wir die benötigten Module in den Azure Automation Account laden. Diese sind unter "Shared Resources" > "Modules" zu finden. Unter der Auswahl "+Add Module" > "Browse from gallery" kann ein neues Modul gesucht und hinzugefügt werden.

Damit Dokumenten-Bibliotheken und Listen (sowie wenn nötig bestimmte Berechtigungen) erstellt werden können, müssen folgende Module in Azure Automation installiert werden:

PnP.PowerShell
ExchangeOnlineManagement

Runbooks

Innerhalb eines Azure Automation Accounts können "Runbooks" hinzugefügt werden. Dort werden die PowerShell Befehle ausgeführt (mit Managed Identity).

Managed Identity

Damit die Befehle mit den installierten Modulen durch eine Managed Identity ausgeführt werden können, müssen diese im Azure Automation Account zugeordnet werden. Dazu wird die Object ID des Azure Automation Accounts benötigt. Diese ist unter "Account Setting" > "Identity" zu finden. Der Status muss auf "On" stehen. Die Object (principal) ID ist ebenfalls dort zu finden.

Um die Module für den Azure Automation Account zu registrieren, müssen das PowerShell Terminal geöffnet und folgende Befehle ausgeführt werden:

PnP.PowerShell:

PnP.PowerShell ist für SharePoint zuständig.

Modul in PowerShell installieren
Object ID aus Azure Automation unter Identity hinzufügen
Berechtigungen auf die Managed Identity in PowerShell mit der Object ID freischalten
PnP Modul in Azure Automation hinzufügen

PowerShell Terminal:

Install-Module PnP.PowerShell
$ObjectID="<Object ID>"
Add-PnPAzureADServicePrincipalAppRole -Principal $ObjectID -AppRole "Group.Read.All" -BuiltInType MicrosoftGraph
Add-PnPAzureADServicePrincipalAppRole -Principal $ObjectID -AppRole "Sites.FullControl.All" -BuiltInType SharePointOnline

Azure Automation Runbook:

Mit folgendem Befehl verbindest du PnP im Azure Automation Runbook mit SharePoint:

Connect-PnPOnline -ManagedIdentity

Danach werden die Befehle ausgeführt, die zur Erstellung von Dokumenten-Bibliotheken, Ordnern, Listen usw. verwendet werden. Dazu im weiteren Verlauf mehr.

Weitere Informationen zu PnP:
PnP Cmdlets
PnP with Azure Automation Runbooks

ExchangeOnlineManagement:

ExchangeOnlineManagement ist unter anderem für die Erstellung von Berechtigungen, Berechtigungsstrukturen und Sicherheitsgruppen zuständig. Exchange Online ist generell für die cloudbasierte Messaging-Plattform von Microsoft verantwortlich (E-Mail und die damit einher gehenden Berechtigungsstrukturen).

Modul in PowerShell installieren
Object ID aus Azure Automation unter Identity hinzufügen
Mit MSGraph verbinden (mit Global Admin Rechten)
Parameter einfügen
Neue Berechtigungen für Exchange erstellen
Managed ID entsprechende Azure AD Rolle zuweisen (Exchange Admin)
Danach in Entra ID prüfen, ob die Rolle hinzugefügt wurde und dann in Azure Automation das Modul für Exchange hinzufügen

PowerShell Terminal:

Install-Module Microsoft.Graph
#Object ID aus Azure Automation unter Identity
$ObjectID="<Object ID>"
#Connect to MSGraph mit Global Admin Rechten
Connect-MgGraph -Scopes AppRoleAssignment.ReadWrite.All,Application.Read.All
#Parameter
$AppRoleID="dc50a0fb-09a3-484d-be87-e023b12c6440" #GUID überall gleich
$ResourceID=(Get-MgServicePrincipal -Filter "AppId eq '00000002-0000-0ff1-ce00-000000000000'").Id
#Neue Berechtigungen für Exchange
New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $ObjectID -PrincipalId $ObjectID -AppRoleId $AppRoleID -ResourceId $ResourceID
#Managed ID entsprechende Azure AD Rolle zuweisen (Exchange Admin)
Connect-MgGraph -Scopes RoleManagement.ReadWrite.Directory
$ERoleID="29232cdf-9323-42fd-ade2-1d097af3e4de" #GUID für Exchange Admin
New-MgRoleManagementDirectoryRoleAssignment -PrincipalId $ObjectID -RoleDefinitionId $ERoleID -DirectoryScopeId "/"
#Danach im Entra ID im Azure Portal prüfen, ob Role hinzugefügt wurde und dann in Azure Automation das Modul für Exchange hinzufügen

Azure Automation Runbook:

Um ExchangeOnline im Azure Automation Runbook mit dem Tenant zu verbinden, verwendest du folgenden Befehl:

Connect-ExchangeOnline -ManagedIdentity -Organization tenant.onmicrosoft.com

Webhooks:

Damit das Azure Automation Runbook automatisch getriggert wird, muss ein Webhook erstellt werden.

Ein Webhook erstellst du im Azure Portal. Wähle dort das entsprechende Runbook und dann "Add Webhook".

Der WebHook wird wie folgt im Azure Automation Runbook hinterlegt, damit das Runbook dadurch getriggert wird:

param
(
    [Parameter(Mandatory=$false)]
    [object] $WebhookData
)

Die URL wird verwendet, um von externen Applikationen aus getriggert zu werden.

Anwendungsbeispiele Power Automate Flow

Automatisches Anlegen eines Ordners bei Hinzufügen einer Person:

Hierfür erstellen wir einen Flow, der ausgeführt wird, sobald eine neue Person einem bestimmten Team in Microsoft Teams hinzugefügt wird. Dieser Flow triggert den Webhook, der das Azure Automation Runbook ausführt. In dem Runbook befindet sich der Code, der zum Beispiel auf einer SharePoint-Seite (PnP.PowerShell) einen Ordner anlegt, auf den nur diese neu hinzugefügte Person Zugriff hat (ExchangeOnline).

Weitere Informationen zu Webhooks und wie diese in Azure Automation gestartet werden: Starten eines Azure Automation-Runbooks über einen Webhook | Microsoft Learn

Automatisches Anlegen einer Dokumenten-Bibliothek in SharePoint:

In diesem Fall wird eine E-Mail versendet, in der automatisch eine Dokumenten-Bibliothek auf einer Kommunikationsseite im SharePoint einer Organisation angelegt werden soll. Dort sollen nur bestimmte Nutzer Zugriff erhalten. Durch die E-Mail wird ein Flow ausgeführt, der die Webhook (URL) triggert und somit das Azure Automation Runbook ausführt.

Azure Automation Runbook:

(Mit " #" gekennzeichnete Zeilen sind auskommentiert und dienen nur dazu das Skript besser zu verstehen.)

#Webhook Verbindung
param
(
    [Parameter(Mandatory=$false)]
    [object] $WebhookData
)

#Output des Webhooks noch einmal wiedergeben
write-output $WebhookData.WebhookName
write-output $WebhookData.RequestBody
write-output $WebhookData.RequestHeader

$BibliothekName=$WebhookData.RequestBody

#Umlaute und Leerzeichen ersetzen, da SharePoint diese in der URL nicht erkennt.
$SecName=$BibliothekName.replace(" ", "_").replace("Ä", "Ae").replace("ä", "ae").replace("Ü", "Ue").replace("ü", "ue").replace("Ö", "Oe").replace("ö", "oe")

####Exchange
#Mit Exchange Online verbinden
Connect-ExchangeOnline -ManagedIdentity -Organization tenant.onmicrosoft.com
#Erstellen einer Sicherheitsgruppe. Die auf diesen Ordner zugreifen dürfen.
New-DistributionGroup -Name "Sicherheitsgruppe1" -Type "Security" -Confirm:$false
#Sicherheitsgruppe Mitglieder hinzufügen
Add-DistributionGroupMember -Identity "Sicherheitsgruppe1" -Member "TestUser@tenant.com" -BypassSecurityGroupManagerCheck -Confirm:$false
#Verbindung zu Exchange trennen
Disconnect-ExchangeOnline -Confirm:$false

####PnP.Online
#Mit der SharePoint Site verbinden, auf dem die Dokumenten-Bibliothek angelegt werden soll
Connect-PnPOnline tenant.sharepoint.com -ManagedIdentity
#Neue Dokumenten Bibliothek erstellen mit Namen, der in der E-Mail stand
New-PnPList -Title $BibliothekName -Url $SecName -Template DocumentLibrary
#Wartezeit, damit alle wichtigen Änderungen erkannt werden (Kann auch weniger Zeit sein)
Start-Sleep -Seconds 180
#Inheritance der Ordner Brechen und Permissions setzen
Get-PnPFolder -Url "$SecName" | Set-PnPFolderPermission -List $BibliothekName -InheritPermissions
Set-PnPFolderPermission -List $BibliothekNa,e -Identity "$SecName"  -User "Sicherheitsgruppe1 -AddRole "Mitwirken" -ClearExisting

Weitere Einsatzmöglichkeiten in der SharePoint-Administration (Approvals, Site Creation mit Genehmigung):

Input/Informationen, die durch eine Canvas-App eingegeben werden
Self-Service für Mitarbeitende und Kontrolle mittels Freigaben/Genehmigungen
Erstellen von SharePoint-Seiten, -Ordnern, -Dokumenten-Bibliotheken und -Listen
Erstellen von Sicherheitsgruppen
Verwalten von Berechtigungen

Fazit

Mit Azure Automation lassen sich insbesondere administrative wiederkehrende Aufgaben mit überschaubarem Programmieraufwand automatisieren und beschleunigen. Dies bedeutet eine Minimierung manueller Aufwände und möglicher Fehlerquellen, effizientere Ressourcennutzung und schnellere Reaktionszeiten. In Verbindung mit SharePoint bietet Azure Automation eine effiziente und vielseitige Lösung zur kompletten oder teilweisen Automatisierung von IT-Prozessen in der Dokumentenverwaltung.

Automatically Open an Entity in a New Tab

Thu, 09 Jan 2025 00:00:00 GMT

Opening a record or an entity in a new tab seems pretty straightforward: Ctrl and click – and we are done, right? So why the need to write a whole blog post about it? Let me explain.

A user could solve this task perfectly fine – but what if you needed to achieve the desired outcome automatically? Imagine the following scenario: your Power App or Model-driven application uses logic to copy a record. Some attributes can directly be applied to the new entity, while others need to be manually inserted by the user. You would need the new entity to pop up for the user to complete the missing data without blocking the original record nor obscuring the navigation.

So how do we achieve this? The short answer would be: Use openURL. But let's dive deeper.

The challenge is to get the URL right. Lucky for us, the structure of Dynamics’ URLs is quite clear:

<baseUrl>?appid=<appid>&pagetype=entityrecord&etn=<logicalName>&id=<entityId>[&formid=<formId>]

Looks complicated? Don’t worry. Our task is to simply determine each single part and attach it to form the URL. Let's start.

First, we need the base URL of our current environment. This can be retrieved from the global context.

const baseUrl = Xrm.Utility.getGlobalContext().getClientUrl();

E.g.: https://mybusiness.crm16.dynamics.com/main.aspx

You might consider getting the name of the environment too. With it you can customize the URL depending on the current stage. E.g. mybusiness-dev or mybusiness-test

const environmentName = baseUrl.split("//")?.[1].split(".")?.[0];

You should be familiar with the app Id. But if you like to enhance this feature and open the entity in another app, then you might want to retrieve it from a settings file.

The entity logical name and id depend on your use case and which entity you like to open. But it shouldn’t be a problem for you to get them.

As a bonus, you could also specify the form which should be used. But this is not mandatory. In case you would like to specify it, just add &formid=<formId> to the end of the URL. Now that we have all parts, let’s put them together.

const myUrl = `${baseUrl}/main.aspx?appid=${appId}&pagetype=entityrecord&etn=${entityLogicalName}&id=${entityId}&formid=${formId}`;

Hooray. We have a nice URL. The last remaining step is to call it:

Xrm.Navigation.openUrl(myUrl);

In the end it comes down to this little function.

static openInNewTab(entityId: string, entityLogicalName: string) {
    const baseUrl = Xrm.Utility.getGlobalContext().getClientUrl();
    const caseServiceUrl = `${baseUrl}/main.aspx?appid=<your App Id>&pagetype=entityrecord&etn=${entityLogicalName}&id=${entityId}`;
    Xrm.Navigation.openUrl(caseServiceUrl);
}

I hope you find this post useful and will use this functionality in your next project or anytime you would like to open an entity in a new tab or even in another app.

File storage solutions in Model-Driven App scenarios

Sun, 10 Sep 2023 00:00:00 GMT

Whenever we design software systems, it is crucial to create and manage documents in a way that makes them accessible through the UI in a streamlined fashion - ideally without leaving the system boundaries. So, let's take a look at different file storage solutions and how they can be applied in your model-driven app scenario.

SharePoint Online Integration

Since the early Dynamics Customer Engagement times, you could store files through a model-driven app by using the built-in SharePoint integration. Meaning you can access files through the documents grid in the model-driven app in the context of a record:

... or by opening the menu Related ➡️Documents: ... as well as via SharePoint Document Library:

The SharePoint integration can bei configured for standard and custom tables and is only limited by the restrictions of the underlying SharePoint.

Integrate documents subgrid on the main form

Your users might find it too difficult or inefficient to navigate to the files tab everytime they need to view a document. In this case, try this more user-friendly approach and directly embed the documents subgrid on a main form's section as subgrid. This is not possible through the app designer but needs to be done directly by manipulating the form xml as described in the docs: Add the Documents tab to the main form for a table.

  <control id="DocumentSubGrid" classid="{E7A81278-8635-4d9e-8D4D-59480B391C5B}" indicationOfSubgrid="true" uniqueid="{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}"> 
    <parameters> 
      <ViewId>{0016F9F3-41CC-4276-9D11-04308D15858D}</ViewId> 
      <IsUserView>false</IsUserView>         
      <RelationshipName>Account_SharepointDocument</RelationshipName>
      <TargetEntityType>sharepointdocument</TargetEntityType> 
      <AutoExpand>Fixed</AutoExpand> 
      <EnableQuickFind>false</EnableQuickFind> 
      <EnableViewPicker>true</EnableViewPicker> 
      <ViewIds /> 
      <EnableJumpBar>false</EnableJumpBar> 
      <ChartGridMode>Grid</ChartGridMode> 
      <VisualizationId /> 
      <IsUserChart>false</IsUserChart> 
      <EnableChartPicker>false</EnableChartPicker> 
      <RecordsPerPage>10</RecordsPerPage> 
      <HeaderColorCode>#F3F3F3</HeaderColorCode> 
    </parameters> 
  </control>

All files will be grouped under the context of a specific Dataverse record and displayed in a list. While this tackles many document management challenges, it can definitely make things difficult if you want to be able to associate a certain document type (e.g., a contract, final quote document, etc.) on a record and want to make this information accessible through business logic. For example, allow proceeding of Business Process Flow only if a certain document is provided. Let's take a look at how to handle that situation in the next section.

Dataverse File Type Column

Dataverse has a dedicated File Datatype column that allows storage of a single file. This file is rendered as a regular control and can be placed directly on the form. As you can see from the screenshot, you could even set business required field levels as well as file size upper boundaries. File upload via the webclient is limited to 128 MB, though via the API it is possible to store up to 10 GB. You can globally restrict the permitted filetype through the system settings general tab.

Interaction server side

You can access the uploaded binary data by using a Power Automate flow with the Download a file or an image action. Alternatively, WebAPI Actions will allow you to download or upload files. Large uploads can be split into chunks to work more reliably.

Sample code for upload and download: Use file column data (Microsoft Dataverse)

The following messages are available for interacting with file type column data:

Upload

Download

For additonal information regarding the datamodel behind the file type, you can find details in the docs.

I would like to highlight that the stored files do not consume database capacity as they are using the file capacity of the Dataverse storage system.

Interaction client side

The attribute on the form can be queried just like a regular column. Executing formContext.getAttribute('new_filetypecolumn').getValue(); will present the following information about the uploaded file:

{
    "attributeName": "new_filetypecolumn",
    "fileName": "Lieferschein Nr. 2022122901.pdf",
    "fileSize": 213212,
    "fileUrl": "https://orgname.crm4.dynamics.com/api/data/v9.0/accounts(8f5b9adb-79a8-ed11-aad1-0022489c4f48)/new_filetypecolumn/$value",
    "mimeType": "application/pdf"
}

Accessing the url in fileUrl property allows downloading the file directly.

Conclusion

When designing the file storage solution for your app, consider whether information about the existence of specific documents is required, as they might be associated with events in your business logic. If so, you should prefer using a file type column since querying and accessibility are far easier.

On the other hand, if you need to store multiple files for a record or need even more advanced capabilities like SharePoint’s full text search or collaborative functionality on Microsoft Office file types, then SharePoint Document Integration is definitely the way to go.

P.S. If you found this article helpful, be sure to also learn how to Automatically create subfolders in SharePoint after record is saved in a model-driven App.

Migrate Steps and Custom Apis to new assembly with a fully automated process

Tue, 18 Jul 2023 00:00:00 GMT

If a plugin-type needs to be renamed or removed completely in a Dataverse environment it is necessary to take some additional steps to make sure that managed solution deployments that incorporate the removal/rename of a plugin-type are still successful. As manually updating all steps and APIs to the new assembly can be tedious and error-prone we'll come up with a fully automated process.

Simply removing or renaming a plugin-type causes error

Imagine you have a plugin assembly with a plugin-type called Plugins.SamplePlugin1 and Plugins.SamplePlugin2. If you decide to remove/rename plugin-type Plugins.SamplePlugin2 from the assembly and try to update the assembly content, you are presented with the error below:

Plug-in assembly does not contain the required types or assembly content cannot be updated.

The probably tempting approach is to just delete the plugin-type with Plugin Registration Tool. While this would work in an unmanaged scenario it will definitly fail once you move to the next stage in a managed solution and try the very same thing upfront in a pre-deployment task. Only the error message differs:

The evaluation of the current component(name=SdkMessageProcessingStep, id=XXX) in the current operation (Delete) failed during managed property evaluation of condition: {Managed Property Name: ismanaged}

Solution: Steps and custom-api need to reference the new assembly

So what is the solution? To correctly remove the plugin-type it is required to bump the assembly version on the first two digits (major.minor.build.revision), while third and fourth do not change assembly handling from a Dataverse standpoint.

After that you cannot do an in-place update but have to re-register that assembly as new and fresh assembly.

You end up with a new registered assembly without any steps associated. Furthermore, in case you have custom APIs defined, those will also reference the plugin-types in the original plugin assembly.

An automated solution for removing or renaming plugin-types

Before you now think about updating the plugin steps and custom apis by hand we will provide you with a programmatic approach to updating the steps and custom-apis to the plugin-types in the new assembly.

Line 4: Change the assembly name
Line 5: Change the original version number
Line 6: Change the new version number

When you run the method MigrateStepsAndApisToNewAssemblyVersion it will look for the assemblies in the given version number and update the associated plugin-types and apis to use the new assembly.

For diagnostic purposes new plugin-types as well as plugin-types that are not present in the new assembly are documented in lines 81/85.

static async Task Main(string[] args)
{
    using var serviceClient = new ServiceClient("ADD-YOUR-CONNECTIONSTRING");
    const string assemblyName = "Pragdev.Sample.Plugins";
    var firstVersion = "2.0.0.0";
    var secondVersion = "3.0.0.0";

    await MigrateStepsAndApisToNewAssemblyVersion(serviceClient, assemblyName, firstVersion, secondVersion);
}

private static async Task MigrateStepsAndApisToNewAssemblyVersion(ServiceClient serviceClient, string assemblyName, string firstVersion, string secondVersion)
{
    // Get assembly by name
    var assemblies = await serviceClient.RetrieveMultipleAsync(new QueryExpression("pluginassembly")
    {
        ColumnSet = new ColumnSet("version"),
        Criteria =
        {
            Conditions =
            {
                new ConditionExpression("name", ConditionOperator.Equal, assemblyName),
            }
        }
    });

    if (assemblies.Entities.Count == 0)
    {
        Console.WriteLine("Assembly {0} not found.", assemblyName);
    }

    var firstVersionAssembly = assemblies.Entities
        .FirstOrDefault(a => string.Equals(a.GetAttributeValue<string>("version"), firstVersion));

    if (firstVersionAssembly == null)
    {
        Console.WriteLine("Assembly {0} not found in version {1}.", assemblyName, firstVersion);
    }

    var secondVersionAssembly = assemblies.Entities
        .FirstOrDefault(a => string.Equals(a.GetAttributeValue<string>("version"), secondVersion));

    if (secondVersionAssembly == null)
    {
        Console.WriteLine("Assembly {0} not found in version {1}.", assemblyName, secondVersion);
    }

    Console.WriteLine("Searching for types in version {0}.", firstVersion);
    var typesFirst = await serviceClient.RetrieveMultipleAsync(new QueryExpression("plugintype")
    {
        ColumnSet = new ColumnSet("typename"),
        Criteria =
        {
            Conditions =
            {
                new ConditionExpression("pluginassemblyid", ConditionOperator.Equal, firstVersionAssembly.Id),
            }
        }
    });

    Console.WriteLine("Found {0} types in first assembly.", typesFirst.Entities.Count);

    Console.WriteLine("Searching for types in version {0}.", secondVersion);
    var typesSecond = await serviceClient.RetrieveMultipleAsync(new QueryExpression("plugintype")
    {
        ColumnSet = new ColumnSet("typename"),
        Criteria =
        {
            Conditions =
            {
                new ConditionExpression("pluginassemblyid", ConditionOperator.Equal, secondVersionAssembly.Id),
            }
        }
    });
    Console.WriteLine("Found {0} types in second assembly.", typesSecond.Entities.Count);


    var typeNamesInFirst = typesFirst.Entities.Select(e => e.GetAttributeValue<string>("typename")).OrderBy(x => x).ToList();
    var typeNamesInSecond = typesSecond.Entities.Select(e => e.GetAttributeValue<string>("typename")).OrderBy(x => x).ToList();

    var typesMissingInNewAssembly = typeNamesInFirst.Except(typeNamesInSecond, StringComparer.InvariantCultureIgnoreCase).ToList();
    Console.WriteLine("Types missing in new Assembly: {0}", typesMissingInNewAssembly.Any() ? string.Join(", ", typesMissingInNewAssembly) : "none");


    var typesNewlyCreatedInNewAssembly = typeNamesInSecond.Except(typeNamesInFirst, StringComparer.InvariantCultureIgnoreCase).ToList();
    Console.WriteLine("Types newly created in new Assembly: {0}", typesNewlyCreatedInNewAssembly.Any() ? string.Join(", ", typesNewlyCreatedInNewAssembly) : "none");

    foreach (var pluginType in typesSecond.Entities)
    {
        var typeName = pluginType.GetAttributeValue<string>("typename");

        if(!typeName.Contains("preserve", StringComparison.OrdinalIgnoreCase))
        {
            continue;
        }

        Console.WriteLine("Analyzing plugintype: " + typeName);

        var typeInBothAssemblies = typesFirst.Entities
            .FirstOrDefault(pt =>
                string.Equals(pt.GetAttributeValue<string>("typename"), typeName, StringComparison.OrdinalIgnoreCase));


        if (typeInBothAssemblies != null)
        {
            var stepsFirst = await serviceClient.RetrieveMultipleAsync(
                new QueryExpression("sdkmessageprocessingstep")
                {
                    ColumnSet = new ColumnSet(),
                    Criteria =
                    {
                        Conditions =
                        {
                            new ConditionExpression("plugintypeid", ConditionOperator.Equal, typeInBothAssemblies.Id),
                            new ConditionExpression("category", ConditionOperator.NotEqual, "CustomAPI"),
                        }
                    }
                });

            Console.WriteLine("Found {0} steps for {1}.", stepsFirst.Entities.Count, typeName);

            foreach (var step in stepsFirst.Entities)
            {
                step["plugintypeid"] = pluginType.ToEntityReference();
                try
                {
                    await serviceClient.UpdateAsync(step);
                }
                catch (Exception ex)
                {
                    Console.WriteLine("Error updating step {0} for type {1}", step.Id, typeName);
                    Console.WriteLine(ex.ToString());
                }
            }

            var apiFirst = await serviceClient.RetrieveMultipleAsync(
                new QueryExpression("customapi")
                {
                    ColumnSet = new ColumnSet(),
                    Criteria =
                    {
                        Conditions =
                        {
                            new ConditionExpression("plugintypeid", ConditionOperator.Equal, typeInBothAssemblies.Id),
                        }
                    }
                });

            Console.WriteLine("Found {0} apis for {1}.", apiFirst.Entities.Count, typeName);

            foreach (var api in apiFirst.Entities)
            {
                api["plugintypeid"] = pluginType.ToEntityReference();
                try
                {
                    await serviceClient.UpdateAsync(api);
                }
                catch (Exception ex)
                {
                    Console.WriteLine("Error updating api {0} for type {1}", api.Id, typeName);
                    Console.WriteLine(ex.ToString());
                }
            }
        }
        else
        {
            Console.WriteLine("Plugintype: " + typeName + " is not contained in both assemblies.");
        }
    }
}

Conclusion

In this article we have walked through the process of renaming/removing a plugin-type in a Dataverse environment and correctly deploying your changes through managed solutions to the target environment. Furthermore, we automated the recurring tasks to prevent errors and make sure that steps and custom-apis reference the new assembly. I hope this approach will help you next time you need to update a plugin-assembly in your managed solution.

Responsive Design in Canvas Apps & Custom Pages

Sun, 10 Apr 2022 00:00:00 GMT

With Custom Pages and Canvas Apps, there is a way to design custom Low Code applications from a blank page for the Power Platform. These kinds of apps require some thought to be put into achieving a responsive layout. By default, the designer puts an absolute number to most of the heights and widths. In this article, I share my key takeaways to designing responsive Canvas Apps. These of course also apply for Custom Pages that bring the possibilities of Canvas Apps into Model-driven apps.

Mobile vs bigger screens (or tablets) - and start from there

At first, it is important to understand how your app will be (mainly) used: on mobile or bigger screens (like tablets or desktops). Although the apps can have a responsive layout, it is always easier to start with the screen dimensions that most users have. So ask yourself: how will your app be used? Especially for Canvas Apps you need to decide on the basic layout when creating the app. Everything else can be configured later in the display settings.

Set the correct display settings

In the designer, you have a couple of display settings you can specify for your app.

Changing these settings can have an impact on your specified dimensions on elements or containers.

Check out the docs for more details here!

Use containers (a lot)

Using containers is key for every responsive layout. Nearly everything needs to be wrapped inside a container. There are three main types of containers that can be nested depending on your requirements.

Vertical Container - Stack elements or containers vertically
Horizontal Container - Stack elements or containers vertically
Container - Wrap certain elements

Use absolute heights for absolute heights

Whenever you want to have a fixed height at some elements or containers an absolute height needs to be specified. Otherwise, a relative layout could crash the dimensions of these containers. In the examples, the header container has a fixed height of 100 Pixels and the height of the content container is calculated.

Use flexible heights for flexible heights

For containers, you can also specify a flexible height including the portions of the available space they are taking up. In this example, we have a fixed header (100 px) and the content (90 %) and footer (10 %) container are sharing the remaining space based on their portions.

Remember to also set a minimum height so that your layout does not screw up on smaller screens. The height of the label should also be based on the Parent.Height.

This also will be applied if you have specified an absolute height for a container which can be confusing. Usually I therefore also reference the Parent.Height so that I know that a relative height has already been taken care of.

Use alignments for (child) elements

Whenever you create responsive containers make sure to specify the alignment so that the available space is filled up properly.

In the following example, the container is configured to stretch vertically and horizontally.

Use relative heights and widths everywhere

We have already looked at the heights in detail. The same applies to the widths of course. Specify absolute sizes only if necessary and use relative sizing / responsive container alignments everywhere else. A single absolute value could potentially screw up the responsive layout.

Testing your layouts

You can use the Developer Tools of all modern browsers for testing your layouts. Open the Device Emulation inside the Dev Tools. There are already some of the dimensions pre-configured but you could also specify your own. Also, you can change the screen orientation through the toolbar on the top of the emulation window.

The following screenshot shows a Canvas App with Dev tools opened. But the same applies to (embedded) Custom Pages. There you can also hide the purple navigation bar of the Maker portal by appending &hideNavbar=true onto the URL.

More to consider

Calculating the X and Y values of containers or elements (e.g. for applying left and right paddings of 10 px) and a relative width
Use the configuration of wrapping containers and their heights for relative font sizes (but maybe set a minimum width as well)
Use flyout menus on small screens

Conclusion

The editor experience provides everything you need for building responsive Power Apps. Start by choosing the general display settings and make sure that you have explicitly updated every height and every width of every container or element.

Need help with your responsive Power Apps? Feel free to send me an email!

Automatically create subfolders in SharePoint after record is saved in a model-driven App

Mon, 20 Sep 2021 00:00:00 GMT

If you need to automatically set up a SharePoint folder structure for your users in a model-driven app in real-time, it is easy to accomplish that with a few lines of code. Power Apps have a build-in integration for file storage inside of a SharePoint document library, if you enable document management on that table.

When you initially access the documents subgrid a new folder is automatically created – accompanied by a record in SharePointDocumentLocation table. This record is the glue that ties the SharePoint folder to a specific record in Dataverse. The referenced record is saved in the RegardingObjectId.

The objective

If we want to automatically create a certain folder structure for our users to initially work with, we must set up this as a prerequisite before we can create any folders, since we do not know when users will access the subgrid for the first time. The upcoming solution uses the same request pattern that the platform is using for the OOB functionality of the document’s subgrid.

A Solution

Use the JavaScript function below in an onload event to create three folders once the record is initially saved. It will only trigger the folder creation once as we determine inside the function if folder creation is necessary.

Things to know

This is client-side code. It runs in the browser so there won't be any folder creation if records get created from workflows or via Web API. If that is an objective you need to revert to Server side logic in Power Automate or try to postpone folder creation until the point when the user is accessing the documents subgrid of the record.

namespace BlogSample {
    let isCreate = false;

    /**
     * Creates folders in default location on entity creation. Upon first load isCreate will be
     * initialized to true and after save with the subsequent onload the folders will be created.
     */
    export async function createFolders(context: Xrm.Events.EventContext) {
        const fCtx = context.getFormContext();
        if (fCtx.ui.getFormType() === XrmEnum.FormType.Create) {
            isCreate = true;
            console.log("first load.")
            return;
        }

        if (isCreate) {
            console.log("Need to create folders.");

            isCreate = false;
            const entityId = fCtx.data.entity.getId();
            const entityLogicalName = fCtx.data.entity.getEntityName();
            await retrieveSPDocuments(entityId, entityLogicalName);

            const foldersToCreate = ["FolderOne", "FolderTwo", "FolderThree"]

            for (const folder of foldersToCreate) {

                await createFolder(entityId, entityLogicalName, folder);
            }
            return;
        }

        console.log("nothing to do.")
    }

    /**
     * Retrieves elements in default sharepoint location or its subdirectory.
     * @param regardingObjectid The id of the record we want query documents for.
     * @param regardingObjectName The logical name of the record we want query documents for.
     * @param relativeLocation Queries for elements in a subdirectory.
     * @returns 
     */
    async function retrieveSPDocuments(regardingObjectid: string, regardingObjectName: string, relativeLocation: string = "") {
        let relLoc = `<filter type="and">
                            <condition attribute="relativelocation" operator="eq" value="${relativeLocation}"/>
                          </filter>`;
        let query = `<fetch distinct="false" mapping="logical" returntotalrecordcount="true" no-lock="false">
                            <entity name="sharepointdocument">
                                <attribute name="documentid"/>
                                <attribute name="fullname"/>
                                <attribute name="relativelocation"/>
                                <attribute name="filetype"/>
                                <attribute name="absoluteurl"/>
                                <attribute name="title"/>
                                <attribute name="sharepointdocumentid"/>
                                <order attribute="relativelocation" descending="false"/>
                                <filter>
                                    <condition attribute="isrecursivefetch" operator="eq" value="0"/>
                                </filter>
                                ${(relativeLocation !== "") ? relLoc : ""}
                                <link-entity name="${regardingObjectName}" from="${regardingObjectName}id" to="regardingobjectid" alias="bb">
                                    <filter type="and">
                                        <condition attribute="${regardingObjectName}id" operator="eq" value="${regardingObjectid}"/>
                                    </filter>
                                </link-entity>
                            </entity>
                        </fetch>`;

        let spDocuments = await Xrm.WebApi.retrieveMultipleRecords("sharepointdocument", `?fetchXml=${encodeURIComponent(query)}`);

        return spDocuments;
    }

    /**
     * Create a folder for given entity record in default sharepoint location.
     * @param regardingObjectid The id of the record we want query documents for.
     * @param regardingObjectName The logical name of the record we want query documents for.
     * @param folderName The name of the new folder.
     * @param folderPath Create in subdirectory
     * @returns 
     */
    async function createFolder(regardingObjectid: string, regardingObjectName: string, folderName: string, folderPath: string = "") {
        console.log(`Create SP folder ${folderName} for ${regardingObjectName}: ${regardingObjectid}`);

        let spDocuments = await retrieveSPDocuments(regardingObjectid, regardingObjectName);

        const folderExists = spDocuments.entities.some((x: any) => x.fullname === folderName);

        if (folderExists) {
            console.log(`Folder '${folderName}' already exists!`);
            return spDocuments;
        }

        console.log(`Creating folder: ${folderName} in path: ${folderPath}`);

        let parentEntityRef: any = {};
        parentEntityRef["@odata.type"] = `Microsoft.Dynamics.CRM.${regardingObjectName}`;
        parentEntityRef[`${regardingObjectName}id`] = `${regardingObjectid}`;

        let folderPayload = {
            "FileName": folderName,
            "LocationId": "00000000-0000-0000-0000-000000000000",
            "ParentEntityReference": parentEntityRef,
            "IsFolder": true,
            "FolderPath": folderPath
        };

        await fetch(`${Xrm.Utility.getGlobalContext().getClientUrl()}/api/data/v${Xrm.Utility.getGlobalContext().getVersion().substring(0, 3)}/NewDocument`, {
            "headers": {
                "accept": "application/json",
                "content-type": "application/json",
                "odata-maxversion": "4.0",
                "odata-version": "4.0",
                "prefer": "odata.include-annotations=\"*\"",
                "sec-fetch-dest": "empty",
                "sec-fetch-mode": "cors",
                "sec-fetch-site": "same-origin"
            },
            "body": JSON.stringify(folderPayload),
            "method": 'POST',
            "mode": "cors",
            "credentials": "include"
        });
    }
}

Creating Word or PDF Documents in Power Platform with Power Automate Word Online connector

Sat, 07 Aug 2021 00:00:00 GMT

Today's post shows a way to create a document with data from arbitrary tables in Dataverse. The data is queried and transformed in a web resource and the document - based on a word template - is created with Power Automate's Connector for Word Online to render the final document as PDF. This allows the creation of sophisticated documents without the limitations (single table+referencing tables, poor formatting) of OOB document templates.

Generating a document in Power Platform with OOB features usually involves Document Templates or SSRS reports based on FetchXML queries. While the first one has several limitations regarding data retrieval - the latter is frankly just cumbersome to work with although it has received some updates to the report authoring extensions lately.

With Power Automate's connector for Word Online we can easily author the template in Word and fill placeholders including repeating content controls like tables or bulleted lists to make sophisticated documents without additional costs for a specific document generation engine.

The main concern one has with the OOB Word Templates in Power Apps is the fact that it is always scoped to a single entity along with its related entities. This makes it not feasible if the document has to span arbitrary tables.

Therefore we are going to fetch all data upfront in the client and pass a tailored dataset for easy consumption to Power Automate. This gives us the flexibility to do the data shaping in javascript and leave it to the Word connector to create the final document.

In our sample, we will print out teams with their roles and members as well as users with there roles and memberships.

Set Up the Word Document

As the process of template creation is thoroughly described by FlowJoe, I would advise going there for further information on how to get going with the document placeholders. The template I have set up can be downloaded here. The template uses two repeating section content controls for the users and teams tables.

The flow

When we create the flow we use a HTTP trigger that receives all data already in its desired shape. To set up the HTTP trigger use the sample JSON below

{
    "users": [
        {
            "fullname": "Test User1",
            "caltype": "Enterprise",
            "title": "Software Architect",
            "teams": "• Team1",
            "roles": "• System Administrator\n• Basic User\n• Sales, Enterprise app access"
        }
    ],
    "teams": [
        {
            "name": "Team1",
            "description": "Default team for the parent business unit. The name and membership for default team are inherited from their parent business unit.",
            "admin": "Test User1",
            "isdefault": "Yes",
            "teamtype": "Owner",
            "members": "• Test User2\n• Test User1",
            "roles": ""
        }
    ]
}

The flow uses an HTTP trigger (1) so that we can call it from a web resource.
Use the sample JSON above to generate the schema for the requests body (2).
Place the template in OneDrive and wire the documents placeholders with the array from the request body (3)/(4).
Create a temporary file in OneDrive (5) and convert it to PDF (6).
Finally, return the file PDF file (7).

Get the data

As explained before we will retrieve the data and pass it in good shape to the flow that is triggered via HTTP. This approach makes it easy to get the data via WebAPI and make the necessary transformations on the data. For example it would be easy to format dates, numbers and currencies to a desired appearance.

If you create a command bar button with the handler PowerAutomateDocCreation.CreateDocument, the users und teams are queried via WebAPI and the document is fetched for the Power Automate HTTP endpoint. Finally the file is download and offered to be downloaded.

var PowerAutomateDocCreation;
(function (PowerAutomateDocCreation) {
  PowerAutomateDocCreation.CreateDocument = async function () {
    const userDto = await getUsers();
    const teamDto = await getTeams();

    const blob = await fetchDocument(userDto, teamDto);

    offerDownload(blob);
  };

  async function getUsers() {
    const users = await Xrm.WebApi.online.retrieveMultipleRecords(
      "systemuser",
      "?$select=fullname,domainname,caltype,userlicensetype,isemailaddressapprovedbyo365admin,islicensed,title,employeeid,_businessunitid_value&$filter=accessmode eq 0&$expand=teammembership_association($select=name,teamid,systemmanaged,isdefault,teamtype),systemuserroles_association($select=name,ismanaged,roleid)"
    );

    const userDto = users.entities.map((x) => {
      return {
        fullname: x.fullname,
        caltype: x["caltype@OData.Community.Display.V1.FormattedValue"],
        title: x.title ?? "",
        isdefault: x["isdefault@OData.Community.Display.V1.FormattedValue"],
        teamtype: x["teamtype@OData.Community.Display.V1.FormattedValue"],
        teams: x.teammembership_association
          .map((y) => "• " + y.name)
          .join("\n"),
        roles: x.systemuserroles_association
          .map((y) => "• " + y.name)
          .join("\n"),
      };
    });

    return userDto;
  }

  async function getTeams() {
    const teams = await Xrm.WebApi.online.retrieveMultipleRecords(
      "team",
      "?$select=name,teamid,description,_businessunitid_value,_administratorid_value,systemmanaged,isdefault,teamtype,teamid&$expand=teammembership_association($select=fullname,domainname;$filter=accessmode eq 0),teamroles_association($select=name,ismanaged,roleid)"
    );

    const teamDto = teams.entities.map((x) => {
      return {
        name: x.name,
        description: x.description ?? "",
        admin:
          x["_administratorid_value@OData.Community.Display.V1.FormattedValue"],
        isdefault: x["isdefault@OData.Community.Display.V1.FormattedValue"],
        teamtype: x["teamtype@OData.Community.Display.V1.FormattedValue"],
        members: x.teammembership_association
          .map((y) => "• " + y.fullname)
          .join("\n"),
        roles: x.teamroles_association.map((y) => "• " + y.name).join("\n"),
      };
    });

    return teamDto;
  }

  async function fetchDocument(userDto, teamDto) {
    const payload = {
      users: userDto,
      teams: teamDto,
    };

    response = await fetch(
      "https://<URL TO YOUR HTTP TRIGGER>",
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
        body: JSON.stringify(payload),
      }
    );

    const blob = await response.blob();
    return blob;
  }

  function offerDownload(blob) {
    const url = window.URL.createObjectURL(blob);
    const a = document.createElement("a");
    a.href = url;
    a.download = "UserAndTeamsReport.pdf";
    document.body.appendChild(a); // we need to append the element to the dom -> otherwise it will not work in firefox
    a.click();
    a.remove();
  }
})(PowerAutomateDocCreation || (PowerAutomateDocCreation = {}));

Power Platform Application Insights Instrumentation

Fri, 02 Jul 2021 00:00:00 GMT

Model-driven apps and Microsoft Dataverse diagnostics and performance data can be monitored in an Azure Application Insights resource. This enhancement allows developers and admins to gain a deep understanding of what's going on inside the platform. Out of the box, there are form-loads, plug-ins, and platform APIs logging error and performance data.

On a high level, you can report user activity with specific forms and it will allow product owners to understand adoption blockers and drivers.

Setup Application Insights

Login to Azure Portal
Create an Application Insights resource
Activate Data Export to App Insights from Power Platform admin center

Monitoring a Model-driven app

Once you have enabled data export you can immediately start to see monitoring events in your Application Insights resource.

Add instrumentation code to your custom plugins

Knowing about timings in platform-level functionality is handy, but this feature really shines if you can extend it to your own plugins. While there has always been a way of utilizing the ITracingService for Plug-in Trace Logs there is now an additional ILogger service that can be obtained from the service provider.

var logger = (ILogger)serviceProvider.GetService(typeof(ILogger));
logger.LogInformation("log something useful");

The sample plugin below retrieves the share price from marketstack once a tickersymbol is set on an account and updates the stackexchange accordingly.

If we create an update on the account we can capture the Request Id from the response headers collection inside F12 developer tools network tab.

This Request Id (req_id) can be used to trace down the request along with the dependency graph of sub-components e.g. the HTTP Call to the marketstack API by searching for it under transaction search.

When we identified the transaction we see all operations that happened inside that transaction including other plugins as well as connections to external dependencies like in this case the financial data service.

Wrapping up

Capture telemetry over time for analysis and debugging.
Easily query events with Kusto Query Language (KQL).
Analyze if issue was caused by custom code or platform code.
Alerts based off performance thresholds for form-loads, APIs, and plug-ins

Sample Plugin to receive stock market prices for an account

public class GetStockExchangePlugin : IPlugin
{
    // Get an API Key from https://marketstack.com/
    private const string ApiKey = "<ENTER YOUR OWN API KEY>";

    public void Execute(IServiceProvider serviceProvider)
    {
        var context = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));
        var logger = (ILogger)serviceProvider.GetService(typeof(ILogger));

        Entity target;

        if (!context.InputParameters.TryGetValue("Target", out var targetParameter))
        {
            throw new InvalidPluginExecutionException("Target not present.");
        }
        else
        {
            target = (Entity)targetParameter;
        }
        var tickersymbol = target.GetAttributeValue<string>("tickersymbol");

        if (!string.IsNullOrWhiteSpace(tickersymbol))
        {
            var stock = GetStockData(logger, tickersymbol);
            var symbol = stock?.data?.FirstOrDefault();
            if (symbol != null)
            {
                target["stockexchange"] = $"{symbol.close:c} @{symbol.date:d}";
            }
        }
    }

    private static Rootobject GetStockData(ILogger logger, string symbol)
    {
        using (logger.BeginScope("FetchStockData"))
        {
            logger.LogInformation("Outbound call to marketstack started.");

            using (HttpClient client = new HttpClient())
            {
                client.Timeout = TimeSpan.FromMilliseconds(15000);
                client.DefaultRequestHeaders.ConnectionClose = true;

                logger.LogInformation("Getting Stock data for: {0}", symbol);

                var response = client
                .GetAsync($"http://api.marketstack.com/v1/eod?access_key={ApiKey}&symbols={symbol}&date_to={DateTime.UtcNow:yyyy-MM-dd)}&limit=1")
                .ConfigureAwait(false)
                .GetAwaiter()
                .GetResult();

                if ((int)response.StatusCode == 422)
                {
                    logger.LogError("'{0}' not found.", symbol);
                    return null;
                }

                response.EnsureSuccessStatusCode();

                var responseStream = response.Content
                    .ReadAsStreamAsync()
                    .ConfigureAwait(false)
                    .GetAwaiter()
                    .GetResult();
                return ParseResponse(logger, responseStream);
            }
        }
    }

    private static Rootobject ParseResponse(ILogger logger, Stream responseStream)
    {
        using (responseStream)
        using (logger.BeginScope("Parsing Response"))
        {
            var rootobject = (Rootobject)new DataContractJsonSerializer(typeof(Rootobject), new DataContractJsonSerializerSettings
            {
                DateTimeFormat = new DateTimeFormat("yyyy-MM-ddTHH:mm:ss+0000")
            }).ReadObject(responseStream);
            return rootobject;
        }
    }

    [DataContract]
    public class Rootobject
    {
        [DataMember]
        public StockData[] data { get; set; }
    }

    [DataContract]
    public class StockData
    {
        [DataMember]
        public decimal close { get; set; }

        [DataMember]
        public DateTime date { get; set; }
    }
}

Calling Dataverse Custom API from JavaScript

Tue, 25 May 2021 00:00:00 GMT

If you followed along our last blog post on how to implement business logic with Dataverse Custom API, you got a solid understanding how to set up a Custom API. Each API can be configured to have multiple request parameters of different datatypes. Passing a request object to Xrm.WebApi.online.execute along with a payload of request parameters triggers the action.

Lets setup a bound action that features all of those parameters and post back to the caller to see if all of them have made it to the server side.

Calling bound API from JavaScript

The function below uses Xrm.WebApi.online.execute to trigger the API. It is important to describe the payload inside the getMetadata function.

Boolean ⇾ Edm.Boolean
Decimal ⇾ Edm.Decimal
Entity ⇾ mscrm.account
EntityCollection ⇾ Collection(mscrm.crmbaseentity)
EntityReference ⇾ mscrm.account
Float ⇾ Edm.Float
Integer ⇾ Edm.Int32
Money ⇾ Edm.Money
Picklist ⇾ Edm.Int32
String ⇾ Edm.String
StringArray ⇾ Collection(Edm.String)

async function callAction() {
  let account = {
    entityType: "account",
    id: "2a932859-0ebb-eb11-bacc-000d3a2d9f66",
  };

  let DecimalParam = 42.2;
  let BooleanParameter = "true";
  let FloatParam = 42.4;
  let MoneyParameter = 42;
  let IntegerParam = 42;
  let StringParam = "Lorem Ipsum";
  let EntityReferenceParam = account;
  let EntityParam = account;
  let EntityCollectionParam = [account, account];
  let PicklistParam = 42;
  let StringArrayParam = ["Lorem", "Ipsum"];

  function new_TestApiParameters(
    entity,
    BooleanParameter,
    DecimalParam,
    FloatParam,
    MoneyParameter,
    IntegerParam,
    StringParam,
    EntityReferenceParam,
    EntityParam,
    EntityCollectionParam,
    PicklistParam,
    StringArrayParam
  ) {
    this.entity = entity;
    this.BooleanParameter = BooleanParameter;
    this.DecimalParam = DecimalParam;
    this.FloatParam = FloatParam;
    this.MoneyParameter = MoneyParameter;
    this.IntegerParam = IntegerParam;
    this.StringParam = StringParam;
    this.EntityReferenceParam = EntityReferenceParam;
    this.EntityParam = EntityParam;
    this.EntityCollectionParam = EntityCollectionParam;
    this.PicklistParam = PicklistParam;
    this.StringArrayParam = StringArrayParam;

    this.getMetadata = function () {
      return {
        operationName: "new_TestApiParameters",
        boundParameter: "entity",
        parameterTypes: {
          entity: {
            typeName: "mscrm.account",
            structuralProperty: 5,
          },
          BooleanParameter: {
            typeName: "Edm.Boolean",
            structuralProperty: 1,
          },
          DecimalParam: {
            typeName: "Edm.Decimal",
            structuralProperty: 1,
          },
          FloatParam: {
            typeName: "Edm.Float",
            structuralProperty: 1,
          },
          MoneyParameter: {
            typeName: "Edm.Money",
            structuralProperty: 1,
          },
          IntegerParam: {
            typeName: "Edm.Int32",
            structuralProperty: 1,
          },
          StringParam: {
            typeName: "Edm.String",
            structuralProperty: 1,
          },
          EntityReferenceParam: {
            typeName: "mscrm.account",
            structuralProperty: 5,
          },
          EntityParam: {
            typeName: "mscrm.account",
            structuralProperty: 5,
          },
          EntityCollectionParam: {
            typeName: "Collection(mscrm.crmbaseentity)",
            structuralProperty: 4,
          },
          PicklistParam: {
            typeName: "Edm.Int32",
            structuralProperty: 1,
          },
          StringArrayParam: {
            typeName: "Collection(Edm.String)",
            structuralProperty: 4,
          },
        },
        operationType: 0,
      };
    };
  }

  var request = new new_TestApiParameters(
    account,
    BooleanParameter,
    DecimalParam,
    FloatParam,
    MoneyParameter,
    IntegerParam,
    StringParam,
    EntityReferenceParam,
    EntityParam,
    EntityCollectionParam,
    PicklistParam,
    StringArrayParam
  );

  let res = await Xrm.WebApi.online.execute(request);
  console.log((await res.json()).Response);
}

Console Output:

BooleanParameter: True DecimalParam: 42.2 FloatParam: 42.4 MoneyParameter: 42 IntegerParam: 42 StringParam: 'Lorem Ipsum' EntityReferenceParam: account EntityParam: 'account' EntityCollectionParam's Count: '2' PicklistParam: '42' StringArrayParam: '2'

Implementing a plugin

This plugin returns all parameters within a single string back to the caller. If it is a collection based parameter the count of elements is returned instead.

public class TestApiParametersPlugin : IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        var context = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));
        var response = "";
        if (context.InputParameters.TryGetValue("BooleanParameter", out var BooleanParameter))
        {
            response += $"{nameof(BooleanParameter)}: {BooleanParameter}\n";
        }
        if (context.InputParameters.TryGetValue("DecimalParam", out var DecimalParam))
        {
            response += $"{nameof(DecimalParam)}: {DecimalParam}\n";
        }
        if (context.InputParameters.TryGetValue("FloatParam", out var FloatParam))
        {
            response += $"{nameof(FloatParam)}: {FloatParam}\n";
        }
        if (context.InputParameters.TryGetValue("MoneyParameter", out var MoneyParameter))
        {
            response += $"{nameof(MoneyParameter)}: {((Money)MoneyParameter)?.Value}\n";
        }
        if (context.InputParameters.TryGetValue("IntegerParam", out var IntegerParam))
        {
            response += $"{nameof(IntegerParam)}: {IntegerParam}\n";
        }
        if (context.InputParameters.TryGetValue("StringParam", out var StringParam))
        {
            response += $"{nameof(StringParam)}: '{StringParam}'\n";
        }
        if (context.InputParameters.TryGetValue("EntityReferenceParam", out var EntityReferenceParam))
        {
            response += $"{nameof(EntityReferenceParam)}: {((EntityReference)EntityReferenceParam).LogicalName}\n";
        }
        if (context.InputParameters.TryGetValue("EntityParam", out var EntityParam))
        {
            response += $"{nameof(EntityParam)}: '{((Entity)EntityParam).LogicalName}'\n";
        }
        if (context.InputParameters.TryGetValue("EntityCollectionParam", out var EntityCollectionParam))
        {
            response += $"{nameof(EntityCollectionParam)}'s Count: '{((EntityCollection)EntityCollectionParam).Entities.Count}'\n";
        }
        if (context.InputParameters.TryGetValue("PicklistParam", out var PicklistParam))
        {
            response += $"{nameof(PicklistParam)}: {((OptionSetValue)PicklistParam)?.Value}\n";
        }
        if (context.InputParameters.TryGetValue("StringArrayParam", out var StringArrayParam))
        {
            response += $"{nameof(StringArrayParam)}: '{((string[])StringArrayParam).Length}'\n";
        }


        context.OutputParameters.Add("Response", response);
    }
}

Implement business logic with Dataverse Custom API

Thu, 13 May 2021 00:00:00 GMT

In march 2021 Microsoft announced that the Dataverse Custom API reaches General Availability and therefore it's about time to take a look at those new extension points for the Power Platform. The concept that allows encapsulating multiple steps of business-logic under a custom operational contract is available since Dynamics 2013 with custom process actions and significantly improved reusability across the application as consumption of those actions was available from scripts in the frontend, plugins/codeactivity on the serverside, as well as workflow steps of the workflow designer. So let's see how custom APIs can make the business-logic shine.

What are custom APIs?

The definition of Custom APIs consists of metadata about the API itself, its optional request parameters as well as response properties. This information is stored in dataverse tables and is solution aware allowing it to be easily managed in ALM scenarios.

Affected Tables

Getting started with an example

Lets dive into a sample to see how this all works out. Imagine we have have setup a table for invoices with a total amount and each of those invoices can have line items with an individual amount.

Requirements

The new API should be bound to the invoice table and accept an input collection of line items that should be added to that invoice.
Once the update of given line items succeeded, the total amount has to be updated on the invoice record and must be returned to the caller.
The Action may only be called by users having create privilege on invoices.
In case of failures the whole operation needs to be rolled back, to prevent an inconsistent state of data (e.g. only some of the line item updates succeeded).

Configuration

Lets start with the metadata describing the API's appearance. The easiest way is use the XrmToolBox plugin CustomApiManager created by David Rivard.

From the screenshot below you can see the configuration:

API Name: new_AddInvoiceLineItems
Plugin Type: BlogDemo.AddInvoiceLineItemsPlugin
Execute Privilege Name: prvCreatenew_Invoice
Request Parameter: InvoiceLineItems
Response Property: TotalAmount

Implementation

Once we setup the API its time to write the plugin code so that we can wire it up later on in the metadata.

using Microsoft.Xrm.Sdk;
using Microsoft.Xrm.Sdk.Query;
using System;
using System.Linq;
using static Microsoft.Xrm.Sdk.Query.ConditionOperator;

namespace BlogDemo
{
    public class AddInvoiceLineItemsPlugin : IPlugin
    {
        public void Execute(IServiceProvider serviceProvider)
        {
            var context = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));

            var factory = (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
            var service = factory.CreateOrganizationService(context.UserId);

            if (!(context.InputParameters.TryGetValue("Target", out var target)
                && context.InputParameters.TryGetValue("InvoiceLineItems", out var lineItems)))
            {
                throw new InvalidPluginExecutionException("Invoice or Line Items are not present.");
            }

            var invoice = target as EntityReference;
            var invoiceLineItems = lineItems as EntityCollection;

            // Retrieve all invoice item that were passed along with request parameter
            var lineitems = service.RetrieveMultiple(new QueryExpression("new_invoicelineitem")
            {
                Criteria = new FilterExpression
                {
                    Conditions =
                    {
                        new ConditionExpression("new_invoicelineitemid", In,
                            invoiceLineItems.Entities.Select(x => x.Id).ToArray())
                    }
                }
            }).Entities;

            // Set the lookup of each line item to the invoice reference
            lineitems.Select(x => new Entity("new_invoicelineitem", x.Id)
            {
                Attributes =
                {
                    ["new_invoiceid"] = invoice
                }
            }).ToList()
            .ForEach(service.Update);

            // Calculate the total amount of all line items including those that might have been previously added.
            var lineItemAmount = new Money(service.RetrieveMultiple(new QueryExpression("new_invoicelineitem")
            {
                ColumnSet = new ColumnSet("new_amount"),
                Criteria = new FilterExpression
                {
                    Conditions = {
                        new ConditionExpression("new_invoiceid", Equal, invoice.Id),
                        new ConditionExpression("new_amount", NotNull),
                    }
                }
            }).Entities
            .Sum(x => x.GetAttributeValue<Money>("new_amount").Value));

            // Uncomment this line if you want to prove that previous service calls are rolled back.
            //throw new InvalidPluginExecutionException("Are we correctly rolling back");

            // Update total amount on invoice
            service.Update(new Entity(invoice.LogicalName, invoice.Id)
            {
                ["new_totalamount"] = lineItemAmount
            });

            context.OutputParameters.Add("TotalAmount", lineItemAmount);
        }
    }
}

When the plugin dll is registered its time to update the custom api's plugin type. Remember we do not register a step for the plugin type as it is configuration option in the custom api record (see red box on screenshot above).

Testing

To test our code we use the F12 tool's console window in the browser to kickstart the action with the help of Xrm.WebApi client object model.

First we create an invoice and two line items that are not yet associated. The action is described with the constructor function AddInvoiceLineItems. You can find find more about this admittedly complex parameter configuration in the official docs.

let invoiceIndex = 1;
let invoiceItemIndex = 1;
var invoiceId = await Xrm.WebApi.createRecord("new_invoice", {
  new_name: "invoice " + invoiceIndex++,
});
let invoiceItemId1 = await Xrm.WebApi.createRecord("new_invoicelineitem", {
  new_name: "invoice" + invoiceIndex + " lineitem " + invoiceItemIndex++,
  new_amount: 100
});
let invoiceItemId2 = await Xrm.WebApi.createRecord("new_invoicelineitem", {
  new_name: "invoice" + invoiceIndex + " lineitem " + invoiceItemIndex++,
  new_amount: 100
});

function AddInvoiceLineItems(invoiceId, invoiceLineItems) {
  return {
    entity: {
      entityType: "new_invoice",
      id: invoiceId,
    },
    InvoiceLineItems: invoiceLineItems,

    getMetadata() {
      return {
        operationName: "new_AddInvoiceLineItems",
        boundParameter: "entity",
        parameterTypes: {
          entity: {
            typeName: "mscrm.new_invoice",
            structuralProperty: 5,
          },
          InvoiceLineItems: {
            typeName: "Collection(mscrm.crmbaseentity)",
            structuralProperty: 4,
          },
        },
        operationType: 0,
      };
    },
  };
};

let response = await Xrm.WebApi.online.execute(
  new AddInvoiceLineItems(invoiceId.id, [invoiceItemId1, invoiceItemId2])
);

let actionReponse = await response.json();

console.log("Total Invoice Amount is: " + actionReponse.TotalAmount);

OUTPUT: Total Invoice Amount is: 200

The Xrm.WebApi.online.execute function executes the action and sends a POST request to the Dataverse Web API.

POST: https://<environnmenturl>/api/data/v9.0/new_invoices(b0ddfe3d-7db4-eb11-8236-0022487eee10)/Microsoft.Dynamics.CRM.new_AddInvoiceLineItems
{
  "entity": {
    "@odata.type": "Microsoft.Dynamics.CRM.new_invoice",
    "new_invoiceid": "b0ddfe3d-7db4-eb11-8236-0022487eee10"
  },
  "InvoiceLineItems": [
    {
      "@odata.type": "Microsoft.Dynamics.CRM.new_invoicelineitem",
      "new_invoicelineitemid": "b1ddfe3d-7db4-eb11-8236-0022487eee10"
    },
    {
      "@odata.type": "Microsoft.Dynamics.CRM.new_invoicelineitem",
      "new_invoicelineitemid": "b2ddfe3d-7db4-eb11-8236-0022487eee10"
    }
  ]
}

As you can see it was very straight forward to implement the logic inside a plugin and call it from client-side scripts. You can find an unmanaged solution of the demo here.

Wrapping up

The new approach of Custom APIs has significant advantages:

Can be unbound (global) or bound to a table/entity
Custom API definitions are solution aware components included in a solution through a set of folders and XML documents.
Can designate that a user must have a specific privilege to call the message.
Can be marked private if they are not intended to be used by anyone else.
With Custom API the message creator simply associates their plug-in type with the Custom API to provide the main operation logic.

Access Dataverse Web API from .NET Core with Microsoft.PowerPlatform.Dataverse.Client

Tue, 11 May 2021 00:00:00 GMT

For applications targeting the full .NET framework the process of connecting to the Dataverse Web API is usually handled by the XrmTooling SDK and the use of connection strings.

For .NET Core applications their is finally (in public preview) an official SDK available providing the same feature set known from Xrm Tooling. This package is intended to work with .NET full framework 4.6.2, 4.7.2 and 4.8, .NET core 3.0, 3.1 and 5.0. Library's source code is available at Github.

In the upcoming sample we will build an application with authentication via client credentials to access the Dataverse Web API.

Application registration in Azure Directory

We assume that you did create an app registration upfront and configured Dynamics impersonation permissions with clientId and client secret. The process is fully documented in docs.microsoft.com.

Create .NET Core Console Application (with Visual Studio Code)

Next step is to create a .NET Core Console App with the required dependency on Microsoft.PowerPlatform.Dataverse.Client.

mkdir "connect-to-dataverse-webapi-with-dataverse-client"
cd "connect-to-dataverse-webapi-with-dataverse-client"
dotnet new console
dotnet add package Microsoft.PowerPlatform.Dataverse.Client
code .

Replace the code in Program.cs with the code below.

Things to note:

Connection is configured with established pattern of connection strings.
The library has async/await support.

Edit lines 13-15 by setting clientId and clientSecret.

In line 21 the Dataverse Web API is queried for 10 accounts along with their name.

using Microsoft.PowerPlatform.Dataverse.Client;
using Microsoft.Xrm.Sdk.Query;
using System;
using System.Linq;
using System.Threading.Tasks;

namespace connect_to_dataverse_webapi_with_dataverse_client
{
    class Program
    {
        static async Task Main(string[] args)
        {
            const string clientId = "<clientId>",
                         clientSecret = "<clientSecret>",
                         environment = "<yourEnvironment>.crm4";

            var connectionString = @$"Url=https://{environment}.dynamics.com;AuthType=ClientSecret;ClientId={clientId};ClientSecret={clientSecret};RequireNewInstance=true";

            using var serviceClient = new ServiceClient(connectionString);

            var accountsCollection = await serviceClient.RetrieveMultipleAsync(new QueryExpression("account")
            {
                ColumnSet = new ColumnSet("name"),
                TopCount = 10
            });

            Console.WriteLine(string.Join("\n",
                accountsCollection.Entities
                    .Select(x => $"{x.GetAttributeValue<string>("name")}, {x.Id}")));
        }
    }
}

Room for improvement

Move the auth constants to app.config (console) or local.settings.json (Azure Function) file and load the values as environment variables
Better error handling

Access Dataverse Web API from .NET Core or Azure Functions with client credentials

Sun, 09 May 2021 00:00:00 GMT

For applications targeting the full .NET framework the process of connecting to the Dataverse Web API is usually handled by the XrmTooling SDK and the use of connection strings.

For .NET Core applications the security handshake needs to be implemented with the help of the Microsoft Authentication Library (MSAL).

Update: There is finally an official SDK library targeting .NET Core. You can find a walkthrough of the setup in Accessing Dataverse Web API from .NET Core with Microsoft.PowerPlatform.Dataverse.Client.

In the upcoming sample we will build an application with authentication via client credentials to access the Dataverse Web API.

Application registration in Azure Directory

We assume that you did create an app registration upfront and configured Dynamics impersonation permissions with clientId and client secret. The process is fully documented in docs.microsoft.com.

Create .NET Core Console Application (with Visual Studio Code)

Next step is to create a .NET Core Console App with the required dependency on Microsoft Authentication Library (MSAL).

mkdir "connect-to-dataverse-webapi"
cd "connect-to-dataverse-webapi"
dotnet new console
dotnet add package Microsoft.Identity.Client --version 4.30.1
code .

Replace the code in Program.cs with the code below.

Edit lines 15-18 by setting clientId, clientSecret and tenantId.

In line 43 the Dataverse Web API is queried for 10 accounts along with their name.

using Microsoft.Identity.Client;
using System;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text.Json;
using System.Threading.Tasks;

namespace connect_to_dataverse_webapi
{
    class Program
    {
        static async Task Main(string[] args)
        {
            const string clientId = "<clientId>",
                         clientSecret = "<clientSecret>",
                         tenantId = "<tenantId>",
                         environment = "<yourEnvironment>.crm4",
                         apiVersion = "9.2";

            var scope = new[] { $"https://{environment}.dynamics.com/.default" };
            var webAPI = $"https://{environment}.dynamics.com/api/data/v{apiVersion}/";
            var authority = $"https://login.microsoftonline.com/{tenantId}";

            var clientApp = ConfidentialClientApplicationBuilder.Create(clientId)
                 .WithClientSecret(clientSecret)
                 .WithAuthority(new Uri(authority))
                 .Build();

            var authResult = await clientApp.AcquireTokenForClient(scope).ExecuteAsync();

            using var httpClient = new HttpClient
            {
                BaseAddress = new Uri(webAPI),
                Timeout = new TimeSpan(0, 0, 10)
            };

            httpClient.DefaultRequestHeaders.Add("OData-MaxVersion", "4.0");
            httpClient.DefaultRequestHeaders.Add("OData-Version", "4.0");
            httpClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
            httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", authResult.AccessToken);

            var response = await httpClient.GetAsync("accounts?$top=10&$select=name");

            var options = new JsonSerializerOptions
            {
                PropertyNameCaseInsensitive = true
            };

            if (response.IsSuccessStatusCode)
            {
                var accountsResponse = await response.Content.ReadAsStringAsync();

                var accounts = JsonSerializer.Deserialize<Response<Account>>(accountsResponse, options).Value;

                Console.WriteLine(string.Join("\n", accounts.Select(x => $"{x.Name}, {x.AccountId}")));
            }
            else
            {
                var errorResponse = await response.Content.ReadAsStringAsync();

                var error = JsonSerializer.Deserialize<ErrorResponse>(errorResponse, options);

                Console.WriteLine("HTTP: {0} ReasonPhrase: {1}\nError: {2}", (int)response.StatusCode, response.ReasonPhrase, error.Error.Message);
            }
        }
    }

    class Response<T>
    {
        public T[] Value { get; set; }
    }

    class Account
    {
        public string Name { get; set; }
        public Guid AccountId { get; set; }
    }

    class ErrorResponse
    {
        public ErrorMessage Error { get; set; }

        public class ErrorMessage
        {
            public string Message { get; set; }
        }
    }
}

Room for improvement

Reuse of bearer token and automatic renewal before its expiration. See authResult.ExpiresOn
Move the auth constants to app.config (console) or local.settings.json (Azure Function) file and load the values as environment variables
Better error handling

Prevent New... button on lookup controls in model-driven apps

Fri, 07 May 2021 00:00:00 GMT

As soon as a user has at least user create privilege on a Dataverse table a 'New ...' button is shown upon opening the lookup search dialog. This sometimes-handy feature might be a source of inconsistency for the user experience and might lead to wrong data entry as records might be created at times when only existing ones should be used, depending on your business process.

Issue

Sadly, there is no way of hiding the out of the box button from the user interface via the form editor and to remove the create privilege might not be a feasible option.

Solution

Luckily there is an option within the form XML schema that allows exactly the desired behavior. Adding the tag <IsInlineNewEnabled>false</IsInlineNewEnabled> (usually this tag is not present in formXml), will remove the button for all users no matter what their privileges allow. The provided solution is supported and works for Dynamics Customer Engagement on-premises as well as current Power Platform model-driven apps.

Procedure

Create an unmanaged solution containing only the form
Export the solution zip file and extract it to disk
Locate the lookup control based on its schema name in customizations.xml
Add IsInlineNewEnabled tag to control's parameters collection
Zip the contents of the extracted folder including your modified customizations.xml
Import the newly created solution zip file and publish all changes
Verify that the button is gone now

The parameters of your lookup instance might not match the ones shown here. Or in case you did not set any additional parameters via form editor might not even be present at all. In that case just add a parameters tag including the tag IsInlineNewEnabled.

<control id="new_contractid" classid="{270BD3DB-D9AF-4782-9025-509E298DEC0A}" datafieldname="new_contractid" uniqueid="{8dcea322-b6ee-5a9b-a429-b47dc98d75a7}">
    <parameters>
        <AutoResolve>true</AutoResolve>
        <DisableMru>false</DisableMru>
        <DisableQuickFind>false</DisableQuickFind>
        <DisableViewPicker>false</DisableViewPicker>
        <AllowFilterOff>false</AllowFilterOff>
        <IsInlineNewEnabled>false</IsInlineNewEnabled>
    </parameters>
</control>

Result

As a result, the 'New...' button is gone.

References

The lookup control schema verifies that this is a valid modification of the formXML and the customization guidelines state that Modifying the customization.xml is a valid act.

Schema in docs.microsoft.com

<!-- Parameters for the lookup control -->
<xs:choice minOccurs="1"
           maxOccurs="unbounded">
    <xs:element name="DefaultViewId"
                type="FormGuidType"
                minOccurs="0"
                maxOccurs="1" />
    <xs:element name="FilterRelationshipName"
                type="xs:string"
                minOccurs="0"
                maxOccurs="1" />
    <xs:element name="DependentAttributeName"
                type="xs:string"
                minOccurs="0"
                maxOccurs="1" />
    <xs:element name="DependentAttributeType"
                type="xs:string"
                minOccurs="0"
                maxOccurs="1" />
    <xs:element name="AutoResolve"
                type="xs:boolean"
                minOccurs="0"
                maxOccurs="1" />
    <xs:element name="ResolveEmailAddress"
                type="xs:boolean"
                minOccurs="0"
                maxOccurs="1" />
    <xs:element name="DefaultViewReadOnly"
                type="xs:boolean"
                minOccurs="0"
                maxOccurs="1" />
    <xs:element name="ViewPickerReadOnly"
                type="xs:boolean"
                minOccurs="0"
                maxOccurs="1" />
    <xs:element name="AllowFilterOff"
                type="xs:boolean"
                minOccurs="0"
                maxOccurs="1" />
    <xs:element name="DisableMru"
                type="xs:boolean"
                minOccurs="0"
                maxOccurs="1" />
    <xs:element name="DisableQuickFind"
                type="xs:boolean"
                minOccurs="0"
                maxOccurs="1" />
    <xs:element name="DisableViewPicker"
                type="xs:boolean"
                minOccurs="0"
                maxOccurs="1" />
    <xs:element name="AvailableViewIds"
                type="xs:string"
                minOccurs="0"
                maxOccurs="1" />
    <xs:element name="EntityLogicalName"
                type="xs:string"
                minOccurs="0"
                maxOccurs="1" />
    <xs:element name="IsInlineNewEnabled"
                type="xs:boolean"
                minOccurs="0"
                maxOccurs="1" />
    <xs:element name="InlineViewIds"
                type="xs:string"
                minOccurs="0"
                maxOccurs="1" />
    <xs:element name="UnboundLookupTypes"
                type="xs:string"
                minOccurs="0"
                maxOccurs="1" />
    <xs:element name="UnboundLookupBrowse"
                type="xs:boolean"
                minOccurs="0"
                maxOccurs="1" />
    <xs:element name="UnboundLookupControlType"
                type="xs:string"
                minOccurs="0"
                maxOccurs="1" />
    <xs:element name="ShowAsBreadcrumbControl"
                type="xs:boolean"
                minOccurs="0"
                maxOccurs="1" />
</xs:choice>