Funktionsaufrufe und Schnittstellen - addresssolutions/as-address-solutions-validator GitHub Wiki

Funktionen

In der vorliegenden Version bieten wir folgende Funktionen

Validierung Namenselemente

  • ASValidateSalutation
  • ASValidateTitle
  • ASValidateFirstname
  • ASValidateLastname

Konvertierung/Strukturierung des Namens

  • ASConvertName

Korrektur/Vorschlagsliste Postalische Anschrift

  • ASPostBoxCheck
  • ASPostBoxList

ASValidateSalutation

Die Funktion wird benutzt, um den Inhalt eines Anredefelds zu prüfen. Der Funktionsufruf lautet:

as_address_solutions_validator.ASValidateSalutation(req, <callbackfunction>);

Als Request-Parameter wird dabei ein Objekt der Struktur as_address_solutions_validator.ASValidateNameRequest übergeben, das folgende Elemente besitzt:

  • VersionInput (z.Zt. immer "1")
  • Countrycode ("de", "nl", "gb") wenn unsicher/mehrsprachig, dann "de"
  • Namenselement (hier: Anrede), das validiert werden soll, z.B. "Herr", "Mrs"

Die Rückgabe erfolgt in einem Objekt as_address_solutions_validator.ASValidateNameResponse, das die folgende Struktur aufweist:

  • ReleaseInfo (z.Zt. "3.1")
  • GeneralStatus ("0" bei erfolgreichem Funktionsaufruf und erfolgreicher Ausführung, <> 0 sonst)
  • ValidationCode
    • "1": Feldinhalt korrekt
    • "2": Feldinhalt enthält keine Anrede, aber eindeutig andere Bedeutung, z.B. Titel bei Eingabe "Dr."
    • "3": Feldinhalt enthält keine Anrede, hat aber mehrere andere Bedeutungen, z.B. Vor- und Nachname bei Eingabe "Frank"
    • "4": Feldinhalt ist ein unbekanntes Wort, z.B. "wrscsf"
  • ValidationMessage
    • z.B. "Dr" ist ein Titel bei ValidationCode 2

Implementierung

// use the address solutions library
var as_address_solutions_validator = require('./public/vendor/as-address-solutions-validator/dist/as-address-solutions-validator.js');  

function call_as_validate_salutation(anrede) {
  var as_req = new as_address_solutions_validator.ASValidateNameRequest(
    1,                                  // VersionInput
    "de",                               // Countrycode
    anrede);                            // Anrede, die validiert werden soll

  as_address_solutions_validator.ASValidateSalutation(as_req, function (error, response) {
    if (error) {
      console.log("error response von ASValidateName: " + error.ErrorStatus + "/" + error.ErrorMessage);
    }
    else {
      // following elements are delivered in response (cf as-address-solutions-validator.js)
      // ReleaseInfo: ReleaseInfo of used Server
      // GeneralStatus: general Status (tbd)
      // ValidationCode: Validation Code 1: Element ok, 2: Not OK, but could stay here, 3: not OK should be moved
      // ValidationMessage: Message zur Validierung
      console.log('');
      console.log('==============================================');
      console.log('ReleaseInfo            : '+ response.ReleaseInfo);
      console.log('GeneralStatus          : '+ response.GeneralStatus);
      console.log('ValidationCode         : '+ response.ValidationCode);
      console.log('ValidationMessage      : '+ response.ValidationMessage);
      console.log('==============================================');
      console.log('');
    }
  });
}

call_as_validate_salutation("Dr.");

Ausgabe

==============================================
ReleaseInfo            : 3.1
GeneralStatus          : 0
ValidationCode         : 3
ValidationMessage      : (Dr) ist ein Titel
==============================================

ASValidateTitle

Die Funktion wird benutzt, um den Inhalt eines Titelfeldes zu prüfen. Der Funktionsufruf lautet:

as_address_solutions_validator.ASValidateTitle(req, <callbackfunction>);

Als Request-Parameter wird dabei ein Objekt der Struktur as_address_solutions_validator.ASValidateNameRequest übergeben, das folgende Elemente besitzt:

  • VersionInput (z.Zt. immer "1")
  • Countrycode ("de", "nl", "gb") wenn unsicher/mehrsprachig, dann "de"
  • Namenselement (hier: Titel), das validiert werden soll, z.B. "Dr.", "Dipl.-Ing."

Die Rückgabe erfolgt in einem Objekt as_address_solutions_validator.ASValidateNameResponse, das die folgende Struktur aufweist:

  • ReleaseInfo (z.Zt. "3.1")
  • GeneralStatus ("0" bei erfolgreichem Funktionsaufruf und erfolgreicher Ausführung, <> 0 sonst)
  • ValidationCode
    • "1": Feldinhalt korrekt
    • "2": Feldinhalt enthält keinen Titel, aber eindeutig andere Bedeutung, z.B. Nachname bei Eingabe "Geerken"
    • "3": Feldinhalt enthält keinen Titel, hat aber mehrere andere Bedeutungen, z.B. Vor- und Nachname bei Eingabe "Frank"
    • "4": Feldinhalt ist ein unbekanntes Wort, z.B. "wrscsf"
  • ValidationMessage
    • z.B. "Geerken" ist ein Titel bei ValidationCode 2
    • "Frank" hat verschiedene andere Bedeutungen bei 3

