diff --git a/docs/assets/images/report/add_report_template.png b/docs/assets/images/report/add_report_template.png new file mode 100644 index 0000000..3268a7a Binary files /dev/null and b/docs/assets/images/report/add_report_template.png differ diff --git a/docs/assets/images/report/filters_invalid.png b/docs/assets/images/report/filters_invalid.png new file mode 100644 index 0000000..7d72abe Binary files /dev/null and b/docs/assets/images/report/filters_invalid.png differ diff --git a/docs/assets/images/report/filters_valid.png b/docs/assets/images/report/filters_valid.png new file mode 100644 index 0000000..777ef96 Binary files /dev/null and b/docs/assets/images/report/filters_valid.png differ diff --git a/docs/assets/images/report/test_report_filters.png b/docs/assets/images/report/test_report_filters.png new file mode 100644 index 0000000..07802f9 Binary files /dev/null and b/docs/assets/images/report/test_report_filters.png differ diff --git a/docs/releases/release_notes.md b/docs/releases/release_notes.md index e0c249d..1926909 100644 --- a/docs/releases/release_notes.md +++ b/docs/releases/release_notes.md @@ -27,6 +27,9 @@ Specific tagged releases are shown below. Click on the release notes for each ve !!! info "Release Notes" Starting from v0.7.2, release notes have been migrated to GitHub. Release notes for older versions are available at the links below. +### 0.11.x +{% with prefix="0.11" %}{% include "release_table.html" %}{% endwith %} + ### 0.10.x {% with prefix="0.10" %}{% include "release_table.html" %}{% endwith %} diff --git a/docs/report/build.md b/docs/report/build.md index 8f9770a..9aa5431 100644 --- a/docs/report/build.md +++ b/docs/report/build.md @@ -4,7 +4,11 @@ title: Build Order Report ## Build Order Report -Custom build order reports may be generated against any given Build Order. For example, build order reports can be used to generate work orders. +Custom build order reports may be generated against any given [Build Order](../build/build.md). For example, build order reports can be used to generate work orders. + +### Build Filters + +A build order report template may define a set of filters against which [Build Order](../build/build.md) items are sorted. ### Context Variables diff --git a/docs/report/purchase_order.md b/docs/report/purchase_order.md index 58c99a7..af2c4f1 100644 --- a/docs/report/purchase_order.md +++ b/docs/report/purchase_order.md @@ -4,10 +4,24 @@ title: Purchase Order Report ## Purchase Order Reports +Custom purchase order reports may be generated against any given [Purchase Order](../buy/po.md). For example, purchase order reports could be used to generate a pdf of the order to send to a supplier. + +### Purchase Order Filters + +The report template can be filtered against available [Purchase Order](../buy/po.md) instances. + ### Context Variables -!!! missing "TODO" - This section requires further work +In addition to the default report context variables, the following variables are made available to the purchase order report template for rendering: + +| Variable | Description | +| --- | --- | +| order | The specific Purchase Order object | +| reference | The order reference field (can also be accessed as `{% raw %}{{ order.description }}{% endraw %}`) | +| description | The order description field | +| supplier | The [supplier](../buy/supplier.md) associated with this purchase order | +| lines | A list of available line items for this order | +| extra_lines | A list of available *extra* line items for this order | ### Default Report Template diff --git a/docs/report/report.md b/docs/report/report.md index eee4ac5..38bade0 100644 --- a/docs/report/report.md +++ b/docs/report/report.md @@ -146,6 +146,62 @@ InvenTree supports the following reporting functionality: | [Sales Order Report](./sales_order.md) | Format a sales order report | | [Return Order Report](./return_order.md) | Format a return order report | +### Default Reports + +InvenTree is supplied with a number of default templates "out of the box". These are generally quite simple, but serve as a starting point for building custom reports to suit a specific need. + +!!! tip "Read the Source" + The source code for the default reports is [available on GitHub](https://github.com/inventree/InvenTree/tree/master/InvenTree/report/templates/report). Use this as a guide for generating your own reports! + +## Creating Reports + +Report templates are created (and edited) via the [admin interface](../settings/admin.md), under the *Report* section. Select the certain type of report template you are wanting to create, and press the *Add* button in the top right corner: + +{% with id="report-create", url="report/add_report_template.png", description="Create new report" %} +{% include 'img.html' %} +{% endwith %} + +!!! tip "Staff Access Only" + Only users with staff access can upload or edit report template files. + +!!! info "Editing Reports" + Existing reports can be edited from the admin interface, in the same location as described above. To change the contents of the template, re-upload a template file, to overrie the existing template data. + +### Name and Description + +Each report template requires a name and description, which identify and describe the report template. + +### Enabled Status + +Boolean field which determines if the specific report template is enabled, and available for use. Reports can be disabled to remove them from the list of available templates, but without deleting them from the database. + +### Filename Pattern + +The filename pattern used to generate the output `.pdf` file. Defaults to "report.pdf" + +### Report Filters + +Each type of report provides a *filters* field, which can be used to filter which items a report can be generated against. The target of the *filters* field depends on the type of report - refer to the documentation on the specific report type for more information. + +For example, the [Test Report](./test.md) filter targets the linked [Stock Item](../stock/status.md) object, and can be used to select which stock items are allowed for the given report. Let's say that a certain test report should only be generated for "trackable" stock items. A filter could easily be constructed to accommodate this, by limiting available items to those where the associated [Part](../part/part.md) is *trackable*: + +{% with id="report-filter-valid", url="report/filters_valid.png", description="Report filter selection" %} +{% include 'img.html' %} +{% endwith %} + +If you enter an invalid option for the filter field, an error message will be displayed: + +{% with id="report-filter-invalid", url="report/filters_invalid.png", description="Invalid filter selection" %} +{% include 'img.html' %} +{% endwith %} + +!!! warning "Advanced Users" + Report filtering is an advanced topic, and requires a little bit of knowledge of the underlying data structure! + +### Metadata + +A JSON field made available to any [plugins](../extend/plugins.md) - but not used by internal code. + ## Report Options A number of global reporting options are available for customizing InvenTree reports: @@ -175,10 +231,6 @@ Setting the *Debug Mode* option renders the template as raw HTML instead of PDF, !!! warning "HTML Rendering Limitations" When rendered in debug mode, @page attributes (such as size, etc) will **not** be observed. Additionally, any asset files stored on the InvenTree server will not be rendered. Debug mode is not intended to produce "good looking" documents! -## Uploading Templates - -Custom report templates can be uploaded using the [Admin Interface](../settings/admin.md). Only users with admin access can upload and/or edit report template files. - ## Report Assets User can upload asset files (e.g. images) which can be used when generating reports. For example, you may wish to generate a report with your company logo in the header. Asset files are uploaded via the admin interface. diff --git a/docs/report/sales_order.md b/docs/report/sales_order.md index 0c7aa66..c83c45d 100644 --- a/docs/report/sales_order.md +++ b/docs/report/sales_order.md @@ -4,10 +4,24 @@ title: Sales Order Reports ## Sales Order Reports +Custom sales order reports may be generated against any given [Sales Order](../sell/so.md). For example, a sales order report could be used to generate an invoice to send to a customer. + +### Sales Order Filters + +The report template can be filtered against available [Sales Order](../sell/so.md) instances. + ### Context Variables -!!! missing "TODO" - This section requires further work +In addition to the default report context variables, the following variables are made available to the sales order report template for rendering: + +| Variable | Description | +| --- | --- | +| order | The specific Sales Order object | +| reference | The order reference field (can also be accessed as `{% raw %}{{ order.description }}{% endraw %}`) | +| description | The order description field | +| customer | The [customer](../sell/customer.md) associated with the particular sales order | +| lines | A list of available line items for this order | +| extra_lines | A list of available *extra* line items for this order | ### Default Report Template diff --git a/docs/report/test.md b/docs/report/test.md index a09f871..00fbcf0 100644 --- a/docs/report/test.md +++ b/docs/report/test.md @@ -10,29 +10,35 @@ Custom test reports may be generated against any given stock item. All testing d For example, an "Acceptance Test" report template may be customized to the particular device, with the results for certain tests rendering in a particular part of the page, with any tests which have not passed highlighted. -### Part Filters +### Stock Item Filters -A TestReport template may define a set of filters against which parts are sorted. Any Part objects which match the provided filters can use the given TestReport. +A TestReport template may define a set of filters against which stock items are sorted. Any [StockItem](../stock/stock.md) objects which match the provided filters can use the given TestReport. -This allows each TestReport to easily be assigned to a particular Part, or even multiple parts. +This allows each TestReport to easily be assigned to a particular StockItem, or even multiple items. -In the example below, a test report template is uploaded and assigned to the part with the name *"My Widget"*. Any combination of fields relevant to the Part model can be used here. +In the example below, a test report template is uploaded and available to any stock items linked to a part with the name *"My Widget"*. Any combination of fields relevant to the StockItem model can be used here. -{% with id="test_report_add", url="admin/test_report_add.png", description="Upload test report template" %} +{% with id="test-report-filters", url="report/test_report_filters.png", description="Test report filters" %} {% include 'img.html' %} {% endwith %} + ### Context Variables In addition to the default report context variables, the following context variables are made available to the TestReport template for rendering: | Variable | Description | | --- | --- | -| stock_item | The individual [StockItem](./context_variables.md#stockitem) object for which this test report is being generated | +| stock_item | The individual [Stock Item](./context_variables.md#stockitem) object for which this test report is being generated | +| serial | The serial number of the linked Stock Item | | part | The [Part](./context_variables.md#part) object of which the stock_item is an instance | +| parameters | A dict object representing the [parameters](../part/parameter.md) of the referenced part | +| test_keys | A list of the available 'keys' for the test results recorded against the stock item | +| test_template_list | A list of the available [test templates](../part/test.md#part-test-templates) for the referenced part | +| test_template_map | A map / dict of the available test templates | | results | A dict of test result objects, where the 'key' for each test result is a shortened version of the test name (see below) | | result_list | A list of each test result object | -| installed_items | A flattened list representing all [StockItem](./context_variables.md#stockitem) objects which are *installed inside* the referenced [StockItem](./context_variables.md#stockitem) object | +| installed_items | A flattened list representing all [Stock Item](./context_variables.md#stockitem) objects which are *installed inside* the referenced [Stock Item](./context_variables.md#stockitem) object | #### Results diff --git a/mkdocs.yml b/mkdocs.yml index 74db35d..3a3ab56 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -112,7 +112,7 @@ nav: - Return Orders: sell/return.md - Report: - Templates: report/report.md - - Reports: + - Report Types: - Test Reports: report/test.md - Build Order: report/build.md - Purchase Order: report/purchase_order.md