ImmyBot Maintenance Sessions

ImmyBot Maintenance Sessions

A maintenance session is the unit of work that reconciles an endpoint (or a whole tenant) against its desired state — installing, updating, or removing software and running remediation. Starting a session is destructive: it can install software and reboot machines.

API Tools

Tool	Purpose
immybot_maintenance_sessions_list	Recent sessions with computer/tenant/status/type/date filters
immybot_maintenance_sessions_get	Snapshot of one session by ID
immybot_maintenance_sessions_active	All currently running sessions
immybot_maintenance_sessions_start	Start a session (DESTRUCTIVE)
immybot_maintenance_sessions_pause	Pause a running session
immybot_maintenance_sessions_resume	Resume a paused session
immybot_maintenance_sessions_cancel	Cancel a queued/running session (DESTRUCTIVE)
immybot_maintenance_sessions_logs	Log stream for a session
immybot_maintenance_sessions_results	Final results / per-task outcomes

Starting a Session

immybot_maintenance_sessions_start targets either a single computer ID or a tenant ID (all computers in that tenant). It takes a session type, priority, a reboot flag (allow reboot if required), and a description / reason.

This operation is destructive — obtain human approval, name the scope explicitly, and decide deliberately whether reboots are permitted before starting.

Monitoring a Running Session

1. immybot_maintenance_sessions_get — poll for status.
2. immybot_maintenance_sessions_logs — tail progress detail.
3. Stop polling once the session reaches a terminal state (completed / failed / cancelled).

Use immybot_maintenance_sessions_active to see everything running across the fleet at once.

Controlling a Session

• Pause — immybot_maintenance_sessions_pause halts a running session (e.g. user reports the machine is busy). Supply a reason.
• Resume — immybot_maintenance_sessions_resume continues a paused session.
• Cancel — immybot_maintenance_sessions_cancel stops a queued or running session. Destructive: an in-progress install may be left half-applied. Supply a cancellation reason.

Investigating a Failed Session

1. immybot_maintenance_sessions_list filtered by computer/tenant and status = failed to locate the session.
2. immybot_maintenance_sessions_results for which tasks failed.
3. immybot_maintenance_sessions_logs for the failing log lines.
4. Cross-reference the underlying tasks via the tasks tools (immybot_tasks_for_computer, immybot_tasks_failed).
5. Re-run a targeted session once the root cause is fixed.

Edge Cases

• Reboot-spanning sessions — when reboot is allowed and an install requires it, the session continues after the reboot; expect a longer wall-clock duration.
• Tenant-scoped sessions — touch every computer in the tenant. Confirm the blast radius before starting.
• Queued vs running — a session may sit queued behind others; immybot_maintenance_sessions_get distinguishes the states.

Best Practices

• Pilot with a single-computer session before a tenant-wide one.
• Schedule fleet-wide sessions during maintenance windows.
• Log the approver, scope, reboot decision, and outcome for every started or cancelled session.

Related Skills

• software-deployment — stage the desired state a session reconciles
• tenant-compliance — confirm the post-session compliance result
• api-patterns — destructive-operation and polling patterns