Maintenance

Items

Definition of a type of regular maintenance created by administrators or planners.

Models

class pytm4srv.models.MaintenanceMeasurementItem

A recurring numeric measurement that can be charted over time.

completion_duration: Mapped[timedelta]: How long it is expected to take to complete this item, in minutes.

cycle_timer: Mapped[timedelta]: The total accumulated cycle time (in minutes) for use when the schedule mode is 1.

difficulty: Mapped[int]

How difficult this maintenance item is to complete. Useful for delegating to operators of varying training levels.

Value	Difficulty
`1`	Easy
`2`	Medium (default)
`3`	Hard
`4`	Expert (management supervision required)

equipment_id: Mapped[int | None]

The ID of the equipment this maintenance item is for.

Set to NULL for items that apply to a machine or the shop as a whole instead of a particular piece of equipment.

Only one of machine_id or equipment_id may be set for a given issue.

frequency: Mapped[str]

How often to repeat this schedule.

Valid options are:

Y (yearly)
M (monthly)
W (weekly)
D (daily)
H (hourly)

id: Mapped[int]: Unique ID across all maintenance items.

indices: Mapped[List[int]]

When to run within each occurrence of frequency.

For example: frequency=M and indices=[1, 14] will run the 1st and 14th of every month, but frequency=M and indices=[-2] will run on the second to last day of every month.

Ignored if frequency is set to H.

initial_entry: Mapped[datetime | None]

For newly-created maintenance items, this field can be used to set the previous entry date without creating an actual entry.

Once an entry exists for this item, the value of field will be ignored.

instructions: Mapped[str]: Instructions to users for completing this maintenance item.

interval: Mapped[int]

One out of how many frequency occurrences to run.

For example: frequency=D and interval=1 will run every day, but frequency=W and interval=3 will run every 3 weeks.

is_critical: Mapped[bool]: Whether the machine should be kept from running until this maintenance item is completed.

item_type: Mapped[str]

The type of this item. This corresponds to a model type and determines which fields are available.

See the item API endpoint documentation for the possible values.

machine_id: Mapped[int | None]

The ID of the machine this maintenance item belongs to.

Set to NULL for items that apply to the shop as a whole instead of a particular machine.

Only one of machine_id or equipment_id may be set for a given issue.

months: Mapped[int]

Months in which to run this schedule.

This is a bitfield (of length 16), so multiple months can be selected by combining their values with bitwise OR.

Value	Binary	Month
`0`	`0000 0000 0000 0000`	(None)
`1`	`0000 0000 0000 0001`	January
`2`	`0000 0000 0000 0010`	February
`4`	`0000 0000 0000 0100`	March
`8`	`0000 0000 0000 1000`	April
`16`	`0000 0000 0001 0000`	May
`32`	`0000 0000 0010 0000`	June
`64`	`0000 0000 0100 0000`	July
`128`	`0000 0000 1000 0000`	August
`256`	`0000 0001 0000 0000`	September
`512`	`0000 0010 0000 0000`	October
`1024`	`0000 0100 0000 0000`	November
`2048`	`0000 1000 0000 0000`	December

For example, to run only at the start of each quarter (January, April, July, and October), the value of this field would be 585 (1 + 8 + 64 + 512, or 0000 0010 0100 1001), or to run regardless of the current month, this field would be 4095 (0000 1111 1111 1111).

Setting this value to zero will deselect all months and prevent this schedule from ever running.

name: Mapped[str]: User-specified name for this rule.

needed_when_archived: Mapped[bool]

Whether this maintenance item needs to be performed for archived machines. Defaults to false.

If this maintenance item is not associated with a machine, this field does nothing.

needed_when_not_archived: Mapped[bool]

Whether this maintenance item needs to be performed for non-archived machines. Defaults to true.

If this maintenance item is not associated with a machine, this field does nothing.

process_id: Mapped[int | None]

If non-null, this maintenance item will only come due when this process is active.

Generally this process will be on the machine associated with this maintenance item, but this is not a requirement so shop-wide and equipment-linked maintenance items can use this as well.

