Jump to content

ICT:FinalConfig - Asset v2 configuration

From Costa Sano MediaWiki

Final Configuration for the Asset Entity – v2 (Automatic Identification & File Normalization)

Document revision: 2026-02-18 by Mngr

This document defines version 2 of the Asset entity. Asset v2 introduces automatic identifier generation and automatic file normalization, building on the validated Asset v1 structure and workflow.

Asset v2 is designed to be:

  • Deterministic
  • Archival
  • User-friendly
  • MediaWiki-compatible
  • Robust against partial failures

This document is normative.

1. Asset Concept (Normative)

An Asset represents the historical metadata of exactly one digital file (e.g. postcard, photograph, document).

  • One Asset = one File
  • The Asset and its File form an immutable couple
  • The Asset identifier and the File name are identical (except extension)
  • Assets may be recursive (derived versions, OCR, AI-enhanced, annexes, etc.)

The Asset identifier is the archival reference and must never change once created.

2. Identifier Scheme

The Asset identifier follows this pattern: 

<ChapterCode>-<ContextCode>-<SequenceNumber>

Where:

  • ChapterCode comes from Chapter.Code
  • ContextCode comes from either Place.Code OR Organisation.Code
  • SequenceNumber is a 4-digit number, incremented per (Chapter, Context) pair

Example: 

CH03-BER-0007

Sequence numbers:

  • are computed automatically
  • may have gaps
  • are never reused
  • are not guaranteed to be contiguous

3. User Workflow (Authoritative)

Asset creation is a single logical operation from the user’s point of view.

3.1 Create Asset

  1. User clicks “➕ New Asset” on Dashboard:Asset
  2. Asset form opens with no identifier
  3. User selects:
    • Chapter
    • Place OR Organisation (mutually exclusive)
  4. System computes the next available identifier
  5. The identifier is:
    • displayed to the user
    • assigned as the page name
  6. User fills remaining metadata
  7. User uploads exactly one file from their PC
  8. User clicks Save

3.2 Save Semantics

  • The file is NOT uploaded when selected
  • The file is uploaded only when Save is clicked
  • Asset page, File page, and Cargo row are committed together
  • If upload or save fails, nothing is committed

The identifier becomes final only after a successful Save.

4. File Handling and Normalization

4.1 Upload

  • File upload is performed through the Asset form
  • Special:Upload must not be used
  • Exactly one file must be uploaded per Asset

4.2 Automatic File Rename

After a successful save:

  • The uploaded file is automatically MOVED to:
File:<AssetIdentifier>.<extension>
  • The MOVE operation:
    • preserves file history
    • suppresses redirect creation
    • deletes the original filename
    • requires no user intervention

The Asset is updated to reference the renamed file if needed.

4.3 Failure Policy

If automatic file rename fails:

  • The Asset and File remain valid
  • The system may log the failure
  • A retry mechanism may be applied later

Rename is mandatory but not blocking.

5. Original Filename (Provenance Metadata)

To preserve provenance, the original local filename (as selected on the uploader’s PC) is captured and stored.

5.1 OriginalFilename Field

  • Stored as a String
  • Captured automatically at file selection time
  • Visible to the user
  • Informational only
  • Immutable after save

Example: 

Original filename: IMG_4587.jpg
System filename: CH03-BER-0007.jpg

5.2 Purpose

This field enables:

  • user confidence after upload
  • reconciliation with local PC files
  • reverse lookup queries
  • long-term archival traceability

6. Immutability Rules

After successful save:

The following fields MUST NOT change:

  • Asset identifier (page name)
  • Chapter
  • Place / Organisation
  • File
  • OriginalFilename

The following fields MAY change:

  • Description
  • Notes
  • Asset type
  • Asset source metadata
  • Parent asset relationships

Deletion of an Asset/File couple:

  • is exceptional
  • must be performed by a sysop
  • removes both Asset page and File page

7. Implementation Architecture (Summary)

7.1 Lua (Identifier Computation)

A Lua module computes:

  • next sequence number
  • formatted identifier

The module:

  • performs no writes
  • does not reserve numbers
  • accepts that numbers may be lost

7.2 JavaScript (Form Assistance)

JavaScript is used only to:

  • detect when Chapter and Context are selected
  • call the Lua module
  • set the page name
  • display the identifier
  • capture OriginalFilename
  • lock identifier/context fields after generation

JavaScript is not authoritative for file identity.

7.3 Server-side Automation

Automatic file MOVE is performed server-side:

  • after successful save
  • with redirect suppression
  • using a privileged execution context

8. Query and Discovery (Future Use)

The OriginalFilename field enables future query pages such as:

  • Find Asset by original filename
  • Reconcile local PC files with system Assets
  • Audit upload batches

These query pages are out of scope for this document.

9. Status

Asset v2 is fully specified.

Implementation may proceed step by step:

  • Lua module
  • JavaScript
  • Server-side MOVE hook

No data migration from Asset v1 is required.

Retrieved from "https://mwiki.costasano.club/index.php?title=ICT:FinalConfig_-_Asset_v2_configuration&oldid=1047"