Unique ID Custom Field

Create auto-generated unique identifier fields with sequential numbering and custom formatting

Unique ID custom fields automatically generate sequential, unique identifiers for your records. They're perfect for creating ticket numbers, order IDs, invoice numbers, or any sequential identifier system in your workflow.

Basic Example

Create a simple unique ID field with auto-sequencing:

mutation CreateUniqueIdField {
  createCustomField(input: {
    name: "Ticket Number"
    type: UNIQUE_ID
    useSequenceUniqueId: true
  }) {
    id
    name
    type
    useSequenceUniqueId
  }
}

Advanced Example

Create a formatted unique ID field with prefix and zero-padding:

mutation CreateFormattedUniqueIdField {
  createCustomField(input: {
    name: "Order ID"
    type: UNIQUE_ID
    description: "Auto-generated order identifier"
    useSequenceUniqueId: true
    prefix: "ORD-"
    sequenceDigits: 4
    sequenceStartingNumber: 1000
  }) {
    id
    name
    type
    description
    useSequenceUniqueId
    prefix
    sequenceDigits
    sequenceStartingNumber
  }
}

Input Parameters

CreateCustomFieldInput (UNIQUE_ID)

Parameter	Type	Required	Description
`name`	String!	✅ Yes	Display name of the unique ID field
`type`	CustomFieldType!	✅ Yes	Must be `UNIQUE_ID`
`description`	String	No	Help text shown to users
`useSequenceUniqueId`	Boolean	No	Enable auto-sequencing (default: false)
`prefix`	String	No	Text prefix for generated IDs (e.g., "TASK-")
`sequenceDigits`	Int	No	Number of digits for zero-padding
`sequenceStartingNumber`	Int	No	Starting number for the sequence

Configuration Options

Auto-Sequencing (`useSequenceUniqueId`)

true: Automatically generates sequential IDs when records are created
false or undefined: Manual entry required (functions like a text field)

Prefix (`prefix`)

Optional text prefix added to all generated IDs
Examples: "TASK-", "ORD-", "BUG-", "REQ-"
No length limit, but keep reasonable for display

Sequence Digits (`sequenceDigits`)

Number of digits for zero-padding the sequence number
Example: sequenceDigits: 3 produces 001, 002, 003
If not specified, no padding is applied

Starting Number (`sequenceStartingNumber`)

The first number in the sequence
Example: sequenceStartingNumber: 1000 starts at 1000, 1001, 1002...
If not specified, starts at 1 (default behavior)

Generated ID Format

The final ID format combines all configuration options:

{prefix}{paddedSequenceNumber}

Format Examples

Configuration	Generated IDs
No options	`1`, `2`, `3`
`prefix: "TASK-"`	`TASK-1`, `TASK-2`, `TASK-3`
`sequenceDigits: 3`	`001`, `002`, `003`
`prefix: "ORD-", sequenceDigits: 4`	`ORD-0001`, `ORD-0002`, `ORD-0003`
`prefix: "BUG-", sequenceStartingNumber: 500`	`BUG-500`, `BUG-501`, `BUG-502`
All options combined	`TASK-1001`, `TASK-1002`, `TASK-1003`

Reading Unique ID Values

Query Records with Unique IDs

query GetRecordsWithUniqueIds {
  todos(filter: { projectIds: ["proj_123"] }) {
    id
    title
    customFields {
      id
      customField {
        name
        type
        prefix
        sequenceDigits
      }
      sequenceId    # The generated sequence number
      text         # The text value for UNIQUE_ID fields
    }
  }
}

Response Format

{
  "data": {
    "todos": [
      {
        "id": "todo_123",
        "title": "Fix login issue",
        "customFields": [
          {
            "id": "field_value_456",
            "customField": {
              "name": "Ticket Number",
              "type": "UNIQUE_ID",
              "prefix": "TASK-",
              "sequenceDigits": 3
            },
            "sequenceId": 42,
            "text": "TASK-042"
          }
        ]
      }
    ]
  }
}

Automatic ID Generation

When IDs Are Generated

Record Creation: IDs are automatically assigned when new records are created
Field Addition: When adding a UNIQUE_ID field to existing records, a background job is queued (worker implementation pending)
Background Processing: ID generation for new records happens synchronously via database triggers

Generation Process

Trigger: New record is created or UNIQUE_ID field is added
Sequence Lookup: System finds the next available sequence number
ID Assignment: Sequence number is assigned to the record
Counter Update: Sequence counter is incremented for future records
Formatting: ID is formatted with prefix and padding when displayed

Uniqueness Guarantees

Database Constraints: Unique constraint on sequence IDs within each field
Atomic Operations: Sequence generation uses database locks to prevent duplicates
Project Scoping: Sequences are independent per project
Race Condition Protection: Concurrent requests are handled safely

