Zum Inhalt

Dataverse-Payloads für Power Pages aus dem Schema ableiten

Wie ich Pflichtfelder, Choices, Multi-select Choices und Lookups für einen Dataverse-Create-Payload aus EntityDefinitions ablese, bevor Power Pages Server Logic einen Lead anlegt.

Das Dataverse-Schema liefert Spaltentypen, Choice-Werte und Lookup-Namen für das Payload-Mapping. Die Schemaprüfung während der Entwicklung ist vom Power-Pages-Laufzeitpfad getrennt.

Inhalt

Ein Formular, mehrere Tabellen

Ich wollte Kontaktanfragen aus einer React-Anwendung über Power Pages Server Logic in Dataverse speichern. Je nach Geschäftsbeziehung sollte daraus ein Lead oder eine Opportunity werden. Dazu kamen Verknüpfungen zu Kontakten, Firmen, Objekten und Flächen.

Für den Payload reichten Anzeigenamen, Formularwerte und die fachliche Beschreibung nicht aus. Ich musste wissen, welchen Wert Dataverse für jede Spalte erwartet und welche Spalten ich beim Anlegen überhaupt schreiben darf. Diese Antworten stehen im Schema.

Für einen Create-Payload prüfe ich deshalb zuerst die Spaltentypen, RequiredLevel und IsValidForCreate. Bei Choices brauche ich die numerischen Optionswerte. Bei Lookups brauche ich zusätzlich die genaue Navigation Property und den Entity-Set-Namen der Zieltabelle.

Wie Server Logic als Grenze zwischen React und Dataverse arbeitet, habe ich im Beitrag über Power Pages Server Logic als Sicherheitsgrenze beschrieben. Hier geht es um den Inhalt der Anfrage, die am Ende bei Dataverse ankommt.

Schema und Daten getrennt abfragen

Ich habe die Dataverse Web API direkt im angemeldeten CRM-Browser aufgerufen. Tabellen, Spalten und Beziehungen liefert der Pfad EntityDefinitions. Das CSDL-Dokument unter $metadata hilft zusätzlich bei den Web-API-Namen. Alle Dataverse-Pfade unten sind relativ zu https://<dataverse-environment-host>/api/data/v9.2 und nutzen die Tabelle lead als Beispiel.

Datenabfragen und Schemaabfragen habe ich getrennt gehalten. Eine Abfrage auf /leads mit $select und $expand zeigt Datensätze und verknüpfte Werte. Eine Spaltendefinition bekommst du darüber nicht. Die Übersicht der Spalten kommt aus diesem Aufruf.

GET /EntityDefinitions(LogicalName='lead')/Attributes?$select=LogicalName,SchemaName,AttributeType,AttributeTypeName,RequiredLevel,IsValidForCreate

Für das Mapping waren vor allem diese Angaben relevant.

AngabeWas ich daraus ablese
LogicalNameTechnischer Spaltenname für das Mapping
AttributeTypeNameTatsächlicher Spaltentyp, auch bei Multi-select Choices
RequiredLevel.ValueDeklarierte Anforderung an einen Wert
IsValidForCreateOb sich die Spalte beim Anlegen setzen lässt
ReferencingEntityNavigationPropertyNameExakter Name für eine einzelne Lookup-Bindung
EntitySetNameRessourcenname für Datensätze der jeweiligen Tabelle

Die letzten beiden Angaben kommen aus Beziehungs- beziehungsweise Tabellendefinitionen. Sie sind keine zusätzlichen Eigenschaften der gezeigten Spaltenabfrage. Microsoft beschreibt diese getrennten Zugriffe in der Dokumentation zu Schemaabfragen mit der Web API.

Diese Abfragen sind ein Werkzeug für die Entwicklung. Im Portal läuft der Zugriff über Server Logic oder über die Power Pages Web API unter /_api mit eigenen Site Settings und Tabellenberechtigungen. Das Schema legt dabei weder die Autorisierung noch die erlaubten Formularfelder fest. Server Logic muss beides unabhängig prüfen.

Der direkte Organisations-Endpunkt gehört nicht als Ersatz für die Portal-API in das öffentliche Frontend. Auch Zugangsdaten für diesen Endpunkt gehören dort nicht hin.

Schemaabfragen im angemeldeten CRM-Browser liefern Metadaten für geprüfte Mapping-Regeln. Zur Laufzeit sendet das React-Formular seine Daten über Power Pages Server Logic an Dataverse.

Oben wird das Schema während der Entwicklung geprüft. Die daraus abgeleiteten Mapping-Regeln werden in Server Logic umgesetzt. Unten läuft die Formularanfrage über diese geprüfte Serverlogik nach Dataverse. Die englisch beschriftete Grafik zeigt keine automatische Codegenerierung.

