Alerts

Model

class pytm4srv.models.PersistentAlert

Represents a system alert.

actions: Mapped[Dict[str, str]]

Alert-specific buttons to display.

The map keys are translated strings to label the buttons. The value of each key is an action string, which will be in on of the following forms:

  1. Server action (indicated by two preceding underscores like __server_action)

  2. Client action (indicated by one preceding underscore like _client_action)

  3. URL to open (with no preceding underscores)

When the user clicks an alert action button, use an algorithm like the following to handle it:

if action.startswith("__"):
    http.post(f"/api/alerts/{alert_id}/action/{action}")
else if action.startswith("_"):
    # Handle action in client using the table below
else:
    browser.open_url(action)

The client should be able to handle the following actions:

Action

Description

_edit_downtime

Open the downtime block editor for the downtime block ID stored in the alert’s downtime_id data property.

_edit_machine_state_defs

Open the machine state definition editor interface. Optionally, highlight the state definitions whose IDs are present in the alert’s state_def_ids data property.

_edit_process

Open the process editor for the process ID stored in the alert’s process_id data property.

_edit_tool

Open the tool editor for the tool ID stored in the alert’s tool_id data property.

_edit_tool_replacement_ notify_rule

Open the tool replacement notification rule editor for the rule ID stored in the alert’s rule_id data property.

_create_maintenance_entry

Ask the user to enter a maintenance record for the maintenance item ID stored in the alert’s item_id data property.

_replace_tool

Open the tool replacement flow for the tool ID stored in the alert’s tool_id data property.

_submit_shift_notes

Open the shift notes submission form for the machine ID stored in the alert’s machine_id data property and the shift ID stored in the alert’s shift_id data property for the current day.

_process_changeover

Guide the user through choosing which tools to keep in the newly loaded process. The previous process’s ID is stored in the alert’s from_process_id data property, and the newly loaded process’s ID is stored in the alert’s to_process_id data property.
data: Mapped[Dict[str, Any]]

Alert-specific metadata to be read by client or server actions.

details: Mapped[str]

Longer HTML detail text about the alert.

id: Mapped[int]

Unique, numeric ID for this alert.

key: Mapped[str]

The type of alert and some identifying data about it.

Used to prevent duplicate alerts.

last_seen: Mapped[datetime]

The date and time the alert was last fired.

machine_id: Mapped[int | None]

The ID of the machine that produced this alert, if any.

message: Mapped[str]

Short title of the alert.

severity: Mapped[str]

The class of alert: INFO (default), REPORT, WARNING, or PROBLEM

times_seen: Mapped[int]

The number of times this alert has been fired without being dismissed.

timestamp: Mapped[datetime]

The date and time the alert was created.

ttl: Mapped[timedelta | None]

How long (in seconds) after the timestamp the alert will expire.

NULL means it never expires.

Endpoints

GET /api/alerts/

Get all current alerts.

Example response:

{
  "11771": {
    "actions": {},
    "data": {},
    "details": "<p>You may need to reconfigure the MTConnect adapter to report these values.</p>",
    "id": 11771,
    "key": "MissingTagAlert?name=Multus&tags=TMAC alarm",
    "machine_id": 5,
    "message": "Multus is not correctly reporting TMAC alarm",
    "severity": "PROBLEM",
    "timestamp": 1608002539.009608
  },
  "11772": {
    "actions": {},
    "data": {},
    "details": "<p>You may need to reconfigure the MTConnect adapter to report these values.</p>",
    "id": 11772,
    "key": "MissingTagAlert?name=Multus&tags=variables",
    "machine_id": 5,
    "message": "Multus is not correctly reporting variables",
    "severity": "PROBLEM",
    "timestamp": 1608002538.922787
  },
  "11773": {
    "actions": {},
    "data": {},
    "details": "<p>You may need to reconfigure the MTConnect adapter to report these values.</p>",
    "id": 11773,
    "key": "MissingTagAlert?name=LB2&tags=TMAC alarm",
    "machine_id": 4,
    "message": "LB2 is not correctly reporting TMAC alarm",
    "severity": "PROBLEM",
    "timestamp": 1608002538.897534
  },
  "11778": {
    "actions": {},
    "data": {},
    "details": "<p>You may need to reconfigure the MTConnect adapter to report these values.</p>",
    "id": 11778,
    "key": "MissingTagAlert?name=LB1&tags=TMAC alarm",
    "machine_id": 1,
    "message": "LB1 is not correctly reporting TMAC alarm",
    "severity": "PROBLEM",
    "timestamp": 1608002538.850579
  },
  "11793": {
    "actions": {
      "View": "/tools/#tool-20"
    },
    "data": {},
    "details": "<p>This tool is expected to make fewer than 1 more part</p>",
    "id": 11793,
    "key": "ToolPartsRemainingAlert?tool_id=20",
    "machine_id": null,
    "message": "Tool 'Saw' is near the end of its life expectancy",
    "severity": "WARNING",
    "timestamp": 1607998976.95984
  }
}
Returns:

an object mapping alert IDs to alert objects

POST /api/alerts/clear

Delete all persisted alerts.

Status Codes:
DELETE /api/alerts/(int: alert_id)

Dismiss an alert.

Parameters:

  • alert_id – The ID of the alert to remove

Status Codes:
POST /api/alerts/(int: alert_id)/action/(action)

Call an alert’s callback action.

Parameters:

  • alert_id – the ID of the alert that has the action

  • action – the name of the action to perform (including the __ prefix)

Status Codes:
PUT /api/alerts/

Create a new custom alert.

Examples

Minimal

This is the smallest set of fields that can be provided.

{
  "key": "my_custom_alert",
  "message": "Something happened"
}

Bad weather

This alert will expire in 3 hours and links to a website. Add ?notify=23 to the URL to also send it to the notification channel with ID 23.

{
  "key": "bad_weather_ahead",
  "severity": "WARNING",
  "message": "Bad weather ahead",
  "details": "<p>There are storms forecasted over the next few hours.</p>\n<p>Shut down the machines to avoid damage if the power goes out.</p>",
  "actions": {
    "View forecast": "https://www.wunderground.com"
  },
  "ttl": 7200
}

Complete

This is the full set of fields that can be specified. The presence of the machine_id field means the alert will automatically be deleted if the machine is deleted.

{
  "key": "fully_defined_alert",
  "severity": "INFO",
  "timestamp": 1692300658,
  "ttl": 86400,
  "machine_id": 42,
  "message": "Fully defined alert",
  "details": "<p>This alert has <i>lots</i> of fields.</p>",
  "actions": {
    "More details": "http://10.0.0.123/info"
  },
  "data": {
    "my_custom_field_1": 123,
    "my_custom_field_2": "present",
    "my_custom_field_3": [3, 1.631, 5]
  }
}

What is the key field for?

  • Creating a new alert with the same key as an existing alert will automatically delete the existing alert first. This allows easily updating an existing alert without risking accidental duplication.

  • The key can be any string, but it’s intended to contain any information that distinguishes one instance of an alert from any other of the same type.

  • The value specified for key in the request will have custom| prepended to it to guarantee it cannot collide with any keys of built-in OnTakt alerts.

Query Parameters:

  • notify (int) – set to the ID of a notification channel to send the newly-created alert as a message in that channel in addition to registering it in OnTakt. If not set, the alert will be persisted but no notification message will be sent.

Reqjson:

a (partial) PersistentAlert object

Resjson:

the new PersistentAlert object

Status Codes: