FOUR-32329: Handle unavailable assets in DevLink bundles

[eiresendez]

Issue & Reproduction Steps

DevLink bundle serialization assumed that every bundle_assets association resolved to an available model. When an association referenced a deleted asset or a model class from an unavailable package, opening or exporting the bundle resulted in a generic HTTP 500 error. The original report associated the failure with bundle volume, but the reproduced failure was caused by an orphaned Collection association.

A local orphaned association can be created with:

php artisan tinker --execute='$bundle=ProcessMaker\Models\Bundle::factory()->create(["name"=>"FOUR-32329 Orphan Collection Repro"]); ProcessMaker\Models\BundleAsset::factory()->create(["bundle_id"=>$bundle->id,"asset_type"=>ProcessMaker\Models\BundleAsset::COLLECTION_CLASS,"asset_id"=>1000006]); echo $bundle->id.PHP_EOL;'

Open /admin/devlink/local-bundles/{bundle-id}/. Before this change, the bundle metadata request returned a 500 while reading properties from the missing model. Exporting or installing the same bundle also surfaced the server exception.

Solution

• Add valid, missing, and type_unavailable integrity states to bundle assets, with safe fallback metadata for unavailable assets.
• Validate the entire bundle before running exporters and return a structured 422 response containing every invalid association.
• Convert remote integrity failures into a concise, actionable installation message while retaining the full exception in server logs.
• Display unavailable assets in Bundle Detail, block export-related actions, and allow administrators to explicitly remove only the invalid association.
• Preserve bundle associations when source assets are deleted; no automatic cleanup or silent pruning is performed.

How to Test

Run the focused automated coverage:

vendor/bin/phpunit tests/Model/BundleAssetTest.php
vendor/bin/phpunit tests/Model/BundleTest.php --filter testExportRejectsBundleWithUnavailableAssetsBeforeExporting
vendor/bin/phpunit tests/Model/DevLinkTest.php --filter testInstallRemoteBundleReportsUnavailableRemoteAssets
vendor/bin/phpunit tests/Feature/Api/DevLinkTest.php --filter '/(testShowBundleReportsUnavailableAssetsWithoutFailing|testExportBundleRejectsUnavailableAssets|testInstalledBundleAllowsRemovingOnlyUnavailableAssets)/'
npm run development

For manual validation:

1. Create the orphaned association using the Tinker command above.
2. Open the generated bundle and confirm it loads successfully.
3. Confirm the unavailable asset is shown as Missing Collection #1000006, without a broken link.
4. Confirm the warning banner is visible and publishing/export actions are disabled.
5. Confirm bundle export returns a structured 422 response.
6. Select Remove from bundle and confirm the dialog states that only the association will be removed.
7. Remove the association and confirm the warning disappears and the bundle becomes exportable.
8. From a linked instance, attempt to install or update a corrupt bundle and confirm the UI shows an actionable message without a stack trace.

Related Tickets & Packages

• https://processmaker.atlassian.net/browse/FOUR-32329

ci:deploy

[processmaker-sonarqube]

Quality Gate passed

Issues
0 New issues
0 Fixed issues
0 Accepted issues

Measures
0 Security Hotspots
No data about Coverage
0.0% Duplication on New Code

See analysis details on SonarQube

[vladyrichter]

QA server K8S was successfully deployed https://ci-e4ae468514.engk8s.processmaker.net