Tool

Model

class pytm4srv.models.tool.Tool

Represents one tool and/or insert.

assembly_id: Mapped[int | None]

The ID of the tool assembly that this tool is part of.

calibration_date: Mapped[date | None]

When the tool was last calibrated. Mainly for durable tools.

Serialized as YYYY-MM-DD.

calibration_interval: Mapped[timedelta | None]

How often the tool needs calibration.

Serialized as a number of days.

NULL means never.

calibration_notify: Mapped[int | None]

Where to send calibration reminders.

NULL disables reminders.

created: Mapped[datetime]

When this tool was created.

day_warning_sent: Mapped[bool]

Whether a “days remaining” warning notification has been sent for this tool since the last replacement.

id: MappedColumn object at 0x79d314f5dd80>]]

Unique, numeric ID for this tool/insert in OnTakt.

image: Mapped[bytes | None]

A user-provided image of this tool.

image_type: Mapped[str | None]

The MIME type of the file stored in image.

in_service_date: Mapped[date | None]

When the tool was put into service. Mainly for durable tools.

Serialized as YYYY-MM-DD.

If this is after the out_service_date (or that date is null), the tool is considered to be in service.

inventory_item_id: Mapped[int | None]

ID of the item to order to supply this tool.

is_critical: Mapped[bool]

Whether the machine should be kept from running when this tool is used beyond its expected life.

last_part_id: Mapped[int | None]

The ID of the last part that was created using this tool.

last_replaced

Get the timestamp of the last time this tool was replaced. If this tool has never been replaced, this will be None.

life_history: WriteOnlyMapped[ToolLifeRecord]

The life records created each time a life field is changed. :meta private:

location_history: WriteOnlyMapped[ToolLocationRecord]

The location records created each time this tool is moved. :meta private:

maintenance_status: Mapped[int]

The current rebuild status of this tool. Mainly for durable tools.

The following states are supported:

  1. Not set

  2. Needs rebuild

  3. Not ready for use

  4. Out for rebuild

  5. Received from rebuild

  6. Ready for use

  7. In service

monitoring_dest: Mapped[int | None]

Channel to send replacement notifications to.

NULL disables notifications.

name: Mapped[str]

User-specified name of the tool/insert.

notes: Mapped[str]

User-specified notes about the tool/insert.

offset_number: Mapped[int | None]

The offset number of this tool’s data in the control’s memory.

order_qty: Mapped[int | None]

How many of this tool are ordered at a time.

out_service_date: Mapped[date | None]

When the tool was taken out of service. Mainly for durable tools.

Serialized as YYYY-MM-DD.

If this is after the in_service_date (or that date is null), the tool is considered to be out of service.

pinned: Mapped[bool]

Whether this tool should be pinned to the top of lists, ignoring sorting.

purchase_date: Mapped[date | None]

When the tool was purchased. Mainly for durable tools.

reorder_point: Mapped[int | None]

How many of this tool remaining should trigger an order.

replace_duration: Mapped[timedelta]

How long it is expected to take to replace this tool, in minutes.

replaced_checklist: Mapped[List[str] | None]

Checklist to display to the user after replacing this tool. The user must check all items to continue.

This field can take three forms:

  1. null (default): the global tool_replaced_checklist option will be inherited

  2. Empty array: no checklist will be displayed

  3. Array of strings: each element of the array will be displayed as a checklist item

When replaced_message is also set, it will be displayed above the checklist.

replaced_message: Mapped[str]

Text to display to the user after replacing this tool.

replacement_history: WriteOnlyMapped[ToolReplacement]

The replacement objects created each time the tool is reset. :meta private:

replacement_rules_snoozed_until: Mapped[datetime | None]

If non-null, notifications will not be sent about this tool’s replacement rules until after this date and time.

slots: Mapped[int]

Number of inventory items (usually inserts) this tool uses at one time.

stick_out: Mapped[float | None]

Measured value when tool is in a machine.

