Auto-Increment Fields
DXP 2024.Q1+/Portal 7.4 GA112+
Auto-Increment fields are configurable read-only fields for uniquely identifying object entries in a human-readable format. For example, an IT ticketing system should generate a unique but meaningful identifier for each ticket, so users can refer to each entry easily.
| Prefix | Starting Value | Suffix | Example Values |
|---|---|---|---|
| life- | 2000 | -ray | life-2000-ray life-2001-ray life-2002-ray … life-3048-ray |
| none | 0 | none | 0 1 2 … 256 |
| FOO- | 01 | none | FOO-01 FOO-02 FOO-03 … FOO-12 |
To add an auto-increment field, first enable its release feature flag. Go to Global Menu (
) → Control Panel → Instance Settings → Feature Flags. Open the Release section and enable Auto-Increment Field Type for Objects (LPS-196724).
You must configure the starting numeric value. Liferay adds 1 to this value for each subsequent object entry. Optionally, you can add a meaningful suffix and/or prefix to each numeric value.
When editing the field, you can change its label and configure how it’s searched.
Exporting and Importing Entries with Auto-Increment Fields
Object entries are imported and exported using the Data Migration Center, a batch client extension, or by calling the batch engine’s import/export task endpoints.
Exporting entries with auto-increment fields preserves the values in the exported JSON. When importing entries that contain auto-increment fields, you must carefully consider whether the data is compatible with the object definition’s existing entries.
Imported entries must have both unique External Reference Codes (ERCs) and unique auto-increment values.
| Unique ERC | Unique Auto-Increment Value | Successful Import |
|---|---|---|
| ✔ | ✔ | ✔ |
| ✘ | ✔ | ✘ |
| ✔ | ✘ | ✘ |
Not following this rule leads to inconsistent results. If you import entries with unique ERCs but overlapping auto-increment values, only entries with unique values import successfully:
| Existing Entries ERC/Auto-Increment |
Entries to Import ERC/Auto-Increment |
Import Result ERC/Auto-Increment |
|---|---|---|
| 11111/foo-01-bar 22222/foo-02-bar |
33333/foo-01-bar 44444/foo-02-bar 55555/foo-03-bar 66666/foo-04-bar 77777/foo-05-bar |
11111/foo-01-bar 22222/foo-02-bar 55555/foo-03-bar 66666/foo-04-bar 77777/foo-05-bar |
If you import entries that don’t follow the auto-increment format defined in the host system, only the values following the specified format import successfully:
| Existing Entries Valid Auto-Increment Values |
Entries to Import Auto-Increment Values |
Import Result Valid Auto-Increment Values |
|---|---|---|
| foo-01-bar foo-02-bar |
foo-003-bar foo-4-bar life-05-ray foo-04-bar foo-05-bar |
foo-01-bar foo-02-bar foo-04-bar foo-05-bar |
When you import entries, the highest numeric value in the system after the import becomes the value used to increment new field values.
If you import entries with no value in an auto-increment field, the system generates one according to the specified prefix/suffix format and uses the next numeric value in the series.
Using Auto-Increment Fields with APIs
When you make a GET request to return object entries with an auto-increment field, the value is returned as a JSON string:
"ticket" : "ticket-12"
To add an object definition field with the headless API, use a POST request body like this one, which defines this auto-increment field format: foo-01-bar, foo-02-bar, etc.
{
"businessType": "AutoIncrement",
"label": {
"en_US": "Able Ticket"
},
"name": "ableTicket",
"objectFieldSettings": [
{
"name": "initialValue",
"value": "01"
},
{
"name": "prefix",
"value": "foo-"
},
{
"name": "suffix",
"value": "-bar"
}
],
"required": false
}
See Managing Objects with Headless APIs for more information.