Manual vs Automatic Mode

Automatic Mode (`useSequenceUniqueId: true`)

IDs are automatically generated via database triggers
Sequential numbering is guaranteed
Atomic sequence generation prevents duplicates
Formatted IDs combine prefix + padded sequence number

Manual Mode (`useSequenceUniqueId: false` or `undefined`)

Functions like a regular text field
Users can input custom values via setTodoCustomField with text parameter
No automatic generation
No uniqueness enforcement beyond database constraints

Setting Manual Values (Manual Mode Only)

When useSequenceUniqueId is false, you can set values manually:

mutation SetUniqueIdValue {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    text: "CUSTOM-ID-001"
  })
}

Response Fields

TodoCustomField Response (UNIQUE_ID)

Field	Type	Description
`id`	String!	Unique identifier for the field value
`customField`	CustomField!	The custom field definition
`sequenceId`	Int	The generated sequence number (populated for UNIQUE_ID fields)
`text`	String	The formatted text value (combines prefix + padded sequence)
`todo`	Todo!	The record this value belongs to
`createdAt`	DateTime!	When the value was created
`updatedAt`	DateTime!	When the value was last updated

CustomField Response (UNIQUE_ID)

Field	Type	Description
`useSequenceUniqueId`	Boolean	Whether auto-sequencing is enabled
`prefix`	String	Text prefix for generated IDs
`sequenceDigits`	Int	Number of digits for zero-padding
`sequenceStartingNumber`	Int	Starting number for the sequence

Required Permissions

Action	Required Permission
Create unique ID field	`OWNER` or `ADMIN` role at project level
Update unique ID field	`OWNER` or `ADMIN` role at project level
Set manual value	Standard record edit permissions
View unique ID value	Standard record view permissions

Error Responses

Field Configuration Error

{
  "errors": [{
    "message": "Invalid sequence configuration",
    "extensions": {
      "code": "BAD_USER_INPUT"
    }
  }]
}

Permission Error

{
  "errors": [{
    "message": "CustomField not found",
    "extensions": {
      "code": "CUSTOM_FIELD_NOT_FOUND"
    }
  }]
}

Important Notes

Auto-Generated IDs

Read-Only: Auto-generated IDs cannot be manually edited
Permanent: Once assigned, sequence IDs don't change
Chronological: IDs reflect creation order
Scoped: Sequences are independent per project

Performance Considerations

ID generation for new records is synchronous via database triggers
Sequence generation uses FOR UPDATE locks for atomic operations
Background job system exists but worker implementation is pending
Consider sequence starting numbers for high-volume projects

Migration and Updates

Adding auto-sequencing to existing records queues background job (worker pending)
Changing sequence settings affects only future records
Existing IDs remain unchanged when configuration updates
Sequence counters continue from current maximum

Best Practices

Configuration Design

Choose descriptive prefixes that won't conflict with other systems
Use appropriate digit padding for your expected volume
Set reasonable starting numbers to avoid conflicts
Test configuration with sample data before deployment

Prefix Guidelines

Keep prefixes short and memorable (2-5 characters)
Use uppercase for consistency
Include separators (hyphens, underscores) for readability
Avoid special characters that might cause issues in URLs or systems

Sequence Planning

Estimate your record volume to choose appropriate digit padding
Consider future growth when setting starting numbers
Plan for different sequence ranges for different record types
Document your ID schemes for team reference

Common Use Cases

Support Systems
- Ticket numbers: TICK-001, TICK-002
- Case IDs: CASE-2024-001
- Support requests: SUP-001
Project Management
- Task IDs: TASK-001, TASK-002
- Sprint items: SPRINT-001
- Deliverable numbers: DEL-001
Business Operations
- Order numbers: ORD-2024-001
- Invoice IDs: INV-001
- Purchase orders: PO-001
Quality Management
- Bug reports: BUG-001
- Test case IDs: TEST-001
- Review numbers: REV-001

Integration Features

With Automations

Trigger actions when unique IDs are assigned
Use ID patterns in automation rules
Reference IDs in email templates and notifications

With Lookups

Reference unique IDs from other records
Find records by unique ID
Display related record identifiers

With Reporting

Group and filter by ID patterns
Track ID assignment trends
Monitor sequence usage and gaps

Limitations

Sequential Only: IDs are assigned in chronological order
No Gaps: Deleted records leave gaps in sequences
No Reuse: Sequence numbers are never reused
Project Scoped: Cannot share sequences across projects
Format Constraints: Limited formatting options
No Bulk Updates: Cannot bulk update existing sequence IDs
No Custom Logic: Cannot implement custom ID generation rules

Text Fields - For manual text identifiers
Number Fields - For numeric sequences
Custom Fields Overview - General concepts
Automations - For ID-based automation rules