remind_channel_id: Mapped[int | None]

The ID of the notification channel to which due reminders (and, optionally, warning messages) will be sent.

null disables sending notifications.

schedule_mode: Mapped[int]

How this maintenance item should be scheduled. This field can take the following values:

Value

Mode

Description

0 (default)

Clock time

The item will be due every timer_interval.

1

Run time

The cycle_timer for this item will be incremented by the active process’s cycle time each time a part is finished on the associated machine.

If the item is not associated with a machine, it will use clock time mode.

The item will be due every timer_interval of process production time.

2

Calendar

The item will be scheduled using the frequency, interval, indices, months, weekdays, and time_of_day fields.

threshold_lower: Mapped[float | None]: A warning will be sent if an entry is below this value.

threshold_notify_id: Mapped[int | None]

The ID of the notification channel to which threshold warnings will be sent.

NULL disables sending notifications, but in-app alerts will still be created.

threshold_upper: Mapped[float | None]: A warning will be sent if an entry is above this value.

time_of_day: Mapped[time]: What time of day to schedule for.

timer_interval: Mapped[timedelta]

If non-zero and the schedule mode is 0 or 1, the item will be due when this much time has passed since the last completion of this task.

Measured in hours.

trigger_alarm_id: Mapped[int | None]

The ID of the alarm that caused this maintenance item to become due at the alarm’s timestamp.

Once a new entry is created, OnTakt will reset this field to null.

trigger_alarms: Mapped[StringArray]

A list of NC alarm messages that will cause this maintenance item to become due immediately when present on the associated machine.

If this maintenance item is not associated with a machine (or is associated with equipment that is in turn not associated with a machine), this field does nothing.

This is processed independently of custom_alarms, so these should be the strings as reported by the control.

unit: Mapped[str]: The unit used for measurements.

warning_interval: Mapped[timedelta]

If non-zero, a warning will be sent this far in advance of the item becoming due.

Measured in hours.

weekdays: Mapped[int]

Days of the week on which to run this schedule.

This is a bitfield (of length 16), so multiple days can be selected by combining their values with bitwise OR.

Value	Binary	Day
`0`	`0000 0000 0000 0000`	(None)
`1`	`0000 0000 0000 0001`	Monday
`2`	`0000 0000 0000 0010`	Tuesday
`4`	`0000 0000 0000 0100`	Wednesday
`8`	`0000 0000 0000 1000`	Thursday
`16`	`0000 0000 0001 0000`	Friday
`32`	`0000 0000 0010 0000`	Saturday
`64`	`0000 0000 0100 0000`	Sunday

For example, to run Monday through Thursday, the value of this field would be 15 (0000 1111), and to run regardless of the current day of the week, this field would be 127 (0111 1111).

Setting this value to zero will deselect all days and prevent this schedule from ever running.

class pytm4srv.models.MaintenanceTaskItem

A recurring task that must be completed on an interval.

completion_duration: Mapped[timedelta]: How long it is expected to take to complete this item, in minutes.

cycle_timer: Mapped[timedelta]: The total accumulated cycle time (in minutes) for use when the schedule mode is 1.

difficulty: Mapped[int]

How difficult this maintenance item is to complete. Useful for delegating to operators of varying training levels.

Value	Difficulty
`1`	Easy
`2`	Medium (default)
`3`	Hard
`4`	Expert (management supervision required)

equipment_id: Mapped[int | None]

The ID of the equipment this maintenance item is for.

Set to NULL for items that apply to a machine or the shop as a whole instead of a particular piece of equipment.

Only one of machine_id or equipment_id may be set for a given issue.

frequency: Mapped[str]

How often to repeat this schedule.

Valid options are:

Y (yearly)
M (monthly)
W (weekly)
D (daily)
H (hourly)

id: Mapped[IntPK]: Unique ID across all maintenance items.

indices: Mapped[List[int]]

When to run within each occurrence of frequency.

For example: frequency=M and indices=[1, 14] will run the 1st and 14th of every month, but frequency=M and indices=[-2] will run on the second to last day of every month.