stick_out_ref: Mapped[str]

Where the stick-out value is measured from.

tags: Mapped[List[str]]

Array of tags applied to this tool for searching and grouping.

Example: ["Sandvik", "cutting", "drawer 1"]

torque_spec: Mapped[float | None]

Torque to use during tool changes.

torque_spec_units: Mapped[str]

The units the torque_spec field is stored in.

Allowed values: - lb_ft for pound-feet - n_m for Newton-meters

usage_mode: Mapped[int]

How usage should be displayed for this tool.

The supported values are described in the table below:

Value

Usage mode

Usage calculation

0 (default)

Parts

part_count / part_life

1

Run time

runtime / max_runtime

2

Clock time

day_count / day_life

Note

Run time and clock time are still experimental. These two modes are not yet considered when suggesting inventory item order quantities or running tool reports.

used_corners: Mapped[int]

The number of indexed cutting positions that have been used since replacement.

warning_sent: Mapped[bool]

Whether a “parts remaining” warning notification has been sent for this tool since the last replacement.

class pytm4srv.models.tool.process_life.ToolProcessLife
day_count_type: Mapped[str]

Which days to count in day_count.

  • all: every day (default)

  • week: weekdays

  • part: days on which this tool produced at least one part

day_life: Mapped[int]

How many days a tool lasts.

A zero value disables day tracking for the tool.

day_warning: Mapped[int]

A warning will be triggered when the expected number of days remaining (day_life minus day_count) is at or below this value.

max_runtime: Mapped[timedelta]

How much machine runtime (in seconds) this tool is expected to last between replacements.

part_count: Mapped[int]

How many parts this tool has produced.

This is equal to the cumulative number of parts produced by all programs this tool has been associated with.

part_life: Mapped[int]

How many parts a tool can make during its lifetime.

A zero value disables part tracking for the tool.

property parts_remaining: float

Get the number of parts remaining based on part_life and part_count.

Returns:

the number of parts remaining or infinity if part_life is not set

process_id: Mapped[int | None]

The ID of the process this tool’s life is associated with.

runtime: Mapped[timedelta]

The total amount of machine runtime (in seconds) this tool has been used for since its last replacement.

This only counts time when the machine reports this tool as active.

Note

To avoid falsely expiring tools when machines go offline, the value of this field will not be increased during a machine update if the machine’s previous update was more than one minute ago.

tool_id: Mapped[int]

The ID of the tool whose life is being stored.

warn_life: Mapped[int]

A warning will be triggered when the expected number of parts remaining is at or below this value.

warn_runtime: Mapped[timedelta]

A warning will be sent when this tool has this much machine runtime (in seconds) remaining.

Endpoints

GET /api/tools/

Get an object mapping tool ID to tool.

Query Parameters:

  • durable (string) – set to durable to include only durable tools or consumable to exclude them

  • unassigned (int) – set to 1 to only include tools that are not assigned to a process

  • process (int) – set to a process ID to include only tools assigned to that process

  • machine (int) – set to a machine ID to include only tools in use by that machine’s currently loaded process

  • active (int) – set to 1 to include only tools assigned to any active process

  • inventory_item (int) – set to an inventory item ID to include only tools that use that item

  • assembly (int) – set to a ToolAssembly ID to get only tools that are in that assembly

  • favorite (int) – set to 1 to include only tools that the current user has marked as favorites

  • life (int) – set to 1 to calculate the average number of parts between replacements of each tool and return it as an additional average_tool_life field in each tool object. This slows down the request processing significantly, so only use it when necessary.

  • warn_life (int) – set to 1 to include only tools past their warning life threshold

  • usage_mode (int) – set to a usage mode value (numeric) to include only tools with that usage mode. Can be passed multiple times to include multiple usage modes. If not set, all usage modes are included.

Note

The following parameters are mutually exclusive, so only one of them can be specified at a time:

  • unassigned

  • process

  • active

  • inventory_item

  • assembly

  • machine

Status Codes:

  • 400 Bad Request – if multiple mutually-exclusive filters are specified in the same request

  • 424 Failed Dependency – if the provided process, inventory_item, tool_assembly, or machine ID does not exist.

Returns:

a JSON object mapping tool IDs to tool objects

GET /api/tools/(int: tool_id)

Get data about a single tool.

Parameters:

  • tool_id – The tool to query

Returns:

the tool object

Status Codes:
PUT /api/tools/

Create a new tool.

Reqjsonobj:

a (partial) tool object

Returns:

the new tool object

Status Codes:
PATCH /api/tools/(int: tool_id)

Edit an existing tool to set new data.

The request body should be a (partial) tool object.

Note

Certain users may not be able to set all fields. Errors will be silently ignored.

Field

Admin

Planner

Shop

notes

X

X

X

part_count

X

X

X

name

X

X

part_life, warn_life

X

X

location

X

X

reorder_point

X

X

order_qty

X

X

tags

X

X

monitoring_dest

X

X

used_orders

X

X

inventory_item_id

X

X
Request JSON Object:

  • life_modification_notes (string) – if any expected life fields have been modified, text provided here will be saved in the tool life change record.

Parameters:

  • tool_id – The ID to the tool to modify

Status Codes:
Returns:

the modified tool object

DELETE /api/tools/(int: tool_id)

Delete an existing tool.

Parameters:

  • tool_id – The ID of the tool to delete

Status Codes:
GET /api/tools/(int: tool_id)/replacements

Get the replacement history for a tool.

Query Parameters:

  • limit (int) – maximum number of items to return (defaults to all). More recent replacements are returned first.

  • offset (int) – skip past this many results

Parameters:

  • tool_id – The ID of the tool to query.

Returns:

an object mapping replacement ID to replacement object

Status Codes:
GET /api/tools/(int: tool_id)/lifeHistory

Get the life history for a tool.

Query Parameters:

  • start (float) – get only changes made to this tool’s life on or after the given UNIX timestamp

  • end (float) – get only changes made to this tool’s life on or before the given UNIX timestamp

Parameters:

  • tool_id – ID of the tool to get the life history for

Status Codes:
Returns:

an object mapping ToolLifeRecord ID to ToolLifeRecord

GET /api/tools/(int: tool_id)/replace

Get the information needed to prompt for a tool replacement.

Parameters:

  • tool_id – the ID of the tool that will be replaced

Status Codes:
Response JSON Object:

  • default_inventory_point_id (int) – The ID of the default inventory point to take an item from, or null.

  • last_replacement – the Tool’s most recent ToolReplacement object or null if it has never been replaced

POST /api/tools/(int: tool_id)/replace

Mark a tool as replaced and add an entry to its history.

An image can be uploaded to the newly created tool replacement record using POST /api/tools/replacements/<id>/image.

Query Parameters:

  • forceSub (int) – set to 1 to reassign substitute tools that are already in another assembly instead of returning an error

Parameters:

  • tool_id – the ID of the tool to replace

Request JSON Object:

  • reason (int) – why the tool is being replaced. See the reason field of the ToolReplacement model for allowed values.

  • condition (int) – the state of the old tool that is being replaced. See the condition field of the ToolReplacement model for details.

  • notes (string) – user-supplied notes to save with this tool replacement.

  • indexed (bool) – whether the tool was indexed (inventory will not be subtracted)

  • substitute (int) – when replacing tools, this can be set to the ID of another tool to move into this one’s place. If this field is non-null, the rebuilt tool will be removed from its assembly and the tool whose ID was specified here will be added in its place. Note that the replacement object will still be recorded for the tool that has tool_id.

  • maintenance_status (int) – set the maintenance status of the tool

  • inv_pt (int) – ID of the inventory point the replacement came from

  • timestamp (float) – a UNIX timestamp to override the replacement timestamp (which defaults to the current time if not specified). This timestamp must be later than that of the previous replacement of this tool (if one exists) but not later than the current time. The replacement’s part and time counters will only account for production up until this timestamp, and any production after this timestamp will be left on the tool’s active counters.

