WSE (WebServiceExport) - Zuordnung

Was bedeutet die Zuordnung (Mapping)?

Damit Daten aus einem Formular in ein Fremdsystem exportiert werden können, muss das Formular mit einer zuvor erstellten WSE-Definition verbunden werden.

Bei der Zuordnung (Mapping) geht es nicht nur darum, Formularfelder direkt mit Ziel-API-Feldern zu verknüpfen. Es stehen mehrere Möglichkeiten zur Verfügung:

• Formularfelder – direkte Zuordnung von Eingabefeldern aus dem Formular.

• Formular-Parameter – formularspezifische Daten, die für alle Anträge eines Formulars gelten (z. B. Programmdaten).

• Platzhalter – feste Systemwerte wie Antragsnummer oder Einreichdatum.

• Ausdrücke – Kombinationen aus Feldern, Parametern, Platzhaltern und freiem Text.

Erst durch diese Zuordnung wird festgelegt, wie Daten aus dem Formular in die Struktur des Fremdsystems übertragen werden.

Formularfelder

Formularfelder sind die am häufigsten genutzte Möglichkeit für die Zuordnung.
Dabei wird ein Eingabefeld aus dem Formular direkt mit einem Ziel-API-Feld verbunden.

• Typischer Einsatz: personenbezogene Daten oder antragsspezifische Informationen.

• Vorteil: immer der konkrete Wert aus dem Antrag wird exportiert.

• Beispiel: Das Formularfeld „Nachname“ wird dem Ziel-API-Feld applicantLastName zugeordnet.

Formular-Parameter

Formular-Parameter sind feste Werte, die für ein gesamtes Formular gelten.
Sie werden nicht vom Antragsteller eingegeben, sondern vom Administrator oder Sachbearbeiter beim Formular hinterlegt.

• Typischer Einsatz: Angaben, die in allen Anträgen des Formulars identisch sind.

• Beispiel: Förderprogramm, Förderjahr, organisatorische Kennungen.

• Vorteil: Änderungen am Parameter wirken automatisch für alle Anträge.

Platzhalter

Platzhalter sind systemseitig bereitgestellte Werte, die unabhängig vom Formular verfügbar sind.
Sie können in jedem Mapping verwendet werden.

• Typischer Einsatz: technische oder systemische Werte, die vom System vergeben werden.

• Beispiele: Antragsnummer, Einreichdatum, aktuelles Bearbeitungsdatum.

• Vorteil: garantierte Konsistenz, da die Werte automatisch durch das System gesetzt werden.

Ausdrücke

Ausdrücke erlauben die Kombination von verschiedenen Quellen (Formularfelder, Formular-Parameter, Platzhalter) mit freiem Text.
Damit können komplexere Werte zusammengesetzt werden.

• Typischer Einsatz: wenn mehrere Felder kombiniert oder zusätzliche Texte ergänzt werden müssen.

• Beispiele:

  • {applicantLastName}, {applicantFirstName}

  • "Antrag " + {Antragsnummer} + " vom " + {Einreichdatum}

• Vorteil: maximale Flexibilität bei der Gestaltung des Exportwerts.

Empfehlungen zur Zuordnung

• Die Zuordnung eines Formulars zu einer WSE-Definition sollte erst durchgeführt werden, wenn das Formular vollständig definiert ist.
  So wird sichergestellt, dass alle benötigten Felder für das Mapping zur Verfügung stehen.

• Formulareigenschaften können gezielt so angelegt werden, dass sie zu bestimmten Ziel-API-Feldern passen.
  Dadurch lassen sich feste oder formularweite Informationen (z. B. Programmdaten, Förderjahr) zuverlässig exportieren.

• Wichtiger Hinweis zur Praxis:
  Vor der Neuentwicklung wurden anstelle von Formulareigenschaften häufig sogenannte Read-only-Felder im Formular verwendet.
  Diese Felder konnten vom Antragsteller nicht bearbeitet werden, wurden aber im Formular angezeigt – was teils zu Verwirrung führte.
  Da solche Informationen nichts mit der Antragstellung selbst zu tun haben, sollten sie künftig nicht mehr als Formularfelder, sondern ausschließlich als Formulareigenschaften abgebildet werden.

Einschränkungen bei der Zuordnung

Nicht jede Quelle kann jedem Ziel-API-Feld zugeordnet werden.
Die Möglichkeiten hängen vom Datentyp und von der Pflichtfeld-Eigenschaft des Ziel-API-Feldes ab.

• Pflichtfelder

  • Müssen zwingend befüllt werden.

  • Können nur mit Quellen verbunden werden, die immer einen Wert liefern (z. B. Formularfelder, Pflicht-Parameter, bestimmte Platzhalter).

• Datentypprüfung

  • Die Quelle muss zum Datentyp des Ziel-API-Feldes passen.

  • Beispiele:

    • Int32 → nur numerische Felder oder passende Parameter.

    • Double → nur numerische Felder oder Parameter mit Dezimalwert.

    • UnixTimeStamp → nur Quellen, die ein Datum liefern.

    • StringValueList → nur Werte aus der vordefinierten Liste.

Übersicht: Zulässige Quellen pro Datentyp

Besonderheit: Zuordnung aus Datengruppen mit mehrfachen Einträgen

Wird ein Ziel-API-Feld einem Formularfeld zugeordnet, das in einer Datengruppe definiert ist, welche mehrfache Einträge erlaubt (z. B. Adressen, Bankverbindungen), gibt es zwei Möglichkeiten, den Wert für den Export zu bestimmen:

1. Fester erster Eintrag

   • Es wird immer der erste vom Antragsteller angelegte Eintrag der Datengruppe verwendet.

   • Beispiel: Die erste Adresse, die der Antragsteller eingibt, wird exportiert.

2. Dynamische Auswahl über ein Wahr/Falsch-Feld

   • Innerhalb der Datengruppe kann ein Wahr/Falsch-Feld als Kriterium festgelegt werden.

   • Der Eintrag, bei dem dieses Feld den Wert true hat, wird für den Export verwendet.

   • Beispiel: In der Datengruppe „Adresse“ existiert das Feld Postanschrift. Ist dieses Feld auf true gesetzt, wird genau diese Adresse exportiert.

Fallback-Logik:

• Falls kein Eintrag der Datengruppe den Wert true im definierten Wahr/Falsch-Feld hat, fällt das System automatisch auf den ersten Eintrag zurück.