Modus "Keine Prüfung"

Der Modus "Keine Prüfung" (SKIP_VERIFY) dient ausschließlich dazu, die Konfiguration im Kontext des Wertauflösers zu unterstützen:

• Das als Eingabewert vorliegende Objekt wird ungeprüft und unverändert als Rückgabewert bereitgestellt.

• Das als Client-Objektstruktur ausgewählte oder ad hoc definierte Datenmodell wird für diesen Rückgabewert deklariert, sodass in dessen Kontext z. B. in einem Objekt-Feld-Wertauflöser die entsprechenden Felder per Dropdown auswählbar sind.

• Da keine Prüfung stattfinden, sind auch keine Prüfungsergebnisse zu erwarten. Der Parameter Feststellungen wird für diesen Modus deshalb ausgeblendet.
  ►HINWEIS◄ Wenn keine Prüfung stattfindet ist auch die Option Optional unerheblich, die jedem anderen Modus eine Feststellung erzeugen würde, wenn "Kein Wert" ($null) als Eingabewert vorliegt.

Beispiel:

Modus "Nur Prüfung"

Der Modus "Nur Prüfung" (VERIFY_ONLY) validiert den Eingabewert gegen die definierte Client-Objektstruktur und protokolliert die Feststellungen, sofern die Wert-Konfiguration auf ein geeignetes Ziel verweist.

Die Unterstützung für den Kontext der Konfiguration (s. Modus "Keine Prüfung") ist ebenfalls gewährleistet.

Die Validierung prüft folgende Aspekte:

1. Wie "Kein Wert" ($null) als Eingabewert bewertet wird, entscheidet die Option Optional:
   

   • Ist die Option Optional abgewählt (Standard), dann ergibt "Kein Wert" ($null) als Eingabewert folgende Feststellung:

     • MISSING in [body]: missing mandatory value

       • Die Referenz body verweist auf den Eingabewert als Ganzes, der - weil nicht "optional" - als "fehlend" beanstandet wird (→Feststellungstyp MISSING).

       • Weitere Prüfungen entfallen.
         
         

   • Ist die Option Optional ausgewählt, dann wird der Eingabewert als "optional" behandelt. Das Fehlen des Eingabewerts erzeugt dann keine Feststellung.

     • • Weitere Prüfungen entfallen.
         
         

2. Handelt es sich beim Eingabewert nicht um ein anonymes Objekt - also um einen simplen Wert oder ein Datenobjekt das eine Instanz einer konkreten Klasse ist - dann lautet die einzige Feststellung immer so:

   • • WRONG_TYPE in [body]: value is not an anonymous object

       • Die Referenz body verweist auf den Eingabewert als Ganzes, dessen Typ ungeeignet ist (→Feststellungstyp WRONG_TYPE).

       • Liegt dieser Fall vor, dann werden keine weiteren Prüfungen durchgeführt.

