openclaw-bms/SKILL.md

BMS Skill — Kaseya BMS Ticket Management

Python-based OpenClaw skill for Kaseya BMS ticket and note workflows.

Scope

This skill focuses on:

• ticket CRUD
• ticket note CRUD
• CRM account and account-scoped location lookup
• template-assisted ticket creation
• token handling with MFA support
• account/location caching

Configuration

export BMS_TENANT="your-tenant-name"
export BMS_USERNAME="user@example.com"
export BMS_PASSWORD="yourpassword"
export BMS_MFA_CODE="123456"               # when needed
export BMS_API_BASE="https://api.bms.kaseya.com"
export BMS_TOKEN_FILE="$HOME/.bms_token.json"
export BMS_CACHE_FILE="$HOME/.cache/openclaw-bms/cache.json"

Commands

Primary entrypoint:

bash scripts/bms.sh --help

Auth

bms auth login
bms auth refresh
bms auth status

Accounts and Locations

bms accounts
bms accounts --refresh
bms locations --account 12345
bms locations --account 12345 --refresh

Important:

• locations are tied to accounts
• the same location name can exist under multiple accounts with different IDs
• always resolve location IDs in the context of a specific account

Tickets

bms tickets list --status Open --assignee "Jane Doe"
bms tickets get 12345
bms tickets create --title "test" --details "Test" --account-id 1 --location-id 2 --status-id 3 --priority-id 4 --type-id 5 --source-id 6 --queue-id 7
bms tickets create --template-id 9 --title "Override title" --account-id 1 --location-id 2 --queue-id 7
bms tickets patch 12345 /StatusId 6
bms tickets assign 12345 --details "Routing" --type-id 1 --status-id 6 --queue-id 7
bms tickets delete 12345

Features:

• --open-date supported for ticket creation
• template-based creation merges template defaults with explicit overrides
• create validation requires all required fields plus either queue-id or assignee-id
• create path makes one API call only and validates response semantics before reporting success

Notes

bms notes list 12345
bms notes add 12345 --message "Investigating" --note-date 2026-04-07T12:00:00+00:00
bms notes update 12345 999 --message "Corrected note" --note-date 2026-04-07T13:00:00+00:00
bms notes delete 12345 999

Features:

• custom note dates supported for create and update
• note CRUD exposed directly in the Python CLI

Templates

bms templates tickets list
bms templates tickets get 9
bms templates notes list
bms templates timelogs list

Templates are read-only.

Endpoints used

Auth:

• POST /v2/security/authenticate
• POST /v2/security/refreshtoken

CRM lookup:

• GET /v2/crm/accounts/lookup
• GET /v2/crm/accounts/{accountId}/locations/lookup

Tickets:

• POST /v2/servicedesk/tickets/search
• GET /v2/servicedesk/tickets/{ticketId}
• POST /v2/servicedesk/tickets
• PATCH /v2/servicedesk/tickets/{ticketId}
• DELETE /v2/servicedesk/tickets/{ticketId}
• POST /v2/servicedesk/tickets/{ticketId}/assignticket

Notes:

• GET /v2/servicedesk/tickets/{ticketId}/notes
• POST /v2/servicedesk/tickets/{ticketId}/notes
• PUT /v2/servicedesk/tickets/{ticketId}/notes/{noteId}
• DELETE /v2/servicedesk/tickets/{ticketId}/notes/{noteId}

Templates:

• GET /v2/servicedesk/templates/tickets/lookup
• GET /v2/servicedesk/templates/tickets/{templateId}
• GET /v2/servicedesk/templates/notes/lookup
• GET /v2/servicedesk/templates/timelogs/lookup

Note Type IDs (Grand Portage tenant)

Known working values from tenant testing:

• 0 — Email Sent
• 1 — Email Received
• 2 — General Notes
• 3 — Phone Call
• 4 — Resolution

These are tenant-specific and may differ elsewhere.

Implementation notes

• Python standard library only
• shell scripts retained as compatibility wrappers around the Python CLI
• cached lookups reduce repeated account/location API calls
• account/location cache TTL is 24 hours by default
• designed for Daniel’s direct use and BMS operator workflows