Ignored if frequency is set to H.

initial_entry: Mapped[datetime | None]

For newly-created maintenance items, this field can be used to set the previous entry date without creating an actual entry.

Once an entry exists for this item, the value of field will be ignored.

instructions: Mapped[str]: Instructions to users for completing this maintenance item.

interval: Mapped[int]

One out of how many frequency occurrences to run.

For example: frequency=D and interval=1 will run every day, but frequency=W and interval=3 will run every 3 weeks.

is_critical: Mapped[bool]: Whether the machine should be kept from running until this maintenance item is completed.

item_type: Mapped[str]

The type of this item. This corresponds to a model type and determines which fields are available.

See the item API endpoint documentation for the possible values.

machine_id: Mapped[int | None]

The ID of the machine this maintenance item belongs to.

Set to NULL for items that apply to the shop as a whole instead of a particular machine.

Only one of machine_id or equipment_id may be set for a given issue.

months: Mapped[int]

Months in which to run this schedule.

This is a bitfield (of length 16), so multiple months can be selected by combining their values with bitwise OR.

Value	Binary	Month
`0`	`0000 0000 0000 0000`	(None)
`1`	`0000 0000 0000 0001`	January
`2`	`0000 0000 0000 0010`	February
`4`	`0000 0000 0000 0100`	March
`8`	`0000 0000 0000 1000`	April
`16`	`0000 0000 0001 0000`	May
`32`	`0000 0000 0010 0000`	June
`64`	`0000 0000 0100 0000`	July
`128`	`0000 0000 1000 0000`	August
`256`	`0000 0001 0000 0000`	September
`512`	`0000 0010 0000 0000`	October
`1024`	`0000 0100 0000 0000`	November
`2048`	`0000 1000 0000 0000`	December

For example, to run only at the start of each quarter (January, April, July, and October), the value of this field would be 585 (1 + 8 + 64 + 512, or 0000 0010 0100 1001), or to run regardless of the current month, this field would be 4095 (0000 1111 1111 1111).

Setting this value to zero will deselect all months and prevent this schedule from ever running.

name: Mapped[str]: User-specified name for this rule.

needed_when_archived: Mapped[bool]

Whether this maintenance item needs to be performed for archived machines. Defaults to false.

If this maintenance item is not associated with a machine, this field does nothing.

needed_when_not_archived: Mapped[bool]

Whether this maintenance item needs to be performed for non-archived machines. Defaults to true.

If this maintenance item is not associated with a machine, this field does nothing.

process_id: Mapped[int | None]

If non-null, this maintenance item will only come due when this process is active.

Generally this process will be on the machine associated with this maintenance item, but this is not a requirement so shop-wide and equipment-linked maintenance items can use this as well.

remind_channel_id: Mapped[int | None]

The ID of the notification channel to which due reminders (and, optionally, warning messages) will be sent.

null disables sending notifications.

schedule_mode: Mapped[int]

How this maintenance item should be scheduled. This field can take the following values:

Value

Mode

Description

0 (default)

Clock time

The item will be due every timer_interval.

1

Run time

The cycle_timer for this item will be incremented by the active process’s cycle time each time a part is finished on the associated machine.

If the item is not associated with a machine, it will use clock time mode.

The item will be due every timer_interval of process production time.

2

Calendar

The item will be scheduled using the frequency, interval, indices, months, weekdays, and time_of_day fields.

time_of_day: Mapped[time]: What time of day to schedule for.

timer_interval: Mapped[timedelta]

If non-zero and the schedule mode is 0 or 1, the item will be due when this much time has passed since the last completion of this task.

Measured in hours.

trigger_alarm_id: Mapped[int | None]

The ID of the alarm that caused this maintenance item to become due at the alarm’s timestamp.

Once a new entry is created, OnTakt will reset this field to null.

trigger_alarms: Mapped[StringArray]

A list of NC alarm messages that will cause this maintenance item to become due immediately when present on the associated machine.

If this maintenance item is not associated with a machine (or is associated with equipment that is in turn not associated with a machine), this field does nothing.

