Costasano Heritage Project — Asset Caption & Code Refactoring

Purpose of this Document

This document describes a proposed refactoring of the Asset ingestion workflow in the Costasano Heritage Project.

The goals of the refactoring are:

eliminate duplicate typing during Asset creation
ensure every Asset receives a meaningful short description
simplify the workflow for contributors (70+ amateur historians)
clarify the conceptual distinction between identifier and description
remain fully compatible with the architectural blueprint

This change affects:

Media entities
the Asset entity
the Asset creation workflow
the custom Drupal automation module

The change does not affect:

identifier generation logic
the global counter
file storage
the authority entities (Chapter, Place, Organisation)

---

Conceptual Model

The archive distinguishes three levels of textual description. The archive distinguishes three levels of textual description.

The archive distinguishes three levels of textual description.

Field	Meaning	Typical Length	Source
Code	System‑generated archival identifier	fixed	system
Caption	Short human‑readable label of the asset	short	user
Description	Detailed contextual explanation	long	user

Example record:

Code: CH03-OOSTEN-00007
Caption: Construction of harbour bridge
Description:
Photograph taken during the installation of the steel beams of the
Oostende harbour railway bridge during the harbour expansion works of 1934.

In Drupal terminology:

Title field  → Caption
Description field → Long description

---

Current Implementation

The current workflow is:

Upload media file
    ↓
Enter Media name
    ↓
Fill Asset Title (labelled Code)
    ↓
Save Asset

Problems with this model:

the Media Name and Asset Title represent the same concept
users must type the caption twice
the two values may diverge
the interface is unnecessarily complex

---

Target Model

The system will distinguish clearly between:

Field	Purpose	Editable
Code	Archival identifier	No
Caption	Short human‑readable description	Yes
Description	Detailed explanation	Yes

|

The Caption will use the Drupal Title field.

The identifier will move to a dedicated field.

---

Resulting Data Structure

Asset entity fields:

Caption (Drupal Title field)
Code (field_as_code)
Counter
Chapter
Place / Organisation
Media
OriginalFileName
Description
Notes

Media entity fields:

Name (caption)
File
Metadata

Relationship:

Asset
  → Media
        → File

Example Asset:

Code: CH03-OOSTEN-00007
Caption: Construction of harbour bridge
Description: Photograph taken during installation of steel beams...

---

Proposed Ingestion Workflow

New workflow:

Upload file
    ↓
Enter Media Name (caption)
    ↓
Create Asset
    ↓
System copies Media Name → Asset Caption
    ↓
System generates Code

The caption is therefore entered once during media upload.

---

Behaviour Rules

1. Media Name must be mandatory. 2. Caption is automatically populated when the Asset is created. 3. Caption is copied only during initial creation. 4. Later edits of Media must not overwrite the Caption. 5. Users may edit the Caption afterwards. 6. The Code field is system-generated and immutable.

---

Migration Strategy

The current system already includes:

Asset entity
Media upload
automatic identifier generation
automatic filename capture

The following steps migrate the system to the new model.

---

Step 1 — Rename the Title Label

Location:

Structure → Content types → Asset → Edit

Change the Title label from:

Code

to:

Caption

The internal machine name remains:

title

Existing values remain unchanged.

---

Step 2 — Create the Code Field

Add a new field to the Asset content type.

Configuration:

Label: Code
Machine name: field_as_code
Type: Text (plain)
Cardinality: 1
Required: No

This field will contain the archival identifier.

---

Step 3 — Adjust the Custom Module

Modify the automation module.

Old behaviour:

$entity->setTitle($identifier);

New behaviour:

$entity->set('field_as_code', $identifier);

All other logic remains unchanged:

counter generation
filename extraction
immutability rules

---

Step 4 — Make Media Name Mandatory

For each Media type:

Structure → Media types → [Media type] → Manage fields

Edit the field:

Name

Enable:

Required

Media types to update:

Image
Document
Video
Audio

---

Step 5 — Copy Media Name to Caption

Extend the custom module with logic:

If Asset is new AND Caption empty
    read Media Name
    copy Media Name → Caption

This ensures the Caption is filled automatically.

---

Step 6 — Adjust Asset Form Display

Reorganize the Asset form fields:

Media
Chapter
Place / Organisation
Caption
Description
Notes

Hide system fields:

Counter
Code
OriginalFileName

---

Step 7 — Adjust Dashboard Views

Update Asset dashboards to display:

Code
Caption
Chapter
Context

This keeps Assets recognizable in listings.

---

Step 8 — Validate Existing Records

After implementation verify:

Code field populated correctly
Caption preserved
Identifier generation working
Media linkage unaffected

No database migration is required because the Title field is only relabelled.

---

Advantages

The refactoring provides:

simplified ingestion workflow
elimination of duplicate typing
clearer conceptual model
improved usability for non-technical contributors
better alignment with archival cataloguing practice

---

Risks and Side Effects

Possible side effects include:

Views displaying the old Title label
dashboards requiring field replacement
module references still pointing to Title
form display requiring adjustment

All should be verified after implementation.

---

Compliance with Project Blueprint

The proposal respects the architectural principles:

Asset remains the authoritative record
Media remains the file container
File remains the physical storage object

Automation assists data entry but does not change the authority model.

---

Status

Proposed design change.

Implementation to be executed in controlled steps after validation.