Skip navigation

XML-Auswahlelemente und XML Domain Mappings

/ February 19, 2019

XSD-Wahlelemente existieren, um eine Anzahl von Alternativen festzulegen, von denen immer nur eine in einer XML-Datei vorhanden sein kann. Bisher wurde der Import von Daten aus XML-Dateien, die Auswahlelemente enthielten, in der Mendix-Plattform nicht vollständig unterstützt. Mit dem Release der Version 5.14 wurde dies jetzt behoben. In diesem Artikel erklären wir, warum das so wichtig ist und wie man die neue Funktionalität nutzen kann.

1. Aktuelle Situation und Einschränkungen

Um Mendix-Anwendungen in die IT-Infrastruktur zu integrieren, können XML-Dokumente importiert und Mendix-Objekte basierend auf den im Dokument enthaltenen Informationen erstellt werden. Dafür sind zwei Dinge notwendig. Zunächst benötigt man ein XML-Schema-Dokument (XSD-Datei), das beschreibt, wie die XML-Daten aussehen dürfen, um die darin beschriebenen Objekte erkennen zu können. Zweitens ist eine Übersetzung dieser XML-Objekte in Mendix-Objekte erforderlich. Ein User der Mendix-Plattform beschreibt diese Übersetzung in einem XML-to-Domain-Mapping-Dokument, welches das Hauptthema dieses Artikels ist. In diesem Dokument muss der Nutzer konfigurieren:

  1. Welche Mendix-Objekte erstellt werden müssen.
  2. Wie diese Objekte miteinander verknüpft werden müssen.
  3. Wie die Attribute dieser Entitäten gefüllt werden müssen.

Um dem User bei der Erstellung dieses Dokuments zu helfen, gibt es eine Funktion, mit der die Mendix-Entitäten automatisch, basierend auf den definierten Elementen, im XML-Schema erstellt werden können.

Die wichtigsten Einschränkungen bei der Umsetzung der oben beschriebenen Situation wurden in Version 5.14 behoben. Diese Einschränkungen waren:

  1. Alternativen für die Auswahl wurden als separate Assoziationen für die Entität, auf die sich die Wahl bezieht, betrachtet.
  2. Die Mul¬ti¬pli¬zi¬tät auf dem Auswahlelement ging verloren (alle verschiedenen Auswahlmöglichkeiten hatten Multiplizität 1, auch wenn das XML-Schema eine Liste definiert hatte).
  3. Auswahlelemente wurden in der Abbildung nicht explizit dargestellt, was nicht transparent war.
  4. Bei der automatischen Generierung von Entitäten für das Mapping wurden vorhandene Entitäten nicht wiederverwendet.

Im weiteren Verlauf dieses Artikels erklären wir, wie die oben genannten Probleme gelöst wurden. Daher richtet sich dieser an Mendix-Entwickler, die allgemein XML-to-Domain Mappings verwenden sowie an Personen, die XML-Schema-Dokumente mit Auswahlelementen benutzen. Zunächst stellen wir ein explizites Beispiel für ein XML-Schema mit einem Auswahlelement vor, um die neue Funktionalität in Abschnitt 2 zu veranschaulichen. Anschließend beschreiben wir in Abschnitt 3 die Einschränkungen, indem wir das Beispiel in der Mendix-Plattform vor Version 5.14 zeigen. Dann veranschaulichen wir in Abschnitt 4 am gleichen Beispiel, wie dies in Version 5.14 behoben wurde. Schließlich zeigen wir in Abschnitt 5 den Wert der Änderungen, indem wir die ausführlicheren Typinformationen im neuen XML-to-Domain Mapping in einem Microflow verwenden.

2. Unser Beispiel: Personen

Wir betrachten das folgende XML-Schema:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" >
<xs:complexType name="employee">
    <xs:sequence>
      <xs:element name="firstname" type="xs:string"/>
      <xs:element name="lastname" type="xs:string"/>
      <xs:element name="salary" type="xs:int"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="customer">
    <xs:sequence>
      <xs:element name="firstname" type="xs:string"/>
      <xs:element name="lastname" type="xs:string"/>
      <xs:element name="company" type="xs:string"/>
    </xs:sequence>
  </xs:complexType>

  <xs:element name="persons">
    <xs:complexType>
      <xs:choice minOccurs="0" maxOccurs="unbounded">
        <xs:element name="employee" type="employee"/>
        <xs:element name="customer" type="customer"/>
      </xs:choice>
    </xs:complexType>
  </xs:element>
</xs:schema>

