Docs for new build procedure

_includes/img.html

@@ -10,7 +10,7 @@
 {% set doc_url = assets  + '/images/' + url %}
 {% endif %}
 
-<figure class='image'>
+<figure class='image image-inventree'>
     {% if id %}
     <!-- The link that, when clicked, will display the image in full screen -->
     <a href="#{{ id }}">

docs/build/allocate.md

@@ -0,0 +1,143 @@
+---
+title: Build Allocation
+---
+
+## Build Allocation
+
+Allocating stock items to a build order signals an intent that those stock items will be removed from the InvenTree database once the build order is completed.
+
+Depending on the particular requirements of the build, and your stock control setup, allocating stock items to a build can be a complex task. In this regard, InvenTree provides an allocation interface which attempts to keep the number of user interactions required to a minimum.
+
+!!! warning "Build Completion"
+    Marking a build as *complete* will remove allocated items from stock. This operation cannot be reversed, so take care!
+
+### Untracked vs Tracked Stock
+
+Before continuing, it is important that the difference between *untracked* and *tracked* parts, as they impose different requirements when it comes to stock allocation.
+
+#### Untracked Stock
+
+*Untracked* stock items disappear from the database once they are "used". Once stock items for these parts are removed from the InvenTree database (e.g. used to create an assembly), the tracking information for these stock items disappears. The stock items no longer persist in the database.
+
+!!! info "Example: Untracked Parts"
+    You require 15 x 47K resistors to make a batch of PCBs. You have a reel of 1,000 resistors which you allocate to the build. At completion of the build, the stock quantity is reduced to 985
+
+#### Tracked Stock
+
+*Tracked* stock items, on the other hand, require special attention. These are parts which we wish to track indefinitely, even if they are "consumed" to create an assembly. *Tracked* stock items are not deleted as they are consumed. Instead, they are installed *within* the assembled unit
+
+!!! info "Example: Tracked Parts"
+    The assembled PCB (in the example above) is a *trackable* part, and is given a serial number #001. The PCB is then used to make a larger assembly in a subsequent build order. At the completion of that build order, the tracked PCB is *installed* in the assembly, rather than being deleted from stock.
+
+#### BOM Considerations
+
+A [Bill of Materials](../bom) to generate an assembly may consist of a mixture of *untracked* and *tracked* components. The build order process can facilitate this, as documentated in the sections below.
+
+### Tracked Build Outputs
+
+If a Build Order is created for an assembled part which is itself designed as *trackable*, some extra restrictions apply:
+
+- Build outputs must be single quantity
+- Build outputs must be serialized as they are created
+
+## Allocating Untracked Stock
+
+Untracked stock items are allocated against the *Build Order* itself. We do not need to track which *Build Output* these items will be installed into, and so the allocation process can be simplified.
+
+Navigate to the *Allocate Stock* tab to view the stock allocation table:
+
+{% with id="build_allocate_detail", url="build/build_allocate_detail.png", description="Allocate stock" %}
+{% include "img.html" %}
+{% endwith %}
+
+In this example, there are two BOM line items which have been partially allocated to the build. Each line has a progress bar indicating how much of the required stock has been allocated.
+
+In each row, pressing the <span class='fas fa-plus'></span> icon expands the row, showing a list of stock items which have been allocated against this build.
+
+!!! info "Multiple Allocations"
+    Note that multiple stock items can be allocated to the given BOM line, if a single stock item does not have sufficient stock
+
+{% with id="build_allocation_expand", url="build/build_allocation_expand.png", description="Allocate expand" %}
+{% include "img.html" %}
+{% endwith %}
+
+### Auto Allocation
+
+To speed up the allocation process, the *Auto Allocate* button can be used to allocate untracked stock items to the build. Automatic allocation of stock items does not work in every situation, as a number of criteria must be met.
+
+For each line in the BOM, stock will be automatically allocated if one (and only one) stock item (for the referenced part) is found (within the specified *source location* for the build):
+
+!!! warning "Multiple Stock Items"
+    If multiple stock items are available, the InvenTree auto allocation system cannot make a determination about which stock item to allocate.
+
+Selecting *Auto Allocate* opens a dialog window which displays the stock items which will be allocated to the build during the auto allocation process:
+
+{% with id="build_auto", url="build/build_auto_allocate.png", description="Auto allocate" %}
+{% include "img.html" %}
+{% endwith %}
+
+!!! info "Note"
+    Note here that the *SAM-M8Q-0-10* part can be automatically allocated as it only exists in a single stock location. However the other BOM line item exists in multiple locations, and thus cannot be automatically allocated
+
+### Manual Allocation
+
+Stock can be manually allocated to the build as required, using the *Allocate stock* button available in each row of the allocation table
+
+### Edit Allocations
+
+Stock allocations can be manually adjusted or deleted using the action buttons available in each row of the allocation table.
+
+### Unallocate Stock
+
+The *Unallocate Stock* button can be used to remove all allocations of untracked stock items against the build order.
+
+## Allocating Tracked Stock
+
+Allocation of tracked stock items is slightly more complex. Instead of being allocated against the *Build Order*, tracked stock items must be allocated against an individual *Build Output*.
+
+Allocating tracked stock items to particular build outputs is performed in the *Build Outputs* tab:
+
+Let us consider the case where the BOM for the assembled part has a single *trackable* part, which we will call simply "Tracked Part".
+
+In the *Build Outputs* tab, we can see that each build output has a stock allocation requirement which must be met before that build output can be completed:
+
+{% with id="build_allocate_tracked_parts", url="build/build_allocate_tracked_parts.png", description="Allocate tracked parts" %}
+{% include "img.html" %}
+{% endwith %}
+
+Here we can see that the incomplete build outputs (serial numbers 5 and 6) now have a progress bar indicating the status of tracked stock item allocation:
+
+- Serial number 5 has been fully allocated, and can be completed
+- Serial number 6 has not been fully allocated, and cannot yet be completed
+
+## Completing a Build Output
+
+An individual build output is completed by selecting the "Complete build output" button associated with that build output:
+
+{% with id="build_output_complete", url="build/build_output_complete.png", description="Complete build output" %}
+{% include "img.html" %}
+{% endwith %}
+
+Here the user can select the destination location for the build output, as well as the stock item status.
+
+### Allocated Stock
+
+*Tracked* stock items which are allocated against the selected build output will be removed from stock, and installed "inside" the output assembly. The allocated stock items will still exist in the InvenTree database, however will no longer be available for regular stock actions.
+
+!!! note "Example: Tracked Stock"
+    Let's say we have 5 units of "Tracked Part" in stock - with 1 unit allocated to the build output. Once we complete the build output, there will be 4 units of "Tracked Part" in stock, with 1 unit being marked as "installed" within the assembled part
+
+## Completing a Build
+
+!!! warning "Complete Build Outputs"
+    A build order cannot be completed if there are outstanding build outputs. Ensure that all build outputs are completed first.
+
+Once all build outputs have been completed, the build order itself can be completed by selecting the *Complete Build* button:
+
+{% with id="build_complete", url="build/complete_build.png", description="Complete build order" %}
+{% include "img.html" %}
+{% endwith %}
+
+### Allocated Stock
+
+All *untracked* stock items which are allocated against this build will be removed from stock.

