# Build orders and work instructions

> Order lifecycle, reservations, the produce flow, work instructions, final test plan.

A build order says how many units of one assembly revision you will build. Work instructions and a test plan say how. You manage orders in **Build Orders**. For a worked example, see [Your first build order](https://buildtrace.eu/docs/getting-started/first-build-order.md).

## Order lifecycle

An order has one of these statuses:

1. `DRAFT`: you chose the revision, the target quantity, where to take materials from and where to put the units. Create it with `createBuildOrder`.
2. `RESERVED`: the materials are set aside for this order. Use `reserveBuildOrder`.
3. `IN_PRODUCTION`: building has started. Use `startBuildOrder`, then `produceUnit` for each unit.
4. `COMPLETED`: use `completeBuildOrder`.
5. `CANCELLED`: use `cancelBuildOrder`. You must give a reason.

You can cancel an order that is not yet `COMPLETED` or `CANCELLED`. To reserve, the order must have acknowledged every ECO in force on its revision. Do this on the **ECOs** tab. See [Change orders](https://buildtrace.eu/docs/concepts/change-orders.md).

## Reservations

Reserving sets stock aside for the order. A serialized part reserves specific units, and they change to `RESERVED`. A `RAW` part reserves a quantity.

Reservations can't oversell. Reserving checks what is available at the location you chose to consume from, and it fails if there isn't enough. Stock that another open order has reserved does not count as available. See [Inventory](https://buildtrace.eu/docs/concepts/inventory.md).

Cancelling releases the reservations. `RAW` stock frees immediately, because a reservation only counts while its order is open. Reserved serials go back to `AVAILABLE`.

## Materials

The **Materials** tab shows the `requirements` of the order as a multi-level tree: every part the order needs, and the parts of each sub-assembly beneath it. The **Need** column is what this order needs. A **Short** chip appears next to any item you don't have enough of. Hover over it to see the numbers. It also says when stock exists but another item in the same tree has already claimed it. The operation is `listBuildOrderRequirements`.

## Producing a unit

Select **Produce unit** on an order that is in production. A wizard guides the operator through the work instructions, the materials used and the final test. The unit gets its serial number and its as-built record. See [Serials](https://buildtrace.eu/docs/concepts/serials.md).

## Work instructions

`work instructions` tell the operator how to build one revision. They belong to the revision, not to the order. You edit them on the **Process** tab. A work instruction has:

- A list of tools and a list of cautions.
- A list of steps, each with a title and a description.
- A switch, **Require operator acknowledgment**. In the API this is `requireAck`. It is set once for the whole work instruction, not per step.

A step can also name the BOM components it concerns, cite a manual and the place in it, and carry images. Each image has alt text.

Like the BOM, work instructions are editable on a draft and frozen on release. To change them on a released revision, raise a process ECO. See [Change orders](https://buildtrace.eu/docs/concepts/change-orders.md). You can read the current version with `getEffectiveWorkInstruction`, which includes any ECO that is in force. You write a draft's with `setWorkInstruction`.

## The final test plan

The `test plan` is the list of checks every unit must pass before it counts as built. It sits next to the work instructions on the **Process** tab, with the same rules: editable on a draft, frozen on release, changed through a process ECO.

Each check has a name that is unique within the plan and one of three types:

- **Measurement**: a number with a unit and a minimum, a maximum or both. A target is optional.
- **Pass/fail**: a yes or no result, such as "BLE pairing".
- **Recorded value**: a value that is kept but not judged, such as "firmware version read back".

A check is required unless you mark it optional. You write a draft's plan with `setTestPlan` and read the current one with `getEffectiveTestPlan`.

### How the result is worked out

The operator records a result for each check. BuildTrace works out the final result:

- `PASS` when every required check passes and no recorded check is out of spec.
- `FAIL` otherwise. An optional check that was recorded and failed still fails the unit.

A failing unit is still produced. It gets its serial number and a `FAIL` result, and it is quarantined. From its page you can rework it, retest it or scrap it.

If the revision has no test plan, the unit is recorded as not tested. If it has a plan, the operator must record the results to produce the unit.