openclaw-bms/SKILL.md

BMS Skill — Kaseya BMS Ticket Management

Manage service desk tickets in Kaseya BMS (Business Management Solution) via the BMS API v2.

Configuration

Required environment variables (store in shell profile or a secrets manager):

export BMS_TENANT="your-tenant-name"       # Your BMS tenant/subdomain
export BMS_USERNAME="user@example.com"     # BMS login username
export BMS_PASSWORD="yourpassword"         # BMS login password
# Or use client credentials (OAuth2):
export BMS_CLIENT_ID="your-client-id"
export BMS_CLIENT_SECRET="your-client-secret"

Tokens are cached automatically at ~/.bms_token.json.

Commands

All commands route through scripts/bms.sh. Run without arguments for usage.

Authentication

bms auth                     # Authenticate and cache token
bms auth --status            # Show token status / expiry

Listing Tickets

bms tickets list                                    # All open tickets (paginated)
bms tickets list --status "Open"                    # Filter by status name
bms tickets list --assignee "John Smith"            # Filter by assignee name
bms tickets list --from 2024-01-01 --to 2024-01-31 # Filter by created date range
bms tickets list --priority "High"                  # Filter by priority
bms tickets list --queue "Support"                  # Filter by queue
bms tickets list --account "Acme Corp"              # Filter by account
bms tickets list --page 2 --page-size 50            # Pagination
bms tickets list --format json                      # Raw JSON output

Getting a Ticket

bms tickets get <ticketId>          # Get full ticket details
bms tickets get <ticketId> --json   # Raw JSON

Creating Tickets

bms tickets create \
  --title "Server is down" \
  --details "The main server stopped responding at 2pm" \
  --account-id 123 \
  --location-id 456 \
  --status-id 1 \
  --priority-id 2 \
  --type-id 1 \
  --source-id 1 \
  --assignee-id 789

Create from a template (pre-fills fields; CLI overrides take precedence):

bms tickets create --template-id 7 --account-id 123 --location-id 456
# Fields from template 7 are used; only account/location are overridden.
# Any required field still missing triggers an interactive prompt.

Or use fully interactive mode (prompts for all required fields):

bms tickets create --interactive

Updating Tickets

bms tickets update <ticketId> --status-id 3              # Change status
bms tickets update <ticketId> --assignee-id 789          # Reassign
bms tickets update <ticketId> --priority-id 1            # Change priority
bms tickets update <ticketId> --title "New title"        # Update title

Adding Notes

bms tickets note <ticketId> --message "Called client, investigating"
bms tickets note <ticketId> --message "Internal update" --internal
bms tickets note <ticketId> --message "Resolved via restart" --status-id 5

Assigning Tickets

bms tickets assign <ticketId> --assignee-id 789 --note "Routing to tier 2"
bms tickets assign <ticketId> --queue-id 3

Resolving Tickets

bms tickets resolve <ticketId> --comment "Replaced failed drive, server is back online"
bms tickets resolve <ticketId> --comment "Fixed" --status-id 6 --publish-kb

Deleting Tickets

bms tickets delete <ticketId>          # Delete single ticket
bms tickets delete 123 456 789         # Delete multiple tickets

Lookup Tables (for getting valid IDs)

bms lookup statuses        # List all ticket statuses with IDs
bms lookup priorities      # List all priorities with IDs
bms lookup queues          # List all queues with IDs
bms lookup issue-types     # List all issue types
bms lookup assignees       # List all assignees/technicians
bms lookup ticket-types    # List ticket types
bms lookup sources         # List ticket sources

Templates

Browse pre-defined ticket, note, and timelog templates configured in BMS.

bms templates tickets list              # List all ticket templates (Id, Name, QueueId, PriorityId, etc.)
bms templates tickets get <id>          # Inspect a specific ticket template (raw JSON)
bms templates notes list                # List all note templates
bms templates timelogs list             # List all timelog templates

# Add --format json to any list command for raw JSON output
bms templates tickets list --format json

Template-Based Ticket Creation

bms tickets create --template-id <N> does the following:

1. Fetches GET /v2/servicedesk/templates/tickets/{templateId} to retrieve template defaults.
2. Merges them with any CLI overrides you provide (--title, --description, --account-id, --location-id, --status-id, --priority-id, --type-id, --source-id, --assignee-id, --queue-id, --due-date, --contact-id). CLI values always win.
3. Prompts interactively (via stdin) for any required field still missing after the merge.
4. Posts the final payload to POST /v2/servicedesk/tickets.

Use bms templates tickets list to see available template IDs before creating.

Notes / Quirks

• Auth: BMS uses JWT Bearer tokens obtained via POST /v2/security/authenticate with GrantType=password. Tokens expire; the skill auto-refreshes using the refresh token endpoint.
• Required fields for ticket creation: Title, Details, AccountId, LocationId, StatusId, PriorityId, TypeId, SourceId, OpenDate — all are required by the API schema.
• IDs not names: The API uses integer IDs for status, priority, type, etc. Use bms lookup commands to find the right IDs for your tenant.
• Search vs GET list: For filtered searches, POST /v2/servicedesk/tickets/search (with body) is more flexible than GET /v2/servicedesk/tickets (with query params); this skill uses the POST search by default.
• Pagination: Default page size is 25. Use --page-size (max appears to be 100) and --page for large result sets.
• Date format: Dates should be ISO 8601 strings, e.g. 2024-01-15T00:00:00.
• Note TypeId: Required when posting notes. Use bms lookup note-types to find valid IDs (typically: 1=Comment, 2=Resolution, etc. — varies by tenant).
• Rate limits: Not documented in the Swagger spec. Treat as standard REST API — avoid tight loops; add a small sleep between bulk operations.

References

• BMS API Swagger UI
• BMS API Swagger JSON
• references/key-schemas.md — TicketInputDto, filter, and note schemas
• scripts/bms.sh — Main CLI entrypoint
• scripts/bms-auth.sh — Auth and token management
• scripts/bms-tickets.sh — Ticket CRUD operations (includes --template-id support)
• scripts/bms-lookup.sh — Lookup table helpers
• scripts/bms-templates.sh — Template listing commands (tickets, notes, timelogs)