Dieses Schema definiert das Element „Personen“. Es enthält eine Liste von Auswahlelementen, die jede „Person“ widerspiegeln (minOccurs=”0” maxOccurs=”unbounded”). Jeder Eintrag in dieser Liste ist entweder ein “Mitarbeiter” oder ein „Kunde“ (aber nicht beides).

Dies ist ein Beispiel für eine gültige XML-Nachricht:

<?xml version="1.0" encoding="UTF-8"?>
<persons>
    <employee>
        <firstname>Piet </firstname>
        <lastname>Pieters</lastname>
        <salary>5</salary>
    </employee>
    <customer>
        <firstname>Customer</firstname>
        <lastname>Klant</lastname>
        <company>Company</company>
    </customer>
    <employee>
        <firstname>Other</firstname>
        <lastname>Guy</lastname>
        <salary>50</salary>
    </employee>
</persons>

Hier enthält die Personenliste drei Einträge: einen Mitarbeiter, einen Kunden und einen weiteren Mitarbeiter.

3. Personenbeispiel in der aktuellen Situation

In diesem Abschnitt zeigen wir, wie das Erstellen eines XML-to-Domain Mappings auf Basis dieses XML-Schemas in der aktuellen Situation funktioniert. Zuerst erstellen Sie ein neues XML-Schema-Dokument und wählen das XML-Schema aus, das wir in Abschnitt 2 definiert haben. Anschließend erstellen Sie ein neues XML-to-Domain Mapping, klicken auf „Select elements“ und wählen im erscheinenden Popup-Fenster das XML-Schema aus, das wir gerade als Schemaquelle erstellt haben . Dies wird in Abbildung 1 dargestellt. In dieser Abbildung sehen wir, dass das Auswahlelement im Schema-Element-Baum nicht dargestellt ist und dass daher auch seine 0-* Multiplizität fehlt.

XML-to-Domain mapping

Abbildung 1. Auswählen der XSD-Elemente, die in ein XML-to-Domain-Mapping vor Version 5.14 aufgenommen werden sollen.

Wenn wir alle Elemente auswählen und auf Ok klicken, ist die linke Seite des Mappings ausgefüllt. Wenn wir anschließend auf „Generate mappings“ klicken, werden zugehörige Entitäten, Attribute und Assoziationen erstellt (im Domain Model, siehe Abbildung 2) und auf der rechten Seite des XML-to-Domain Mappings ausgefüllt. Das Ergebnis ist in Abbildung 3 dargestellt. In dieser Abbildung sehen wir, dass auf der linken Seite die Auswahloption tatsächlich fehlt. Die Hauptfolge daraus ist, dass Personen nicht wie bei der Definition im XML-Schema-Dokument eine Zuordnung zu einer Liste haben, die sowohl mit Mitarbeitern als auch mit Kunden gefüllt ist (gemischt), sondern zwei 1:1-Verbindungen, eine zu den Mitarbeitern und eine zu den Kunden. Dies ist etwas komplett anderes und kann daher zu Datenverlust führen, wenn Listen von Kunden/Mitarbeitern importiert werden, da nur die erste tatsächlich auf ein Mendix-Objekt abgebildet wird. Dies wurde in der Version 5.14 der Mendix-Plattform behoben.

Person, Employee, Customer Relationship Microflow

Abbildung 2. Das automatisch generierte Domain Model für das Personenbeispiel vor Version 5.14.

Configuring the mapping in a XML-to-Domain Mapping

Abbildung 3. Konfiguration des Mappings in einem XML-to-Domain Mapping im Personenbeispiel vor Version 5.14

4. Konvertierung des Personenbeispiels in die neue Situation

In diesem Abschnitt zeigen wir, wie die im vorherigen Abschnitt beschriebene Situation gelöst werden kann. Dabei gehen wir von der vorherigen Situation aus, beschreiben die Schritte, die zur Konvertierung des Projekts unternommen werden müssen und reflektieren die daraus resultierenden Veränderungen. So möchten wir es den Nutzern erleichtern, ein Upgrade durchzuführen. Natürlich ist es durchaus möglich, gleich ein komplett neues Projekt in der neuen Situation zu beginnen. Führen Sie dazu einfach die gleichen Schritte wie in Abschnitt 3 beschrieben aus und erweitern Sie diese mit den in diesem Abschnitt beschriebenen zusätzlichen Schritten.