Implementierung

// use the address solutions library
var as_address_solutions_validator = require('./public/vendor/as-address-solutions-validator/dist/as-address-solutions-validator.js');  

function call_as_validate_title(titel) {
  var as_req = new as_address_solutions_validator.ASValidateNameRequest(
    1,                                  // VersionInput
    "de",                               // Countrycode
    titel) ;                            // Titel, der validiert werden soll

  as_address_solutions_validator.ASValidateTitle(as_req, function (error, response) {
    if (error) {
      console.log("error response von ASValidateName: " + error.ErrorStatus + "/" + error.ErrorMessage);
    }
    else {
      // following elements are delivered in response (cf as-address-solutions-validator.js)
      // ReleaseInfo: ReleaseInfo of used Server
      // GeneralStatus: general Status (tbd)
      // ValidationCode: Validation Code 1: Element ok, 2: Not OK, but could stay here, 3: not OK should be moved
      // ValidationMessage: Message zur Validierung
      console.log('');
      console.log('==============================================');
      console.log('ReleaseInfo            : '+ response.ReleaseInfo);
      console.log('GeneralStatus          : '+ response.GeneralStatus);
      console.log('ValidationCode         : '+ response.ValidationCode);
      console.log('ValidationMessage      : '+ response.ValidationMessage);
      console.log('==============================================');
      console.log('');
    }
  });
}

call_as_validate_title("Dr.");

Ausgabe

==============================================
ReleaseInfo            : 3.1
GeneralStatus          : 0
ValidationCode         : 1
ValidationMessage      : 
==============================================

ASValidateFirstname, ASValidateLastname

Die Funktion wird benutzt, um den Inhalt des Vor- bzw. Nachnamensfeldes zu prüfen. Die Funktionsufrufe lauten:

as_address_solutions_validator.ASValidateFirstname(req, <callbackfunction>); as_address_solutions_validator.ASValidateLastname(req, <callbackfunction>);

Hinsichtlich der Übergabe der Parameter und Rückgabe der Ergebnisse wird auf die beiden oben beschriebenen Funktionen ASValidateSalutation und ASValidateTitle verwiesen. Die Verwendung ist analog.

ASConvertName

Die Funktion wird benutzt, um den Inhalt der Namensfelder Anrede, Titel, Vorname und Nachname zu strukturieren und standardisieren. Dabei werden alle Namenselemente aus den Eingabefeldern geprüft und im Interpretationsmodul der AS ConvertBox verarbeitet. Sollten sich in der dort ermittelten Prüfung Änderungen zum Inhalt der einzelnen Felder bzgl. Struktur und/oder Schreibweise ergeben, so wird die so erzeugte Ausgabe zurückgeliefert und ein entsprechender Statuscode mit Meldung geliefert.

Der Funktionsufruf lautet:

as_address_solutions_validator.ASConvertName(req, <callbackfunction>);

Als Request-Parameter wird dabei ein Objekt der Struktur as_address_solutions_validator.ASConvertNameRequest übergeben, das folgende Elemente besitzt:

  • VersionInput (z.Zt. immer "1")
  • Countrycode ("de", "nl", "gb") wenn unsicher/mehrsprachig, dann "de"
  • Namenselement (hier: Anrede), das validiert werden soll, z.B. "Herr", "Mrs"

