inquiry - Forms - WEBSALE Dokumentation

The inquiry node controls shop-side forms (e.g. contact, cancellation, return, catalogue order). Forms are configured in the Admin Interface under the Inquiries service. Each form is defined as its own sub-node under inquiry.form.<name>.

`inquiry*` - Basic structure

The basic structure of the inquiry node is shown below:

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

Parameter description

Parameter	Description
`form`	Container for all form definitions below `inquiry`. The direct keys within `form` are the technical form names.
`<name>`	Placeholder for a specific form node (e.g. `catalogue`, `contact`, `productQuestion`, `returnInquiry`). The associated object contains the full configuration of this form (e.g. fields, validations, email settings).
`fieldPreset`	Container for global, reusable field definitions.
`ruleSet`	Container for rule-based field controls that can be assigned to forms.

`inquiry.form` - Form configuration

Each form below inquiry.form contains the full configuration for a specific inquiry form (e.g. contact, catalogue request, product question, return). The form fields, validations, optional captcha checks as well as the email parameters via which the inquiry is forwarded or confirmed are defined here.

Example configuration for a contact form (`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"
}

Parameter description

Parameter	Type	Description
`name`	string	Technical name of the form. Can be chosen freely but must be unique.
`fieldPresets`	multiAssoc	References predefined field groups (global form fields) defined centrally under `inquiry.fieldPreset`. This way commonly used fields (e.g. name, email address) can be reused in multiple forms. The assignment is done via a list of references to the respective preset nodes, e.g.: `"fieldPresets": [ "inquiry.fieldPreset.firstName", "inquiry.fieldPreset.lastName" ]` If no global field presets should be used, the value must be `null`.
`fields`	list (object)	List of input fields to be requested in the form.
`name`	string	Technical field name (key).
`label`	string	Display name in the form.
`required`	bool	Required flag (`true`/`false`). Default: `false`
`validations`	multiService	List of validation rules for the field. Optional. Target: `InputValidation`
`service`	—	Validation service, e.g. `dataChecker.minLength`, `dataChecker.maxLength`. Each entry references a node under `dataChecker`. An overview of the available validation and check rules for form fields can be found here.
`options`	—	Options object for the rule configuration, e.g. `{ "len": 200 }`.
`captcha`	singleService	Object for the captcha configuration (spam / bot protection). Optional.
`service`	—	Contains the service name, e.g. `captchaCheck.recaptchav3`. Each entry references a node under `captcha`.
`inquiryEmail`	object	Object for the email dispatch of the inquiry.
`fromAddress`	string	Sender email address.
`fromName`	string	Sender display name.
`merchantEmail`	string	Optional copy sent to an internal merchant/service address. The main recipient of the receipt confirmation is always the requester – the recipient address is not configured here, but taken dynamically from the HTML form field `<input type="email" name="email">` (required parameter of the `InquirySend` action).
`subject`	string	Subject line of the outgoing message.
`template`	string	Name of the HTML file for the email template, e.g. `contact.htm`.

Recipient address and BCCThe confirmation email to the customer is always sent to the address submitted in the HTML form via the <input type="email" name="email"> field. If this field is missing from the frontend template, no receipt confirmation is sent – regardless of which fields are configured under fields. The email field is a separate action parameter (see InquirySend) and does not need to be declared additionally under fields.A bcc or cc parameter is not supported by inquiryEmail. Only merchantEmail is available for an additional internal copy.

| ruleSet | string | Reference to a ruleSet under inquiry.ruleSet, e.g. “inquiry.ruleSet.contactRules”.
Enables rule-based control of field attributes such as visibility, required status, labels and default values. |

`inquiry.fieldPreset` - Global field definitions

The inquiry.fieldPreset node is used for the central definition of reusable form fields. These global field presets allow standardised fields (e.g. first name, last name, email address, phone number) to be defined once and then used in multiple forms. A single preset node below inquiry.fieldPreset contains the full field definition, analogous to the field objects within the respective form configuration (inquiry.form.<name>.fields). The integration is done via the fieldPresets parameter in the respective form by referencing the preset names.

Example configuration for all `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 overview

Parameter	Type	Description
`label`	string	Display name of the field in the form.
`name`	string	Technical field name (key) — used for data transmission and email output.
`required`	bool	Required flag (`true`/`false`). Default: `false`
`validations`	multiService	List of validation rules for the field. Optional.
`service`	—	Name of the validation service, e.g. `dataChecker.minLength`, `dataChecker.maxLength`. An overview of the available validation and check rules for form fields can be found here.
`options`	—	Parameter object defining the rule, e.g. `{ "len": 50 }`.

`inquiry.ruleSet` - Rule-based field control

The inquiry.ruleSet node enables dynamic, rule-based control of form fields. Via RuleSets, field attributes such as visibility, required status, labels and default values can be adjusted at runtime based on conditions (e.g. the current value of another field). A RuleSet is defined via inquiry.ruleSet.<name> and integrated via the ruleSet parameter in the respective form (inquiry.form.<name>).

Example configuration for `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 overview for the general rule structure

Parameter	Type	Description
`conditions`	list (object)	List of conditions that must all be satisfied for the rule to apply. If `null`, the rule always applies.
`field`	string	Technical name of the field whose value is checked.
`type`	string	Type of check. Available types: - `value` — exact comparison value. - `notvalue` — value does not match. - `inlist` — value is contained in a list.
`value`	string	Comparison value (for `type` = `value` or `notvalue`).
`valueList`	list (string)	List of comparison values (only `type` = `inlist`).
`fields`	list (string)	List of technical field names to which the rule is applied.

Additional parameters per definition

customLabelsDefinition

Parameter	Type	Description
`label`	string	The new label that the affected fields receive when the conditions apply.

defaultValuesDefinition

Parameter	Type	Description
`value`	string	The default value set for the affected fields.

inputVisibilityDefinition

Parameter	Type	Description
`visible`	bool	Indicates whether the affected fields should be visible (`true`) or hidden (`false`).
`resetIfHidden`	bool	Indicates whether the field value is reset when hidden (`true`) or preserved (`false`). Default: `false`

requiredDefinition

Parameter	Type	Description
`value`	bool	Indicates whether the affected fields are treated as required (`true`) or as optional (`false`).

​inquiry* - Basic structure

​Parameter description

​inquiry.form - Form configuration

​Example configuration for a contact form (inquiry.form.contact)

​Parameter description

​inquiry.fieldPreset - Global field definitions

​Example configuration for all inquiry.fieldPreset

​Parameter overview

​inquiry.ruleSet - Rule-based field control

​Example configuration for inquiry.ruleSet.contactRules

​Parameter overview for the general rule structure

​Additional parameters per definition

`inquiry*` - Basic structure

Parameter description

`inquiry.form` - Form configuration

Example configuration for a contact form (`inquiry.form.contact`)

Parameter description

`inquiry.fieldPreset` - Global field definitions

Example configuration for all `inquiry.fieldPreset`

Parameter overview

`inquiry.ruleSet` - Rule-based field control

Example configuration for `inquiry.ruleSet.contactRules`

Parameter overview for the general rule structure

Additional parameters per definition