RequiredLevel und IsValidForCreate zusammen lesen

Spalten mit der Anforderungsstufe ApplicationRequired lassen sich direkt über RequiredLevel filtern.

GET /EntityDefinitions(LogicalName='lead')/Attributes?$select=LogicalName,RequiredLevel,IsValidForCreate&$filter=RequiredLevel/Value eq Microsoft.Dynamics.CRM.AttributeRequiredLevel'ApplicationRequired'

Im untersuchten Schema waren auch abgeleitete Namensspalten als ApplicationRequired markiert. Gleichzeitig stand bei ihnen IsValidForCreate: false. Diese Spalten gehören also nicht in den Create-Payload, obwohl die Metadaten sie als Pflicht ausweisen. Ich musste beide Angaben deshalb gemeinsam prüfen.

Das deckt sich mit den Spaltendefinitionen in der Dataverse-Dokumentation. Dataverse gibt allein wegen eines fehlenden Werts in einer Spalte mit ApplicationRequired keinen Fehler zurück. Modellgesteuerte Apps erzwingen diese Stufe in ihrer Oberfläche. Serverseitig erzwingt Dataverse auf dieser Metadatenebene nur SystemRequired, und diese Stufe gibt es nur für Spalten, die das System selbst angelegt hat. Plugins und serverseitig ausgeführte Geschäftsregeln können trotzdem weitere Bedingungen setzen.

IsValidForCreate: true beschreibt die Beschreibbarkeit einer Spalte. Es sagt nicht, dass die aufrufende Identität sie schreiben darf oder dass jeder Wert gültig ist. Länge, Wertebereich und fachliche Prüfungen bleiben relevant.

Welche Mindestangaben in der konkreten Umgebung reichen, zeigt deshalb erst ein echter Create-Aufruf. Die fachlich nötigen Angaben des Formulars prüfe ich unabhängig davon, ob Dataverse einen kleineren Payload akzeptieren würde.

Illustratives Metadatenbeispiel

Die beiden Spalten veranschaulichen das Zusammenspiel der Eigenschaften. Namen und Werte sind frei gewählte Beispiele. Der Ausschnitt ist keine Originalantwort von Microsoft oder aus einer Kundenumgebung.

{
  "value": [
    {
      "LogicalName": "prefix_input",
      "RequiredLevel": { "Value": "ApplicationRequired" },
      "IsValidForCreate": true
    },
    {
      "LogicalName": "prefix_derivedname",
      "RequiredLevel": { "Value": "ApplicationRequired" },
      "IsValidForCreate": false
    }
  ]
}

Die Anforderungsstufe allein entscheidet nicht, ob eine Spalte in den Create-Payload gehört. Die Eigenschaften und den Filter beschreibt Microsoft unter Schemaabfragen nach RequiredLevel.

Choice und Multi-select Choice

Bei einer einfachen Choice schicke ich den numerischen Optionswert. Die sichtbare Beschriftung hat im Payload keinen Platz. Die Optionen einer solchen Spalte lassen sich mit einem Cast auf PicklistAttributeMetadata abfragen.

GET /EntityDefinitions(LogicalName='lead')/Attributes(LogicalName='prefix_requesttype')/Microsoft.Dynamics.CRM.PicklistAttributeMetadata?$select=LogicalName&$expand=OptionSet

Alle Namen mit prefix_ und alle Optionswerte in diesem Beitrag sind Beispiele. Ersetze sie durch die Namen und Werte aus deiner Umgebung. In OptionSet.Options stehen die numerischen Value-Werte neben ihren Labels. Die Zahl ist der übertragene Wert, das Label dient der Anzeige.

Bei der Multi-select Choice war das Schema zuerst unklar. Die Spalte für Produktgruppen erschien in der Übersicht als AttributeType: Virtual. Laut den Spaltentypen in der Dataverse-Dokumentation zeigt die ältere Eigenschaft AttributeType Multi-select Choices tatsächlich als Virtual. Den eigentlichen Typ nennt AttributeTypeName. Virtual allein reicht deshalb nicht aus, um die Spalte einzuordnen. Erst der Cast auf MultiSelectPicklistAttributeMetadata hat mir die Spalte als Mehrfachauswahl gezeigt, zusammen mit ihren Optionen.

GET /EntityDefinitions(LogicalName='lead')/Attributes(LogicalName='prefix_productgroups')/Microsoft.Dynamics.CRM.MultiSelectPicklistAttributeMetadata?$select=LogicalName&$expand=OptionSet

Im Web-API-Payload steht eine Multi-select Choice als String mit kommaseparierten Optionswerten. Auch einen einzelnen Wert habe ich als String übergeben. Das Format beschreibt Microsoft im Artikel über Multi-select Choices.

