Represents a defined reason used to explain an operational occurrence.
For example, a line stoppage may be caused by a mechanical failure, a Hold may be caused by a quality issue, or a Complaint may be classified as a packaging defect.
Reasons can be organised hierarchically so that broad categories can contain more specific reasons.
The Reason object
{
"code": "CMP-FOREIGN-BODY",
"name": "Foreign body",
"parent": "CMP-SAFETY"
}
Fields
| Field | Type | Description | Example |
|---|---|---|---|
code |
string | Unique business code used to identify the reason. | "CMP-FOREIGN-BODY" |
name |
string | Human-readable name of the reason. | "Foreign body" |
parent |
string or null | Business code of the parent reason. Omit for a top-level reason. | "CMP-SAFETY" |
Important
code must be unique. Two reasons cannot use the same code.
When parent is provided, the referenced parent reason must already exist.
A reason cannot be assigned a parent that would create a cycle in the hierarchy.
Reason hierarchy
Reasons form a tree with no fixed hierarchy depth.
For example:
Complaint
└── Safety
└── Foreign body
A reason references the level directly above it through parent.
The same hierarchy can be used across stoppages, deviations, complaints, and other operational records.
A reason that has child reasons cannot be deleted until those child references are removed or reassigned.
API resource
| Resource | Base path |
|---|---|
Reason |
/manufacturing/food-beverage/v1/reasons |
API methods
Create a reason
POST /manufacturing/food-beverage/v1/reasons/insert
Creates a new reason.
Request
POST /manufacturing/food-beverage/v1/reasons/insert
Content-Type: application/json
{
"code": "CMP-FOREIGN-BODY",
"name": "Foreign body",
"parent": "CMP-SAFETY"
}
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
code |
string | yes | Unique business code of the reason. |
name |
string | yes | Human-readable name of the reason. |
parent |
string or null | no | Business code of the parent reason. |
Update a reason
PUT /manufacturing/food-beverage/v1/reasons/update
Updates an existing reason identified by its business code.
Request
PUT /manufacturing/food-beverage/v1/reasons/update
Content-Type: application/json
{
"code": "CMP-FOREIGN-BODY",
"name": "Foreign body contamination",
"parent": "CMP-SAFETY"
}
Patch a reason
PATCH /manufacturing/food-beverage/v1/reasons/patch
Partially updates an existing reason.
The reason is identified by properties.code. The current implementation also requires properties.name. The parent field can be supplied when the hierarchy should change.
Request
PATCH /manufacturing/food-beverage/v1/reasons/patch
Content-Type: application/json
{
"properties": {
"code": "CMP-FOREIGN-BODY",
"name": "Foreign body contamination"
}
}
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
properties |
object | yes | Fields included in the partial update. |
properties.code |
string | yes | Business code of the reason to update. |
properties.name |
string | yes | Human-readable name of the reason. |
properties.parent |
string or null | no | New parent reason. Use null to make the reason top-level. |
Retrieve a reason
GET /manufacturing/food-beverage/v1/reasons/select
Returns the reason identified by its business code.
Request
GET /manufacturing/food-beverage/v1/reasons/select?id=CMP-FOREIGN-BODY
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id |
string | yes | Business code of the reason to retrieve. |
Example response
{
"code": "CMP-FOREIGN-BODY",
"name": "Foreign body",
"parent": "CMP-SAFETY"
}
List reasons
GET /manufacturing/food-beverage/v1/reasons/query
Returns reasons matching the supplied filters.
Request
GET /manufacturing/food-beverage/v1/reasons/query?parents=CMP-SAFETY
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
codes |
string or array of strings | no | Limits results to reasons with the specified business codes. |
names |
string or array of strings | no | Limits results to reasons with the specified names. |
parents |
string or array of strings | no | Limits results to reasons with the specified parent reason codes. An empty value can be used to include top-level reasons. |
Example response
[
{
"code": "CMP-FOREIGN-BODY",
"name": "Foreign body",
"parent": "CMP-SAFETY"
}
]
Delete a reason
DELETE /manufacturing/food-beverage/v1/reasons/delete
Deletes the reason identified by its business code.
A reason cannot be deleted while child reasons still reference it.
Request
DELETE /manufacturing/food-beverage/v1/reasons/delete?id=CMP-FOREIGN-BODY
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id |
string | yes | Business code of the reason to delete. |