Die Rückgabe erfolgt in einem Objekt as_address_solutions_validator.ASConvertNameResponse, das die folgende Struktur aufweist:

  • ReleaseInfo (z.Zt. "3.1")
  • GeneralStatus
    • "0": 'Unbekannter Fehler. Bitte Prüfen Sie erneut die Eingabe',
    • "1": 'Der Name konnte validiert werden. Mit [OK und weiter] gelangen Sie zur Eingabe der Anschrift.',
    • "2": 'Der Name ist valide, es wurden aber leichte Normkorrekturen durchgeführt. Überprüfen Sie Ihre Eingabe und betätigen Sie [OK und weiter] wenn alles korrekt ist.',
    • "3": 'Es wurden Namenselemente verschoben bzw. Korrekturen durchgeführt. Überprüfen Sie das Ergebnis und betätigen Sie [OK und weiter] wenn alles korrekt ist.',
    • "4": 'Ihre Angaben konnten nicht validiert und korrigiert werden. Überprüfen Sie Ihre Eingabe und betätigen Sie [OK und weiter] wenn alles korrekt ist.',
    • "5": 'Unbekannter Fehler. Bitte Prüfen Sie erneut die Eingabe',
    • "6": 'Wir haben eine Personengemeinschaft erkannt. Es kann nur eine Einzelperson registriert werden. Überprüfen Sie Ihre Eingabe und betätigen Sie [OK und weiter] wenn alles korrekt ist.',
    • "7": 'Wir haben einen Personennamen erkannt, allerdings ist das Ergebnis unsicher. Überprüfen Sie Ihre Eingabe und betätigen Sie [OK und weiter] wenn alles korrekt ist.',
    • "8": 'Wir haben unbekannte Namenselemente gefunden oder der Name ist nicht strukturierbar. Überprüfen Sie Ihre Eingabe und betätigen Sie [OK und weiter] wenn alles korrekt ist.',
    • "9": 'Wir haben einen Hinweis auf einen Firmennamen gefunden. Es kann nur eine natürliche Einzelperson registriert werden. Überprüfen Sie Ihre Eingabe und betätigen Sie [OK und weiter] wenn alles korrekt ist.',
  • ConversionMessage: Erläuterungen zum Statuscode 0-9 (s.o.). Die Texte sind im File as-language-pack.js im Array conversion_messages_de hinterlegt und können nach Bedarf dort geändert werden.
  • SalutationOutput: korrigierte Anrede (ggf. korrigiert)
  • SalutationOutputMessage: Hinweis zur Anrede wie das Feld behandelt wurde. Folgende Meldungen sind möglich:
    • (generiert): In der Eingabe war das Feld leer, es konnte aber aus dem Kontext ermittelt werden
    • (standardisiert): Es wurden geringfügige Änderungen wie Groß-/Kleinschreibung durchgeführt
    • (korrigiert): Das Feld war gefüllt, der Inhalt wurde aber korrigiert
    • (in anderem Feld gefunden): Das Feld war leer, die Anrede konnte aber in einem anderen Feld gefunden werden
    • (in anderes Feld verschoben): Der Feldinhalt war kein Anrede, konnte aber in das korrekte Feld (z.B. Titel) verschoben werden
  • TitleOutput: korrigierter Titel
  • TitleOutputMessage: vgl. SalutationOutputMessage
  • FirstnameOutput: korrigierter Vorname
  • FirstnameOutputMessage: vgl. SalutationOutputMessage
  • LastnameOutput: korrigierter Nachname
  • LastnameOutputMessage: vgl. SalutationOutputMessage

Implementierung

// use the address solutions library
var as_address_solutions_validator = require('./public/vendor/as-address-solutions-validator/dist/as-address-solutions-validator.js');

function call_as_convert_name(anrede, titel, vorname, nachname) {
  var as_req = new as_address_solutions_validator.ASConvertNameRequest(
    1,                                  // VersionInput
    "de",                               // Countrycode
    anrede,                             // Anrede leer, soll generiert werden
    titel,                              // Titel, leer, soll aus Gesamtnamen gezogen werden
    vorname,                            // Vorname leer, soll aus Gesamtnamen gezogen werden
    nachname);// (Nach)name

  as_address_solutions_validator.ASConvertName(as_req, function (error, response) {
    if (error) {
      console.log("error response von ASConvertName: " + error.ErrorStatus + "/" + error.ErrorMessage);
    }
    else {
      // following elements are delivered in response (cf as-address-solutions-validator.js)
      // ReleaseInfo: ReleaseInfo of used Server
      // GeneralStatus: general Status (1=everything fine no conversion needed, 2=slight corrections, ...)
      // ConversionMessage: informational text to conversion
      // SalutationOutput: corrected Salutation output
      // SalutationOutputMessage: message about (wrong) content in Salution field
      // TitleOutput: see Salution
      // TitleOutputMessage
      // FirstnameOutput
      // FirstnameOutputMessage
      // LastnameOutput
      // LastnameOutputMessage
      console.log('');
      console.log('==============================================');
      console.log('ReleaseInfo            : '+ response.ReleaseInfo);
      console.log('GeneralStatus          : '+ response.GeneralStatus);
      console.log('ConversionMessage      : '+ response.ConversionMessage);
      console.log('SalutationOutput       : '+ response.SalutationOutput);
      console.log('SalutationOutputMessage: '+ response.SalutationOutputMessage);
      console.log('TitleOutput            : '+ response.TitleOutput);
      console.log('TitleOutputMessage     : '+ response.TitleOutputMessage);
      console.log('FirstnameOutput        : '+ response.FirstnameOutput);
      console.log('FirstnameOutputMessage : '+ response.FirstnameOutputMessage);
      console.log('LastnameOutput         : '+ response.LastnameOutput);
      console.log('LastnameOutputMessage  : '+ response.LastnameOutputMessage);
      console.log('==============================================');
      console.log('');
    }
  });
}


call_as_convert_name("", "", "", "dipl.-inform gustav gans, lehrer");

Ausgabe

==============================================
ReleaseInfo            : 3.1
GeneralStatus          : 3
ConversionMessage      : Der Name ist valide, es wurden aber leichte Normkorrekturen durchgeführt. Überprüfen Sie Ihre Eingabe und betätigen Sie [OK und weiter] wenn alles korrekt ist.
SalutationOutput       : Herr
SalutationOutputMessage: (generiert)
TitleOutput            : Dipl.-Inform.
TitleOutputMessage     : (in anderem Feld gefunden)
FirstnameOutput        : Gustav
FirstnameOutputMessage : (in anderem Feld gefunden)
LastnameOutput         : Gans
LastnameOutputMessage  : (korrigiert)
==============================================```

***