Skip to content

Counters

Counters generate sequential numbers in Pantarey – for example for invoice numbers, order numbers or ticket IDs. Each counter has its own name and a current value. On every call the value is incremented atomically by one and returned as a guaranteed unique value. This produces complete, traceable number ranges with no risk of duplicates.

What are counters used for?

  • Invoice numbers: INV-2026-0001, INV-2026-0002, …
  • Order numbers: ORD-1024, ORD-1025, …
  • Ticket IDs: T-501, T-502, …
  • Any sequential identifier in document names, business labels or process data.

Each counter name is its own number range. The invoice counter is independent of the order counter.

Use in templates and JSONata

Counters are called via the nextId function – both in templates (e.g. document name, business label) and in JSONata expressions (e.g. input mappings of service tasks).

Simple call

$fn('nextId', 'invoice')

Returns 1 on the first call, then 2, 3, … The name invoice is freely chosen.

Practical examples

Template Result
INV-$fn('nextId', 'invoice') INV-1, INV-2, …
INV-$fn('str_padStart', $fn('nextId', 'invoice'), 5, '0') INV-00001, INV-00002, …
2026-$fn('str_padStart', $fn('nextId', 'ticket'), 4, '0') 2026-0001
ORD-$fn('date_toGermanDate', $(today))-$fn('nextId', 'order') ORD-29.04.2026-42

Use in JSONata

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

Live preview in the JSONata editor

The JSONata editor (e.g. when editing input/result parameters) evaluates $fn('nextId', …) with mock values. Formats can be checked directly in the editor without starting the process.

Management in the "Counters" area

The Administration → Counters area lists all business-relevant counters used in Pantarey. For each counter the page shows:

  • Name: the counter name (e.g. invoice)
  • Current value: the most recently assigned value
  • Last changed: timestamp of the last change
  • Changed by: who last manually set the value (only for manual changes)

Setting the value manually

The value of a counter can be adjusted via the pencil icon. This is particularly useful in two situations:

  • Migration from a legacy system: The last invoice number from the previous system was 2917. The counter invoice is set to 2917 – the next call to $fn('nextId', 'invoice') then returns 2918.
  • Cleanup after testing: During process development, test numbers were issued that should not count in production.

Only reduce the value when no one is actively using the counter

If a counter value is set to a lower number, already issued numbers can be reissued. This leads to duplicates (e.g. invoice number INV-1024 issued twice). Before reducing the value always make sure that no processes using this counter are active.

Deleting a counter

Counters that are no longer needed can be removed via the trash icon. The next call to $fn('nextId', '<name>') with the same name will recreate the counter automatically and start at 1 again.

Key properties

  • Atomic: Even with many concurrent processes, every value is issued exactly once. There are no duplicates.
  • Persistent: Counter values are kept permanently – across deployments and tenant updates.
  • Tenant-isolated: Each tenant has its own counters. The invoice counter in tenant A has nothing to do with the one in tenant B.
  • Freely named: Any counter name is allowed as long as it does not start with __ (two underscores). These prefixes are reserved for internal platform counters and are not shown in the management area.

Tips

  • Use descriptive names: invoice_2026, order_roof, ticket_support – instead of seq1, seq2. This keeps it clear what a counter is used for.
  • Format with str_padStart: To make sorting (e.g. in file names) work correctly, counter values should be padded to a fixed length.
  • Use a new counter per year: To restart at 1 every year, anchor the year in the name: invoice_2026, invoice_2027, …
  • Don't use counters as IDs: For unique technical keys, $fn('sys_ulid') is more appropriate – global uniqueness and chronological sortability are guaranteed there.

FAQ

What happens when a counter is called for the first time? The counter is created automatically and returns the value 1. No prior setup is required.

Can the counter value be reset? Yes, via the management page using the pencil icon. Make sure beforehand that no duplicates can occur.

Are values consumed if a process fails? Yes. The counter is incremented when nextId is called – regardless of whether the process later succeeds or fails. Gaps in the number sequence are therefore possible.

What is the difference to sys_nextCounter? sys_nextCounter is a historical alias for the same function. New templates should use nextId; both variants behave identically.