# inbound-shipment-create-form

## Overview

Creates an inbound shipment in DRAFT status against an existing confirmed (ORDERED) purchase order. Lines are pre-populated from the PO's remaining undelivered quantities; the operator adjusts the receive quantities before submitting. In erp-kit 0.45 an inbound shipment is an `InboundShipment` whose lines require a purchase-order source link, so an inbound shipment is always raised from a PO — there is no manual / non-PO entry mode.

Submitting invokes the [createInboundShipment](../resolver/createInboundShipment.md) resolver.

## Screen Type

Form

### Form Details

#### Input Fields

| Field Name | Field Type | Required (Yes/No) | Options / Lookup |
| --- | --- | --- | --- |
| Purchase Order | Combobox (searchable by supplier name / PO number) + Browse Dialog | Yes | PurchaseOrder lookup (PurchaseOrder.docNumber, supplier name) |
| Receipt Date | date | Yes | — |

Supplier is shown read-only after PO selection (derived from the PO).

**PO-sourced lines (pre-populated from PO remaining quantities):**

Lines with zero remaining are filtered out on PO selection. Only lines with open quantity are shown.

| Field Name | Field Type | Required (Yes/No) | Options / Lookup | Description |
| --- | --- | --- | --- | --- |
| Item | text (read-only) | Yes | — | Item name from PO line snapshot |
| Ordered | number (read-only) | — | — | PO line ordered quantity |
| Prev Received | number (read-only) | — | — | Sum of received from POSTED inbound shipments |
| Remaining | number (read-only) | — | — | Ordered - Prev Received |
| Receive Qty | number (editable) | Yes | — | Defaults to remaining; user can adjust (including to 0) |
| UoM | text (read-only) | — | — | Unit of measure |

Lines can be removed via a trash icon, or excluded by setting the quantity to 0. At least one line must have quantity > 0.

**Fully received state:** If all PO lines have zero remaining, a warning message is shown and there are no lines to receive.

On submit, each line passes:
- `purchaseOrderLineId` — the source PO line
- `quantity` — the user-entered receive qty
- `itemId` — item reference
- `unitId` — unit reference (if set)

Lines with quantity 0 are filtered out before submission.

**Purchase Order Selection:**

The PO field offers two selection methods:

1. **Combobox** — searchable dropdown for users who know the supplier name or PO number. Displays `{Supplier Name} — {PO number prefix}`.
2. **Browse Dialog** — a "Browse" button opens a dialog with:
   - Text filter (searches supplier name, item SKU, item name)
   - Table with columns: Supplier, PO number (truncated), Order Date, Total Open Qty
   - Clicking a row expands it to show SKU-level detail (item name + remaining quantity)
   - Cancel / Select footer buttons

On selection (via either method), the form auto-populates supplier info and pre-fills line items from the PO's open quantities. Switching to a different PO replaces the lines.

**Actions:**

- Create — submits the form (disabled while submitting or when no lines exist)
- Cancel — discards and returns to previous screen

## Access Control

- [purchaser](../actor/purchaser.md)