# Opening Balance Import Column Dictionary

**Task:** AST-1.8.1 — Opening Balance Import Template Design
**Workbook:** [`templates/asset-opening-balance-import-template-v1.0.0.xlsx`](./templates/asset-opening-balance-import-template-v1.0.0.xlsx)
**Version:** 1.0.0
**WBS:** [Phase 1.8, item 1.8.1](./ASSET_MANAGEMENT_WBS.md#18--phase-8--opening-balance-import)
**Schema:** [Asset Management database schema](./ASSET_MANAGEMENT_DATABASE_SCHEMA.md)

The workbook is a column contract for the later upload, validation, and confirm cards. It does not itself create records. Column names below are the exact workbook headers and must remain unchanged until a versioned replacement is approved.

## Serialized Assets

| Header | Required | Type / allowed values | Schema mapping | Import meaning |
|---|---:|---|---|---|
| Asset Code | Yes | Text, 1–50 characters; unique within the workbook and company | `serialized_assets.asset_code` | New physical-asset identifier. |
| Item Code | Yes | Text; must resolve to an active `asset_items.code` with `tracking_mode = SERIALIZED` | `serialized_assets.item_id` via `asset_items.code` | Identifies the serialized item master. |
| Serial Number | No | Text, 1–100 characters; unique for the resolved item when supplied | `serialized_assets.serial_number` | Manufacturer or device serial. |
| Status | Yes | `RECEIVED`, `AVAILABLE`, `ASSIGNED`, `UNDER_MAINTENANCE`, `LOST`, `RETIRED`, `DISPOSED`, or `WRITTEN_OFF` | `serialized_assets.status` | Current lifecycle status. |
| Condition | Yes | `NEW`, `GOOD`, `FAIR`, `POOR`, `DAMAGED`, or `UNUSABLE` | `serialized_assets.condition` | Current physical condition. |
| Location Code | No | Text; must resolve to an active `asset_locations.code` | `serialized_assets.current_location_id` via `asset_locations.code` | Current Asset-module location. |
| Acquired On | No | Date, ISO display `yyyy-mm-dd` | `serialized_assets.acquired_on` | Opening acquisition date. |
| Acquisition Cost | No | Decimal, non-negative, up to 2 decimal places | `serialized_assets.acquisition_cost` | Frozen opening cost; no journal is created by this template. |
| Currency | No | Text, 1–10 characters | `serialized_assets.currency` | Currency of Acquisition Cost when a cost is supplied. |
| Cost Center Code | No | Text; must resolve to `cost_centers.code` | `serialized_assets.cost_center_id` via `cost_centers.code` | Optional cost-center reference. |

## Quantity Assets

| Header | Required | Type / allowed values | Schema mapping | Import meaning |
|---|---:|---|---|---|
| Item Code | Yes | Text; must resolve to an active `asset_items.code` with `tracking_mode = QUANTITY` | `inventory_transactions.item_id` via `asset_items.code` | Quantity item master. |
| Location Code | Yes | Text; must resolve to an active `asset_locations.code` | `inventory_transactions.location_id` via `asset_locations.code` | Location receiving the opening balance. |
| Quantity | Yes | Positive decimal, up to 4 decimal places | `inventory_transactions.quantity`; `inventory_balances.quantity` projection | Opening quantity. |
| Occurred On | Yes | Date, ISO display `yyyy-mm-dd` | `inventory_transactions.occurred_on` | Opening-balance effective date. |
| Unit Cost | No | Decimal, non-negative, up to 2 decimal places | `inventory_transactions.unit_cost` | Optional per-unit opening valuation; not a weighted-average calculation. |
| Currency | No | Text, 1–10 characters | `asset_receipt_inbox.currency` | Receipt-context currency associated with an optional Unit Cost. |
| Cost Center Code | No | Text; must resolve to `cost_centers.code` | `asset_receipt_inbox.cost_center_id` via `cost_centers.code` | Optional receipt-context cost center. |

Confirmed quantity rows create `inventory_transactions` with `type = OPENING_BALANCE`; their receipt/inbox context supplies the currency and cost-center references. The spreadsheet does not expose internal transaction IDs, balances, references, idempotency keys, or audit columns.

## Optional Warranty

| Header | Required | Type / allowed values | Schema mapping | Import meaning |
|---|---:|---|---|---|
| Asset Code | Yes | Text; must match a serialized-asset row in the same import or an eligible imported serialized asset | `asset_warranties.serialized_asset_id` via `serialized_assets.asset_code` | Links the warranty to one serialized asset. |
| Provider Code | Yes | Text; must resolve to an active `asset_service_providers.code` | `asset_warranties.provider_id` via `asset_service_providers.code` | Existing service-provider reference. |
| Starts On | Yes | Date, ISO display `yyyy-mm-dd` | `asset_warranties.starts_on` | Coverage start date. |
| Ends On | Yes | Date, ISO display `yyyy-mm-dd`; not before Starts On | `asset_warranties.ends_on` | Coverage end date. |
| Coverage | No | Text | `asset_warranties.coverage` | Summary of coverage. |
| Terms | No | Text | `asset_warranties.terms` | Warranty terms. |
| Reference No | No | Text, 1–100 characters | `asset_warranties.reference_no` | Supplier or manufacturer reference. |

The warranty sheet intentionally excludes attachments (`file_path`, `original_name`) because an import template cannot supply a verified stored file. It also excludes system-managed IDs, company IDs, and audit timestamps.