Storage Areas
Storage Areas: Setup Guide for the APS Integration
Audience: ERP users who are familiar with Action Target's system but are new to PlanetTogether. Scope: Phase 1 — storage area management, cell groups, and the item storage coverage requirement. Related stories: US-005 (Inventory and Warehouse Maintenance Matrix), US-006 (Inventory and Warehouse Maintenance Tools).
1. How PlanetTogether Uses Storage Areas
PlanetTogether requires three objects before it will accept an item during import:
- An Items row — the item master record.
- An Inventories row — the item's inventory definition for a warehouse.
- At least one ItemStorage row — a mapping from that item/warehouse pair to a specific storage area.
If any of the three is missing for an exported item, PT will reject the item and any sales orders, work orders, shop jobs, or job materials that reference it. Storage areas are therefore not optional configuration — they are a gating requirement for every item that will be scheduled in PT.
The ERP manages storage area data in the aps schema. PT reads the data through export views; it does not write back to storage area records in Phase 1.
2. The Three Storage Area Types
Every storage area has an ERP Type that describes how it is linked to the ERP:
| Type | What it represents | Storage Area ID generated as |
|---|---|---|
| Location | Linked to a specific ERP material location (mat_loc_cell). Use when one location's inventory maps cleanly to one PT storage area. |
LOC-{location_id} |
| Cell Group | Linked to a named set of bank/column/row ranges (aps.cell_groups). Use when physical cells defined by a cell group represent a single logical storage area. |
CELLS-{cell_group_slug} |
| Placeholder | No ERP link. Used for default/unmapped areas such as UNMAPPED or AMS_PLACEHOLDER. |
The storage area name itself |
Storage area IDs are generated automatically by a database trigger. You supply a name when creating the area; the system assigns the ID based on the type and linked object. Once created, the ID is frozen — it cannot change even if the name is edited later.
A storage area cannot link to both a location and a cell group at the same time. The system enforces an either/or (XOR) rule. Selecting a different ERP Type in the create form automatically clears the other field.
The Default / Unmapped Placeholder
Every active warehouse should have at least one placeholder storage area that acts as the unmapped default. When an item/warehouse pair does not yet have a business-owned storage area assignment, the export system can assign it to this default row so PT can still import the item. Without a default, those items fail the ItemStorage requirement and block the export.
Use the Validate / Readiness check (see Section 5) to confirm each warehouse has a default before exporting.
3. Cell Groups and Mappings
A Cell Group is a named, reusable set of physical cell ranges. It exists independently of any single storage area and can be referenced by exactly one active storage area at a time.
Each cell group has:
- A Name — a human-readable label (e.g., "Weld Cells").
- A Slug — a short uppercase identifier used in the auto-generated storage area ID. Must be uppercase letters, digits, and hyphens only — no spaces. Examples:
WELD-CELLS,ASSEMBLY-A.
Cell Group Mappings define which physical cells the group covers. Each mapping row specifies:
- Bank — the racking bank identifier (e.g.,
101A). - Col From / Col To — the column range within that bank.
- Row From / Row To — the optional row range within those columns.
One cell group can have many mapping rows — one per bank or contiguous range. The union of all mapping rows describes the full set of cells the group covers.
4. The ERP Data Model
All storage area data that flows to PlanetTogether is owned in the aps schema. PT reads from export views (aps.*_v) that filter and shape the source tables.
Source Tables
| Table | What it holds |
|---|---|
aps.storage_area_source |
Storage area master records. Holds erp_type, erp_inv, mrp_nettable, constrained, erp_location_id, and erp_cell_group_id. The storage_area_id column is trigger-assigned on insert and cannot be changed afterward. |
aps.cell_groups |
Cell group master records. The slug column drives the CELLS-{slug} storage area ID. |
aps.cell_group_mappings |
Bank/column/row range rows for each cell group. |
Export Views (what PT reads)
| View | Feeds PT object | Notes |
|---|---|---|
aps.storage_areas_v |
Inventories / ItemStorage reference |
Active storage areas only. |
aps.item_storage_v |
ItemStorage |
Active item/storage area pairs only. |
aps.item_storage_lots_v |
ItemStorageLots |
Active lot-level assignments. |
The ERP is the authoritative source. Changes made inside PT to storage area data are not written back in Phase 1.
5. Using the Inventory Manager Setup Screen
The Setup tab in the Inventory Manager app is the central place to maintain storage areas and cell groups.
Access to create, edit, and retire records requires the Quality Manager role.
The screen operates in two modes controlled by toolbar toggles. The default mode when you open the tab is Storage Areas.
Main Toolbar
| Button | What it does |
|---|---|
| Show / Hide Storage Areas | Toggles the Storage Areas list. Visible by default. |
| Show / Hide Setup Tools | Toggles the Setup Tools section (cell groups and mappings). Hidden by default. |
| Validate / Readiness | Runs a live readiness check and opens the results modal. |
| Preview Ensure Item Storage | Shows which item/warehouse pairs would receive a default storage area assignment if the ensure function were run. |
| Refresh | Reloads the storage areas list from the database. |
Storage Areas List
This grid shows all storage areas from aps.storage_area_source.
Columns displayed: Storage Area ID, Name, Warehouse, ERP Type, ERP Inv, Location / Cell Group link target, Default, Default-only Item Count.
Toolbar actions:
| Action | Behavior |
|---|---|
| Create Storage Area | Opens the create modal. |
| Edit | Opens the edit modal for the selected row. Requires exactly one row selected. |
| Retire | Prompts for confirmation, then marks the storage area inactive. Records are never physically deleted. A default placeholder cannot be retired if it is the only default for its warehouse. |
Create / Edit Storage Area Modal
Both create and edit use the same form. In edit mode, the Storage Area ID is shown as read-only — it was assigned at creation and cannot change.
Form fields:
| Field | Required | Notes |
|---|---|---|
| Storage Area Name | ✅ | The display label in PT and in the ERP. |
| Warehouse | ✅ | Autocomplete from active warehouses. |
| ERP Type | ✅ | Location, Cell Group, or Placeholder. Changing type resets the other link field. |
| Inventory Class | ✅ | INV, WIP, or AMS. Defaults to INV. |
| ERP Location | Context | Shown when ERP Type is Location. Autocomplete from active ERP material locations. |
| Cell Group | Context | Shown when ERP Type is Cell Group. Autocomplete from active cell groups, sorted by slug. |
| MRP Nettable | Checkbox. Defaults to checked. Controls whether PT includes this area's stock in net requirements. | |
| Constrained | Checkbox. Defaults to unchecked. | |
| Notes | Optional free text. Not sent to PT. |
ERP Location and Cell Group are mutually exclusive. Only one field is visible at a time based on ERP Type. Switching types clears the previously chosen value.
Validate / Readiness Modal
Click Validate / Readiness in the main toolbar to open this modal. It displays four counters plus a row-level issue list.
| Counter | What it flags |
|---|---|
| Warehouses Missing Default | Warehouses with no active placeholder storage area marked as default. |
| Items Missing Storage | Item/warehouse pairs with no ItemStorage row — these will fail PT import. |
| Inactive Location Links | Storage areas of type Location whose linked mat_loc_cell row is no longer active. |
| Inactive Cell Group Links | Storage areas of type Cell Group whose linked cell group is no longer active. |
The issue list provides row-level detail: the issue code, a plain-language message, and the affected Storage Area ID if applicable.
This modal is read-only. Resolve issues by correcting the underlying storage area, location, or cell group data, then run the check again.
Preview Ensure Item Storage Modal
Click Preview Ensure Item Storage to see which item/warehouse pairs currently lack an ItemStorage row. The modal shows the row count that would be inserted and a table of the affected item/warehouse/storage area combinations.
This is preview-only. No data is written when you open this modal. The actual ensure operation requires a separate approval step and is run through a database function before export.
Use this preview as a pre-export check to confirm all items are covered before kicking off a PT import.
Setup Tools — Cell Groups
Click Show Setup Tools in the main toolbar, then Show Cell Groups to manage cell groups and their mappings.
Cell Groups grid toolbar:
| Action | Behavior |
|---|---|
| Create Cell Group | Opens the cell group form in create mode. |
| Edit | Opens the form for the selected cell group. |
| Retire | Marks the cell group inactive. Blocked if an active storage area currently references this cell group. |
| Show All (incl. Inactive) / Show Active Only | Toggles visibility of inactive cell groups. |
Cell group form fields:
| Field | Required | Notes |
|---|---|---|
| Name | ✅ | Human-readable label. |
| Slug | ✅ | Uppercase letters, digits, and hyphens only. Drives the CELLS-{slug} storage area ID. Must be unique. |
| Description | Optional. | |
| Notes | Optional internal notes. |
Cell Group Mappings grid:
Selecting a cell group row filters the Mappings grid to that group's rows. Each mapping covers one bank/range.
| Action | Behavior |
|---|---|
| Add Mapping | Opens the mapping form. Select a bank and enter column/row ranges. |
| Retire | Removes the mapping row from the active set. |
Mapping form fields: Bank (autocomplete from ERP racking banks), Col From, Col To, Row From (optional), Row To (optional), Notes (optional).
6. Phase 1 Scope: What's Used and What's Not
| Feature | Phase 1 Status | Notes |
|---|---|---|
| Storage area create / edit / retire | ✅ Used | Full CRUD via Inventory Manager Setup tab. |
| All three ERP Types (Location, Cell Group, Placeholder) | ✅ Used | All supported. |
| Cell group create / edit / retire | ✅ Used | Managed in Setup Tools. |
| Cell group bank/column/row mappings | ✅ Used | Add / retire mapping rows per cell group. |
| Validate / Readiness check | ✅ Used | Four-counter check plus row-level issue list. |
| Preview Ensure Item Storage | ✅ Used | Pre-export coverage check. |
| ERP location editor (create/edit ERP locations) | ❌ Deferred | Locations are read-only lookup targets in Phase 1. |
| Racking cell / cell range preview | ❌ Deferred | Phase 2 Setup Tools expansion. |
| Legacy Material setup functions | ❌ Deferred | Ported from Tcl in a later phase. |
| PT write-back (PT → ERP storage area changes) | ❌ Not in scope | ERP is authoritative; PT is a read-only consumer for Phase 1. |
7. Summary: The Minimum You Need Before Items Can Export
Before PlanetTogether can successfully import item and inventory data, the following must be true:
- ✅ Every active warehouse has at least one default placeholder storage area.
- ✅ Every active storage area of type
Locationlinks to a currently active ERP material location. - ✅ Every active storage area of type
Cell Grouplinks to a currently active cell group with at least one mapping row. - ✅ Every item/warehouse pair that will be exported has at least one
ItemStoragerow — confirm with Preview Ensure Item Storage before running the export. - ✅ Validate / Readiness shows zero issues in all four counters.
Missing any of these will cause PT to reject the affected items and all dependent sales orders, work orders, and job materials during import.