Beispiel für Attribute von Vorgängen in Rohwerten:
Es ist selbstverständlich möglich, diese beiden Arten von Werten innerhalb desselben Anfrage-Körpers zu kombinieren.
Angabe der UID im Request-Body:
- Dies ist nur beim Anlegen einer Ressource oder eines Vorgangs zulässig.
- Dies ist beim Ändern einer Ressource oder eines Vorgangs nicht zulässig.
Am häufigsten wird die Software eingesetzt, wenn Sie Entitäten aus mehreren Datenquellen über eine einzige Kennung miteinander verknüpfen möchten.
Bitte beachten Sie: Es liegt in der Verantwortung des Anwenders bzw. Programmierers, die Eindeutigkeit dieser Kennungen sicherzustellen, sofern diese bei der Erstellung von Vorgängen und/oder Ressourcen angegeben werden.
POST-Anfrage-Rückgabe
Wenn die Anfrage ohne Fehler abgeschlossen wird (HTTP-Code 200), enthält die Rückgabedatenstruktur stets die UID der erstellten Ressource oder des erstellten Vorgangs (das Gleiche gilt für Verknüpfungen zwischen Vorgängen).
Beispiel: Datenstruktur der Rückgabe bei der Erstellung einer Entität mit API V2
(Beachten Sie, dass in diesem Beispiel die UID bei der Erstellung angegeben wurde).
Beispiel: Datenstruktur als Rückgabewert beim Anlegen einer Entität mit dem APIDesigner
POST-Anfrage – UPSERT-Modus (aus VP9)
Bei den Methoden zur Erstellung von Ressourcen und Vorgängen (POST) ist es möglich, Schlüssel zur Identifizierung von Entitäten (Ressourcen, Vorgänge) zu definieren und so entweder eine Erstellung oder eine Änderung vorzunehmen (dieses Prinzip leitet sich aus dem Import von Ressourcen oder Vorgängen ab).
Es gibt mehrere mögliche Fälle:
- Wenn kein Element als Schlüssel markiert ist, wird eine neue Ressource oder ein neuer Vorgang angelegt.
- Wenn ein oder mehrere Elemente als Schlüssel markiert sind,
- Sofern eine oder mehrere Ressourcen oder Vorgänge identifiziert wurden, werden diese aktualisiert.
- Wurde keine Ressource oder kein Vorgang angegeben, wird eine neue Ressource oder ein neuer Vorgang
erstellt.
Bei der Methode zur Erstellung von Vorgängen (POST) ist es möglich, übergeordnete Schlüssel zu definieren, um übergeordnete Vorgänge zu identifizieren. Die Angabe übergeordneter Schlüssel ist nur im Falle einer vertikalen Hierarchie sinnvoll und anwendbar.
Es gibt mehrere mögliche Fälle:
Wenn ein oder mehrere Elemente als übergeordneter Schlüssel markiert sind
- Wurde kein übergeordneter Vorgang identifiziert, wird die Anfrage mit einem Fehler abgebrochen (HTTP-Code 422)
interner Code 13).
- Wenn ein oder mehrere übergeordnete Vorgänge identifiziert wurden, werden untergeordnete Vorgänge angelegt oder geändert.
(sofern untergeordnete Vorgänge anhand von Schlüsseln identifiziert werden).
In der API V2 werden Schlüssel durch das Schlüsselwort „keys“ und übergeordnete Schlüssel durch das Schlüsselwort „parentKeys“ im Hauptteil der POST-Anfrage gekennzeichnet. Beispiel 1: API V2: Erstellung einer Ressource – Schlüsselkonfiguration
Beispiel 2: API V2: Erstellung eines Vorgangs – Festlegen von Schlüsseln
Beispiel 3: API V2: Erstellung eines Vorgangs – Festlegen von Schlüsseln und übergeordneten Schlüsseln
Dieser UPSERT-Modus ist auch in APIDesigner verfügbar. In diesem Fall muss die HTTP-Methode der Anfrage „POST“ lauten, und das Kontrollkästchen „UPSERT-Modus“ muss im Abschnitt „Spezifisch“ des Einstellungsfensters für API-Anfragen aktiviert sein.
Beispiel 1: APIDesigner: Anlegen einer Ressource – wichtige Einstellungen.
Anzeige der Spalte „Schlüssel?“ im Dialogfeld zur Attributauswahl
Beispiel 2: APIDesigner: Erstellung von Vorgängen – Wichtige Einstellungen
Anzeige der Spalten „Schlüssel?“ und „Übergeordneter Schlüssel?“ im Dialogfeld zur Attributauswahl
Beispiel 3: APIDesigner: Erstellung von Vorgängen – Festlegen von Schlüsseln und übergeordneten Schlüsseln
Anzeige der Spalten „Schlüssel?“ und „Übergeordneter Schlüssel?“ im Dialogfeld zur Attributauswahl
Ressourcenidentifikation
Gemeinsamer Mechanismus für Ressourcen und Vorgänge
Die Identifizierung von Ressourcen erfolgt über:
- Die UID
- Die für die Dimension definierten Identifikationsfelder (diese sollten einfach gehalten werden und
(die Verwendung dieser Art der Identifikation, wenn die Identifikationsfelder ein Feld „Resourcetype“ enthalten).
Beispiel 1: Erstellung eines Vorgangs und Identifizierung einer Ressource in der Dimension „Aufgaben“ anhand ihrer UID sowie Identifizierung einer Ressource in der Dimension „Status“ anhand ihres Identifikationsfeldes (Name).
Rubrik zur Identifizierung der Dimension „Status“
Beispiel 2: Erstellung einer Ressource und Identifizierung eines Feldes vom Typ „Kunde“ in der Dimension „Customer_RI“ anhand seiner beiden Identifikationsfelder (Ansprechpartner, Unternehmen).
Die Werte der Identifikationsfelder werden durch das Trennzeichen getrennt, das im Abschnitt „Bezeichnungen“ des Bearbeitungsfensters der Dimension „Client_RI“ definiert ist.
(Im Beispiel dient das „Bindestrich“-Zeichen (-) als Trennzeichen.)
Identifikationsfelder der Dimension „Customer_RI“
Beim Anlegen eines Vorgangs
Es müssen mindestens die obligatorischen Ressourcen für die betreffende Hierarchieebene eingegeben werden.
Beispiel für eine Hierarchie
Um dieser Hierarchie gerecht zu werden, muss bei der Erstellung eines übergeordneten Vorgangs (Ebene 1) mindestens eine Ressource aus der Dimension „Aufgaben“ und eine aus der Dimension „Status“ referenziert werden, da diese Pflichtfelder sind.
Das Hinzufügen eines Verweises auf eine Ressource in der Dimension „Kunden“ ist optional.
Beispiel für die Erstellung eines übergeordneten Vorgangs (Erstellung einer Aufgabe)
Dimensionsressourcen werden anhand der UID oder anhand von Identifikationsfeldern identifiziert (siehe § 2.3.3.1 Gemeinsamer Mechanismus für Ressourcen und Vorgänge).
