Hold

Models

class pytm4srv.models.MachineHold
end: Mapped[datetime | None]

Date and time when this hold should end.

NULL means this hold is indefinite and must be manually released.

id: MappedColumn object at 0x7d28dc361c60>]]

Unique, numeric ID for this hold.

machine_id: Mapped[int]

ID of the machine this hold applies to.

notes: Mapped[str]

User-supplied notes for this hold.

Usually added or modified after creation.

reason: Mapped[str]

User-supplied reason for this hold.

schedule_id: Mapped[int | None]

ID of the schedule that created this hold.

Will be NULL for holds that were created manually.

start: Mapped[datetime]

Date and time when this hold should start.

Defaults to the time of creation.

user_id: Mapped[int | None]

ID of the user who created this machine hold.

May be NULL for holds imported from before the user was stored, holds created by users who have been deleted, or holds created automatically from a schedule.

class pytm4srv.models.MachineHoldSchedule
duration: Mapped[timedelta | None]

How long to hold the machine each time this schedule fires (in minutes).

NULL means the hold will be indefinite and must be manually released.

frequency: Mapped[str]

How often to repeat this schedule.

Valid options are:

  • Y (yearly)

  • M (monthly)

  • W (weekly)

  • D (daily)

  • H (hourly)

id: MappedColumn object at 0x7d28dc361c60>]]

Unique, numeric ID for this hold schedule.

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.

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.

machine_id: Mapped[int]

ID of the machine this schedule applies to.

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-supplied name of this schedule.

reason: Mapped[str]

Reason to apply to holds created from this schedule.

time_of_day: Mapped[time]

What time of day to schedule for.

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/machines/holds/

Query across all holds.

Query Parameters:

  • machine (int) – if specified, only holds for this machine ID will be returned. Can be specified multiple times to get holds across multiple machines.

  • user (int) – if specified, only holds created by this user ID will be returned. Can be specified multiple times to get holds created by multiple users. Use 0 to get holds created automatically.

  • end (int) – set to 1 to only get holds with an end set, set to 0 to only get holds without an end set, or omit for both (default)

  • start_after (float) – only get holds starting after this time

  • end_before (float) – only get holds ending at or before this time (assumes end = 1)

  • limit (int) – maximum number of results to return (default = unlimited)

  • offset (int) – skip this many results

Returns:

a list of MachineHold objects in chronological order by start timestamp

GET /api/machines/holds/(int: hold_id)

Get details about a single machine hold.

Parameters:

  • hold_id – the ID of the hold to get information about

Status Codes:
Return:

the MachineHold object

PATCH /api/machines/holds/(int: hold_id)

Edit an existing machine hold.

Parameters:

  • hold_id – the ID of the hold to edit

Status Codes:
Reqjson:

a (partial) MachineHold object

Return:

the modified MachineHold object

DELETE /api/machines/holds/(int: hold_id)

Delete an existing machine hold.

This can only be done by administrators and planners.

Parameters:

  • hold_id – the ID of the hold to delete

Status Codes:
GET /api/machines/holds/schedules/

Get all existing machine hold schedules.

Return:

object mapping MachineHoldSchedule ID to MachineHoldSchedule object

PUT /api/machines/holds/schedules/

Create a new machine hold schedule.

Status Codes:
Reqjson:

a MachineHoldSchedule object

Return:

the new MachineHoldSchedule object

POST /api/machines/holds/schedules/previewSchedule

List the next few times when the provided schedule would run. The request body should include at least the scheduling fields of a machine hold schedule, but if id is provided, the schedule will start from the timestamp of the last hold with that schedule ID.

Query Parameters:

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

Reqjson:

a partial MachineHoldSchedule object

Returns:

an array of count UNIX timestamps

GET /api/machines/holds/schedules/(int: schedule_id)

Get details about a single machine hold schedule.

Parameters:

  • schedule_id – the ID of the hold schedule to get information about

Status Codes:
Return:

the MachineHoldSchedule object

PATCH /api/machines/holds/schedules/(int: schedule_id)

Edit an existing machine hold schedule.

Parameters:

  • schedule_id – the ID of the hold schedule to edit

Status Codes:
Reqjson:

a (partial) MachineHoldSchedule object

Return:

the modified MachineHoldSchedule object

DELETE /api/machines/holds/schedules/(int: schedule_id)

Delete an existing machine hold schedule.

Parameters:

  • schedule_id – the ID of the hold schedule to delete

Status Codes: