Configuration Packages is the official bulk data import and export surface in Dragon Guard WMS Web. Inspired by the configuration package model in Microsoft Dynamics 365 Business Central, this module gives tenant administrators a controlled, auditable mechanism to load or update large datasets — items, inventory movements, receipt headers and lines, and shipment headers and lines — without resorting to manual entry. Every import is gated behind backend signature validation, which means only Excel files generated by Dragon Guard itself are accepted. This is not a financial or posting module; it deals exclusively with master data and transactional records that feed WMS operations.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/CodexaCP/DG_WEB/llms.txt
Use this file to discover all available pages before exploring further.
Access Control
Navigate to Dashboard → Admin → Config Packages (/dashboard/admin/config-packages). The route is protected by both adminGuard and AuthService.isSystemAdmin(). Only users with the ADMIN role can reach this screen.
Supported Package Types
Dragon Guard WMS Web currently supports six official package types. Each type targets a specific dataset and carries its own insert/update rules defined by the backend.| Package | Description |
|---|---|
| Items Master | Import or update item (SKU) records including descriptions, units, and attributes. |
| Inventory Movements | Import opening balances or manual inventory adjustments. |
| Receipt Headers | Bulk import or export of receipt (inbound shipment) header records. |
| Receipt Lines | Bulk import or export of individual lines belonging to receipt headers. |
| Shipment Headers | Bulk import or export of outbound shipment header records. |
| Shipment Lines | Bulk import or export of individual lines belonging to shipment headers. |
Import Flow
Select a package type
On the Config Packages screen, choose the package type that matches the data you want to import (e.g., Items Master).
Export the official template or current data
Click Export to download the official Excel file for that package. This file contains the correct sheet structure, column headers, and the backend-embedded signature that authorizes re-import.
Edit the exported Excel file
Open the downloaded
.xlsx file and fill in or modify the rows. Do not add, remove, or rename sheets or column headers. Do not open the file in a third-party converter that strips metadata.Upload the edited file
Return to the same package type in Dragon Guard and click Import. Select the
.xlsx file you edited in the previous step.Backend validates the package
The backend verifies the file signature, checks that all required sheets and columns are present, and validates every row for data type correctness, referential integrity, and company context.
Review validation errors (if any)
If any row fails validation the entire import is rejected — nothing is applied. The UI displays a structured error table so you can locate and fix every issue before re-uploading.
Validation Error Format
When the backend finds problems, errors are returned at row-level precision:| Field | Description |
|---|---|
| Sheet name | The Excel worksheet where the error was found |
| Row number | The 1-based row number inside that sheet |
| Field name | The column that contains the invalid value |
| Error message | Human-readable description of the problem |
What the Backend Rejects
The backend will reject the upload immediately (before row-level validation) if any of the following conditions are detected:Wrong file format
Only
.xlsx files are accepted. .xls, .csv, and other formats are rejected outright.Missing system signature
Files not originally generated by Dragon Guard WMS do not carry the required metadata signature and are rejected.
Structural mismatch
Required sheets or columns are missing, renamed, or reordered relative to the official template.
Invalid metadata
Embedded metadata or package identifiers inside the file do not match the selected package type.
Bad data types
Cells that must contain numbers, dates, or specific enumeration values contain incompatible types.
Wrong company context
The package was exported under a different tenant than the one currently authenticated in the session.
Apply Rules
Each package type defines its own write behavior. These rules are enforced by the backend and cannot be overridden from the UI:- Insert-only packages add new records; rows that match existing keys are rejected.
- Update-only packages modify existing records; rows that do not match an existing key are rejected.
- Insert + Update packages upsert records based on the natural key defined by the package.
Dragon Guard does not support partial imports. If a valid package contains 500 rows and 1 row fails validation, all 500 rows are rejected until the error is resolved. This is by design to preserve data consistency.
Line Package Header Dependency
Receipt Lines and Shipment Lines are dependent packages. Before importing lines, the corresponding headers must already exist in Dragon Guard WMS (either pre-existing or imported in a prior Headers package run).- The backend rejects any line row that references a header that does not exist.
- Import Receipt Headers before Receipt Lines; import Shipment Headers before Shipment Lines.
- There is no combined header-plus-lines package — they are intentionally separate to allow independent correction and re-upload.
Security
- Access is restricted to ADMIN role users only, enforced by
adminGuardandAuthService.isSystemAdmin(). - The company context is derived from the authenticated JWT; users cannot import data into a different tenant’s dataset.
- The backend independently re-validates the company context on every import request regardless of what the UI sends.
How to Add a New Package Type
When the backend team adds support for a new package, the following checklist ensures the frontend surfaces it correctly:Register the package type in the package list
Add the new type to the package-type enumeration or configuration array used by the Config Packages component.
Add UI labels and descriptions
Create translation keys for the package display name and description in the active language packs via
TranslationService.Wire the export action
Map the package type to the correct export API call so the Export button downloads the appropriate template.
Wire the import action
Map the package type to the correct import endpoint and ensure the file-upload handler passes the type identifier in the request.
Define apply-rule label
Display the correct insert/update mode badge (insert-only, update-only, or insert+update) in the package card, sourced from backend metadata or a static mapping.