inquiry - Formulare - WEBSALE Dokumentation

Der Knoten inquiry steuert shopseitige Formulare (z. B. Kontakt, Widerruf, Retoure, Katalogbestellung). Die Konfiguration von Formularen erfolgt im Admin Interface unter dem Service Anfragen. Jedes Formular wird als eigener Unternode unter inquiry.form.<name> definiert.

`inquiry*` - Grundstruktur

Nachfolgend der Grundaufbau des Knotens inquiry:

{
  "inquiry": {
    "form": {
      "catalogue": { ... },
      "contact": { ... },
      "productQuestion": { ... },
      "returnInquiry": { ... }
    },
    "fieldPreset": { ... },
    "ruleSet": { ... }
  }
}

Parameterbeschreibung

Parameter	Beschreibung
`form`	Container für alle Formular-Definitionen unterhalb von `inquiry`. Die direkten Keys innerhalb von `form` sind die technischen Formularnamen.
`<name>`	Platzhalter für einen konkreten Formular-Knoten (z. B. `catalogue`, `contact`, `productQuestion`, `returnInquiry`). Das zugehörige Objekt enthält die vollständige Konfiguration dieses Formulars (z. B. Felder, Validierungen, E-Mail-Einstellungen).
`fieldPreset`	Container für globale, wiederverwendbare Felddefinitionen.
`ruleSet`	Container für regelbasierte Feldsteuerungen, die Formularen zugewiesen werden können.

`inquiry.form` - Formular-Konfiguration

Jedes Formular unterhalb von inquiry.form enthält die vollständige Konfiguration für ein bestimmtes Anfrageformular (z. B. Kontakt, Kataloganforderung, Produktfrage, Retoure). Hier werden die Formularfelder, Validierungen, optionale Captcha-Prüfungen sowie die E-Mail-Parameter definiert, über die die Anfrage weitergeleitet oder bestätigt wird.

Beispielkonfiguration für ein Kontaktformular (`inquiry.form.contact`)

{
  "captcha": {
    "service": "captchaCheck.recaptchav3"
  },
  "fieldPresets": null,
  "fields": [
    {
      "label": "<Textbaustein>",
      "name": "subject",
      "required": true,
      "validations": [
        {
          "options": { "len": 1 },
          "service": "dataChecker.minLength"
        },
        {
          "options": { "len": 200 },
          "service": "dataChecker.maxLength"
        }
      ]
    },
    {
      "label": "<Textbaustein>",
      "name": "comment",
      "required": true,
      "validations": [
        {
          "options": { "len": 1 },
          "service": "dataChecker.minLength"
        },
        {
          "options": { "len": 10000 },
          "service": "dataChecker.maxLength"
        }
      ]
    }
  ],
  "inquiryEmail": {
    "fromAddress": "noreply@websale.de",
    "fromName": "Mustershop",
    "merchantEmail": "noreply@websale.de",
    "subject": "Ihre Kontaktanfrage",
    "template": "contact.htm"
  },
  "name": "contact",
  "ruleSet": "inquiry.ruleSet.contactRules"
}

Parameterbeschreibung

Parameter	Typ	Beschreibung
`name`	string	Technischer Name des Formulars. Ist frei wählbar, muss aber eindeutig sein.
`fieldPresets`	multiAssoc	Verweist auf vordefinierte Feldgruppen (globale Formularfelder), die zentral unter `inquiry.fieldPreset` definiert sind. Dadurch können gemeinsam genutzte Felder (z. B. Name, E-Mail-Adresse) in mehreren Formularen wiederverwendet werden. Die Zuweisung erfolgt über eine Liste von Referenzen auf die jeweiligen Preset-Knoten, z. B.: `"fieldPresets": [ "inquiry.fieldPreset.firstName", "inquiry.fieldPreset.lastName" ]` Wenn keine globalen Feldvorgaben verwendet werden sollen, ist der Wert `null` zu setzen.
`fields`	list (object)	Liste der Eingabefelder, die im Formular abgefragt werden sollen
`name`	string	Technischer Feldname (Key).
`label`	string	Anzeigename im Formular.
`required`	bool	Pflichtfeldkennzeichen (`true`/`false`). Default: `false`
`validations`	multiService	Liste von Validierungsregeln für das Feld. Optional. target: `InputValidation`
`service`	—	Validierungsdienst, z. B. `dataChecker.minLength`, `dataChecker.maxLength`. Jeder Eintrag verweist auf einen Knoten unter `dataChecker` Übersicht der verfügbaren Validierungs- und Prüfregeln für Formularfelder finden Sie hier.
`options`	—	Optionsobjekt zur Regelkonfiguration, z. B. `{ "len": 200 }`.
`captcha`	singleService	Objekt für die Captcha-Konfiguration (Spam-/Bot-Schutz). Optional.
`service`	—	Enthält den Service-Namen, z. B. `captchaCheck.recaptchav3`. Jeder Eintrag verweist auf einen Knoten unter `captcha`.
`inquiryEmail`	object	Objekt für den E-Mail-Versand der Anfrage.
`fromAddress`	string	Absender-E-Mailadresse.
`fromName`	string	Absender-Anzeigename.
`merchantEmail`	string	Optionale Kopie an eine interne Händler-/Service-Adresse. Der Hauptempfänger der Eingangsbestätigung ist immer der Anfragende – die Empfängeradresse wird nicht hier konfiguriert, sondern dynamisch aus dem HTML-Formularfeld `<input type="email" name="email">` übernommen (Pflichtparameter der `InquirySend`-Aktion).
`subject`	string	Betreffzeile der ausgehenden Nachricht.
`template`	string	Name der HTML-Datei für das E-Mail-Template, z. B. `contact.htm`. Der Wert wird relativ zum Verzeichnis `mails/` des Template-Themes aufgelöst - das System stellt `mails/` automatisch voran. `mails/` darf daher nicht mit angegeben werden (richtig: `contact02.htm`, falsch: `mails/contact02.htm`). Mehr dazu unter E-Mails & E-Mail Einstellungen.