SpaltentypBeispielwert im JSONNicht als Schreibwert verwenden
Choice100000001Das sichtbare Label
Multi-select Choice"100000000,100000002"Ein JSON-Array oder die Labels
Multi-select Choice mit einer Auswahl"100000000"Eine einzelne JSON-Zahl

Das beschreibt den Dataverse-Web-API-Vertrag. Ein SDK kann dafür andere Datentypen verwenden. Eine Sammlung von Optionswerten ist außerdem etwas anderes als eine Sammlung verknüpfter Datensätze.

Aus Microsofts Multi-select-Beispiel abgeleitet

Microsoft verwendet die Beispielspalte sample_outdooractivities auf contact. Die folgende Metadatenansicht ist redaktionell zusammengestellt und auf zwei Optionen gekürzt. Sie ist keine unveränderte GET-Antwort.

{
  "LogicalName": "sample_outdooractivities",
  "OptionSet": {
    "Options": [
      {
        "Value": 1,
        "Label": {
          "LocalizedLabels": [{ "Label": "Swimming", "LanguageCode": 1033 }]
        }
      },
      {
        "Value": 9,
        "Label": {
          "LocalizedLabels": [{ "Label": "Camping", "LanguageCode": 1033 }]
        }
      }
    ]
  }
}

Für diese beiden Optionen lautet der entsprechende Schreibwert im JSON-Payload:

{
  "sample_outdooractivities": "1, 9"
}

Aufbau nach Microsofts Optionsmetadaten, Werte aus dem Multi-select-Beispiel. Diese Zahlen gehören zur Beispielspalte auf contact. Die Produktgruppen auf lead brauchen ihre eigenen Optionswerte.

Lookups brauchen die Navigation Property

Lookups schreibe ich über die Navigation Property mit @odata.bind. Der Wert ist ein Pfad aus dem Entity-Set-Namen der Zieltabelle und der GUID des Datensatzes. Spaltenname, Relationship-Schemaname und Navigation Property können voneinander abweichen. Auch die Groß- und Kleinschreibung der Navigation Property zählt.

Microsoft nennt das Raten dieses Namens in der Dokumentation zu Multi-table Lookups einen häufigen Fehler. Den exakten Namen enthält die Beziehung selbst in ReferencingEntityNavigationPropertyName.

GET /EntityDefinitions(LogicalName='lead')/ManyToOneRelationships?$select=ReferencingAttribute,ReferencedEntity,ReferencingEntityNavigationPropertyName

Ich suche die Beziehung zur gewünschten Lookup-Spalte und prüfe ReferencedEntity. Den Ressourcenpfad der Zieltabelle lese ich separat aus. Er ergibt sich nicht zuverlässig aus einem angehängten „s“.

GET /EntityDefinitions(LogicalName='contact')?$select=LogicalName,EntitySetName

Für contact ist der Entity-Set-Name contacts. Den Wert übernehme ich aus der Definition, statt diese Pluralbildung auf andere Tabellen zu übertragen.

Bei polymorphen Lookups muss zusätzlich das Ziel stimmen. Ein Customer-Lookup kann auf einen Account oder einen Contact zeigen. Die Web API hat dafür je Zieltabelle eine eigene Navigation Property, zum Beispiel customerid_account und customerid_contact. Welche Namen für die konkrete Ausgangstabelle gelten, prüfe ich weiterhin in deren Beziehungen oder im CSDL-Dokument.

Die Lookup-Beziehung liefert die Navigation Property, die Zieltabelle ihren EntitySetName. Zusammen mit einer gültigen Datensatz-GUID ergeben sie Namen und Wert der @odata.bind-Eigenschaft im Create-Payload.

Die Beziehung liefert den Namen links von @odata.bind. Die Zieltabelle liefert den Entity-Set-Namen für den Wert rechts davon. Die GUID muss einen zulässigen Datensatz dieser Tabelle bezeichnen. prefix_ContactId ist ein Platzhalter.

Schematisch sieht ein Create-Payload damit so aus. Der Ausschnitt zeigt nur die Typen und die Lookup-Bindung. Er ist kein nachgewiesener Mindest-Payload für einen Lead.

{
  "prefix_requesttype": 100000001,
  "prefix_productgroups": "100000000,100000002",
  "prefix_ContactId@odata.bind": "/contacts(<contact-guid>)"
}

Vor einem echten Aufruf müssen die Beispielnamen, Optionswerte und <contact-guid> ersetzt werden. Die Navigation Property wird exakt aus dem Schema übernommen. Ein als _..._value gelesener Lookup-Wert ersetzt beim Schreiben diese Bindung nicht.

Wo Server Logic an Grenzen stieß