Response JSON Object:

  • tool – the tool object that was replaced with reset counters

  • replacement – the tool replacement history object that was created

  • substitute – if substitute was set in the request object, this field in the response will contain the tool that is taking the rebuilt tool’s place, and is now in its assembly.

Response JSON Array of Objects:

  • list (string) – post-replacement checklist

Status Codes:

  • 400 Bad Request – if the tool was not indexed and the inventory point is missing or does not have at least one of this tool, or if it runs out of corners to index

  • 403 Forbidden – if the current user is not allowed to replace a tool with the data provided

  • 404 Not Found – if the tool doesn’t exist

  • 409 Conflict – if the substitute tool is in an assembly

  • 424 Failed Dependency – if substitute is set to an invalid tool ID

  • 425 – if the tool’s usage is less than the value set in the tool_replacement_min_usage option

POST /api/tools/bulkAdjustPartCount

Adjust the part count of multiple tools.

Request JSON Object:

  • count (int) – positive adds to the part count, negative decreases it

Request JSON Array of Objects:

  • tools (int) – list of tool IDs to modify

Returns:

a JSON object of modified tools

POST /api/tools/bulkChangeTags

Adds and/or removes tags across multiple tools.

Tags will not be duplicated on tools that already have one or more of the new tags. If a tag is present in both add and remove, it will be removed.

Request JSON Array of Objects:

  • tools (int) – list of tool IDs to modify

  • add (string) – list of tags to add

  • remove (string) – list of tags to remove

Returns:

a JSON object of modified tools

POST /api/tools/updatePartLife

Update the part life of all selected tools to their calculated average life.

Request JSON Array of Objects:

  • int – list of tool IDs to update

Returns:

a JSON object containing all updated tools, keyed by tool ID

GET /api/tools/(int: tool_id)/dayCount/(force_type)

Get the day count of a tool for any type of day counting, not just the one it has set.

Parameters:

  • tool_id – the ID of the tool to query

  • force_type – the type of day counting to use

Returns:

the number of days the tool has been in use

Status Codes:
GET /api/tools/(int: tool_id)/processLife

Get a single tool’s usage and life for each process that uses it.

Parameters:

  • tool_id – the ID of the tool to get information about

Returns:

an object mapping process ID (or "" for the tool’s intrinsic life without a process) to ToolProcessLife object.

Status Codes:
PATCH /api/tools/(int: tool_id)/processLife/(int: process_id)

Edit a single tool’s usage and life for a single process. :param tool_id: the ID of the tool to edit life for :param process_id: the ID of the process to edit this tool’s life for :return: the created or modified ToolProcessLife object :status 404: if the tool and/or process IDs are invalid

GET /api/tools/import

Get a copy of the tool import template that can be filled in to bulk import tools.

Returns:

an XLTX file

POST /api/tools/import

Upload a filled-in copy of the tool import template.

The request body should be the binary file.

Query Parameters:

  • process (int) – if provided, tool assemblies created during this import will be assigned to the process with this ID.

Status Codes:
Resjsonobj:

maps tool ID to new tool object

GET /api/tools/(int: obj_id)/image

Get the current image file of the Tool.

Parameters:

  • obj_id – ID of the Tool to get the image for

Status Codes:
Returns:

the image file, with the Content-Type header set to its MIME type

POST /api/tools/(int: obj_id)/image

Upload a new image file for the Tool.

The request body should be an image file, and the Content-Type header should contain its MIME type.

Parameters:

  • obj_id – ID of the Tool to set the image for

Status Codes:
Returns:

the modified Tool

DELETE /api/tools/(int: obj_id)/image

Remove the image from the Tool.

Parameters:

  • obj_id – ID of the Tool to clear the image from

Status Codes:
Returns:

the modified Tool