Number generator
Content is published on https://docs.folio.org/docs/settings/settings_service_interaction/settings_service_interaction/ as well.
Functional for Pattern number in Serials Management and Publication request number in Open Access
Sunflower: Accession number, Call number, Item Barcode, Vendor Code
Trillium: User Barcode, Item Barcode (Fast Add)
Please note: the number generators for accession number, call number, item barcode, vendor code, users barcode are the only ones supported at this point using this concept.
New number generator functionality for additional fields cannot be integrated though the Service interaction UI via New alone. It requires development work.
Information on Using Number generators within Apps at the end of this page
Settings > Service interaction
The Service interaction section of the Settings App is where you can configure central settings like the number generators and number generator sequences.
For enabling number generators for Apps like Inventory, Receiving, Organizations, Users please view descriptions in those Settings areas. Number generators need to be enabled separately and in addition FOLIO users need permissions listed below.
Permissions / Capability sets
In order to interact with Service interaction settings, a user needs to be assigned the following permissions:
permissionDisplayName (Okapi) | Capability Set (Eureka) | Type | Application | Action | Descriptions |
|---|---|---|---|---|---|
Settings (service-interaction): display list of settings pages | Settings Service-Interaction Enabled | Settings | app-platform-complete (Sunflower) app-service-interaction (Trillium) | view | This permission/capability set allows the user to view Settings > Service Interaction |
Settings (Service-interaction): View number generator settings and use number generators within apps | UI-Service-Interaction NumberGenerator | Data | app-platform-complete (Sunflower) app-service-interaction (Trillium) | view | This permission/capability set allows the user to view the number generators and number generator sequences settings (Service interaction) and allows the user to generate numbers within apps. |
Settings (Service-interaction): Manage number generator settings and use number generators within apps | UI-Service-Interaction NumberGenerator | Data | app-platform-complete (Sunflower) app-service-interaction (Trillium) | manage | This permission/capability set allows the user to manage (view, create, edit, delete) the number generators and number generator sequences settings (Service interaction) and allows the user to generate numbers within apps. |
OKAPI
In order to view or manage settings user needs to be assigned Settings (service-interaction): display list of settings pages and either Settings (Service-interaction): View number generator settings and use number generators within apps or Settings (Service-interaction): Manage number generator settings and use number generators within apps.
In order to generate numbers within apps in addition to the appropriate create and edit permissions for the individual apps user needs to be assigned Settings (Service-interaction): View number generator settings and use number generators within apps or Settings (Service-interaction): Manage number generator settings and use number generators within apps. This applies for the use of number generators in Inventory, Receiving, Organizations as well as Serials Management and Open Access.
EUREKA
In order to view or manage settings user needs to be assigned Settings Service-Interaction Enabled and UI-Service-Interaction NumberGenerator either with Action view or manage.
In order to generate numbers within apps in addition to the appropriate create and edit capabilities for the individual apps user needs to be assigned UI-Service-Interaction NumberGenerator either with Action view or manage. This applies for the use of number generators in Inventory, Receiving, Organizations, Users as well as Serials Management and Open Access.
Settings > Service interaction > Number generators
New number generators need frontend and backend development work to integrate them with FOLIO apps. In this case use New to create a row for the new number generator to match with the development work.
The following number generators are available. In case the reference data is not included in your FOLIO environment please add the corresponding row (Name + Code) via New and store by clicking "Save". Especially important are the exact codes as indicated in the following table as identifiers of the number generators.
Please note: the number generators below are the only ones supported at this point using this concept. New number generator functionality for additional fields cannot be integrated though the Service interaction UI via New alone. It requires development work.
Name | Code | Descriptions | Type |
|---|---|---|---|
Inventory: Accession number
| inventory_accessionNumber | Used for Accession number in Inventory as well as in Receiving (Item level) | A |
Inventory: Call number
| inventory_callNumber | Used for Call number on Item level in Inventory as well as in Receiving and in addition in Inventory on Holdings level | A |
Inventory: Item barcode
| inventory_itemBarcode | Used for Item Barcode on Item level in Inventory as well as in Receiving and in addition in fast add | A |
Open access: Publication request number | openAccess | Used as identifier "Publication request number" in the Open Access App
| B |
Organizations: Vendor code
| organizations_vendorCode | Used for Code in Organizations
| A |
Serials management: Pattern number | serialsManagement_patternNumber | Used as identifier "Pattern number" in the Serials Management App
| B |
Users: Patron barcode
| users_patronBarcode | Used for User barcode in Users
| A |
Type A:
One or more sequences possible to select from when create or edit records and using the number generator
Sequences need to be defined before use at Settings > Service Interaction > Number generator sequences
Type B:
Number automatically assigned to the record defined by one sequence
If reference data is not included in your FOLIO environment, one sequence with the following code needs to be defined before use at Settings > Service interaction > Number generator sequences or sequence might be changed to your requirements
Number generator | Code of sequence |
|---|---|
Open access: Publication request number | requestSequence |
Serials management: Pattern number | patternNumber |
The display in Service interaction > Number generators can be used as overview of possible number generators and the count of sequences:
Name. The display label of the number generator. Used to group number generator sequences, and select from them in certain circumstances. Naming recommendation: App: Field e.g. Inventory: Accession number
Code. A unique string representing the number generator for technical purposes. Must not contain whitespaces. Once set, this field can no longer be changed. Naming recommendation: app_field e.g. inventory_accessionNumber
Sequences. The count of the number of sequences assigned to this generator in Settings > Service interaction > Number generator sequences.
Click the pencil icon under Actions to edit the name.
Click the trash can icon under Actions to delete the row for a number generator. Only available if no sequences are assigned. This number generator is then no longer functional.
Settings > Service interaction > Number generator sequences
A sequence of a number generator defines how the number will be generated and then displayed by settings of several values.
To select a number generator for managing its number generator sequences use the drop-down menu Generator. In the section Sequences existing number generator sequences will then be displayed or made searchable.
In case the reference data is included in your FOLIO environment example sequences are defined. Please delete or change according to your own requirements.
Creating new number generator sequences
Select the Generator in the drop-down menu for which sequences should be created
In the Number generator sequences pane, click New.
In the New sequence window enter
Name. Name of the number generator sequence. In cases where a selection from number sequences is required, this name will be displayed in the window for generating a new number. This field is editable.
Code. Unique code of the number generator sequence. This must be unique within the number generator and contain no whitespaces. Once set, this field can no longer be changed.
Enabled. An enabled number generator sequence will be displayed when selecting the sequence in the App UI. A sequence with the status false will not be displayed in the App UI until it is enabled again.
Note. Description or information about this sequence can be entered here e.g. disabled sequence because of this reason
Sequence settings
Maximum value. This is the maximum possible value for the sequence. When the maximum is reached, the sequence will no longer be usable.
Warning threshold value. When set, a warning will be displayed to users of the sequence when its value is reached. Must be lower than the maximum value.
Next value. This field shows the next value in the sequence based on the current value in the database. It can be set manually as the starting value for a new sequence.
Format. The Format field supports optional padding, while the Maximum value field defines the length of the generated incremental number (excluding the check digit, prefix and suffix)
Use # for digits without padding (e.g., #### for four digits).
To add padding, specify the character. E.g., 0000 for leading zeros, resulting in outputs like 0045.
If a Maximum value is set, the Format length must match it. The maximum value field enforces the length of the field, e.g. the maximum value of 9999 indicates a maximum length of four characters and must be paired with a matching format value, e.g. #### or 0000.
Checksum settings
Method. The checksum method for the check digit. Use the checksum input template to define what needs to be included in the calculation e.g. prefix or suffix.
Input template. Create rules to define the number to be inputted when calculating the check digit. Both the prefix and suffix can be templated, using Groovy markup. Use ${generated_number} as placeholder for the generated number. E.g. 05${generated_number}01
Output settings
Output template. The output template defines the rules applied to create the sequence. Templates are formed using Groovy. See below for more information.
4. Once you have included all of the information you want about the sequence, click Save & close. A confirmation message appears, and the sequence is saved and appears in the Number generator sequences table.
Checksum settings
Method
Select “None” for no checksum calculation.
Methods for calculating check digits differ in weighting, direction, calculation like mod10 or mod11, calculation of remainder and other factors.
Additionally some methods are named after its creator e.g. Luhn, others may be named after the number which is generated e.g. ISSN. Those methods can be used to generally generate numbers not related to numbers they are named after.
Name | Weighting | Direction | mod10/mod11 | Remainder | Additional information | Length |
|---|---|---|---|---|---|---|
21-RTL-mod10-I (Luhn) | 21 | right to left | weighted values greater than 9 have 9 subtracted mod10 | (I) 10-remainder = check digit | Luhn / Double-Add-Double | scalable |
31-RTL-mod10-I (EAN) | 31 | right to left | mod10 | (I) 10-remainder = check digit | Method is used for the European Article Number (EAN) / ISBN13 | scalable |
12-LTR-mod10-R | 12 | left to right | mod10 | (R) remainder = check digit |
| scalable |
1793-LTR-mod10-R | 1793 | left to right | mod10 | (R) remainder = check digit |
| scalable |
8765432-LTR-mod11-I-X (ISSN) | 8765432 | left to right | mod11 | (I) 11-remainder = check digit result = 10 → check digit = X | Method is used for ISSN pattern for calculation: 8-7-6-5-4-3-2-1-0-10-9-8-... | 7 + check digit scalable |
2345678910-RTL-mod11-I-X (ISBN10) | 2345678910 | right to left | mod11 | (I) 11-remainder = check digit result = 10 → check digit = X | Method is used for ISBN10 pattern for calculation: ...-14-13-12-11-10-9-8-7-6-5-4-3-2 | 9 + check digit scalable |
Input template
In those cases where the prefix and/or suffix needs to be included in addition to the sequential number generated into the calculation it can be defined via the field input template. Use ${generated_number} as placeholder for the generated number.
Examples
Included in calculation | Example |
|---|---|
no prefix/suffix | ${generated_number} |
prefix | 05${generated_number} 358${generated_number} |
suffix | ${generated_number}01 ${generated_number}1 |
prefix and suffix | 05${generated_number}01 358${generated_number}2 |
Output settings
Output template defines the rules applied to create the sequence.
Please use Maximum value for the length and Format for padding.
Prefix and/or suffix can be included in the output template. (space characters are allowed)
In case the prefix or suffix includes $ please use \$ for displaying $
Use ${generated_number} for the sequential generated number
to include the check digit (calculation defined by method and input template) use ${checksum}
Examples
Output template | Maximum value | Format | Next value | Display of number |
|---|---|---|---|---|
2025-ABC ${generated_number} | 999 | 000 | 1 | 2025-ABC 001 |
2025-ABC ${generated_number} | 999 | ### | 1 | 2025-ABC 1 |
A1/${generated_number}-B | 9999 | 0000 | 51 | A1/0051-B |
\$ABC ${generated_number} | 99999 | 00000 | 7 | $ABC 00007 |
\$ABC ${generated_number} | 99999 | ##### | 7 | $ABC 7 |
1 N ${generated_number}: 2013 | 9999 | 0000 | 325 | 1 N 0325: 2013 |
${generated_number}-${checksum} | 9999 | 0000 | 45 | 0045-5 |
A${generated_number}${checksum} | 9999 | 0000 | 45 | A00455 |
05${generated_number}01${checksum} | 9999 | 0000 | 45 | 050045012 |
Depending on the method selected check digits are calculated differently. In those examples check digits are examples.
Searching and viewing number generator sequences
Select the number generator in the drop-down menu Generator
To search for number generator sequences for a number generator, enter your search term in the search box in the section Sequences and click Search. The search box searches through the Name and Code fields. In order to limit your search to specific fields, check or uncheck one or more of the Name, Code, Note and/or Output template check boxes below the search box, and the search will only search through the selected fields.
You can also filter on Enabled and Usage status. For more information on the filters, see the filter descriptions below.
Results are listed in a table with pagination of 25. Use the buttons previous or next to display other pages. Number of results can be found at the right top corner of the result table.
To sort by a column, click the column name.
To view details of a sequence in the 4th pane, click on the name of the sequence in the first column.
Enabled
To filter sequences by enabled, select one of the following:
All. All enabled and disabled sequences.
True. Enabled sequences, which are displayed for selection in the window of the App UI
False. Disabled sequences, which are not displayed for selection in the window of the App UI.
Usage status
To filter sequences by Usage status, select one of the following:
All. All values are displayed
At maximum. Maximum value is reached. Sequence is no longer available for generating numbers.
Below threshold. Below warning threshold value, defined in sequence configuration for displaying warnings if desired.
Over threshold. Between warning threshold value and maximum value, defined in sequence configuration if desired.
No threshold set. No warning threhold value was set.
Editing number generator sequences
Select number generator in drop-down menu Generator.
Search for the sequence and click on name of sequence in the left column of the table to open the detail view in the 4th pane.
To edit the sequence click Edit in Actions menu in the 4th pane
Window Edit sequence will be displayed
Edit sequence and Save & close or Cancel
Apart from the code of the sequences you can edit all other content in the edit sequence window - please be aware that changing content in edit sequences has impact on numbers being generated from this sequence in the future (e.g. it could cause duplicates or different length)
Comments
Hi @Lynne Fors. I think @Martina Tumulla is planning on adding some tips and tricks help documentation so this may be good feedback to take into account.
Hi @Lynne Fors thank you for your feedback.
Will there be supplemental screenshot examples of properly configured number generator sequences? While this documentation is thorough, it is confusing for the general end user attempting to set up number generators. I would suggest adding that the number generators listed are the only ones supported and you cannot create your own names for them. Number sequences are the only place to create locally named number generators.