Empfängeradresse und BCCDie Bestätigungsmail an den Kunden geht immer an die Adresse, die im HTML-Formular über das Feld <input type="email" name="email"> übermittelt wird. Fehlt dieses Feld im Frontend-Template, wird keine Eingangsbestätigung versendet – unabhängig davon, welche Felder unter fields konfiguriert sind. Das Feld email ist ein separater Aktionsparameter (siehe InquirySend) und muss nicht zusätzlich unter fields deklariert werden.Ein bcc- oder cc-Parameter wird von inquiryEmail nicht unterstützt. Für eine zusätzliche interne Kopie steht ausschließlich merchantEmail zur Verfügung.

| ruleSet | string | Verweis auf ein ruleSet unter inquiry.ruleSet, z.B. “inquiry.ruleSet.contactRules”.
Ermöglicht die regelbasierte Steuerung von Feldattributen wie Sichtbarkeit, Pflichtfeld-Status, Labels und Standardwerten. |

`inquiry.fieldPreset` - Globale Felddefinitionen

Der Knoten inquiry.fieldPreset dient zur zentralen Definition von wiederverwendbaren Formularfeldern. Über diese globalen Feldvorgaben können standardisierte Felder (z. B. Vorname, Nachname, E-Mail-Adresse, Telefonnummer) einmalig definiert und anschließend in mehreren Formularen eingebunden werden. Ein einzelner Preset-Knoten unterhalb von inquiry.fieldPreset enthält die vollständige Felddefinition analog zu den Feldobjekten innerhalb der jeweiligen Formular-Konfiguration (inquiry.form.<name>.fields). Die Einbindung erfolgt über den Parameter fieldPresets im entsprechenden Formular, indem auf die Preset-Namen verwiesen wird.

Beispielkonfiguration für alle `inquiry.fieldPreset`

{
      "firstName": {
        "label": "<Textbaustein>",
        "name": "firstName",
        "required": true,
        "validations": [
          {
            "service": "dataChecker.minLength",
            "options": { "len": 1 }
          },
          {
            "service": "dataChecker.maxLength",
            "options": { "len": 50 }
          }
        ]
      },
      "lastName": {
        "label": "<Textbaustein>",
        "name": "lastName",
        "required": true,
        "validations": [
          {
            "service": "dataChecker.minLength",
            "options": { "len": 1 }
          },
          {
            "service": "dataChecker.maxLength",
            "options": { "len": 50 }
          }
        ]
      }
    }

Parameterübersicht

Parameter	Typ	Beschreibung
`label`	string	Anzeigename des Feldes im Formular.
`name`	string	Technischer Feldname (Key) – wird für Datenübergabe und E-Mail-Ausgabe verwendet.
`required`	bool	Pflichtfeldkennzeichen (`true`/`false`). Default: `false`
`validations`	multiService	Liste der Validierungsregeln für das Feld. Optional.
`service`	—	Name des Validierungsdienstes, z. B. `dataChecker.minLength`, `dataChecker.maxLength`. Übersicht der verfügbaren Validierungs- und Prüfregeln für Formularfelder finden Sie hier.
`options`	—	Parameterobjekt zur Definition der Regel, z. B. `{ "len": 50 }`.

