Item Definitions

Backlog field	Value
Story ID	INV-DASH-005
Epic	Inventory
Story type	Dashboard
Review status	Draft - business analyst and business owner review required
Source evidence	Inventory MFE route/form, Inventory.Apis controller, application command/query handlers, validators, domain entities, and posting services
Last source review	2026-07-10

Purpose

Maintain the sellable, purchasable, storable, and service items used across AppsPortal.

User stories

• As an inventory master-data user, I want to search, view, add, edit, import, export, and deactivate items so that the catalog remains controlled.
• As a catalog user, I want to define an item's general identity and category before configuring its dependent data.
• As a catalog user, I want to configure units, variants, attributes, barcodes, fixed cost, tax, inventory, pricing, and accounting in separate tabs so that complex items can be maintained safely.
• As an operational user, I want barcodes and QR codes to identify the correct variant during transactions.

Workflow

1. Enter the item's code/name, type, category, and general properties.
2. Save the base definition and configure applicable tabs.
3. Define unit conversions and the default unit.
4. Define variants directly or from attribute combinations.
5. Assign barcodes, tax treatment, stock policy, prices, costs, and accounts.
6. Review the item before using it in transactions.

Acceptance criteria

1. An item cannot be saved without its required identity and configuration fields.
2. Item code and barcode uniqueness is validated within the applicable tenant scope.
3. Only configuration relevant to the chosen item type is required or enabled.
4. One valid default unit and default variant are available where the item uses units/variants.
5. A barcode resolves to one unambiguous item variant and unit.
6. Import validates rows and presents errors for correction before confirmation.
7. Deletion/deactivation is blocked or handled safely when the item has dependent transactions.
8. List export respects the active search/filter context.
9. Permissions independently control list, view, add, edit, delete, import, export, and activation actions.

Exceptions

• Duplicate codes, names where policy requires uniqueness, or barcodes are rejected.
• Invalid unit conversions, missing accounts, incomplete variant combinations, and incompatible tracking configuration prevent completion.

Required base definition

Field	Rule
English name	Required.
Arabic name	Required.
Short name	Optional.
Item type	Required and controls applicable configuration; item category type must match it.
Item category	Required, must exist, be active, and match item type.
UOM category	Required.
ETA code type/code	Optional as a pair unless electronic-invoice policy makes them mandatory.
Active	Defaults to true.

The item code is sequence/system-generated in the normal add workflow rather than entered by the command.

Tab rules

General

Category and localized names are required. Tags, photo, origin country, warranty, lifetime, special care, color, maximum discount, ETA data, and an item-specific slow-moving threshold are optional/conditional. Maximum discount and numeric durations cannot be negative.

Units of measure

The item keeps its UOM category and a list of UOMs with conversion ratio, active state, and optional usages. One base/default unit is required for stock calculations. A zero/missing base calculation blocks posting.

Variants and attributes

Selected attribute groups/values form variants. Duplicate combinations are not allowed. Disabling a value already used by history must preserve existing variant identity.

Barcode

Each barcode maps to an item, variant, and UOM; SKU is optional. Barcode identity must be unambiguous. Inactive barcodes remain visible in historical transactions but cannot be used for new entry.

Fixed cost

Fixed cost is stored by variant and UOM. It is used when fixed-cost information is required by stock records; it must be non-negative.

Tax and pricing

VAT applied, selected tax/tax ratio, price-includes-VAT, and variant/UOM prices are interdependent. Tax is required when VAT is enabled. Price must be non-negative. Changing tax/price affects future documents, not posted history.

Inventory

Tracking type and expiry behavior are required configuration choices. Batch, Serial, and No Tracking drive conditional transaction fields. Once stock/history exists, incompatible tracking changes must be blocked or migrated explicitly.

Accounting and service configuration

Item accounting contains purchase, purchase-return, sales/revenue, and sales-return accounts. Service items additionally support item cost center, expense account, and revenue account. Transaction-specific resolution may fall back from item to category and sometimes settings; see Posting and Account Resolution.

Action behavior

• Save base item: creates the item and default setup but no stock or GL transaction.
• Save a tab: changes only that configuration area and must preserve other tabs.
• Activate/deactivate: affects selection for new work; historical records remain readable.
• Delete: allowed only when dependency checks permit it; otherwise use deactivation.
• Import: validates every row, stages row errors, and commits only confirmed valid data according to import policy.
• Export: returns the authorized filtered item set.