Wenn Sie das Projekt öffnen, das wir in Abschnitt 3 in Version 5.14 der Mendix-Plattform erstellt haben, sind einige manuelle Schritte erforderlich, um Ihr Projekt zu konvertieren. Im Error-Fenster erscheint die folgende Fehlermeldung: „The mapping element is an option of a choice. Please reselect schema elements and include the choice element”. Wenn Sie auf die Nachricht doppelklicken, wird das XML-to-Domain-Dokument geöffnet und das entsprechende Element ausgewählt (siehe Abbildung 4).

App Development Example

Abbildung 4. Nach der Konvertierung sind manuelle Schritte zur Konvertierung des Projekts erforderlich.

Wie in der Meldung beschrieben, müssen wir die Schema-Elemente neu auswählen, um den Konsistenzfehler zu beheben. Klicken Sie dazu auf „Select elements…“ und der in Abbildung 5 dargestellte Dialog erscheint.

App Development Example

Abbildung 5. Neuselektion der Schema-Elemente nach der Konvertierung

Im Schema-Elementbaum sehen wir, dass es nun ein explizites Element für das XML-Auswahlelement „(choice)“ gibt. Beachten Sie, dass die Multiplizität dieses Elements korrekt auf 0…* eingestellt ist. Das Auswahlelement wurde beim Öffnen dieses Fensters automatisch ausgewählt, klicken Sie also auf Ok, um die Einstellung zu speichern und mit der Konfiguration der Zuordnung fortzufahren.

Wie in Abbildung 6 zu sehen ist, wurde das Mapping-Element “(choice)” in das Import-Mapping-Dokument eingefügt. Dieses zusätzliche Mapping-Element bedeutet folgendes: Alle Alternativen für die Auswahl (in diesem Fall Mitarbeiter und Kunde) sollen etwas gemeinsam haben, da sie Alternativen zu etwas sind. In diesem Fall ist die Gemeinsamkeit zwischen ihnen, dass sie beide eine Person sind. Daher sollen in der neuen Situation alle Alternativen einer Auswahl von einer allgemeineren Entität (Person) übernommen werden und diese Entität soll auf das Mapping gezogen werden. Es ist wichtig, die Bedeutung davon wirklich zu verstehen. Für das Beispiel heißt das, dass die Personen-Entität eine Liste vom Typ Person hat und Mitarbeiter und Kunden bestimmte Arten von Personen sind, die daher in der Liste erscheinen können.

In Abbildung 6 gibt es vier Konsistenzfehler. Die ersten beiden werden durch die Auswahl einer geeigneten Generalisierungs-Entität für Mitarbeiter und Kunden gelöst. Die letzten beiden haben damit zu tun, dass in der Ausgangssituation (ohne das explizite Auswahlelement) die Auswahlalternativen selbst (Mitarbeiter und Kunde) mit Personen in der Abbildung verbunden waren. Das ist nicht mehr erlaubt, da dies im Auswahlelement konfiguriert werden sollte. Um dies zu beheben, führen Sie einen Doppelklick auf den Mitarbeiter und den Kunden aus. Es erscheint eine Meldung, in der die Zuordnung erläutert wird. Klicken Sie auf Ok, um zu bestätigen.

App Development Example

Abbildung 6. Das XML-to-Domain-Mapping-Dokument nach Auswahl des neuen (Auswahl-)Elements.

Die Behebung der ersten beiden Konsistenzfehler kann durch manuelles Anlegen einer Generalisierungsklasse für Mitarbeiter und Kunden und Auswahl dieser im Mapping-Dokument erfolgen. Alternativ können Sie dies auch über die Schaltfläche „Map automatically“ tun. Wenn Sie auf diese Schaltfläche klicken, wird die in Abbildung 7 dargestellte Meldung angezeigt, welche erklärt, was passiert ist.

App Development Example

Abbildung 7. Eine Übersicht über die Änderungen bei der automatischen Generierung der Mappings, Entitäten, Assoziationen und Attribute.

Hier sehen Sie, dass die meisten Entitäten und Assoziationen in der Abbildung von der vorherigen Situation übernommen wurden. Für das Auswahlelement wurde eine Klasse namens ChoiceBase angelegt, Mitarbeiter und Kunde sind zu Spezialisierungen dieser Klasse geworden und ChoiceBase ist der Entität Person zugeordnet. Dies ist eine große Verbesserung gegenüber der Art und Weise, wie die Funktion „Map automatically“ in früheren Versionen Entitäten, Attribute und Assoziationen erstellt hat. Denn früher wurden alle Entitäten, Attribute und Assoziationen jedes Mal neu erstellt, wenn sie ausgeführt wurden, was zu einem ständig wachsenden Domain Model mit Entitäten führte, die nicht mehr benötigt wurden.

