Zum Inhalt

Zähler

Zähler erzeugen in Pantarey fortlaufende Nummern – zum Beispiel für Rechnungsnummern, Auftragsnummern oder Ticket-IDs. Jeder Zähler hat einen eigenen Namen und einen aktuellen Stand. Bei jedem Aufruf wird der Wert atomar um eins erhöht und garantiert eindeutig zurückgegeben. So entstehen lückenlose, nachvollziehbare Nummernkreise ohne Risiko von Doppelvergaben.

Wofür werden Zähler genutzt?

  • Rechnungsnummern: RE-2026-0001, RE-2026-0002, …
  • Auftragsnummern: AUF-1024, AUF-1025, …
  • Ticket-IDs: T-501, T-502, …
  • Beliebige fortlaufende Kennungen in Dokumentnamen, Geschäfts-Labels oder Prozessdaten.

Jeder Zählername ist ein eigener Nummernkreis. Der Zähler rechnung hat nichts mit dem Zähler auftrag zu tun.

Verwendung in Templates und JSONata

Zähler werden über die Funktion nextId aufgerufen – sowohl in Templates (z. B. Dokumentname, Geschäfts-Label) als auch in JSONata-Ausdrücken (z. B. Input-Mappings von Service-Tasks).

Einfacher Aufruf

$fn('nextId', 'rechnung')

Liefert beim ersten Aufruf 1, dann 2, 3, … Der Name rechnung ist frei wählbar.

Praxisbeispiele

Template Ergebnis
RE-$fn('nextId', 'rechnung') RE-1, RE-2, …
RE-$fn('str_padStart', $fn('nextId', 'rechnung'), 5, '0') RE-00001, RE-00002, …
2026-$fn('str_padStart', $fn('nextId', 'ticket'), 4, '0') 2026-0001
AUF-$fn('date_toGermanDate', $(today))-$fn('nextId', 'auftrag') AUF-29.04.2026-42

Verwendung in JSONata

{
  "invoiceNumber": "RE-" & $fn('str_padStart', $fn('nextId','rechnung'), 5, '0'),
  "createdAt": $now()
}

Live-Vorschau im JSONata-Editor

Im JSONata-Editor (z. B. beim Bearbeiten von Input-/Result-Parametern) wird $fn('nextId', …) mit Mock-Werten ausgewertet. So lässt sich das Format direkt im Editor prüfen, ohne den Prozess starten zu müssen.

Verwaltung im Bereich „Zähler"

Im Bereich Verwaltung → Zähler werden alle in Pantarey verwendeten, geschäftsrelevanten Zähler aufgelistet. Die Seite zeigt für jeden Zähler:

  • Name: der Zählername (z. B. rechnung)
  • Aktueller Wert: der zuletzt vergebene Wert
  • Zuletzt geändert: Zeitstempel der letzten Änderung
  • Geändert von: wer den Wert zuletzt manuell gesetzt hat (nur bei manuellem Setzen)

Wert manuell setzen

Über das Stift-Symbol kann der aktuelle Wert eines Zählers angepasst werden. Das ist vor allem in zwei Situationen nützlich:

  • Migration aus einem Altsystem: Die letzte Rechnungsnummer aus dem Vorgängersystem war 2917. Der Zähler rechnung wird auf 2917 gesetzt – der nächste Aufruf von $fn('nextId', 'rechnung') liefert dann 2918.
  • Korrektur nach Tests: Während der Prozessentwicklung wurden Testnummern vergeben, die produktiv nicht zählen sollen.

Wert nur reduzieren, wenn niemand den Zähler aktiv nutzt

Wird ein Zählerstand nach unten gesetzt, können bereits vergebene Nummern erneut ausgegeben werden. Das führt zu Doppelvergaben (z. B. zweimal Rechnungsnummer RE-1024). Vor dem Reduzieren immer prüfen, dass keine Prozesse mit diesem Zähler aktiv sind.

Zähler löschen

Über das Papierkorb-Symbol kann ein nicht mehr benötigter Zähler entfernt werden. Beim nächsten Aufruf von $fn('nextId', '<name>') mit demselben Namen wird der Zähler automatisch neu angelegt und beginnt wieder bei 1.

Wichtige Eigenschaften

  • Atomar: Auch bei vielen gleichzeitigen Prozessen wird jeder Wert genau einmal vergeben. Es gibt keine Doppelvergaben.
  • Persistent: Zählerstände bleiben dauerhaft erhalten – auch über Deployments und Tenant-Updates hinweg.
  • Mandantenisoliert: Jeder Mandant hat seine eigenen Zähler. Der Zähler rechnung in Mandant A hat nichts mit dem in Mandant B zu tun.
  • Frei benennbar: Beliebige Zählernamen sind möglich, solange sie nicht mit __ (zwei Unterstrichen) beginnen. Diese Präfixe sind für interne Plattform-Zähler reserviert und werden im Verwaltungsbereich nicht angezeigt.

Tipps

  • Sprechende Namen verwenden: rechnung_2026, auftrag_dach, ticket_support – statt seq1, seq2. So bleibt nachvollziehbar, wofür ein Zähler genutzt wird.
  • Mit str_padStart formatieren: Damit Sortierungen (z. B. in Dateinamen) korrekt funktionieren, sollten Zählerwerte auf eine feste Länge aufgefüllt werden.
  • Pro Jahr neuen Zähler anlegen: Soll der Zähler jedes Jahr bei 1 neu starten, einfach den Jahresbestandteil im Namen verankern: rechnung_2026, rechnung_2027, …
  • Zähler nicht für IDs nutzen: Für eindeutige technische Schlüssel ist $fn('sys_ulid') besser geeignet – dort sind globale Eindeutigkeit und zeitliche Sortierbarkeit garantiert.

FAQ

Was passiert, wenn ein Zähler zum ersten Mal aufgerufen wird? Der Zähler wird automatisch angelegt und liefert den Wert 1 zurück. Eine vorherige Anlage ist nicht nötig.

Kann der Zählerstand zurückgesetzt werden? Ja, über die Verwaltungsseite mit dem Stift-Symbol. Bitte vorher prüfen, dass keine Doppelvergaben entstehen können.

Werden Werte verbraucht, wenn ein Prozess fehlschlägt? Ja. Der Zähler wird beim Aufruf von nextId erhöht – unabhängig davon, ob der Prozess später erfolgreich abschließt oder fehlschlägt. Lücken in der Nummernfolge sind also möglich.

Was ist der Unterschied zu sys_nextCounter? sys_nextCounter ist ein historischer Aliasname für dieselbe Funktion. Neue Templates sollten nextId verwenden, beide Varianten liefern aber identisches Verhalten.