Counters – running numbers for records¶
A counter hands out running numbers: ticket numbers, invoice numbers, order numbers. This chapter describes how counters are set up, how numbers are drawn and formatted, what happens when many users draw numbers at the same time, and how a counter is reset.
It is intended for administrators who design numbering schemes.
1. Counters at a glance¶
A counter is a definition that stores a current value. Every time a counter expression is evaluated, the counter adds its increment and returns the new value – the next number.
| Part | Where | What it does |
|---|---|---|
| Counter | Admin Studio → Automation → Counters | Defines the start value, the increment and an optional automatic reset |
| Counter expression | An expression of the type "Counter" | Draws the next number from a counter |
| Business rule or action | Where the number is needed | Writes the number into a field, typically the "Public ID" of the entity |
Summary¶
- Every evaluation of a counter expression uses up a number, unless "View Only" is on. Numbers are never given back, so gaps are normal.
- Numbers are drawn safely in the database: two users never get the same number, also with several servers – including the very first number and the number after an automatic reset.
- A counter returns a whole number. Prefixes, years and leading zeros come from a text expression around it.
- An automatic reset is applied when the next number is drawn, not at a fixed time.
2. Setting up a running number¶
Example: Tickets should get numbers like T-000042.
- Create the counter. In Admin Studio → Automation → Counters, choose "Add". Name it "Ticket number", "Initial Value" 0, "Increment" 1. Save.
- Create a field for the number, for example the String field "Ticket number" in the entity "Ticket", and select it as "Public ID" of the entity (see Entities and fields).
- Create the counter expression. An expression of the type "Counter" with "Counter" "Ticket number".
- Format the number. A text expression that writes
T-followed by the counter expression, padded to six digits with the value modification rule "PadLeft" (see Expressions). - Write it into the field with a business rule or an action step that runs once per ticket (see section 4).
The first ticket gets T-000001, the next T-000002.
3. Settings¶
The counter¶
| Setting | Meaning | Default |
|---|---|---|
| "Display Name", "Description", "Tags" | Name and documentation | – |
| "Initial Value" | The value before the first number. The first number is "Initial Value" plus "Increment". | 0 |
| "Increment" | What is added for every number, usually 1. Must not be 0 – a counter with increment 0 returns an empty value. | 0 |
| "Scoped" | A separate running number per scope key, see section 7 | off |
| "Auto Reset" | Reset the counter automatically, see section 6 | off |
| "Frequency" | How often the counter is reset. Only with "Auto Reset". | None |
| "Reset Value" | An expression that returns the value the counter is reset to, for example 1. Only with "Auto Reset". Without it, nothing is reset. | empty |
| "Day of Week", "Day of Month", "Day of Year" | The day of the reset, depending on "Frequency" | – |
Note that "Increment" starts at 0. Set it to 1 when you create a counter.
The counter expression¶
| Setting | Meaning | Default |
|---|---|---|
| "Counter" | The counter that hands out the number | – |
| "Scope" | An expression that returns the scope key. Only shown for a scoped counter. | – |
| "View Only" | Returns the current value without drawing a number – to show the last number drawn | off |
4. How numbers are drawn¶
- Each evaluation of a counter expression without "View Only" draws the next number and returns it as a whole number.
- The preview in the editors shows the current value and draws no number.
- A number that was drawn is used up – also when the record it was meant for is never saved. Gaps are therefore normal.
Use counter expressions only where they run exactly once per record. Do not use them in a caption, a grid column, a form display or a condition: every display would draw a number.
A default value rule on the number field draws the number as soon as a new record is created – before it is saved. A user who opens "New ticket" and cancels uses up a number. If gaps matter, draw the number later, for example in an action that runs when a new record is saved (see Business rules).
5. Many users at the same time¶
The number is drawn in a single step in the database, which processes simultaneous requests one after another. Two users – or two servers, or a user and a scheduled action – who draw at the same moment get different numbers.
This also applies to the very first number of a counter or of a scope key, and to the number that triggers an automatic reset (section 6): the reset is applied exactly once, and the numbers drawn right after it continue from the reset value.
A counter with an automatic reset hands out the same numbers again after every reset – that is its purpose. Combine such a number with the date or the period in a text expression, and add a unique index on the number field (see Entities and fields, section 6) if a duplicate must be refused when the record is saved.
6. Automatic reset¶
With "Auto Reset", the counter starts again at the "Reset Value" at the chosen frequency.
| "Frequency" | Reset |
|---|---|
| "Every Hour" | see section 10 |
| "Every Day" | With the first number of each new day |
| "Every Week" | With the first number on or after the chosen "Day of Week" |
| "Every Month" | With the first number on or after the chosen "Day of Month". In a month without that day – the 31st in April, the 29th to 31st in February – on the last day of the month. |
| "Every last day of the Month" | With the first number drawn on the last day of a month |
| "Every Year" | see section 10 |
How the reset works:
- The reset is checked when a number is drawn. Nothing happens at midnight by itself – the first number after the reset date triggers it.
- The number that triggers the reset is the reset value itself. With "Reset Value" 1, the first number after the reset is 1, the next one 2.
- Days are determined in UTC. In Central Europe, a new day starts for the counter at 1:00 or 2:00 local time.
- "Every last day of the Month" only resets if a number is drawn on the last day of the month. A month in which no number is drawn on its last day is not reset.
Example: Invoice numbers per day, "Every Day", "Reset Value" 1. The first invoice on 3 March
gets 1, the second 2. The first invoice on 4 March gets 1 again. Combine the number with the date in a
text expression – 2026-03-04/1 – so that numbers stay unique.
7. Scoped counters¶
A scoped counter keeps a separate running number per scope key – for example per customer, per department or per year. The key is computed by the "Scope" expression of the counter expression. Every key starts at "Initial Value" and counts on its own; an automatic reset applies to each key separately, with the first number drawn for that key after the reset date. A scoped counter used without a scope key, or with one that is empty, returns an empty value and draws no number.
Example: Scope key = the year of the creation date. Tickets of 2026 and of 2027 each count from 1.
Scope keys are compared as text. With the usual settings of the database, upper and lower case are
not distinguished: abc and ABC share one running number.
8. Changing the current value¶
To continue numbering at a certain value – after taking over data from an earlier system, for example – change the current value of the counter:
- Open the management view of the counters – Admin Studio → Automation → Counters.
- Select the counter and choose "Change Value".
- Enter the new current value, a whole number. The next number is this value plus the "Increment".
This requires the permission "Reset Counter Value".
- The new value takes effect immediately, also while a sketch is open. The current value is not part of the definition of the counter and is never collected in a sketch.
- Before the first number has been drawn, the dialog shows "Initial Value". The value you enter is used from then on.
- It is not possible for scoped counters ("Changing the value is not supported for scoped counters.").
- A value that is not a whole number is rejected, and the current value stays as it is.
Changing "Initial Value" in the editor has no effect on a counter that has already handed out numbers.
9. Permissions¶
| Permission | Allows |
|---|---|
| "Open Counter Manager" | Seeing the counters |
| "Add Counter", "Edit Counter", "Delete Counter" | Creating, changing and deleting counters |
| "Reset Counter Value" | "Change Value" (section 8) |
All of them are part of "System Administrator".
10. Limitations¶
- "Every Hour" currently resets only once per day, with the first number of a new day.
- "Every Year" currently ignores "Day of Year" and resets much more often than once a year. Do not use it. For yearly numbering, put the year into the number with a text expression instead of resetting the counter.
- "Change Value" is not available for scoped counters (section 8).
- Int64 fields hold at most 2,147,483,647 in the database (see Field types). A counter can count higher, but such a number does not fit into an Int64 field.
- A drawn number is never given back (section 4).
11. Frequently asked questions¶
Why does my counter return nothing? Most often "Increment" is still 0. Other causes: a scoped counter without a scope key, or "Auto Reset" on without a "Reset Value" expression.
Why are there gaps in my numbers? Every evaluation draws a number, also for records that are never saved and in expressions that are evaluated more often than expected. See section 4.
Can two records get the same number? Not from the same counter and scope key – except after an automatic reset, which starts the numbers again on purpose (section 5). A unique index on the field prevents duplicates from being saved.
Does deleting a record give its number back? No.