Planned use

Defines the resources that a Run, Batch, or Clean is expected to use.

For example, a Run may be planned to use 300 kg of an ingredient, 24,000 packaging units, or a defined amount of Labor.

Each Planned-use record identifies one specific item, its planned quantity, and optionally its planned cost per unit.

The Planned use object

{
  "usedBy": "L01-260810-002",
  "category": "ingredient",
  "item": "MAT0042",
  "quantity": 300,
  "unit": "kg",
  "unitValue": 2.44
}

Fields

Categories

Supported categories are:

Category	Item resource	Purpose
ingredient	Material	Ingredients used during production.
packaging	Material	Packaging materials.
chemical	Material	Cleaning or process chemicals.
water	Cost line	Water use.
energy	Cost line	Energy use.
effluent	Cost line	Effluent or waste-water related use.
labour	Crew	Labor resources.
equipment	Machine	Equipment resources.
expense	Cost line	Other defined production expenses.

Each category is associated with a corresponding cost Measurement in Pulse:

Category	Cost measurement
ingredient	ingredient-cost
packaging	packaging-cost
chemical	chemical-cost
water	water-cost
energy	energy-cost
effluent	effluent-cost
labour	labour-cost
equipment	equipment-cost
expense	expense-cost

Item-level planning

Planned use is recorded for a specific item rather than only for a category.

For example:

{
  "usedBy": "L01-260810-002",
  "category": "ingredient",
  "item": "MAT0042",
  "quantity": 300,
  "unit": "kg"
}

is valid because the planned quantity belongs to a specific Material.

A category-only plan such as:

{
  "usedBy": "L01-260810-002",
  "category": "ingredient",
  "quantity": 12200,
  "unit": "kg"
}

is not supported.

The category also determines what kind of resource item must reference. For example, an ingredient item must be a Material, while an equipment item must be a Machine.

Planned and actual use

Planned use describes what a production activity was expected to consume.

Actual use is submitted separately through Consumption.

For example:

Planned use
    ↓
MAT0042 — 300 kg

Actual consumption
    ↓
MAT0042 — 318 kg

Keeping the planned and actual records separate allows Pulse to compare expected and actual resource use for the same item.

Reference protection

A Material, Cost line, Crew, or Machine referenced by an existing Planned-use record cannot be deleted until the reference is removed.

API resource

Resource	Base path
Planned use	/manufacturing/food-beverage/v1/planned-use

API methods

Create planned use

POST /manufacturing/food-beverage/v1/planned-use/insert

Creates a Planned-use record for a Run, Batch, or Clean.

Request

POST /manufacturing/food-beverage/v1/planned-use/insert
Content-Type: application/json

{
  "usedBy": "L01-260810-002",
  "category": "ingredient",
  "item": "MAT0042",
  "quantity": 300,
  "unit": "kg",
  "unitValue": 2.44
}

Parameters

Parameter	Type	Required	Description
usedBy	string	yes	Business code of the Run, Batch, or Clean.
category	string	yes	Resource category.
item	string	yes	Business code of the resource supported by the selected category.
quantity	number	yes	Planned quantity.
unit	string	yes	Unit of the planned quantity.
unitValue	number or null	no	Planned cost per unit.

Update planned use

PUT /manufacturing/food-beverage/v1/planned-use/update

Updates an existing Planned-use record.

The record is identified by the combination of usedBy, category, and item.

Request

PUT /manufacturing/food-beverage/v1/planned-use/update
Content-Type: application/json

{
  "usedBy": "L01-260810-002",
  "category": "ingredient",
  "item": "MAT0042",
  "quantity": 320,
  "unit": "kg",
  "unitValue": 2.44
}

Patch planned use

PATCH /manufacturing/food-beverage/v1/planned-use/patch

Partially updates an existing Planned-use record.

The record is identified by properties.usedBy, properties.category, and properties.item. All three are required.

quantity and unit are preserved when omitted. unitValue can be explicitly cleared by including it with a null value.

Request

PATCH /manufacturing/food-beverage/v1/planned-use/patch
Content-Type: application/json

{
  "properties": {
    "usedBy": "L01-260810-002",
    "category": "ingredient",
    "item": "MAT0042",
    "quantity": 320
  }
}

Parameters

Parameter	Type	Required	Description
properties	object	yes	Fields included in the partial update.
properties.usedBy	string	yes	Business code of the Run, Batch, or Clean.
properties.category	string	yes	Resource category.
properties.item	string	yes	Business code of the planned item.
properties.quantity	number	no	New planned quantity.
properties.unit	string	no	New unit of the planned quantity.
properties.unitValue	number or null	no	New planned cost per unit, or null to clear it.

Retrieve planned use

GET /manufacturing/food-beverage/v1/planned-use/select

Returns the Planned-use record identified by its subject, category, and item.

Request

GET /manufacturing/food-beverage/v1/planned-use/select?usedBy=L01-260810-002&category=ingredient&item=MAT0042

Query parameters

Parameter	Type	Required	Description
usedBy	string	yes	Business code of the Run, Batch, or Clean.
category	string	yes	Resource category.
item	string	yes	Business code of the planned item.

List planned use

GET /manufacturing/food-beverage/v1/planned-use/query

Returns Planned-use records matching the supplied filters.

Request

GET /manufacturing/food-beverage/v1/planned-use/query?usedBy=L01-260810-002&categories=ingredient

Query parameters

Parameter	Type	Required	Description
usedBy	string or array of strings	no	Limits results to the specified Runs, Batches, or Cleans.
categories	string or array of strings	no	Limits results to the specified resource categories.
items	string or array of strings	no	Limits results to the specified planned-item business codes.

Multiple values can be supplied by repeating the query parameter:

GET /manufacturing/food-beverage/v1/planned-use/query?categories=ingredient&categories=packaging

Delete planned use

DELETE /manufacturing/food-beverage/v1/planned-use/delete

Deletes the Planned-use record identified by its subject, category, and item.

Request

DELETE /manufacturing/food-beverage/v1/planned-use/delete?usedBy=L01-260810-002&category=ingredient&item=MAT0042

Query parameters

Parameter	Type	Required	Description
usedBy	string	yes	Business code of the Run, Batch, or Clean.
category	string	yes	Resource category.
item	string	yes	Business code of the planned item.