li-unique-id

Added in: release-2024-11

Supported Features

Document✔
Media✗
Include✗
Document Creation Flow✔
Push Message✗
Table Dashboard✔
Display Filter✗
Search Indexing✔
System Metadata✗
Webhook Conditions✔

Description

The li-unique-id plugin is ideal for managing user-defined IDs or handles where uniqueness among values is required. The user interface is similar to an li-text field, but it includes additional validation properties:

  • Uniqueness: Ensures uniqueness among values within the same uniquenessScope per project.
    The uniquenessScope must not be updated, as doing so would break the uniqueness validation for new values. Changing it requires a manual database migration.
  • Format: Enforces the accepted input format using a regular expression.
  • Required: Ensures that a value is provided.

These validations are enforced only when publishing a document, meaning that uniqueness is guaranteed only for published values.

Scheduled publishing may fail if another document has claimed the unique value in the meantime. Use scheduled publishing with li-unique-id properties carefully to avoid conflicts.

Fetch Documents by li-unique-id

Deliveries can query the public API to find documents using their li-unique-id metadata property. Unlike document IDs, this approach allows the same identifier to be used across different environments (e.g., staging, production). When querying with the key metadata.<handle>.id and the value <uniquenessScope>.<uniqueId>, the li-unique-id metadata plugin ensures a single matching result.

const filters = JSON.stringify([
  {key: 'metadata.name.id', term: 'menu:main'}
])
const response = await fetch(`api/v1/publications/search?filters=${filters}`)

Storage Format

<String>

Content Type Config

{
  handle: 'myContentType',
  // ...
  metadata: [
    {
      handle: 'name'
      type: 'li-unique-id',
      config: {
        index: true,                // default: false
        hideFromForm: false,        // default: false
        required: true,             // default: false
        requiredErrorMessage: '',   // default: "The field '{label}' is required"
        // Regular expression the value must match
        regex: '^[a-zA-Z0-9\\-]+$', // default: undefined
        regexErrorMessage: '',      // default: "{label} does not match the required format"
        // Defines the scope within which the value must be unique. Uniqueness
        // is enforced across all values sharing the same uniquenessScope
        uniquenessScope: 'menu'     // required, must not be updated
      },
      ui: {
        label: 'Name',              // default: "{handle}"
        config: {
          placeholder: 'Name',      // default: "{label}"
          readOnly: true            // default: false
        }
      }
    }
    // ...
  ]
}