# Upgrade compatibility

The package preserves the MarvelPBX entity-module identity and Tools placement while setting version 12.5.1. It is intended for VTiger 8.4.x.

On upgrade, vtlib retains existing entity metadata and tables and replaces packaged runtime files. The module.preupdate handler validates and idempotently normalizes Tools placement without recreating the reporting view. The module.postupdate handler repeats that normalization and recreates the reporting view. It neither rewrites nor deletes PBXManager, crmentity, MarvelPBX base-table, or custom-field-table data.

MarvelPBX 12.4.1 could install its runtime files and have VTiger write the new module version before module.postupdate failed. MariaDB exposes the nullable SQL defaults of vtiger_app2tab.tabid, appname, and sequence through INFORMATION_SCHEMA as the exact metadata string `NULL`, while 12.4.1 expected PHP null.

Version 12.5.1 canonicalizes only the exact metadata string `NULL` to PHP null when IS_NULLABLE is exactly `YES`. Lowercase or mixed-case values, quoted literal defaults, empty strings, numeric/string zero, CURRENT_TIMESTAMP, and every other value remain unchanged. Column order, names, types, nullability, resulting defaults, EXTRA metadata, and constraints remain strict and fail closed.

The package adds no RecordingProxy, UCM client, credentials, Settings module, cron job, or automatic profile grant. Existing profile policy remains an administrator decision.

Before an upgrade, back up module metadata, both MarvelPBX tables, the reporting view definition, and the active runtime files. Validate on a clone first. Rollback restores those captured artifacts and the prior module version; it must not use an uninstall when business data must be retained.

## Legacy Tools placement normalization

Legacy manual installations can contain duplicate rows because the audited VTiger 8.4 schemas provide no primary or unique constraint on either vtiger_parenttabrel or vtiger_app2tab. Version 12.5.1 validates the audited column and constraint shapes and resolves the single parenttab row whose actual label is Tools before changing placement.

For MarvelPBX only, the lifecycle retains one canonical Tools relation, collapses duplicate canonical relations, replaces incorrect MarvelPBX parent relations with one canonical relation, and creates it when absent. For vtiger_app2tab it collapses only duplicate MarvelPBX TOOLS rows and preserves the selected row's visibility; other application mappings are untouched. Unrelated modules, links, filters, sharing, profile permissions, and utility permissions are never broadened or normalized.

Schema validation and unique Tools/MarvelPBX identifier resolution complete before an atomic placement transaction begins. An unexpected schema or ambiguous/missing identifier throws a sanitized exception without guessing IDs.