Skip to main content

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.

The Shipments module controls the lifecycle of outgoing inventory documents in Dragon Guard WMS. The Angular web frontend is responsible for document creation, header and line setup, and release to the warehouse floor. All physical actions — picking items, recording shipped quantities, and posting stock changes — are performed exclusively by the MAUI handheld application. This boundary guarantees that stock is never decremented without a corresponding physical operation, maintaining an accurate and auditable inventory.

​
Responsibility Split

CapabilityWeb (Angular)Handheld (MAUI)
Create shipment documents✅❌
Edit document header and lines✅❌
Release document to handheld✅❌
Reopen released document✅❌
View shipment progress and posted results✅✅
Query released shipments❌✅
Pick and ship items (partial or full)❌✅
Post shipment and update stock❌✅
Mark document complete❌✅
Never add a Post or Ship button to any web screen. Posting a shipment decrements warehouse stock. This action is reserved exclusively for the MAUI handheld app so that physical picking is confirmed before inventory balances are updated. Introducing a posting trigger in the web UI would bypass physical verification and corrupt the audit trail.

​
Document Numbering

Shipment documents are assigned sequential numbers in the format SHP-000001, SHP-000002, and so on. The number is generated by the backend on creation and is read-only in the web UI. The sales order number in the administrative flow mirrors this visual shipment number, providing a consistent reference across commercial and logistics documents.

​
Web Workflow

1

Create a New Shipment Header

Navigate to the Shipments list (shipments.component) and select New. The create form (create-shipment.component) opens with an empty header. Provide:
  • Customer name — free-text entry, required.
  • Location — fixed to MAIN in the current UI; no selection is needed.
  • Sales order reference — optional; link to a commercial sales order via the lookup dialog. When linked, backend validation confirms the order belongs to the active company.
2

Add Shipment Lines

Lines are added using the item lookup control. Each line captures the item reference and the quantity to ship. ShippedQty is always a read-only visual field — its value reflects posted progress returned from the backend and cannot be set manually.Line numbers must continue from the highest existing line number in the document. Duplicate line numbers are not permitted, and the backend rejects them with a validation error.
3

Save as Open

Saving the document creates it in Open status. The POST /api/shipmentheaders endpoint is used for initial creation; subsequent edits use PUT /api/shipmentheaders/{id}. The document remains fully editable in this state.
4

Release to Handheld

When the document is ready for the warehouse floor, release it. Status changes to Released and the document becomes read-only in the web UI. Handheld operators can now query, pick, and ship against it.
5

Monitor Progress

Open the detail view (details/:id) to track shipment progress. Posted quantities per line and overall shipment status are displayed in read-only form while the document is released.
6

Reopen if Required (Optional)

If corrections are needed before picking begins, the document can be explicitly reopened from Released back to Open. If a handheld operator has already started picking, the reopen is blocked and a message displays the shipment number and the operator’s email address.

​
Status Transitions

Open  ──────► Released
  ▲                │
  └── (Reopen) ◄───┘
       (blocked if handheld work started)
TransitionTriggered byCondition
Open → ReleasedWeb operator clicks ReleaseDocument must have at least one line
Released → OpenWeb operator clicks ReopenNo handheld picking activity recorded
Released → Open (blocked)—Handheld has started work; shows operator email

​
Editing Constraints

​
Open Documents (no partial posts)

All header fields, line quantities, and lines themselves are fully editable. Removing a non-posted line from the form deletes it from the backend when the document is saved.

​
Open Documents with Partial Handheld Posts

When a document has been reopened after partial handheld activity, the following constraints apply:

Quantity Floor

A line’s planned quantity can be lowered, but never below the quantity already posted by the handheld. Going below the posted amount would create a negative shipment variance.

Posted Lines Protected

Lines with any posted quantity cannot be deleted. Only lines with zero posted quantity can be removed from the document.

​
Released Documents

Released documents are entirely read-only in the web UI. No edits are possible until the document is explicitly reopened.

​
Line Numbering Rules

New lines added to an existing shipment document must use a line number greater than the current highest line number in that document. The UI automatically suggests the next number. Submitting a duplicate line number results in a backend validation error displayed in the blocking modal.

​
Error Handling

Backend validation errors are surfaced as a blocking modal. Error messages are resolved via the messageKey field in the API response, which maps to translated strings in the Angular i18n layer. The modal must be dismissed before any further action is possible. No partial saves occur on a blocking error.

​
API Endpoints

All requests include the company context. The PUT endpoint is used for all edits after initial creation.
MethodEndpointPurpose
GET/api/shipmentheaders?companyId={id}List all shipment documents for the active company
GET/api/shipmentheaders/{id}Fetch a single shipment document with all lines
POST/api/shipmentheadersCreate a new shipment header and lines
PUT/api/shipmentheaders/{id}Update an existing shipment document

​
Config Package Endpoints (Admin Only)

Supreme administrators have access to additional endpoints for exporting, previewing, and applying configuration packages:
MethodEndpointPurpose
GET/api/shipmentheaders/export-configExport shipment configuration as a package
POST/api/shipmentheaders/preview-configPreview the effect of a configuration package
POST/api/shipmentheaders/apply-configApply a configuration package to the system
GET /api/shipmentheaders?companyId=42
Authorization: Bearer {token}

POST /api/shipmentheaders
Authorization: Bearer {token}
Content-Type: application/json

{
  "companyId": 42,
  "customerName": "Retail Partner S.A.",
  "locationId": 1,
  "lines": [
    { "itemId": 205, "lineNo": 10000, "quantityToShip": 20 }
  ]
}
The endpoint POST /shipmentheaders/{id}/post is a backend route reserved for the MAUI handheld. It must never be called from the web frontend. No Angular service method, button, or route should trigger it.

Build docs developers (and LLMs) love

Get started for freeTalk to us