TABLE OF CONTENTS
Auto-Num is an advanced field type that allows a unique auto-number sequence to be generated using your own custom format.
Ideal for scenarios where a team of users is completing jobs/tasks out in the field or where unique company-wide purchase orders, invoices, tracking numbers, etc. are required.
Basically, a global format counter increments per form from multiple devices/users. This is a superior alternative to other methods of generating unique values like trying to base new values off values from a data source, which is not recommended.
Auto-Number values will always increment, with the incremental values continuing into subsequent Forms across all users. The number does not reset after a Form is submitted. Auto-Num is unsuitable for a variety of scenarios and it is important for you to read this entire article to ensure you are using it correctly.
If you are simply looking to create a unique identifier for each Form, and don’t necessarily need a sequential number, we recommend not using the AUTO-NUM field but rather using a read-only text or number field with something that the following formula or similar might produce:
FORMAT-DATE(NOW(),'MMddyyhmmss')
Note also that in order to function, Auto-Num fields must be on the first page of a Form and cannot be inside a table, repeating or otherwise.
Based on the above, Auto-Num is unsuitable for repeating items (such as repeating tables or repeating pages) that require an ordered list. For these cases, the Repeat/Row Position function POSITION({{table}}) is recommended.
The following Basic and Advanced Properties of this field type coupled with examples should give you a better understanding of how it can be used.
Basic Properties
Data Name
This is the name of the field that should be referenced in any form logic or API calls. Users will not see this name on the form.
Data names cannot contain spaces or any special characters other than an underscore and must begin with a letter. They are case-sensitive and must be referred to precisely whenever they are referenced.
Title Text
This is the name of the field that will be displayed to users on the app. This property is completely optional; while a field must contain a data name, a field title is optional.
The text color may be chosen with a hex code. The text may be also formatted as Bold or Italic and given a relative size -- Small, Medium (the default) or Large.
Hint Text
This optional field can be used to show secondary information to the user in the app. Consider using this to provide instruction or clarification to the user as they fill out the field.
Formatting options for this property are the same as those given available for the Title Text property.
Number Format
Define the format of this automatic number sequence using template syntax. Your format MUST include !NUM! – this is the sequence placeholder. Insert syntax in the text box or click the hammer icon to insert fields and functions using our Formula Builder.
Example | Syntax (Formula Builder | Generated |
Auto-num + Suffix | !NUM!-ORD | 0001-ORD |
Prefix + Field data-name + Auto-num | PO-{{category}}-!NUM! | PO-STOCK-0001 |
Contextual + Auto-num | {(USERLASTNAME())}-!NUM! | SMITH-0001 |
)A comprehensive list of syntax possibilities can be found here: Formula Cheat Sheet
Generate on Upload
This checkbox option determines whether the auto-number will generated at the time the form is opened or when the form is uploaded to the server. By default, the “Generate on Upload” box is unchecked, with Auto-Numbers being generated at the time the Form is opened. The user must be online for the Form to receive the next number. Checking the box “Generate on Upload” will give the Form a number when the Form hits the server. There are advantages and disadvantages to each method so please consider carefully whether to use “Generate on Upload.”
Not Using Generate on Upload
Leaving the “Generate on Upload” checkbox unchecked requires the device to have an internet connection at the time of capture, or at least prior to uploading the Form. The device will query the server for an Auto Number whenever the page is opened before allowing the user to continue onto other pages or submit the Form. If no network connection is present, the user can (optionally) save the Form as a draft and return to finish when a connection can be established. Whenever the user leaves and returns to the Form, for this or any other reason, the number will increment and be one higher than the previous unique number provided by the server. As a result, there may be gaps in the generated number sequence due to the previous number(s) having been generated but not included with an upload.
One advantage of not using “Generate on Upload” is that it grants users the capability to edit and re-submit previously uploaded Forms that have Auto Number fields, provided the "Users Can Edit Completed Entries” checkbox within the Form-level settings is checked. Though we do not recommend allowing users to edit entries after submitting them, in the event that you do use this option, you should not check “Generate on Upload” because a user who edits a Form and re-uploads it will over-write the previous number with no number at all.
Using Generate on Upload
If the “Generate on Upload” box is checked, the Auto-Num field will only create the next number in the sequence after the Form has been submitted and successfully uploaded to the server – not during Form entry. This allows users to complete all pages of a form in both online and offline scenarios, since no connectivity needs to be established to generate a number while completing the Form. The Auto-Num sequence will also be completely sequential on the backend, with no numbers being skipped.
The disadvantages to this option, however, are:
The Auto Numbers will not be visible to the user on the Form. They will only be visible on the backend, as well as on Form outputs like PDFs and emails.
Users will not have the capability to generate new Auto-Numbers when editing and re-submitting previously uploaded Forms. Any Auto Number captured on a re-submitted Form will yield a blank value on the output; thus, we deem “Generate on Upload” to be incompatible with “Users Can Edit Completed Entries.”
Generate on Upload and Workflows
When used in a process step workflow, an Auto-Number will behave differently depending on whether Generate on Upload has been used. We recommend always enabling Generate on Upload when placing an Auto-Number within a workflow for the reasons given below. If this makes the Auto-Number feature impractical for the form's use case scenario, consider an alternative unique identifier like the one suggested earlier in this article.
With Generate on Upload enabled:
- The generated number will be invisible to the user in the first stage of the workflow but be visible after it has been submitted to the next step.
- The generated number will remain constant throughout the workflow's various steps and will not change when the form moves to another process step.
With Generate on Upload disabled:
- The generated number will always be visible to the user, even when the form is first loaded.
- The generated number will not change when the form moves to another step, which maintains a single identifying number for the form entry.
Generate on Upload is recommended for these reasons.
AUTO-NUM | AUTO-NUM | |
Works Offline | No | Yes |
Compatible with Workflow* | Yes | Yes |
Compatible with Edit Entries | Yes | No |
First person can see number | Yes | No |
Subsequent people in a workflow can see number | Yes* | Yes |
May create gaps in numbers | Yes | No |
Sequence Padding
This dropdown determines the string length of the auto-number, with the system adding as many leading zeroes as necessary to achieve the length specified by the chosen integer. The available values range from 0-10. For example, if padding is set to 4, then a sequence value of '3' results in !NUM! being output as 0003.
Layout & Styling
Field Layout
This drop-down determines how this field is shown on the screen.
- Vertical places the Title and Hint vertically above the entry field.
- Horizontal will stack the entry field to the right of the Title and Hint text.
- Horizontal (Tablets Only) will use Vertical layout for phones and Horizontal for tablets.
Background Color
The color chosen in the hex code field here will apply to the field. The Transparent box can also be chosen instead for making this transparent instead of a solid color.
Advanced Properties
Sequence Uniqueness
This dropdown determines the uniqueness conditions for the numeric sequence of this auto-number.
- Unique per Entry
Every new entry of this Form will increment the sequence. - Unique per Format Result
Each distinct result of the formula is treated as a new sequence start. Format uniqueness is organization-wide, so the same sequence can drive auto-numbers in multiple Forms if these share the same formatting formula.
Example
Assume a number format of {{mychoice}}-!NUM! where mychoice is a Choices field with options of 'STOCK' and 'TIME'.
Number generation per option selected would look like:
Choice Selection | Unique per Entry | Unique per Format Result |
1st - STOCK | STOCK-0001 | STOCK-0001 |
2nd - TIME | TIME-0002 | TIME-0001 |
3rd - TIME | TIME-0003 | TIME-0002 |
4th - STOCK | STOCK-0004 | STOCK-0002 |
Sequence Start
This property determines the desired sequence and starting value for the automatic number. The first number to use for this sequence defaults to 1 if this is left bank
Note: Once a sequence has begun, setting a Sequence Start will have no effect. A starting value needs to be implemented prior to the initial testing of a field for the desired starting value to take effect!
Generate Message
The text displayed to the user when attempting to retrieve a new automatic number value.
Display Value
The default value/text displayed to the user prior to auto-number generation. Useful in "Generate on Upload" scenarios to display the number format that will be used - i.e., XXXX-ORD, or simply text informing the user when the unique number will be generated (e.g., "Generated on upload”).
Display Result to User
This checkbox option determines whether the user will see the auto-generated number on their screen. Note that with "Generate on Upload" enabled (see earlier in this article), the user will not be able to see the auto-number until the entry has uploaded to the server (i.e., during a workflow), even with this checkbox enabled.
Bind to Data Source Column
This property allows for the binding of the contents of the field to a data source that is linked to either a choices field or data field on the form. For details, please see the screenshot below:
- The data source can be selected with this dropdown. More than one will be available if multiple data source control fields (choices fields or data fields) have been added to the form.
- The data source control field can be selected from this dropdown. More than one will be available if multiple data source control fields for the same data source have been added to the form.
- The column on the data source to be bound can be selected from this dropdown.
Data Source binding allows you to create forms that can load data from, and update data to, any given data source. This opens up amazing opportunities to have dynamic data that is updated on the move (e.g., adding contacts or clients). For more information, please see this article.
Bind to Global Value
Global Values are a local key/value store that is available to any Screen on the app. Use this property to allow the user to view and save defaults for use across the app (e.g., a default project or customer). Please see this article for more information.
Exclude from Export/Display
By default, every field is displayed on Form entries in the Data area, and is included in non-templated exports (e.g., generic pdf, CSV, spreadsheet, database connectors). Use this property to prevent this field from showing on all such display and exports.
Is Personal Data
Indicates that data captured in this field may contain personal or sensitive data, which in turn can be anonymized when exported from the platform when then the "Anonymize Personal Data" option is checked on a form connector. Please see this article for more on this.
NOTE: Use of this option does not grant or imply additional security, protection and privacy of data.
FAQs
Below are some commonly-asked questions.
Q: Is it possible to have multiple Auto-num fields in one Form?
A: Yes, the sequence placeholder !NUM! is specific to an Auto-num field. This means that each field will sequentially increment respectively according to its format.
Q: How to restart a Unique per Entry sequence
A: Simply change the data-name property of the Auto-Num field in question. The sequence of this field will now start from 1 or a specified Sequence Start value.
Q: How to restart a Unique per Format Result sequence
A: Change the format in the following ways. Either by the order of text/value used with !NUM! or the value of a Choices field. E.g.,
- !NUM!-ORD > ORD-!NUM!
- !NUM!-{{mychoice}} > {{mychoice}}-!NUM!
- !NUM!-{{mychoice}} > !NUM!-{{mychoice}}
"STOCK" "STOCK1"
Note that changing symbols between !NUM! and the text/value won't reset the sequence. E.g.,
!NUM!-ORD > !NUM!_ORD
!NUM!-{{mychoice}} > !NUM!({{mychoice}})
Q: After testing a Form, will an Auto-Num sequence reset after publishing and selecting the option "Delete Entries and Proceed"?
A: No, if this is required. Please follow the above-mentioned solutions on restarting a sequence prior to publishing.