core:clear (Löschen aller Einträge einer Liste)

Datenstrukturen können "plurale Merkmale" unterschiedlicher Typen enthalten, die vereinfacht als "Liste" mit ggf. mehreren "Einträgen" beschrieben können.

Das Attribut core:clear kann innerhalb einer Importstruktur für eine Aktualisierung (UPDATE) verwendet werden, um aus solche "Listen" gezielt alle bestehenden Einträge zu entfernen, ggf. um sie anschließend mit neuen Einträgen zu bevölkern.

  • Eine Liste wird genau dann gelöscht, wenn das Attribut den Wahrheitswert true enthält.

  • Mit dem Wert false (oder einem anderen von true verschiedenen Wert) wird das Attribut ignoriert und die Einträge der Liste in der Importstruktur werden individuell verarbeitet, um Listeneinträge entweder hinzuzufügen, zu aktualisieren oder zu löschen (s. core:delete (Löschen individueller Elemente)).

WICHTIG◄ Abhängig vom Typ der Datenstruktur, die als Liste gelöscht werden soll, unterscheidet sich die Vorgehensweise in Details, wie die folgenden Beispiele verdeutlichen.

Beispiel 1: Alle Werte einer Liste löschen

Zu einem bestimmten Zeitpunkt im Lebenszyklus eines Geschäftsobjekts vom Typ "Bestellung" sollen durch einen Import sämtliche bestehenden Attribute gelöscht werden, so dass anschließend ausschließlich die in demselben Import bereitgestellten Attributwerte belegt sind. Diese sollen die Bestellung als "archiviert" kennzeichnen und eine Referenznummer benennen, über die bei Bedarf archivierte Daten beschafft werden können.

Der rechts abgebildete Import verwendet die Aktion UPDATE.

  • Im hier nur angedeuteten search-Knoten muss die betreffende Bestellung per Suche eindeutig identifiziert werden.


  • Der attributes-Knoten beinhaltet das Attribut core:clear mit dem Wert true, sodass vor den nachfolgenden Zuweisungen sämtliche Attribute entfernt werden.


  • Anschließend wird das Kennzeichenattribut ARCHIVED mit dem Wert true gesetzt und in einem Referenzattribut ARCHIVED_ORDER_NO eine Referenznummer eingetragen.

ANMERKUNG◄ Die Kopfdaten der Bestellung sowie die Positionsdaten (inkl. Attribute) bleiben unverändert erhalten.

<?xml version="1.0" encoding="UTF-8"?>
<core:Import ... action="UPDATE">
<search> ... </search>
<ord:Order>
<attributes core:clear="true">
<ord:OrderFlag>
<value flagValue="true" flagType="ARCHIVED"></value>
</ord:OrderFlag>
<ord:OrderReference>
<value referenceType="ARCHIVED_ORDER_NO" reference="10025164852"></value>
</ord:OrderReference>
</attributes>
</ord:Order>
</core:Import>

Beispiel 2: Alle Werte eines Mehrfachattributs löschen

Per Import aus einem anderen System sollen regelmäßig "Kommunikationsinformationen" in die Adressdaten für Benutzer synchronisiert werden. Soweit für dieses Mehrfachattribut (s. Plurale Attribute) bereits Angaben vorliegen, sollen die Angaben aus dem Import diese komplett ersetzen. Im folgenden Beispiel stellt das Fremdsystem nur zwei E-Mail-Adressen bereit, die über das Merkmal "Kontext" (communicationContext) klassifiziert werden, das für den automatischen Versand von Benachrichtigungen (z. B. per Wertauflöser Mailadresse Benutzer) ausgewertet wird.

WICHTIG◄ Die Werte eines Mehrfachattributs werden nicht in einem eigenen Listenelement zusammengefasst, sondern erscheinen als Gruppe von formal eigenständigen Elementen des Typs AddressCommunicationInfo in der Liste attributes, die auch alle anderen Attribute enthält. Deshalb kann das core:clear-Attribut im Import keinem übergeordneten Element für "Kommunikationsinformationen" zugeordnet werden. Stattdessen muss es (mit dem Wert true) genau einmal, nämlich im ersten importierten AddressCommunicationInfo-Element erscheinen, damit alle bestehenden Einträge entfernt und durch die im Import enthaltenen ersetzt werden.