`inquiry.ruleSet` - Regelbasierte Feldsteuerung

Der Knoten inquiry.ruleSet ermöglicht die dynamische, regelbasierte Steuerung von Formularfeldern. Über RuleSets können Feldattribute wie Sichtbarkeit, Pflichtfeld-Status, Labels und Standardwerte abhängig von Bedingungen (z.B. dem aktuellen Wert eines anderen Feldes) zur Laufzeit angepasst werden. Ein RuleSet wird über inquiry.ruleSet.<name> definiert und über den Parameter ruleSet im jeweiligen Formular (inquiry.form.<name>) eingebunden.

Beispielkonfiguration für `inquiry.ruleSet.contactRules`

customLabelsDefinition:
  - conditions:
      - field: subject
        type: value
        value: Anruf
    fields:
      - text
    label: <Textbaustein>

defaultValuesDefinition:
  - conditions:
      - field: lastName
        type: value
        value: Musterfrau
    fields:
      - firstName
    value: Maria
  - conditions: null
    fields:
      - text
    value: |-
      Sehr geehrtes Myshop-Team,
      Ich interessiere mich brennend für euer Produktsortiment. Bitte tretet mit mir in Kontakt.
      Viele Grüße,

inputVisibilityDefinition:
  - conditions:
      - field: subject
        type: inlist
        valueList:
          - Anruf
    fields:
      - customerNumber
    visible: false
    resetIfHidden: false

requiredDefinition:
  - conditions:
      - field: lastName
        type: notvalue
        value: Musterfrau
    fields:
      - firstName
    value: true

Parameterübersicht für die Allgemeine Regelstruktur

Parameter	Typ	Beschreibung
`conditions`	list (object)	Liste von Bedingungen, die alle erfüllt sein müssen, damit die Regel greift. Bei `null` greift die Regel immer.
`field`	string	Technischer Name des Feldes, dessen Wert geprüft wird.
`type`	string	Art der Prüfung. Verfügbare Typen: - `value` - exakter Vergleichswert - `notvalue` - Wert stimmt nicht überein - `inlist` - Wert ist in einer Liste enthalten
`value`	string	Vergleichswert (bei `type`= `value` oder `notvalue`).
`valueList`	list (string)	Liste von Vergleichswerten (nur `type` = `inlist`).
`fields`	list (string)	Liste der technischen Feldnamen, auf die die Regel angewendet wird.

Zusätzliche Parameter je Definition

customLabelsDefinition

Parameter	Typ	Beschreibung
`label`	string	Das neue Label, das die betroffenen Felder erhalten, wenn die Bedingungen zutreffen.

defaultValuesDefinition

Parameter	Typ	Beschreibung
`value`	string	Der Standardwert, der für die betroffenen Felder gesetzt wird.

inputVisibilityDefinition

Parameter	Typ	Beschreibung
`visible`	bool	Gibt an, ob die betroffenen Felder sichtbar (`true`) oder ausgeblendet (`false`) sein sollen.
`resetIfHidden`	bool	Gibt an, ob der Feldwert beim Ausblenden zurückgesetzt wird (`true`) oder erhalten bleibt (`false`). Default: `false`

requiredDefinition

Parameter	Typ	Beschreibung
`value`	bool	Gibt an, ob die betroffenen Felder als Pflichtfeld (`true`) oder als optionales Feld (`false`) behandelt werden.

​inquiry* - Grundstruktur

​Parameterbeschreibung

​inquiry.form - Formular-Konfiguration

​Beispielkonfiguration für ein Kontaktformular (inquiry.form.contact)

​Parameterbeschreibung

​inquiry.fieldPreset - Globale Felddefinitionen

​Beispielkonfiguration für alle inquiry.fieldPreset

​Parameterübersicht

​inquiry.ruleSet - Regelbasierte Feldsteuerung

​Beispielkonfiguration für inquiry.ruleSet.contactRules

​Parameterübersicht für die Allgemeine Regelstruktur

​Zusätzliche Parameter je Definition

`inquiry*` - Grundstruktur

Parameterbeschreibung

`inquiry.form` - Formular-Konfiguration

Beispielkonfiguration für ein Kontaktformular (`inquiry.form.contact`)

Parameterbeschreibung

`inquiry.fieldPreset` - Globale Felddefinitionen

Beispielkonfiguration für alle `inquiry.fieldPreset`

Parameterübersicht

`inquiry.ruleSet` - Regelbasierte Feldsteuerung

Beispielkonfiguration für `inquiry.ruleSet.contactRules`

Parameterübersicht für die Allgemeine Regelstruktur

Zusätzliche Parameter je Definition