Material

Represents a material used in production, for example a raw material, a component, packaging, a consumable, or a utility such as water or electricity. In the Excel templates, materials are registered on the Materials sheet.

Materials are a shared entity. They work the same way in every manufacturing domain model.

The Material object

{
  "code": "STEEL-S355",
  "name": "Structural steel S355",
  "unit": "kg",
  "group": "MG-RAW",
  "lotTracked": true,
  "classifications": {}
}

Fields

Material groups

A material group is registered as a material of its own, with a code and a name. Other materials refer to it through their group field.

For example, register the group first:

{
  "code": "MG-RAW",
  "name": "Raw materials"
}

Then assign materials to it, as in the object above.

• The group must exist before a material refers to it. Otherwise the request is refused.
• A group can itself belong to a group. A chain of groups that leads back to itself is refused.
• A group cannot be deleted while materials belong to it.

Lot tracking

Set lotTracked to true for materials you receive and use in identifiable lots, such as raw materials with a supplier lot number. Set it to false for materials that are not tracked by lot, such as utilities.

Classifications

Classifications describe a material with values from a fixed list, for example its origin or its material family. They are written in classifications as pairs of classification type and value code:

"classifications": {
  "{classification type}": "{value code}"
}

• Each domain model defines which classification types a material can have. For the classifications of each domain model, see Materials in Food & Beverage and Materials in Metal & Machining.
• The classification type and its values must be registered as Types that apply to materials before you use them. Otherwise the request is refused.
• A classification type that the domain model does not support is refused.

API resource

Resource	Base path
Material	/manufacturing/v1/materials

For the operations shared by all shared entities, see Shared entities API.

API methods

Create a material

POST /manufacturing/v1/materials/insert

Creates a new material and returns its Pulse identifier.

Request

POST /manufacturing/v1/materials/insert
Content-Type: application/json

{
  "code": "STEEL-S355",
  "name": "Structural steel S355",
  "unit": "kg",
  "group": "MG-RAW",
  "lotTracked": true
}

Parameters

Parameter	Type	Required	Description
code	string	yes	Unique business code of the material.
name	string	yes	Human-readable name of the material.
unit	string or null	no	Unit in which quantities of the material are stated.
group	string or null	no	Business code of an existing material group.
lotTracked	boolean	no	Whether the material is tracked by lot. Default: true.
classifications	object	no	Classification values, as pairs of classification type and value code.

Update a material

PUT /manufacturing/v1/materials/update

Updates an existing material. The material must already exist.

An update replaces all fields. If you leave out unit, group, or a classification, it is removed, and lotTracked returns to true. To change only some fields, use patch.

Request

PUT /manufacturing/v1/materials/update
Content-Type: application/json

{
  "code": "STEEL-S355",
  "name": "Structural steel S355, hot rolled",
  "unit": "kg",
  "group": "MG-RAW",
  "lotTracked": true
}

Parameters

The parameters are the same as for creating a material. code identifies the material to update.

Patch a material

PATCH /manufacturing/v1/materials/patch

Partially updates an existing material.

The fields to update are supplied in the properties object. The material is identified by its business code, which cannot be changed. Fields you leave out keep their current values. To remove the unit or the group, send it as null.

If you send classifications, it replaces all classification values of the material.

Request

PATCH /manufacturing/v1/materials/patch
Content-Type: application/json

{
  "properties": {
    "code": "STEEL-S355",
    "lotTracked": false
  }
}

Parameters

Parameter	Type	Required	Description
properties	object	yes	Fields included in the partial update.
properties.code	string	yes	Business code of the material to update.
properties.name	string	no	New name of the material.
properties.unit	string or null	no	New unit, or null to remove it.
properties.group	string or null	no	Business code of an existing material group, or null to remove the group.
properties.lotTracked	boolean	no	Whether the material is tracked by lot.
properties.classifications	object	no	The material's classification values. Replaces all current values.

Retrieve a material

GET /manufacturing/v1/materials/select

Returns the material identified by its business code. If no material has this code, the response is empty.

Request

GET /manufacturing/v1/materials/select?id=STEEL-S355

Parameters

Parameter	Type	Required	Description
id	string	yes	Business code of the material to retrieve.

Example response

{
  "code": "STEEL-S355",
  "name": "Structural steel S355",
  "unit": "kg",
  "group": "MG-RAW",
  "lotTracked": true,
  "classifications": {}
}

List materials

GET /manufacturing/v1/materials/query

Returns materials matching the supplied filters.

Request

GET /manufacturing/v1/materials/query?groups=MG-RAW&lotTracked=true

Query parameters

Parameter	Type	Required	Description
codes	string or array of strings	no	Limits results to materials with the specified business codes.
names	string or array of strings	no	Limits results to materials with the specified names. Upper and lower case are not distinguished.
groups	string or array of strings	no	Limits results to materials that belong directly to the specified groups.
lotTracked	boolean	no	Limits results to materials that are, or are not, tracked by lot.
classifications	string or array of strings	no	Limits results to materials with any of the specified classification value codes.

Example response

[
  {
    "code": "STEEL-S355",
    "name": "Structural steel S355",
    "unit": "kg",
    "group": "MG-RAW",
    "lotTracked": true,
    "classifications": {}
  }
]

Delete a material

DELETE /manufacturing/v1/materials/delete

Deletes the material identified by its business code. If no material has this code, nothing happens. A material group cannot be deleted while materials belong to it.

Request

DELETE /manufacturing/v1/materials/delete?id=STEEL-S355

Parameters

Parameter	Type	Required	Description
id	string	yes	Business code of the material to delete.