Falls der Import keine Einträge erzeugen, sondern nur bestehende Einträge in der Liste ersatzlos löschen soll, muss der Import trotzdem einen Dummy-Eintrag wie den folgenden enthalten, der neben dem Attribut core:clear auch das Attribut core:delete mit dem Wert true verwenden muss, um zu verhindern, dass ein leerer Eintrag erzeugt wird:

<base:AddressCommunicationInfo core:clear="true" core:delete="true"></base:AddressCommunicationInfo>

Vor dem Import liegen für ein bestimmtes Benutzerkonto die rechts gezeigten Angaben zu "Kommunikationsinformationen" vor:

  • Der Import wird im Beispiel für die beiden E-Mail-Adressen Aktualisierungen bereitstellen.

  • Eine Fax-Nummer wird nicht mehr benötigt. Sie soll daher auch aus der Adresse im Benutzerkonto verschwinden.

images/download/attachments/201675201/image2020-7-22_18-6-1-version-1-modificationdate-1747128039637-api-v2.png

Der rechts abgebildete Import verwendet die Aktion UPDATE:

  • Die interne ID (id="4252") des Benutzerkontos wird in diesem Beispiel explizit adressiert. Eine Suche erübrigt sich daher.


  • Der attributes-Knoten liefert zwei Werte für das plurale Attribut "Kommunikationsinformation" (AddressCommunicationInfo), von denen nur das erste per Attribut core:clear den Wert true liefern darf.


  • Für die zweite "Kommunikationsinformation" liefert hier das Attribut core:clear explizit den Wert false. Es könnte stattdessen auch komplett entfallen.

<?xml version="1.0" encoding="UTF-8"?>
<core:Import ... action="UPDATE">
<base:User id="4252">
<address>
<attributes>
<base:AddressCommunicationInfo core:clear="true" communicationType="EMAIL" communicationContext="user">
<communicationValue>u4252@compa.ny</communicationValue>
</base:AddressCommunicationInfo>
<base:AddressCommunicationInfo core:clear="false" communicationType="EMAIL" communicationContext="manager">
<communicationValue>u2407@compa.ny</communicationValue>
</base:AddressCommunicationInfo>
</attributes>
</address>
</base:User>
</core:Import>

Nach dem Import erscheinen im Benutzerkonto (für die ID 4252) nur noch die beiden neuen E-Mail-Adressen;

  • Die E-Mail-Adresse für den Kontext user entspricht dem Stand vor dem Import, wurde aber neu geschrieben.

  • Die E-Mail-Adresse für den Kontext manager ist neu.

  • Die Fax-Nummer ist verschwunden, weil sämtliche Einträge vor der Aktualisierung entfernt wurden und der Import keine Angabe für "Fax" enthielt.

images/download/attachments/201675201/image2020-7-22_18-17-23-version-1-modificationdate-1747128039634-api-v2.png

Beispiel 3: Alle Werte eines typisierten pluralen Attributs löschen

Für ein typisiertes plurales Attribut greift grundsätzlich dieselbe Methodik wie für ein Mehrfachattribut (s. voriges Beispiel). Allerdings ist eine Angabe für den Typ des typisierten pluralen Attributs notwendig, dessen Werte gelöscht werden sollen.

Im folgenden Beispiel sollen bei einem Import alle Einträge für ein plurales Textattribut "Container Nr." (CONTAINER_NO) auf der Kopfebene einer Bestellung gelöscht werden.

Der rechts abgebildete Import verwendet die Aktion UPDATE:

  • Im hier angedeuteten search-Knoten muss die betreffende Bestellung per Suche eindeutig identifiziert werden.


  • Der attributes-Knoten enthält neben anderen hier nicht dargestellten Attributen einen OrderText-Knoten, der für die Attribute core:clear und core:delete den Wert true angibt und sich im enthaltenen value-Element auf den textType für die "Container Nr." bezieht. Daher werden alle OrderText-Einträge mit diesem Typ gelöscht.

<?xml version="1.0" encoding="UTF-8"?>
<core:Import ... action="UPDATE">
<search> ... </search>
<ord:Order>
<attributes>
...
<ord:OrderText core:clear="true" core:delete="true">
<value textType="CONTAINER_NO"></value>
</ord:OrderText>
...
</attributes>
</ord:Order>
</core:Import>