Document numbering

Document numbering gives new records an automatic, structured number such as INV-25102026-000001. A document setting decides what the number looks like for one entity, and a running counter remembers the last number used in each series. Numbers are written when a record is first saved. Nothing is renumbered later, so it pays to decide the format before people start creating records.

Overview

Two things work together:

• Document settings are the recipes. Each one names an entity, the field that receives the number, and how the number is built: a series prefix, a date part, a separator and a zero-padded running number. You manage them under Setup → Feature Hub → Platform → Document settings, or for one entity under Setup → Design Studio → Entities → (entity) → Document settings.
• Document numbers are the running counters, one per series. xMatix creates a counter the first time a series is used and moves it forward with every new record. You see and adjust the counters on the Document Numbers tab of a document setting.

xMatix ships with document settings for most transaction and master entities. Many are active from the start. For example, invoices are numbered INV-, orders SO- and partner onboarding applications PO-. A few are shipped switched off, such as the one for contacts. Those records keep the name the user typed.

When to use it

• You want your invoices, orders or other documents to follow your own numbering pattern, for example a yearly sequence instead of a daily one.
• Each branch or each company needs its own number range.
• You are moving from another system and the next number must carry on from where the old system stopped.
• A custom entity needs automatic numbers.
• You want a second generated value on a record, for example a partner code next to the record number.

How xMatix handles it

When a record is saved for the first time, xMatix looks for the active document settings of its entity and builds one value per setting:

series + separator + date part + separator + running number

1. Series. If the setting has a Series field and that field has a value on the record, the value is the series. Otherwise the Default series is used. If both are empty, the number starts with the separator.
2. Date part. The date comes from the Date field when it holds a date. Otherwise xMatix uses the creation date. Dates are taken in UTC, so a record saved shortly after midnight local time can carry the previous day's date. The Date format turns the date into text (see Date format tokens). An empty format gives the four-digit year.
3. Running number. xMatix takes the next number from the counter for series + separator + date part and pads it with zeros to the Number length.
4. Writing it. The value goes into the Destination field and replaces anything the user typed there. When the destination is the Name field, the record's Label gets the same value.

Each date gives its own counter

The counter belongs to the series together with the date part. SO-2026 and SO-2027 are separate counters, so a yearly format restarts at 1 every January. A monthly format restarts every month. A daily format restarts every day.

Most shipped settings use a daily format ({DD}{MM}{YYYY}). So as shipped, the first invoice of each day is INV-ddmmyyyy-000001. If you want one sequence for the whole year, change the date format to {YYYY}. To use no date at all, change it to a fixed text, such as a dash.

Counters are shared by series, not by entity

Counters are kept per organization, keyed only by the series text and the date part. Two settings that produce the same text share one counter, even on different entities, and their numbers interleave. The New and Edit dialog warns you when another active setting on the same entity uses the same series. It cannot warn you about other entities.

Numbers are taken at the last moment

Opening a New form takes no number, and a preview takes none either. On save, xMatix first works out the series and the date, and takes the running number just before the record is written. A save that is stopped by a validation, a business rule or a script does not use up a number. Deleting a saved record leaves a gap, because numbers are never handed out again.

Duplicates are skipped

Before it writes a number, xMatix checks that no saved record of the entity already holds that value in the destination field. If one does, for example after a counter was lowered or old records were imported in the same format, it moves on to the next number of the series. After 25 attempts in one save it stops and shows an error (see Common problems). This check covers the built-in entities. Custom entities are not checked this way.

Prerequisites

• Access to Setup → Feature Hub.
• To change a counter, edit permission on the Document Name entity. The shipped System Admin, Standard User, Sales Manager and Sales Executive security profiles have full access to it.
• Know which entity you are numbering, which field should receive the number, and which date the number should follow.

Procedure

Step 1 — Check what is already set up

1. Go to Setup → Feature Hub → Platform → Document settings. The list shows Name, Label, the source (standard or your own), Entity, Destination field, Default series, Date format, Number length, Active, Created and Modified.
2. Search for the entity, or filter on Active.
3. Select the name of a setting to open its detail page. The header shows Entity, Default Series, Date Format, Number Length and Status. The page has two tabs, Overview and Document Numbers.

If the entity already has an active setting for the field you want to number, edit that setting rather than adding a second one (Step 3).

Step 2 — Create a document setting

1. On the Document settings list, select New. The New document setting dialog opens.
2. Fill in Label. Name is filled in from the label. You can change it now, but not later.
3. Choose the Entity. Its fields become available in the field pickers.
4. Choose the Destination field, usually the Name field (labelled Document Number on orders and invoices).
5. Optionally choose a Series field and a Date field.
6. Enter the Default series, Date format, Number length and Separator.
7. Check Active. The switch is on by default in the dialog. Turn it off if you want to review the setting before it starts numbering.
8. Select Create. The setting appears in the list.