Bei Leads mit mehreren verknüpften Objekten haben wir unterschiedliche Fehler gesehen. Für die N:N-Beziehung verlangte die Collection-Bindung ein Array. Der getestete Server-Logic-Aufruf scheiterte aber an der Verarbeitung dieses Arrays. Einen einzelnen String hat Dataverse für die Collection anschließend abgelehnt.

Damit ließ sich der Fehler wenigstens eingrenzen. Eine gültige OData-Struktur wird nicht zwangsläufig von jedem Server-Logic-Aufruf verarbeitet. Aus diesem Versuch leite ich keine allgemeine Aussage ab, dass Server Logic keine Arrays unterstützt. Der Befund betrifft den getesteten Aufruf.

Eine Multi-select Choice wird als kommaseparierter String geschrieben. Eine Collection-valued Navigation Property beschreibt dagegen verknüpfte Datensätze. Das sind unterschiedliche Verträge. Der String für Produktgruppen ist deshalb kein Ausweg für eine N:N-Bindung.

Wir haben außerdem separate $ref-Aufrufe und eine eigene Zwischentabelle untersucht. Mit einzelnen Lookup-Spalten könnte so eine Tabelle jede Verbindung abbilden. Die bestehende native N:N-Beziehung würde sie aber nicht befüllen. Die systemeigene Intersect-Tabelle lässt sich laut der Dokumentation zu Navigation Properties in der Web API auch nicht direkt beschreiben. Verknüpfungen laufen über die Collection-valued Navigation Properties der beteiligten Tabellen.

Einzelne Lookup-Bindungen, Collection-Bindungen und nachgelagerte $ref-Aufrufe brauchen deshalb jeweils einen eigenen Test. Ein erfolgreicher Lead-Create würde noch nicht belegen, dass danach alle gewünschten Beziehungen vorhanden sind.

Den Payload in der Zielumgebung prüfen

Für die Prüfung würde ich in einer freigegebenen Testumgebung mit den fachlich nötigen, beim Anlegen beschreibbaren Spalten beginnen. Danach lassen sich Choice, Multi-select Choice und eine einzelne Lookup-Bindung schrittweise ergänzen. So bleibt erkennbar, welche Änderung einen Fehler auslöst.

Dabei müssen zwei Ebenen getrennt geprüft werden. Der direkte Dataverse-Aufruf prüft den Datenvertrag unter der dort verwendeten Identität. Derselbe fachliche Vorgang über Power Pages Server Logic prüft zusätzlich den Portalweg, seine Serialisierung und seine Autorisierung. Ein erfolgreicher CRM-Aufruf belegt keine Berechtigung für einen Portalnutzer.

Für jeden Versuch gehören Request, tatsächlicher HTTP-Status und Antwort zusammen. Anschließend muss der gespeicherte Datensatz mit seinen Werten und Beziehungen geprüft werden. Produktive Anfragen oder echte Kontaktdaten sind dafür nicht nötig.

Gekürztes Microsoft-Dokumentationsbeispiel

Microsoft zeigt den grundlegenden Create-Aufruf mit einem Account. Request und Antwort unten stammen aus diesem Beispiel; der Request ist auf die hier relevanten Felder gekürzt. Das ist kein Lead- oder Server-Logic-Test aus meinem Projekt. Ein solcher POST legt einen Datensatz an und gehört nur in eine freigegebene Testumgebung.

POST [Organization URI]/api/data/v9.2/accounts
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
  "name": "Sample Account",
  "accountcategorycode": 1
}

Microsoft zeigt dazu diese Antwort ohne JSON-Body:

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v9.2/accounts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)

Quelle: Microsoft, Create a table row, Basic create. OData-EntityId enthält die Adresse des angelegten Datensatzes. Das Beispiel erklärt den direkten Dataverse-Vertrag und belegt weder Portalberechtigungen noch einen erfolgreichen End-to-End-Test.

Was die Metadaten leisten und was nicht

Mit den Metadaten kann ich Formularwerte nach ihrem tatsächlichen Typ in den Payload übersetzen. Beschreibbare Spalten trenne ich von abgeleiteten. Bei Lookups prüfe ich Zieltabelle und Navigation Property, statt Namen zu raten.

Fehler lassen sich so besser zuordnen. Ein falscher Optionswert, eine falsche Navigation Property, fehlende Berechtigungen und ein Serialisierungsproblem brauchen jeweils eine andere Lösung.

Ob das Speichern klappt, ob alle Verknüpfungen entstehen und ob die Geschäftsregeln greifen, zeigt das Schema nicht. Das prüfe ich weiterhin in der Zielumgebung. Einen erfolgreichen Live-Test für jeden untersuchten Weg habe ich damit noch nicht.

Ähnliche Beiträge

Was soll Ihr Portal können?

Beschreiben Sie Ihren Workflow. Wir klären gemeinsam, welcher nächste Schritt sinnvoll ist.

Workflow besprechen