This is processed independently of custom_alarms, so these should be the strings as reported by the control.

warning_interval: Mapped[timedelta]

If non-zero, a warning will be sent this far in advance of the item becoming due.

Measured in hours.

weekdays: Mapped[int]

Days of the week on which to run this schedule.

This is a bitfield (of length 16), so multiple days can be selected by combining their values with bitwise OR.

Value	Binary	Day
`0`	`0000 0000 0000 0000`	(None)
`1`	`0000 0000 0000 0001`	Monday
`2`	`0000 0000 0000 0010`	Tuesday
`4`	`0000 0000 0000 0100`	Wednesday
`8`	`0000 0000 0000 1000`	Thursday
`16`	`0000 0000 0001 0000`	Friday
`32`	`0000 0000 0010 0000`	Saturday
`64`	`0000 0000 0100 0000`	Sunday

For example, to run Monday through Thursday, the value of this field would be 15 (0000 1111), and to run regardless of the current day of the week, this field would be 127 (0111 1111).

Setting this value to zero will deselect all days and prevent this schedule from ever running.

Endpoints

GET /api/maintenance/items/

List all existing maintenance items.

Query Parameters:

item_type (string) – get only items of a certain type
machine_id (int) – limit results to issues with this machine. Use 0 to get issues with no machine assigned. Can be provided multiple times to include issues from multiple machines.
equipment_id (int) – limit results to issues with this equipment. Use 0 to get issues with no equipment assigned. Can be provided multiple times to include issues from multiple pieces of equipment.

Returns:

a map of MaintenanceItem ID to MaintenanceItem object

GET /api/maintenance/items/(int: item_id)

Get details about a single maintenance item.

Parameters:

item_id – the ID of the item to get details for

Status Codes:

404 Not Found – if the item ID is invalid

Returns:

a MaintenanceItem object

PUT /api/maintenance/items/

Create a new maintenance item.

Reqjson:

a MaintenanceItem object with at least the following fields: - item_type: one of measurement, task - name: name for the item

Status Codes:

400 Bad Request – if a required field is missing or invalid
201 Created – on success

Returns:

the newly created MaintenanceItem object

PATCH /api/maintenance/items/(int: item_id)

Edit an existing maintenance item.

Reqjson:

a (partial) MaintenanceItem object. It is not possible to change an item’s type, so the item_type field will be ignored.

Status Codes:

400 Bad Request – if the item properties are invalid
404 Not Found – if the item ID is not valid

Returns:

the modified MaintenanceItem object

DELETE /api/maintenance/items/(int: item_id)

Delete an existing maintenance item.

Status Codes:

404 Not Found – if the item ID is not valid
204 No Content – on success

GET /api/maintenance/items/(int: item_id)/entries

Get a maintenance item’s entries.

Use limit and offset to get only recent entries (results are queried newest to oldest, but the returned object is unordered).

Parameters:

item_id – the ID of the maintenance item to get entries for

Query Parameters:

limit (int) – limit the number of entries returned
offset (int) – skip this many entries

Status Codes:

404 Not Found – if the item ID is invalid

Returns:

a map of MaintenanceEntry ID to MaintenanceEntry object

GET /api/maintenance/items/schedule

Get recurrence timestamps of all maintenance items in a selected date range.

Query Parameters:

start (int) – start of time range (UNIX timestamp)
end (int) – end of time range (UNIX timestamp)

Status Codes:

400 Bad Request – if start and/or end are missing

Returns:

an object mapping maintenance item ID to a list of due dates (UNIX timestamps)

POST /api/maintenance/items/previewSchedule

List the next few times when the provided schedule would run. The request body should include at least the scheduling fields of a maintenance item, but the id and initial_entry fields are also used if provided:

If id is set, the schedule will start from the timestamp of the last maintenance entry with that item ID, falling back to the initial_entry field otherwise. If neither field is set, the schedule will start from the current date in the local time zone.

Query Parameters:

count (int) – how many future times to get (defaults to 1)

Reqjson:

a partial MaintenanceItem object

Returns:

an array of count UNIX timestamps