To add a setting for one entity, you can also open Setup → Design Studio → Entities, open the entity, and choose Document settings. There, the entity is already filled in and cannot be changed.

Step 3 — Change a setting

1. Open the setting and select Edit in the page header, or use Edit in the row's actions on the list.
2. Change the fields and select Save.

The change affects only records created after it. Changing the series or the date format changes the counter key, so the new pattern starts at 1 again. The old counter stays on the Document Numbers tab.

Standard settings. If your organization locks standard (shipped) metadata, a standard setting has no Edit or Delete on the list. Its dialog lets you change only Active and Default series, and a banner explains why. To change anything else, create your own setting for the same entity and destination field (Step 2), test it, then deactivate the standard one (Step 4).

Step 4 — Switch a setting on or off, or delete it

• Use Activate Document Setting or Deactivate Document Setting in the row's actions on the list. Only active settings number records. While a setting is off, new records keep whatever was typed in the destination field.
• Use Delete and confirm to remove a setting you no longer need. Records it numbered keep their numbers.

Keep one active setting per destination field. If two active settings write the same field, only one of them is used, and which one is not something you choose. Deactivate the one you don't want.

Step 5 — See the running numbers

1. Open the setting and select the Document Numbers tab.
2. The table lists one row per counter of the setting's entity: Name, Label, Series, Last number used, Created and Modified. Use the search box to find a series.

A counter appears only after the first record in that series is saved. A new setting shows No document numbers generated yet for this entity. until then. With a daily or monthly date format, a new row appears for each day or month.

Step 6 — Set the next number

1. On the Document Numbers tab, select the series name, or Edit last number used in its row.
2. In Edit last number used, enter the last number that has already been used. It must be 0 or more. The next record in the series gets this number plus one.
3. Select Save. The message Last number used updated for … confirms the change.

Raise a counter when you migrate from another system and want to carry on its numbering. Lower it only when the higher numbers are no longer in use. If you lower it below numbers that still exist, the built-in entities skip the taken numbers one at a time, but custom entities can end up with duplicate numbers.

Never delete a counter to "reset" a series. The next record would start again at 1.

Fields

Document setting

Date format tokens

Tokens are upper case and in curly braces. {FY}, {FYYY} and {YYYYFY} print the calendar year of the date. They do not follow your fiscal year.

Document number (running counter)

Business rules

• Numbers are generated only when a record is created. Editing a record, previewing it or changing a setting never renumbers anything.
• When a destination field will be numbered, you can leave it empty on a new record. The "required" check waits for the number.
• Numbering is worked out before the save's validations and business rules run. A Series field must therefore depend only on values typed, defaulted or mapped onto the record. It cannot depend on a value a business rule sets. A rule that runs before the save also cannot read the generated number. Use a rule that runs after the save.
• One record can be numbered by several settings, one per destination field. Each uses its own series and counter, unless their series text is the same.
• Two active settings for the same destination field: one is used and the other is ignored.
• Numbers for records saved together come as one consecutive block. Users saving at the same moment never get the same number.
• A save that fails before the record is written gives its number back. Deleting a record does not.
• A counter is shared by every setting and entity whose series and date part produce the same text.

Example

A distributor wants one invoice sequence per branch and year instead of the shipped daily INV- numbering. Its two branches have the Document Name Code values N1 and S1, and the partner account the invoices are issued under has GH. The invoice's Document Series field is calculated from the Partner Account's code followed by the Branch's code, so it gives GHN1 or GHS1.

1. The administrator opens Setup → Feature Hub → Platform → Document settings and finds the standard Invoice Document Name Setting: Default series INV, Date format {DD}{MM}{YYYYFY}, Number length 6, Separator -. The organization locks standard settings, so only Active and Default series can be changed.
2. They select New and create Invoice Number by Branch: Entity Invoice, Destination field Document Number, Series field Document Series, Date field Document Date, Default series INV, Date format {YYYY}, Number length 5, Separator -, Active on.
3. They deactivate the standard invoice setting, so that only one setting writes Document Number.
4. A test invoice for the north branch, dated 3 November 2026, is saved as GHN1-2026-00001. A south-branch invoice the same day becomes GHS1-2026-00001. An invoice with no branch code falls back to GH-2026-00001. With neither code it would get INV-2026-00001.
5. The old system's last north-branch invoice of 2026 was number 1834. On the Document Numbers tab they open the series GHN1-2026 and set Last number used to 1834. The next north-branch invoice is GHN1-2026-01835.
6. On 1 January 2027 the first invoice of each branch starts again at 00001 under the new keys GHN1-2027 and GHS1-2027.

Training

Practice exercise

In a sandbox, number a custom entity (or any entity whose numbering is switched off) with a yearly series:

1. Create a document setting with Default series TRN, Date format {YYYY}, Number length 4, Separator -, Destination field the Name field, Active on.
2. Create two records without typing a name.
3. Open the setting's Document Numbers tab and set Last number used to 100.
4. Create a third record.