3. Handelt es sich beim Eingabewert um ein anonymes Objekt, dann werden dessen Felder wie folgt ausgewertet:

   • Enthält der Eingabewert ein unerwartetes Feld, das in der Client-Objektstruktur nicht enthalten ist, dann wird für dieses Feld folgende Feststellung erzeugt:

     • UNEXPECTED_CONTENT in [body, statusCode]: unexpected property found
       

       • Die Feststellung verweist hier auf ein unmittelbares Feld statusCode des Objekts im Eingabewerts, das als unerwarteter Inhalt (→ Feststellungstyp UNEXPECTED_CONTENT) beanstandet wird, weil es in der Client-Objektstruktur fehlt.
         ►HINWEIS◄ Der Feststellungstyp UNEXPECTED_CONTENT tritt häufig dann auf, wenn ein Tippfehler in einem Feldnamen vorliegt, wofür bereits ein Fehler in der Groß-/Kleinschreibung ausreicht.
         
         

   • Fehlen im Eingabewert Daten für ein Feld, das die Client-Objektstruktur als Pflichtfeld (nicht "Optional") deklariert, wird eine Feststellung wie die folgende erzeugt:

     • MISSING in [body, active]: missing mandatory value

       • Die Feststellung vermisst Angaben für ein unmittelbares Feld active des Objekts im Eingabewert (→ Feststellungstyp MISSING), das in der Client-Objektstruktur als nicht-optional definiert ist.
         ►WICHTIG◄ Mit einer expliziten Zuweisung von $null als Wert (z. B. per JSON-Struktur { "active" : null }) gilt ein Pflichtfeld ebenfalls als MISSING.

   • Handelt es sich beim Wert für ein erwartetes Feld um einen unerwarteten Datentyp, dann wird dieser wie folgt als unpassend (→ Feststellungstyp WRONG_TYPE) beanstandet:

     • WRONG_TYPE in [body, active]: the value is not of type Boolean

       • Das active-Feld in der Client-Objektstruktur ist hier offenbar als Boolean deklariert. Übergeben wurde im Test der Text "false" (in JSON: { "active" : "false" } wo { "active" : false } korrekt wäre.

     • WRONG_TYPE in [body, salutation]: the value is not of type Salutation, valid values are [COMPANY, MR, MS]
       

       • Diese Beanstandung betrifft das salutation-Feld, das die Client-Objektstruktur mit der Dynamischen Aufzählung Anrede (Salutation) verknüpft. Der Eingabewert im Test (in JSON: { "salutation" : "TBD" }) liefert einen String-Wert, der keinem Namen für einen Wert in dieser Aufzählung entspricht. Die listet hier alle zulässigen Werte (valid values) auf.
         
         

   • Beinhaltet der Eingabewert einen dem Datentyp nach geeigneten Wert für ein Feld, für das der Client-Objektstruktur Validierer vorsieht, werden diese sämtlich ausgewertet und ggf. das Nicht-Bestehen beanstandet (→ Feststellungtyp INVALID_CONTENT):

     • INVALID_CONTENT in [body, username]: >=5 characters required
       

       • Offensichtlich ist die Validierung für das username-Feld gescheitert, weil der zugewiesene Textwert nicht genügend Zeichen enthielt.

       • Die spezifische "Fehlermeldung" (>=5 characters required) ist ein optionaler Bestandteil der Validierer-Konfiguration in der Client-Objektstruktur.

     • INVALID_CONTENT in [body, username]: user exists

       • Hier wurde offenbar geprüft, ob der im username-Feld des Eingabewerts angegebene Text bereits zu Identifikation eines Benutzerkontos (s. Benutzer) beansprucht wird.
         ►HINWEIS◄ Falls der Eingabewert für den username weniger als 5 Zeichen umfasst und der betreffende Benutzername bereits in Verwendung ist, würden ggf. beide Feststellungen generiert.

Unabhängig davon ob/welche Feststellungen im Kontext der Validierung erzeugt wurden, wird im Modus "Nur Prüfung" der Eingabewert unverändert zurückgegeben,

Modus "Typänderungen aktualisieren"

Der Modus "Typänderungen aktualisieren" (UPDATE_CASTED_VALUES) führt die für den Modus "Nur Prüfung" beschriebene Validierung aus und protokolliert die beschriebenen Feststellungen, sofern die Wert-Konfiguration auf ein geeignetes Ziel verweist.

Zusätzlich werden aber die im Kontext Prüfung implizit vorgenommene Typumwandlungen (z. B. von String-Werten zu Dynamischen Aufzählungswerten mit dem adressierten "Namen") auch explizit auf den Rückgabewert abgebildet:

Erfolgreiche Typumwandlungen werden dabei nicht über Feststellungen dokumentiert.

Beispiel:

{ "active": "true",
  "salutation": "MR", 
  "type": "DROID",
  "username": "R2D2",
}

{ "active": "true", 
  "salutation": { "class": "de.lobster.scm.denum.DynamicEnumDto", 
                  "enumName": "de.lobster.scm.base.address.Salutation", 
                  "name": "MR" },
  "type": "DROID",
  "username": "R2D2"
}

["INVALID_CONTENT in [body, username]: >=5 characters required",
"WRONG_TYPE in [body, active]: the value is not of type Boolean",
"UNEXPECTED_CONTENT in [body, type]: unexpected property found"]

►HINWEIS◄ Die Typumwandlung von einem String-Namen zu einem Dynamischen Aufzählungswert ist weit mehr als reine "Formsache". Nur nach einer erfolgreichen Umwandlung von Aufzählungswerten im Rückgabewert greift die volle Unterstützung für Dynamische Aufzählungswerte im Kontext des Client-Objekts im Rückgabewert. Sofern für die betreffende Aufzählung Konfigurationsmerkmale vorgesehen und gepflegt sind, kann auf diese im Kontext des angereicherten "Client-Objekts" im Rückgabewert zugegriffen werden.

Beispiel:

Der Eingabewert beinhaltet ein Feld origin mit der Zeichenfolge US. Die Client-Objektstruktur bezieht dieses Feld auf die Dynamische Aufzählung Land. Nach der Prüfung mit dem Modus "Typänderungen aktualisieren" unterstützt der Rückgabewert erweiterte Konfigurationsmerkmale:

{ "origin": "US",
  "active": "true",  
  "salutation": "MR", 
  "username": "R2D2",
}

{ "origin": { "class": "de.lobster.scm.denum.DynamicEnumDto", 
              "enumName": "de.lobster.scm.localization.Country", 
              "name": "US" },
  "active": "true", 
  "salutation": { "class": "de.lobster.scm.denum.DynamicEnumDto", 
                  "enumName": "de.lobster.scm.base.address.Salutation", 
                  "name": "MR" }, 
  "username": "R2D2" }

Modus "Vereinfachen"

Der Modus "Vereinfachen" (SIMPLIFY) führt die für den Modus "Nur Prüfung" beschriebene Validierung aus und protokolliert die beschriebenen Feststellungen, sofern die Wert-Konfiguration auf ein geeignetes Ziel verweist.

Der Eingabewert wird dabei nach folgenden Regeln überarbeitet:

• Felder im Eingabewert, die in der Client-Objekstruktur nicht enthalten sind, entfallen im Rückgabewert ohne dass eine Feststellung vom Typ UNEXPECTED_CONTENT erscheint.

• Felder im Eingabewert, für die in der Prüfung ein unerwarteter Datentyp (laut Client-Objekstruktur) festgestellt wird, entfallen im Rückgabewert und es wird eine Feststellung vom Typ WRONG_TYPE erzeugt.

• Felder im Eingabewert, die eine in der Client-Objektstruktur definierte Validierung nicht bestehen, erscheinen im Rückgabewert und es wird eine Feststellung vom Typ INVALID_CONTENT erzeugt.

• Felder im Eingabewert, deren Datentyp laut Client-Objektstruktur eine Typumwandlung unterstützt, werden - soweit nötig - in den einfacheren Datentyp (z. B. String für einen Aufzählungswert) umgewandelt.

►HINWEIS◄ Der Modus "Vereinfachen" ist z. B. sinnvoll für Antworten einer Rest API (s. Rest API Definition).

Beispiel:

Im Kontext einer Ausführen mit-Ereignisaktion soll ein Block von Ereignisaktionen mit einer für diesen Zweck definierten Client-Objektstruktur ( MailAddess) ausgeführt werden, die bestimmte Merkmale für die Adressierung von Briefpost (nachfolgend als "Anschrift" bezeichnet) festlegt.

Als Eingabewert für die Ausführen mit-Ereignisaktion dient ein Client-Objekt das Formulardaten aus einem Portal abbildet, in dem neben der konventionellen Anschrift noch viele weitere Merkmale (Telefonnummern, Kundennummern, usw.) eingegeben werden können.

Für den auszuführenden Aktionsblock interessieren nur die für die Anschrift relevanten Felder, die mit Hilfe des Prüfe Client-Objektstruktur (Wertauflöser)-Wertauflösers geprüft werden sollen:

• Das temporäre Bezugsobjekt für den Aktionsblock der Ausführen mit-Ereignisaktion soll ausdrücklich nur die Felder aus dem Client-Objekt im Eingabewert wiedergeben, die für das MailAddress-Objekt definiert sind.

• Einige Felder sind Pflichtfelder (salutation, name1, street1, streetNo, countryCode, postalCode, city), für die ein Wert vorliegen muss.

• Für Felder mit Bezug zu einer Dynamischen Aufzählung (salutation, countryCode) sind nur Werte aus der betreffenden Aufzählung zulässig.

• Andere Felder sind optional (name2, name3, street2). Sie werden in das temporäre Bezugsobjekt übernommen, soweit ein Wert vorhanden ist.

Konfiguration:

Laufzeitbeispiel:

{
    "accNumber": "159486423",
    "city": "Friesenried",
    "countryCode": "DE",
    "id": "23351",
    "name1": "Karola",
    "name3": "Mustermann",
    "salutation": "MS",
    "stateCode": "BY",
    "stateProvince": "Bayern",
    "street1": "Am Leuchtturm",
    "streetNo": "32",
    "zipcode": "87654"
    ...
}

{
	"salutation": "MS",
	"name1": "Karola"
	"name2": null,
	"name3": "Mustermann",
	"street1": "Am Leuchtturm",
	"street2": null,
	"streetNo": "32",
	"countryCode": "DE",
	"city": "Friesenried"
}

{
	"class": "list",
	"data": [
		{
			"class": "de.lobster.scm.client.structure.ClientStructureFinding",
			"input": null,
			"loc": [
				"body",
				"postalCode"
			],
			"msg": "missing mandatory value",
			"type": "MISSING",
			"validValues": null
		}
	]
}

• Die einzige "Feststellung" in der findings-Variable vom Typ MISSING bezieht sich hier auf das Pflichtfeld postalCode für die Postleitzahl.

  • Die Datenstruktur im Eingabewert stellt zwar eine Postleitzahl (87654) bereit, verwendet dafür allerdings ein Feld zipcode.

  • Das zipcode-Feld erscheint genausowenig im Rückgabewert des Wertauflösers, wie alle anderen Felder des Eingabewert-Objekts, die in der MailAddress-Client-Objektstruktur nicht definiert sind.

• Die Werte für die Felder salutation und countryCode werden gegen die jeweilige Dynamische Aufzählung (Anrede, Land) geprüft.

  • Sofern sich der Textwert im Eingabewert nicht auf den Namen für einen bekannten Aufzählungswert bezieht, entfällt das betreffende Feld im Rückgabewert.

  • Stimmt der Textwert im Eingabewert mit dem Namen eines Werts in der betreffenden Aufzählung, erscheint (im Unterschied zum Modus "Typänderungen aktualisieren") trotzdem nur der Textwert im Rückgabewert.

Man könnte den Rückgabewert im Modus "Vereinfachen" als Schnittmenge zwischen den Daten aus dem Eingabewert und Client-Objektstruktur bezeichnen.

►ANMERKUNG◄ Die Feldnamen von Eingabewert und der Client-Objektstruktur MailAddress sind hier - abgesehen vom postalCode-Feld - in Anlehnung an die vordefinierte Datenstruktur für Adressen in Lobster Data Platform / Orchestration gewählt. Trotzdem scheitert der Versuch eine "Adresse"-Instanz direkt als Eingabewert für den Prüfe Client-Objektstruktur (Wertauflöser) zu verwenden, um die "Schnittmenge" mit einer benutzerdefinierten "Client-Objektstruktur" (hier: MailAddress) zu gewinnen. Dies liegt daran, dass der Entitätstyp "Adresse" (Address) eben nicht als anonymes Objekt gilt. Stattdessen lautet in diesem Fall die einzige Feststellung: WRONG_TYPE in [body]: value is not an anonymous object und der Rückgabewert ist "Kein Wert" ($null).