docs/build/build.md

@@ -1,88 +1,190 @@
 ---
-title: Build Parts
+title: Build Orders
 ---
 
-## Building Parts
+## Build Orders
 
-Build management can be accessed via the *Build* navigation tab.
+A *Build Order* is used to create new stock by assembling component parts, according to a [Bill of Materials](../bom)(BOM).
 
-A "basic" build flow is as follow:
+A BOM can be specified for any [Part](../../part/part) which is designated as an *Assembly*. The BOM consists of other Parts which are designated as *Components*.
 
-1. create a part with the [*Assembly option*](../../part/views/#part-options) turned-on
-0. add a Bill of Material (BOM)
-0. create a "Build Order" for this part
-0. allocate stocks from your inventory
-0. update build status and notes
-0. complete the build.
+A *Build Order* uses the BOM to allocate stock items to the assembly process. As the *Build Order* is completed, the required stock quantities are subtracted from allocated stock items.
+
+### View Build Orders
+
+To navigate to the Build Order display, select *Build* from the main navigation menu:
+
+{% with id="build_display", url="build/build_display.png", description="Display Builds" %}
+{% include "img.html" %}
+{% endwith %}
+
+#### Table View
+
+*Table View* provides a table of Build Orders, which can be filtered to only show the orders you are interested in.
+
+#### Calendar View
+
+*Calendar View* shows a calendar display with upcoming build orders, based on the various dates specified for each build.
+
+## Build Order Details
+
+### Build Parameters
+
+The following parameters are available for each Build Order, and can be edited by the user:
+
+| Parameter | Description |
+| --- | --- |
+| Reference | Build Order reference e.g. '001' |
+| Description | Description of the Build Order |
+| Part | Link to the *Part* which will be created from the Build Order |
+| Quantity | Number of stock items which will be created from this build |
+| Sales Order | Link to a *Sales Order* to which the build outputs will be allocated |
+| Source Location | Stock location to source stock items from (blank = all locations) |
+| Destination Location | Stock location where the build outputs will be located |
+| Target Date | Target date for build completion |
+| Responsible | User (or group of users) who is resonsible for the build |
+| External Link | Link to external webpage |
+| Notes | Build notes, supports markdown |
+
+### Build Output
+
+A *Build Output* creates a new stock instance of the assembly part, of a specified quantity. Each *Build Order* requires at least one build output. Multiple build outputs can be specified if the build is completed in batches.
+
+!!! info "Example - Build Outputs"
+	For example, let's say we wish to create 10 new "Widgets". We create a new build for the widget, which signals an *intent* to assemble the "Widget" in quantity 10. We can produce 5 widgets in a single day, and so we create 2 build outputs, each of quantity 5.
 
 ### Build Status
 
+Each *Build Order* has an associated *Status* flag, which indicates the state of the build:
+
 | Status | Description |
 | ----------- | ----------- |
-| `Pending` | "Build Order" has been created and build is ready for subpart allocation |
-| `Allocated` | All subparts stocks in the part BOM have been allocated |
+| `Pending` | Build has been created and build is ready for subpart allocation |
+| `Production` | One or more build outputs have been created for this build |
 | `Cancelled` | Build has been cancelled |
 | `Completed` | Build has been completed |
 
-### Part BOM
+### Stock Allocations
 
-A Part BOM is required to allocate inventory to a build.
+When a *Build Order* is created, we then have the ability to *allocate* stock items against that build order. The particular parts we need to allocate against the build are specified by the BOM for the part we are assembling.
 
-Read through the [Bill of Materials documentation](../bom).
+- A *Stock Alloction* links a certain quantity of a given *Stock Item* to the build.
+- At least one stock allocation is required for each line in the BOM
+- Multiple stock allocations can be made against a BOM line if a particular stock item does not have sufficient quantity for the build
 
-### Build Order
+!!! info "Example - Stock Allocation"
+	Let's say that to assembly a single "Widget", we require 2 "flanges". So, to complete a build of 10 "Widgets", 20 "flanges" will be required. We *allocate* 20 flanged against this build order.
 
-Builds orders are used to create parts builds.
+Allocating stock to a build does not actually subtrack the stock from the database. Allocations signal an *intent* to take that stock for the purpose of this build. Stock allocations are actioned at the completion of a build.
+
+!!! info "Part Allocation Information"
+    Any part which has stock allocated to a build order will indicate this on the part information page.
+
+For further information, refer to the [stock allocation documentation](../allocate).
+
+## Build Order Display
+
+The detail view for a single build order provides multiple display tabs, as follows:
+
+### Build Details
+
+The *Build Details* tab provides an overview of the Build Order:
+
+{% with id="build_details", url="build/build_details.png", description="Details tab" %}
+{% include "img.html" %}
+{% endwith %}
+
+### Allocate Stock
+
+The *Allocate Stock* tab provides an interface to allocate required stock (as specified by the BOM) to the build:
+
+{% with id="build_allocate", url="build/build_allocate.png", description="Allocation tab" %}
+{% include "img.html" %}
+{% endwith %}
+
+The allocation table (as shown above) shows the stock allocation progress for this build. In the example above, there are two BOM lines, which have been partially allocated.
+
+!!! info "Completed Builds"
+	The *Allocate Stock* tab is not available if the build has been completed!
+
+### Build Outputs
+
+The *Build Outputs* tab shows the outputs (created stock items) associated with this build.
+
+As shown below, there are separate panels for *incomplete* and *completed* build outputs.
+
+{% with id="build_outputs", url="build/build_outputs.png", description="Outputs tab" %}
+{% include "img.html" %}
+{% endwith %}
+
+!!! info "Example: Build Outputs"
+	In the example image above, a single output (serial number 2) has been completed, while serial numbers 1 and 4 are still in progress.
+
+- Build outputs can be created from this screen, by selecting the *Create New Output* button
+- Outputs which are "in progress" can be completed or cancelled
+- Completed outputs (which are simply *stock items*) can be viewed in the stock table at the bottom of the screen
+
+### Child Builds
+
+If there exist any build orders which are *children* of the selected build order, they are displayed in the *Child Builds* tab:
+
+{% with id="build_childs", url="build/build_childs.png", description="Child builds tab" %}
+{% include "img.html" %}
+{% endwith %}
+
+### Attachments
+
+Files attachments can be uploaded against the build order, and displayed in the *Attachments* tab:
+
+{% with id="build_attachments", url="build/build_attachments.png", description="Attachments tab" %}
+{% include "img.html" %}
+{% endwith %}
+
+### Notes
+
+Build order notes (which support markdown formatting) are displayed in the *Notes* tab:
+
+{% with id="build_notes", url="build/build_notes.png", description="Notes tab" %}
+{% include "img.html" %}
+{% endwith %}
+
+## Create Build Order
 
 To create a build order for your part, you have two options:
 
-1. navigate to the Part detail page, click on "Build Orders" tab then click on "Start New Build" button
-0. navigate to the Build page, click on "New Build Order".
+### Part Detail Page
+
+- Navigate to the detail page for the assembly part you wish to create
+- Select the *Build Orders* tab
+- Select *Start new Build*
+
+{% with id="build_create_from_part", url="build/build_create_from_part.png", description="Create build from Part view" %}
+{% include "img.html" %}
+{% endwith %}
+
+### Build Order Page
+
+- Navigate to the Build Order overview page
+- Select *New Build Order*
+
+-----
+
+Either of these options will launch the *Start new Build* form:
 
 {% with id="build_start_new", url="build/build_start_new.png", description="Start New Build Form" %}
 {% include 'img.html' %}
 {% endwith %}
 
-Fill-out the form then click the "Submit" button to create the build.
+Fill-out the form as required, then click the "Submit" button to create the build.
 
-### Stock Allocation
-
-To allocate stock for a build, you have two options:
-
-1. **automatic** allocation: if each subpart has only **one** storage location, InvenTree can allocate stock from this location automatically
-0. **manual** allocation: user can define allocation for each subpart in the build.
-
-During allocation, InvenTree relies on [Stock items](../../stock/stock/#stock-item) to reference parts that will be used for the build. Make sure to read through the [stock documentation](../../stock/stock) before proceeding with stock allocation.
-
-#### Automatic Allocation
-
-Click on the "Allocated Parts" tab then click on the "Auto Allocate" button to automatically allocate stock for this build.
-
-The `Allocate Stock` form will be displayed. Verify each subpart automatic allocation, click on the confirmation switch, then click on the "Submit" button to process the stock allocation.
-
-#### Manual Allocation
-
-Click on the "Allocated Parts" tab then click on the <span class='fas fa-plus'></span> icon next to each subpart in the build to manually allocate stock.
-
-The `Allocate new Part` form will be displayed. Select a `Stock Item` and fill-out the `Quantity` field then click on the "Submit" button to allocate stock for this subpart.
-
-#### Unallocate
-
-Click on the "Allocated Parts" tab then click on the "Unallocate" button to unallocate stock items allocated for this build.
-
-### Cancel Build
-
-To cancel a build, click on <span class='fas fa-times-circle'></span> icon on the build detail page.
-
-The `Cancel Build` form will be displayed, click on the confirmation switch then click on the "Cancel Build" button to process the build cancellation.
-
-!!! warning "Cancelled Build"
-	**A cancelled build cannot be re-opened**. Make sure to use the cancel option only if you are certain that the build won't be processed.
-
-### Complete Build
+### Complete Build Order
 
 To complete a build, click on <span class='fas fa-tools'></span> icon on the build detail page, the `Complete Build` form will be displayed.
 
+#### Build Outputs
+
+If incomplete build outputs remain, the build order will not be able to be completed. All build outputs *must* be completed first.
+
 !!! info "Incomplete Allocation"
 	If the warning message `Warning: Build order allocation is not complete` is shown, make sure to allocate stock for the build before proceeding with build completion.
 
@@ -92,7 +194,16 @@ Finally, click on the "Complete Build" button to process the build completion.
 !!! warning "Completed Build"
 	**A completed build cannot be re-opened**. Make sure to use the confirm only if you are certain that the build is complete.
 
-### Overdue Builds
+## Cancel Build Order
+
+To cancel a build, click on <span class='fas fa-times-circle'></span> icon on the build detail page.
+
+The `Cancel Build` form will be displayed, click on the confirmation switch then click on the "Cancel Build" button to process the build cancellation.
+
+!!! warning "Cancelled Build"
+	**A cancelled build cannot be re-opened**. Make sure to use the cancel option only if you are certain that the build won't be processed.
+
+## Overdue Builds
 
 Build orders may (optionally) have a target complete date specified. If this date is reached but the build order remains incomplete, then the build is considered *overdue*.
 

docs/stylesheets/extra.css

@@ -22,6 +22,15 @@
 	transition: opacity .3s;
 }
 
+.image-inventree {
+	border-radius: 2px;
+	border: 1px solid #ddd;
+}
+
+.image-inventree:hover {
+	opacity: 75%;
+}
+
 .overlay img {
 	/* Maximum image size */
 	max-width: 90%;

mkdocs.yml

@@ -66,8 +66,9 @@ nav:
     - Stock Ownership: stock/owner.md
     - Test Results: stock/test.md
   - Build:
-    - Build Parts: build/build.md
-    - Bill of Materials (BOM): build/bom.md
+    - Build Orders: build/build.md
+    - Bill of Materials: build/bom.md
+    - Allocating Stock: build/allocate.md
   - Companies:
     - Suppliers: companies/supplier.md
     - Manufacturers: companies/manufacturer.md