Wie definiere ich Freifelder (benutzerdefinierte Felder)?

Ab Tarif Pro

Kurzantwort

Freifelder legst du im Modul Daten über die Schaltfläche „Felder” des jeweiligen Objekttyps an: mit Schlüssel, Bezeichnung, Feldtyp, optionalen Optionen und der Kennzeichnung Pflichtfeld. Für Assets (und andere Systemobjekte) pflegst du Freifelder unter Katalog & Ausgabe → Tab „Custom-Fields” mit Objekttyp = asset.

Voraussetzungen

Freifelder erfordern Pro oder höher (Feature custom_fields). Ohne das Feature zeigt der Tab „Custom-Fields” den Hinweis „Freifelder sind ab dem Pro-Tarif verfügbar.” und die API antwortet mit 403.

Die Feldtypen

Feldtyp	Bedeutung / Eingabe
`text`	Freitext (Standard)
`number`	Zahl
`boolean`	Ja/Nein (Kontrollkästchen)
`date`	Datum
`select`	Einfachauswahl: Optionen kommagetrennt hinterlegen
`multiselect`	Mehrfachauswahl: Optionen kommagetrennt hinterlegen
`url`	Web-Adresse
`currency`	Geldbetrag
`user`	Verweis auf einen Benutzer des Mandanten
`relation`	Verweis auf einen Datensatz eines anderen Objekttyps, im Feld „Optionen / Relationsziel” den Ziel-Typschlüssel angeben

Felder-Dialog öffnen. Wähle im Modul Daten den Objekttyp und klicke auf „Felder”. Der Dialog zeigt die vorhandenen Felder als Chips (mit Feldtyp) und darunter das Formular für neue Felder.

Screenshot ausstehend katalog-freifelder-01 Dialog 'Felder' eines Objekttyps mit Feld-Chips und dem Formular Schlüssel, Bezeichnung, Feldtyp, Optionen und Pflichtfeld

Der Felder-Dialog: bestehende Felder als Chips, darunter das Anlage-Formular.
Feld definieren. Fülle aus:
- Schlüssel (z. B. plate): nur Kleinbuchstaben, Ziffern, Unterstriche.
- Bezeichnung (z. B. „Kennzeichen”): der Anzeigename im Formular.
- Feldtyp: siehe Tabelle oben.
- Optionen / Relationsziel: bei select/multiselect die Werte kommagetrennt (z. B. Benzin,Diesel,Elektro), bei relation der Schlüssel des Ziel-Objekttyps.
- Pflichtfeld: ankreuzen, wenn der Wert bei jedem Datensatz nötig ist.
Klicke auf „Feld hinzufügen”.
Freifelder für Assets. Öffne Katalog & Ausgabe → Tab „Custom-Fields”. Hier verwaltest du Freifelder für beliebige Objekttypen. Trage als Objekttyp z. B. asset ein, damit das Feld im Asset-Formular (Bereich Benutzerdefinierte Felder) erscheint.

Screenshot ausstehend katalog-freifelder-02 Tab 'Custom-Fields' unter Katalog & Ausgabe mit der Freifeld-Liste und dem Anlage-Formular

Freifelder für Assets und andere Objekttypen: der Tab 'Custom-Fields'.

Ein POST auf /api/v1/custom-fields (Scope write). entity_type ist der Schlüssel des Objekttyps, für Asset-Felder asset:

curl -X POST https://demo.notory.io/api/v1/custom-fields \
  -H "Authorization: Bearer inv_dein_token" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "vehicle",
    "name": "fuel",
    "label": "Antrieb",
    "field_type": "select",
    "options": "Benzin,Diesel,Elektro",
    "required": true
  }'

{
  "id": "5b8d1e20-9c3f-4a7b-b2e6-0d4f8a1c7e33",
  "tenant_id": "3d9b0c12-4e5a-4f88-b1c7-2a9e6d4f0011",
  "entity_type": "vehicle",
  "name": "fuel",
  "label": "Antrieb",
  "field_type": "select",
  "options": "Benzin,Diesel,Elektro",
  "required": true
}

Ein Freifeld für Assets. Es erscheint danach im Asset-Formular:

curl -X POST https://demo.notory.io/api/v1/custom-fields \
  -H "Authorization: Bearer inv_dein_token" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "asset",
    "name": "cost_center",
    "label": "Kostenstelle",
    "field_type": "text"
  }'

Auflisten, ändern, löschen (Löschen nur als Administrator):

curl -H "Authorization: Bearer inv_dein_token" \
  https://demo.notory.io/api/v1/custom-fields

curl -X PUT https://demo.notory.io/api/v1/custom-fields/5b8d1e20-9c3f-4a7b-b2e6-0d4f8a1c7e33 \
  -H "Authorization: Bearer inv_dein_token" \
  -H "Content-Type: application/json" \
  -d '{ "required": false }'

Mögliche Fehler: 403 (Tarif unter Pro oder fehlende Rolle), 404 („Custom field not found”), 422 (Validierung, z. B. leerer name).

Was passiert dabei?

Sofort wirksam: Neue Felder erscheinen umgehend in den Formularen. Bei Objekttypen im Datensatz-Formular, bei entity_type = asset im Asset-Formular unter Benutzerdefinierte Felder und in der Asset-Detailansicht.
Validierung: Beim Speichern von Datensätzen und Assets prüft Notory die übergebenen Werte gegen die Definitionen: falsche Typen, unbekannte Optionen oder fehlende Pflichtfelder ergeben 422 mit einer Fehlermeldung je Feld.
Mandanten-Isolation: Definitionen gelten nur für deinen Mandanten.
Löschen entfernt die Definition, nicht die Werte: Bereits gespeicherte Werte in bestehenden Datensätzen/Assets bleiben in den Daten erhalten, werden aber ohne Definition nicht mehr als Formularfeld angeboten.
Scanner-Grundlage: Das Modul Scannen nutzt die Freifelder als Code-Feld (z. B. serial, plate) und Mengenfeld (number/currency). Sinnvoll benannte Felder zahlen sich dort aus.