ICT:FinalConfig - Asset v2.1 - private extension
Final Configuration for the Asset Entity – v2.1 - with private extension
(Automatic Identification, Provenance Capture, File Normalization)
Document revision: 2026-02-21 by Mngr This document defines the intermediate configuration for the Asset entity (version 2.1). It supersedes all previous drafts and experimental implementations.
0. Runtime Baseline (LOCKED)
The following environment is assumed and MUST NOT change during Asset v2.x implementation:
- OS: AlmaLinux 10.1 with * PHP: 8.3
- MediaWiki: 1.45.x runnin on Almalinix 10.1 Virtual Machine 1.
- DocumentRoot: /var/ww/mediawiki
- MariaDB and Cargo running on AlmaLinux 10.1 Virtual Machine 2
- Virtual Machines are running on a Windows 11 Hyper-V wit 8 virtual-cores and 16 GB of central memory.
- Page Forms: 6.x
- Scribunto (Lua 5.1)
- Reverse Proxy use on IIS
- Redirects defined in Vhost
- Site URL https://mwiki.costasano.club
Remark Lua 5.4 is explicitly excluded being incompatible with the precious setup.
1. Asset Concept (Normative)
An Asset represents the historical metadata of exactly one digital file.
Rules:
- One Asset = one File
- The Asset identifier and the File name are identical (except extension)
- The Asset/File pair is immutable after creation.
- Only specific informative fields are editable after first creation.
- Assets may reference parent Assets (derivatives, OCR, AI output, annexes)
] Deletion of a pair is only permitted by sysop.
The Asset identifier is the archival reference and MUST NEVER change once created.
2. Identifier Scheme (Normative)
Asset identifiers follow 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 integer
Example:
CH03-BER-0007
Rules:
- Sequence numbers are computed automatically
- Gaps are allowed in the numbering
- Numbers are never reused
- Contiguity is NOT guaranteed
3. Draft Asset Strategy (Mandatory)
Form Pages does not allow the creating of a Form without giving a pagename. However, the pagename in our workflow is based on some user inputs in the form. The solution is to start with ta draft Asset creation using a timestamp because tests showed that using a fixed name is not feasable in our setup.
3.1 Draft Page Workflow
The draft page exist after creating and needs to be filled in, migrated (moved) to a final version and should not survice.
- All new Assets are initially created with a timestamp as initial name
- This inital draft page itself is never queried or displayed in dashboards.
- The page is "moved" to its final identifier when the user decides to save
- The file uploaded during the draft phase is also "moved" to use exactly te same automatic code as the asset it is linked to. The original name will be stored in the OrignalFilename field for later reference.
3.2 imolementation strategy
It has been decided to realise the above requirement server-side and as such a private extension is to be created. Lua and Javascript are not forbidden if for one reason this might simplify the design or be needed to overcome MediaWiki 1.43 limits. It has been observed that AlmaLinux 10.1 with php 8.3 and MediaWiki 1.43 are all very new and documented is limited which makes it difficult to come to a working setup. A lot of trial and error is sometimes needed to detect by inspection code how this setup behaves. The design should also take care to look for robust solution which need to last for a decade at least and survive software updates of all sorts.
4. Cargo Table and Template
4.1 Template:Asset
<noinclude>
Asset data template (v2)
{{#cargo_declare:
|_table=Assets
|Code=Page
|Label=String
|Chapter=Page
|Place=Page
|Organisation=Page
|Sequence=Integer
|File=String
|OriginalFilename=String
|Parent=Page
|AssetType=Page
|Description=Text
|Notes=Text
}}
</noinclude>
{{#cargo_store:
|Code={{FULLPAGENAME}}
|Label={{{Label|}}}
|Chapter={{{Chapter|}}}
|Place={{{Place|}}}
|Organisation={{{Organisation|}}}
|Sequence={{{Sequence|}}}
|File={{{File|}}}
|OriginalFilename={{{OriginalFilename|}}}
|Parent={{{Parent|}}}
|AssetType={{{AssetType|}}}
|Description={{{Description|}}}
|Notes={{{Notes|}}}
}}
== {{{Label|}}} ==
{{DISPLAYTITLE:{{{Label}}}}}
{{#if:{{{File|}}}|'''File:''' [[{{{File}}}]]}}
{{#if:{{{OriginalFilename|}}}|'''Original filename:''' {{{OriginalFilename}}}}}
{{#if:{{{Parent|}}}|'''Parent asset:''' [[{{{Parent}}}]]}}
'''Description:'''
{{{Description|}}}
'''Notes:'''
{{{Notes|}}}
4.2 Cargo Setup
After saving the template:
- Go to Special:CargoTables
- Manually create the table Assets
5. Page Form
5.1 Form:Asset
<noinclude>
Form for creating and editing Asset pages (v2)
</noinclude>
{{{info
|page name=Asset:<Asset[Label]>
|no summary
|no preview
|no minor edit
|no watch
|no footer
}}}
{{{for template|Asset}}}
{| class="formtable"
! Chapter (*)
| {{{field|Chapter
|input type=combobox
|values from namespace=Chapter
|existing values only
}}}
|-
! Place
| {{{field|Place
|input type=combobox
|values from namespace=Place
|existing values only
|placeholder=Use Organisation instead
}}}
|-
! Organisation
| {{{field|Organisation
|input type=combobox
|values from namespace=Organisation
|existing values only
|placeholder=Use Place instead
}}}
|-
! Identifier
| {{{field|Label|readonly}}}
|-
! Sequence
| {{{field|Sequence|readonly}}}
|-
! File
| {{{field|File
|input type=page
|namespace=File
|uploadable=yes
}}}
|-
! Original filename
| {{{field|OriginalFilename|readonly}}}
|-
! Asset type
| {{{field|AssetType
|input type=combobox
|values from namespace=AssetType
|existing values only
}}}
|-
! Parent asset
| {{{field|Parent
|input type=combobox
|values from namespace=Asset
|existing values only
|placeholder=Top level
}}}
|-
! Description
| {{{field|Description|input type=textarea}}}
|-
! Notes
| {{{field|Notes|input type=textarea}}}
|}
{{{standard input|save}}}
{{{end template}}}
6. Dashboard
6.1 Dashboard:Asset
= 🗂️ Asset Dashboard =
{| class="wikitable sortable"
! Code !! Chapter !! Place !! Organisation !! File !! Type
{{#cargo_query:
tables=Assets
|fields=_pageName,_pageTitle,Chapter,Place,Organisation,File,AssetType
|where=_pageName!='Asset:DRAFT'
|order by=_pageTitle
|format=template
|template=AssetRow
|named args=yes
|cache=no
}}
|}
{{#formlink:
form=Asset
|target=Asset:{{#time: YmdHis }}
|link text=➕ New Asset
|link type=button
|query string=Asset[Label]=GENERATING...&Asset[File]=
|returnto=Dashboard:Asset
}}
6.2 Template:AssetRow
<includeonly>
|-
| {{#formlink:
form=Asset
|target={{{_pageName}}}
|link text={{{_pageTitle}}}
|returnto=Dashboard:Asset
}}
| {{{Chapter}}}
| {{{Place}}}
| {{{Organisation}}}
| {{{File}}}
| {{{AssetType}}}
</includeonly>
7. Private Extension AssetLifecycle
7.1 LocalSystems.php loading
wfLoadExtension( 'AssetLifecycle' );
7.2 Extension.json
{
"manifest_version": 2,
"name": "AssetLifecycle",
"version": "1.0",
"author": "Heritage Research Club",
"description": "Automated labeling for Heritage Assets",
"AutoloadClasses": {
"LegacyHooks": "LegacyHooks.php"
},
"Hooks": {
"PageForms::WritePageData": "LegacyHooks::onPFWritePageData",
"PageForms::SetTargetName": "LegacyHooks::onPFSetTargetName"
}
}
7.2 LegacyHooks.php
<?php
use MediaWiki\MediaWikiServices;
use MediaWiki\Title\Title;
use MediaWiki\Context\RequestContext;
class LegacyHooks {
/**
* Hook: PageForms::WritePageData
*/
public static function onPFWritePageData( $formName, $title, &$wikitext ) {
$logFile = '/var/www/mediawiki/hook_debug.log';
$time = date('H:i:s');
if ( !is_string( $wikitext ) ) return true;
// 1. Extract values using multiline regex with flexible whitespace
preg_match( '/^\|\s*Chapter\s*=\s*(.*?)\s*$/m', $wikitext, $matchCh );
preg_match( '/^\|\s*Place\s*=\s*(.*?)\s*$/m', $wikitext, $matchPl );
preg_match( '/^\|\s*Organisation\s*=\s*(.*?)\s*$/m', $wikitext, $matchOrg );
preg_match( '/^\|\s*File\s*=\s*(.*?)\s*$/m', $wikitext, $matchFile );
$chapter = isset($matchCh[1]) ? trim($matchCh[1]) : '';
$place = isset($matchPl[1]) ? trim($matchPl[1]) : '';
$org = isset($matchOrg[1]) ? trim($matchOrg[1]) : '';
$oldFile = isset($matchFile[1]) ? trim($matchFile[1]) : '';
if ( empty( $chapter ) ) return true;
try {
// 2. Query External DB (10.10.10.2)
global $wgCargoDBserver, $wgCargoDBname, $wgCargoDBuser, $wgCargoDBpassword, $wgCargoDBtype;
$dbFactory = MediaWikiServices::getInstance()->getDatabaseFactory();
$db = $dbFactory->create( $wgCargoDBtype, [
'host' => $wgCargoDBserver, 'user' => $wgCargoDBuser, 'password' => $wgCargoDBpassword, 'dbname' => $wgCargoDBname
]);
// Query MAX Sequence
$row = $db->selectRow('Assets', ['MAX(Sequence) AS m'], ['Chapter' => $chapter], __METHOD__);
$nextSeq = ( $row && $row->m ) ? (int)$row->m + 1 : 1;
$db->close();
// 3. Generate Label
$cleanCh = preg_replace('/^.*?:/', '', $chapter);
$subVal = !empty($place) ? $place : $org;
$cleanSub = preg_replace('/^.*?:/', '', $subVal);
$newLabel = sprintf("%s-%s-%04d", $cleanCh, $cleanSub, $nextSeq);
// 4. Update OriginalFilename (Crucial: Replace the whole line including potential whitespace)
if ( !empty($oldFile) ) {
$wikitext = preg_replace('/^\|\s*OriginalFilename\s*=.*$/m', "|OriginalFilename=$oldFile", $wikitext);
$ext = pathinfo($oldFile, PATHINFO_EXTENSION);
$newFileName = "$newLabel.$ext";
// Update File field
$wikitext = preg_replace('/^\|\s*File\s*=.*$/m', "|File=$newFileName", $wikitext);
// 5. Physically rename the file
self::moveUploadedFile( "File:$oldFile", "File:$newFileName" );
}
// 6. Update Label and Sequence
$wikitext = preg_replace('/^\|\s*Label\s*=.*$/m', "|Label=$newLabel", $wikitext);
$wikitext = preg_replace('/^\|\s*Sequence\s*=.*$/m', "|Sequence=$nextSeq", $wikitext);
file_put_contents($logFile, "[$time] SUCCESS: Updated $newLabel. Original: $oldFile\n", FILE_APPEND);
} catch ( \Exception $e ) {
file_put_contents($logFile, "[$time] ERROR: " . $e->getMessage() . "\n", FILE_APPEND);
}
return true;
}
private static function moveUploadedFile( $oldName, $newName ) {
if ( empty($oldName) || $oldName === $newName || $oldName === "File:" ) return;
$oldTitle = Title::newFromText( $oldName );
$newTitle = Title::newFromText( $newName );
if ( $oldTitle && $newTitle && $oldTitle->exists() ) {
$user = RequestContext::getMain()->getUser(); // Use current user for simplicity in this step
$movePage = MediaWikiServices::getInstance()->getMovePageFactory()->newMovePage( $oldTitle, $newTitle );
$movePage->move( $user, "Heritage Auto-Rename", false );
}
}
/**
* SetTargetName: We force the name here to ensure the Page Move happens.
*/
public static function onPFSetTargetName( $formName, &$target_name, $wikitext = null ) {
if ( is_string($wikitext) && preg_match('/^\|\s*Label\s*=\s*(.*)$/m', $wikitext, $m) ) {
$label = trim($m[1]);
if ( !empty($label) && $label !== 'GENERATING...' ) {
$target_name = "Asset:" . $label;
}
}
return true;
}
}
7.4 Extension structure
/var/www/mediawiki/extensions/AssetLifecycle/extension.json /var/www/mediawiki/extensions/AssetLifecycle/LegacyHooks.php
8. Immutability Rules
After a successful save, the following fields MUST NOT change:
- Asset identifier (page name)
- Label
- Chapter
- Place / Organisation
- File
- OriginalFilename
Other metadata MAY change.
Deletion of an Asset/File pair is sysop-only.
9. Status
Asset v2.1 is partially functionnal
File upload and move: OK Asset move: NOK Automatic numbering combination: OK for Chapter-Place-Number (Organisation not tested yet) Automatic counter increment: NOK OriginalFIleName filled in: NOK Identifier filled in: OK
Further work and testing needs to be done.