Reason – Pulse

Represents a reason code used to explain why something happened, for example why a machine stopped, why material was scrapped, or why maintenance was needed. In the Excel templates, reasons are registered on the Reason codes sheet.

Reason codes can be arranged in a hierarchy. For example, Mechanical failure and Electrical failure can both belong to Breakdown.

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

The Reason object

{
  "code": "R-MECH",
  "name": "Mechanical failure",
  "parent": "R-BREAKDOWN"
}

Fields

Field	Type	Description	Example
`code`	string	Unique business code used to identify the reason in external systems and integrations.	`"R-MECH"`
`name`	string	Human-readable name of the reason.	`"Mechanical failure"`
`parent`	string or null	Business code of the reason this reason belongs to. `null` for a top-level reason.	`"R-BREAKDOWN"`

Important

code must be unique. Two reasons cannot use the same code.

Reason hierarchy

The parent must exist before a reason refers to it. Otherwise the request is refused.
A chain of parents that leads back to itself is refused.
A reason cannot be deleted while other reasons belong to it.

API resource

Resource	Base path
`Reason`	`/manufacturing/v1/reasons`

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

API methods

Create a reason

POST /manufacturing/v1/reasons/insert

Creates a new reason and returns its Pulse identifier.

Request

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

{
  "code": "R-MECH",
  "name": "Mechanical failure",
  "parent": "R-BREAKDOWN"
}

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 an existing parent reason.

Update a reason

PUT /manufacturing/v1/reasons/update

Updates an existing reason. The reason must already exist.

An update replaces all fields. If you leave out parent, the reason becomes a top-level reason. To change only some fields, use patch.

Request

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

{
  "code": "R-MECH",
  "name": "Mechanical failure (drive)",
  "parent": "R-BREAKDOWN"
}

Parameters

Parameter	Type	Required	Description
`code`	string	yes	Business code of the reason to update.
`name`	string	yes	Human-readable name of the reason.
`parent`	string or null	no	Business code of an existing parent reason.

Patch a reason

PATCH /manufacturing/v1/reasons/patch

Partially updates an existing reason.

The fields to update are supplied in the properties object. The reason is identified by its business code, which cannot be changed. Fields you leave out keep their current values. To make the reason a top-level reason, send parent as null.

Request

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

{
  "properties": {
    "code": "R-MECH",
    "parent": null
  }
}

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	no	New name of the reason.
`properties.parent`	string or null	no	Business code of an existing parent reason, or `null` for a top-level reason.

Retrieve a reason

GET /manufacturing/v1/reasons/select

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

Request

GET /manufacturing/v1/reasons/select?id=R-MECH

Parameters

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

Example response

{
  "code": "R-MECH",
  "name": "Mechanical failure",
  "parent": "R-BREAKDOWN"
}

List reasons

GET /manufacturing/v1/reasons/query

Returns reasons matching the supplied filters.

Request

GET /manufacturing/v1/reasons/query?parents=R-BREAKDOWN

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. Upper and lower case are not distinguished.
`parents`	string or array of strings	no	Limits results to reasons that belong directly to the specified parents. Include an empty value to also return top-level reasons.

Example response

[
  {
    "code": "R-MECH",
    "name": "Mechanical failure",
    "parent": "R-BREAKDOWN"
  }
]

Delete a reason

DELETE /manufacturing/v1/reasons/delete

Deletes the reason identified by its business code. If no reason has this code, nothing happens. A reason cannot be deleted while other reasons belong to it.

Request

DELETE /manufacturing/v1/reasons/delete?id=R-MECH

Parameters

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