# Work Plans

Work orders / cellar tasks issued from the ERP system. One row per work plan. In Claret, these populate the **Work Planning** module's board, kanban, and capacity views.

## Schema

<table><thead><tr><th>#</th><th>Column</th><th data-type="checkbox">Required?</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>1</td><td><code>external_system_id</code></td><td>true</td><td>The ERP's identifier for this work order. Unique per row. Used as the merge key so re-deliveries update the same work plan in Claret.</td><td><code>WO-2026-0501-001</code></td></tr><tr><td>2</td><td><code>activity_type</code></td><td>true</td><td>The kind of work being done. Must be one of the values in Controlled vocabularies.</td><td><code>Cap Management</code></td></tr><tr><td>3</td><td><code>status</code></td><td>true</td><td>Current state of the work plan. Must be one of the values in Controlled vocabularies.</td><td><code>Scheduled</code></td></tr><tr><td>4</td><td><code>description</code></td><td>true</td><td>Short title.</td><td><code>Punch-downs on Tank 4</code></td></tr><tr><td>5</td><td><code>location_name</code></td><td>true</td><td>The site where the work occurs. Must match a <code>location</code> from the Locations file.</td><td><code>ZAM-WINERY</code></td></tr><tr><td>6</td><td><code>priority</code></td><td>false</td><td>One of: <code>Critical</code>, <code>High</code>, <code>Medium</code>, <code>Low</code>. Defaults to <code>Medium</code>.</td><td><code>High</code></td></tr><tr><td>7</td><td><code>location_area_name</code></td><td>false</td><td>Sub-area within the location. Must match a <code>location_area</code> from the Locations file.</td><td><code>North</code></td></tr><tr><td>8</td><td><code>item_name</code></td><td>false</td><td>The item this work targets, if applicable. Can reference <strong>any</strong> item level: an FG <code>item_name</code> or <code>vintage_name</code> from the Finished Good Items file, or a <code>parent_wip_name</code> or <code>child_wip_name</code> from the Bulk Wine Items file. Use the level that best matches what the work order is actually for. A generic "rack a barrel of Cab" might target the parent WIP <code>ZAMNVCAS</code>; "transfer SS-01 to SS-02" for the 2020 vintage targets <code>ZAMNVCAS20</code>.</td><td><code>ZAMNVCAS20</code></td></tr><tr><td>9</td><td><code>comments</code></td><td>false</td><td>Long-form notes from the ERP.</td><td><code>Twice daily punchdowns until end of fermentation</code></td></tr><tr><td>10</td><td><code>earliest_start_date</code></td><td>false</td><td>The earliest date this work can begin, as <code>YYYY-MM-DD</code>.</td><td><code>2026-05-08</code></td></tr><tr><td>11</td><td><code>due_date</code></td><td>false</td><td>When this work must be completed, as <code>YYYY-MM-DD</code>.</td><td><code>2026-05-12</code></td></tr><tr><td>12</td><td><code>scheduled_start</code></td><td>false</td><td>Planned start, as <code>YYYY-MM-DD HH:MM</code> (24h, client local time).</td><td><code>2026-05-08 07:00</code></td></tr><tr><td>13</td><td><code>scheduled_end</code></td><td>false</td><td>Planned end, as <code>YYYY-MM-DD HH:MM</code>.</td><td><code>2026-05-08 09:00</code></td></tr><tr><td>14</td><td><code>actual_start</code></td><td>false</td><td>Actual start, as <code>YYYY-MM-DD HH:MM</code>. Omit until work begins.</td><td><code>2026-05-08 07:05</code></td></tr><tr><td>15</td><td><code>actual_end</code></td><td>false</td><td>Actual end, as <code>YYYY-MM-DD HH:MM</code>. Omit until work completes.</td><td><code>2026-05-08 08:55</code></td></tr><tr><td>16</td><td><code>quantity</code></td><td>false</td><td>Estimated work quantity (e.g., gallons to move, cases to handle). Numeric value. Decimals fine, whole numbers fine. No thousands separators.</td><td><code>5000</code></td></tr><tr><td>17</td><td><code>uom</code></td><td>false</td><td>Unit of measure for <code>quantity</code>.</td><td><code>Gallon</code></td></tr></tbody></table>