POST /api/maintenance/items/averageCompletionDurations

Calculates the average of the duration values for successful completions of a maintenance item.

Example request body

 [42, 43, 44, 45]

Example response body for the above example request, where maintenance item 44 has never been completed successfully and 45 doesn’t exist.

 {"42": 18.4, "43": 26.1, "44": null}

Reqjsonarr:

IDs of the maintenance item to analyze. Invalid item IDs will be ignored.

Returns:

an object mapping each maintenance item ID to a floating point number of minutes, which will be null for maintenance items that have never been completed successfully.

Status Codes:

400 Bad Request – if the JSON request body is invalid.

GET /api/maintenance/items/import

Get a copy of the maintenance item import template that can be filled in to bulk import maintenance items.

Returns:: an XLTX file

POST /api/maintenance/items/import

Upload a filled-in copy of the maintenance item import template.

The request body should be the binary file.

Query Parameters:

machine (int) – if provided, maintenance items created during this import will be assigned to the machine with this ID.

Status Codes:

201 Created – on success
404 Not Found – if an invalid machine ID is provided
422 Unprocessable Entity – if the workbook is invalid for any reason

Resjsonobj:

maps maintenance item ID to new maintenance item object

Entries

Completion of a maintenance item by a shop user.

Models

class pytm4srv.models.MaintenanceMeasurementEntry

A single measured value for a MaintenanceMeasurementItem.

duration: Mapped[timedelta | None]: How long it took to complete this entry (in minutes).

entry_type: Mapped[str]

The type of this entry. This corresponds to a model type and determines which fields are available.

See the entry API endpoint documentation for the possible values.

id: Mapped[IntPK]: Unique ID across all maintenance entries.

item_id: Mapped[int]: The ID of the maintenance item this entry is for.

notes: Mapped[str]: User-specified notes about this entry.

timestamp: Mapped[datetime]: When this entry was created.

unit: Mapped[str | None]

The unit the value was measured in.

Can be NULL, in which case the maintenance measurement’s unit may be assumed, but that could have changed after this measurement was taken. Therefore, it is best for the user to always enter this with the measurement, though the client can suggest the measurement item’s default unit and require the user to change it.

user_id: Mapped[int]: The ID of the user who entered this information.

value: Mapped[float | None]

The measured value.

Can be NULL, but the notes should explain why.

class pytm4srv.models.MaintenanceTaskEntry

A single completion of a MaintenanceTaskEntry.

duration: Mapped[timedelta | None]: How long it took to complete this entry (in minutes).

entry_type: Mapped[str]

The type of this entry. This corresponds to a model type and determines which fields are available.

See the entry API endpoint documentation for the possible values.

id: Mapped[IntPK]: Unique ID across all maintenance entries.

item_id: Mapped[int]: The ID of the maintenance item this entry is for.

notes: Mapped[str]: User-specified notes about this entry.

success: Mapped[bool]

Whether the task was completed successfully.

If FALSE, the notes should explain why.

timestamp: Mapped[datetime]: When this entry was created.

user_id: Mapped[int]: The ID of the user who entered this information.

Endpoints

PUT /api/maintenance/entries/

Create a new maintenance entry.

Reqjson:

a MaintenanceEntry object

Request JSON Object:

entry_type (string) – one of measurement, task (required)
item_id (int) – ID of the item this entry is for (required)

Status Codes:

400 Bad Request – if a required field is missing or invalid
201 Created – on success

Returns:

the newly created MaintenanceEntry object

PATCH /api/maintenance/entries/(int: entry_id)

Edit an existing maintenance entry.

Reqjson:

a (partial) MaintenanceEntry object. It is not possible to change an entry’s type, so the entry_type field will be ignored.

Status Codes:

404 Not Found – if the entry ID is not valid

Returns:

the modified MaintenanceEntry object

DELETE /api/maintenance/entries/(int: entry_id)

Delete an existing maintenance entry.

Status Codes:

404 Not Found – if the entry ID is not valid
204 No Content – on success

Issues

Independent of preconfigured maintenance items.