DocumentIdAlias

What is DocumentIdAlias?

documentIdAlias is a fallback feature that allows documents to be found using an alternative identifier when the primary documentId doesn't match. This ensures that documents remain accessible even when ID formats change or during system migrations.

How It Works

When you try to access a document, the system:

1. First: Looks for the document using the provided ID as the primary documentId
2. If not found: Automatically tries the same ID as documentIdAlias
3. Result: Returns the document if found with either identifier

This happens automatically - no special configuration needed.

How to Use It

URL Access (Most Common)

The feature works seamlessly with the standard Fieldtec Web URL structure:

# Both of these URLs will work for the same document:
/form/primary-document-uuid
/form/legacy-document-123

Example: If a document has:

• documentId: "abc123-def456-ghi789"
• documentIdAlias: "legacy-123"

Then both URLs work:

• /form/abc123-def456-ghi789 ✅
• /form/legacy-123 ✅

For Users

Bookmarking & Sharing: Users can bookmark or share URLs using either ID format - both will work.

Navigation: When navigating to a document, you can use either ID format in the URL.

Transparent Operation: The fallback happens automatically - users don't need to know which ID format to use.

API Calls

// Standard API calls work with both ID formats
GET /api/documents/{documentId}

Common Use Cases

1. User-Friendly IDs

Documents can have both a system-generated UUID and a human-readable alias.

Document Structure

Documents can contain both fields:

{
    "documentId": "primary-uuid-12345",
    "documentIdAlias": "legacy-123",
    "systemHeader": {
        "currentVersion": true
    }
}

Important: Document-Level Only

documentIdAlias is only set on individual documents, not on templates.

How to Set documentIdAlias

You must set documentIdAlias manually on each document:

⚠️ Important: documentIdAlias must be unique across all documents. This uniqueness is not enforced by the system - it must be handled by the application developer.

Best Practice: Use a sc-reference-no component to define unique integer values for documentIdAlias.

Ensuring Uniqueness

Since the system doesn't enforce uniqueness, you must implement your own strategy:

1. Using sc-reference-no Component (Recommended)

// In your template, add a sc-reference-no component
// This automatically generates unique sequential numbers
const document = {
    documentId: "generated-uuid-12345",
    documentIdAlias: "123", // Generated by sc-reference-no component
    // ... other fields
};

2. Manual Uniqueness Check

Uniqueness Requirements

• Scope: Must be unique across ALL documents in the system
• Format: Can be any valid string format (alphanumeric + hyphens)
• Validation: Not enforced by the system - developer responsibility
• Collision Handling: If duplicate documentIdAlias exists, both documents will be found by the same URL

// When creating a document from template
const fieldValues = {
    name: "My Document",
    description: "Document description",
    documentIdAlias: "legacy-123" // Must be set manually
};

## Configuration

### Default Behavior
- **Enabled by default** - no configuration needed
- Fallback happens automatically when primary ID doesn't match

### Disabling the Feature
```javascript
const options = {
    disableDocumentIdAlias: true
};