Das resultierende Domain Model ist in Abbildung 8 dargestellt.

automatically generated domain model

Abbildung 8. Das automatisch generierte Domain Model für das Personen-Beispiel

Beachten Sie, dass wir einige Verbesserungen an diesem automatisch generierten Modell vornehmen können. Erstens ist ChoiceBase ein sehr allgemeiner Begriff und weil wir unser eigenes Domain Model tatsächlich verstehen, können wir es noch spezifischer gestalten. Wir können die Entität zum Beispiel in „Person“ umbenennen. Wenn wir das tun, ist es auch eine gute Idee, die „ChoiceBase_persons“ Assoziation umzubenennen. Anschließend können wir die Attribute „firstname“ und „lastname“ von der Mitarbeiter- und Kunden-Entität auf diese Personen-Entität verschieben, da beide Spezialisierungen diese Attribute enthalten. Schließlich können wir die Assoziationen zwischen Mitarbeiter und Personen sowie Kunden und Personen beseitigen, da sie mit der Einführung der Personen-Entität nicht mehr benötigt werden. Dies geschieht, weil sie die Assoziation mit Personen von der Person-Entität erben. Nach all diesen Änderungen wird das Domain Model wie in Abbildung 9 dargestellt aussehen.

Manual improvement of the automatically generated domain model

Abbildung 9. Manuelle Verbesserung des automatisch generierten Domain Models für das Personen-Beispiel

Nachdem wir diese Änderungen vorgenommen haben, bemerken wir vier neue Konsistenzfehler für das XML-to-Domain Mapping. Diese Konsistenzfehler liegen vor, weil wir die Attribute „Vorname“ und „Nachname“ von den Spezialisierungseinheiten (Mitarbeiter und Kunde) auf die Generalisierung (Person) verschoben haben und diese manuell neu zuordnen müssen. Gehen Sie dazu in das XML-to-Domain Mapping und doppelklicken Sie sowohl auf Kunde als auch auf Mitarbeiter und ordnen Sie die Attribute entweder manuell oder durch Anklicken der Schaltfläche „Map attributes by name“ zu. Dadurch werden alle Konsistenzfehler behoben und das XML-to-Domain-Mapping-Dokument sieht wie in Abbildung 10 dargestellt aus.

Final version of the XML-to-Domain mapping document

Abbildung 10. Endgültige Version des XML-to-Domain-Mapping-Dokuments für das Personen-Beispiel

5. Verwendung des neuen XML-to-Domain Mappings

Nachdem wir in den vorangegangenen Abschnitten erläutert haben, wie man ein XML-to-Domain Mapping für XML-Schemata mit Auswahlelementen erstellt und konfiguriert, schließen wir diesen Artikel mit einem Beispiel für die Verwendung dieses Mappings in einem Microflow. In diesem Beispiel berechnen wir die Summe der Gehälter aller Mitarbeiter in der importierten XML-Datei unter Berücksichtigung der Kunden (die kein Gehalt definiert haben).

Dazu erstellen wir den in Abbildung 11 dargestellten Microflow. Wir gehen dabei wie folgt vor: Zuerst wählen wir ein Filedocument als Eingabeparameter aus. Anschließend ziehen wir eine „Import XML document“-Aktion hinein, wählen das Filedocument als Eingabe, unser definiertes XML-to-Domain Mapping als Mapping und entscheiden, die Ausgabe in einer Personen-Variablen zu speichern. Anschließend ziehen wir eine Abrufaktion hinein, in der wir die personList über die Assoziation „Person_persons“ der Personen-Variablen abrufen. Danach erstellen wir eine Variable, um die Summe aller Gehälter zu speichern und initialisieren sie auf Null. Dann iterieren wir über alle Elemente in der personList und führen unterschiedliche Aktionen durch, je nachdem, um welchen spezifischen Subtyp von Person es sich handelt (unter Verwendung eines Vererbungssplits). Wenn die Person ein Mitarbeiter ist, verteilen wir sie auf einen Mitarbeiter und addieren ihr Gehalt zur Gesamtsumme. Wenn die Person ein Kunde ist, ignorieren wir sie. Nachdem wir über alle Positionen iteriert haben, schreiben wir die Summe aller Gehälter in das Protokoll.

Abbildung 11. Microflow zum Summieren der Gehälter aller Kunden in einer XML-Datei unter Verwendung des XML-to-Domain Mappings für das Personen-Beispiel

Danksagungen

Dieser Artikel wurde gemeinsam von Pieter van Balen und Kevin Dullemond verfasst.