## Header row

```
external_system_id,activity_type,status,description,location_name,priority,location_area_name,item_name,comments,earliest_start_date,due_date,scheduled_start,scheduled_end,actual_start,actual_end,quantity,uom
```

## Sample data

```csv
external_system_id,activity_type,status,description,location_name,priority,location_area_name,item_name,comments,earliest_start_date,due_date,scheduled_start,scheduled_end,actual_start,actual_end,quantity,uom
WO-2026-0501-001,"Cap Management",Scheduled,"Punch-downs on Tank 4",ZAM-WINERY,High,North,ZAMNVCAS20,"Twice daily punchdowns until end of fermentation",2026-05-08,2026-05-12,"2026-05-08 07:00","2026-05-08 09:00",,,3,Hour
WO-2026-0501-002,Filter,"In Progress","Filter Pinot Noir from SS-01 to SS-02",ZAM-WINERY,Medium,North,FNESLPNO26,,2026-05-07,2026-05-09,"2026-05-08 13:00","2026-05-08 17:00","2026-05-08 13:15",,5000,Gallon
WO-2026-0501-003,Bottling,Planned,"Bottling run for 2016 Napa Cab",ZAM-WINERY,High,South,122-16,"Run scheduled per bottling schedule",2026-05-12,2026-05-12,"2026-05-12 06:00","2026-05-12 14:00",,,1500,"9LE Case"
WO-2026-0501-004,Moves,Planned,"Consolidate Cabernet across vintages",ZAM-WINERY,Medium,North,ZAMNVCAS,"Generic move applies to whole Cab parent; target vintage TBD",2026-05-09,2026-05-11,,,,,1500,Gallon
WO-2026-0430-014,Sanitation,Completed,"CIP clean SS-01 post-filtration",ZAM-WINERY,Medium,North,,,2026-04-30,2026-05-01,"2026-04-30 16:00","2026-04-30 18:00","2026-04-30 16:05","2026-04-30 17:50",2,Hour
```

{% hint style="info" %}

* Row 1: bulk wine, **child WIP** target (`ZAMNVCAS20`).
* Row 3: FG bottling, **vintage** target (`122-16`).
* Row 4: bulk wine, **parent WIP** target (`ZAMNVCAS`), used when the work isn't tied to a specific vintage.
* Row 5: no item; work is location-only (sanitation).
  {% endhint %}

## Snapshot semantics

* Full snapshot of all open and recently-closed work plans every delivery. Plans completed or cancelled more than 30 days ago may be omitted.
* `external_system_id` is the merge key; re-delivering the same id updates the existing plan in place.
* A work plan absent from a new file but present in a prior file is **not** treated as cancelled. To cancel, deliver the row with `status=Cancelled`. (This avoids accidental loss when an ERP query temporarily excludes recent records.)
* Activity types, statuses, and priorities must use the controlled vocabularies below. Unknown values will be rejected.

## Controlled vocabularies

### Activity types

`activity_type` must be one of:

`Additions`, `Bottling`, `Cap Management`, `Centrifuge`, `Circulation`, `Cross Flow`, `De-alc`, `De-va`, `Drain/Press`, `Filter`, `Harvest`, `Inventory`, `Measure`, `Moves`, `Oak Additions`, `Pickup Inbound`, `Pickup Outbound`, `Sanitation`, `Site Projects`, `Ullage`

### Statuses

| Status        | Meaning                                                       |
| ------------- | ------------------------------------------------------------- |
| `Planned`     | Work identified but not yet scheduled to a specific date/time |
| `Scheduled`   | Work assigned a specific scheduled start/end                  |
| `In Progress` | Work has started but is not yet complete                      |
| `On Hold`     | Work has been paused; will resume                             |
| `Completed`   | Work is done                                                  |
| `Cancelled`   | Work will not be performed                                    |

### Priorities

`priority` must be one of:

`Critical`, `High`, `Medium`, `Low`


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.claret.app/integrations/inbound-file-feed/work-plans.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.