Expected result: the first two records are named TRN-<this year>-0001 and TRN-<this year>-0002. The tab shows the series TRN-<this year> with Last number used 2, then 100 after your edit. The third record is TRN-<this year>-0101.

Quick reference

• Numbers are written on create only. Nothing is ever renumbered.
• Format: series, date part and running number, joined by the separator.
• Series field beats Default series. An empty Series field falls back to the Default series.
• Date tokens must be in braces and upper case: {DD}, {MM}, {YY}, {YYYY}.
• Every date part is its own counter. {YYYY} restarts yearly, and the shipped {DD}{MM}{YYYY} restarts daily.
• Settings with the same series text share one counter, even on different entities.
• Keep one active setting per destination field.
• To continue from an old system, raise Last number used. Never delete a counter.
• On a locked standard setting you can change only Active and Default series. For anything else, create your own setting and deactivate the standard one.

Permissions

• Document settings are part of Setup. Anyone who can open Setup → Feature Hub can see and manage them, subject to the standard-metadata lock described in Step 3.
• Document numbers (the counters) are records of the Document Name entity. Viewing the tab needs read access to it, and Edit last number used needs edit access. In the shipped security profiles, System Admin, Standard User, Sales Manager and Sales Executive have full access.
• Ordinary users never need access to settings or counters to get numbered records. Numbering runs as part of every save.

Configuration

See also Branches for the Document Name Code field.

Common problems

New records get no number

The setting is inactive, it has no Destination field, or it is for a different entity. Open the setting and check all three. Records created while it was off keep the name that was typed. If the destination is the Name field and the entity's New form has no Name field, the save fails with "Name is required" until numbering is active.

The number shows "yyMM" (or other letters) instead of a date

The date format was typed without tokens. Only {DD}, {MM}, {YY}, {YYYY}, {FY}, {FYYY} and {YYYYFY} are replaced. Everything else is copied as typed. Change the format to, for example, {YY}{MM}.

Numbering starts again at 1 every day

The date format includes the day (most shipped settings use {DD}{MM}{YYYY}), and each date part has its own counter. Use {YYYY} for a yearly sequence or {YY}{MM} for a monthly one. On a locked standard setting, create your own setting and deactivate the standard one.

Two kinds of document share one sequence

Their settings produce the same series text and the same date part, so they use one counter. Give each setting its own Default series, or a Series field value that differs.

The number ignores my Series field and uses the Default series

The Series field was empty on the record when it was saved, or a business rule fills it during the save, which is too late for numbering. If the Series field is calculated, check that its formula does not total child records, because those formulas are not supported. Make the series depend on values the record has when the user saves it.

"Document Number '…' already exists and the '…' series could not find a free number. Check the series counter."

xMatix tried 25 numbers in a row and each was already in use. This usually happens after a counter was lowered, or after records were imported that already use the same format. On the Document Numbers tab, raise Last number used above the highest number in use, then save again.

The Document Numbers tab is empty, or a series is missing

A counter is created only when the first record in the series is saved. A counter shared with another entity appears on the tab of the entity that used it most recently.

The date in the number is one day early

The creation date is taken in UTC. A record saved shortly after midnight in a time zone ahead of UTC gets the previous day's date. Set a Date field, such as the Document Date, to use the record's own date.

Common questions

Do existing records get renumbered when I change a setting?

No. Numbers are written only when a record is created. Records that already exist keep their numbers, and records created while a setting was inactive keep the value that was typed. Changing the series or the date format affects only records created after the change, and the new pattern starts a new counter at 1. The old counter is kept, so switching back carries on where it stopped.

Can I make numbering restart every financial year?

Not on a fiscal calendar. The {FY}, {FYYY} and {YYYYFY} tokens print the calendar year of the date, so {YYYY} and {YYYYFY} both restart on 1 January. If your financial year starts in April, you can change the Default series at the start of each financial year, for example from INV26 to INV27. Because the series text changes, numbering starts again at 1.

Can one record get two generated numbers?

Yes. Create one setting for each destination field, for example one for Document Number and one for a partner code. Each setting builds its own value, and each uses its own counter as long as the series texts differ. Two active settings that write the same field do not combine. Only one of them is used, so deactivate the one you don't need.

Will two users saving at the same time get the same number?

No. Each series hands out its numbers one block at a time, so users who save at the same moment get different numbers, and a batch of records saved together gets consecutive numbers. If a save fails before the record is written, its number is given back. Deleting a saved record leaves a permanent gap, because numbers are never reused.

Can I type my own number instead?

Not while a setting for that field is active. The generated value replaces whatever was typed when the record is first saved. On entities where you can edit the field later, you can change the number after the record is created. To let users type their own numbers, deactivate the setting.

Related topics

• Email templates and document numbering
• Branches
• Execution order
• Business rules
• Document Name entity reference
• Document Name Setting entity reference
• Administration guide