Migrate BMS skill to Python-only CLI with audit logging
This commit is contained in:
Steve W
108
SKILL.md
108
SKILL.md
@@ -2,15 +2,19 @@
|
||||
|
||||
Python-based OpenClaw skill for Kaseya BMS ticket and note workflows.
|
||||
|
||||
## Scope
|
||||
## Run
|
||||
|
||||
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
|
||||
Preferred:
|
||||
|
||||
```bash
|
||||
bms --help
|
||||
```
|
||||
|
||||
Alternative:
|
||||
|
||||
```bash
|
||||
python3 -m openclaw_bms --help
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
@@ -18,60 +22,40 @@ This skill focuses on:
|
||||
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_MFA_CODE="123456"
|
||||
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
|
||||
bash scripts/bms.sh --help
|
||||
```
|
||||
|
||||
### Auth
|
||||
|
||||
```bash
|
||||
bms auth login
|
||||
bms auth refresh
|
||||
bms auth status
|
||||
```
|
||||
## Key functionality
|
||||
|
||||
### Accounts and Locations
|
||||
|
||||
Use CRM endpoints and respect account/location relationships:
|
||||
|
||||
```bash
|
||||
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
|
||||
- locations are account-scoped
|
||||
- a location name under one account is not interchangeable with the same location name under another account
|
||||
- accounts and per-account locations are cached for 24 hours
|
||||
|
||||
### Tickets
|
||||
|
||||
```bash
|
||||
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 --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 --open-date 2026-04-07T14:00:00+00:00
|
||||
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
|
||||
|
||||
```bash
|
||||
@@ -81,9 +65,14 @@ bms notes update 12345 999 --message "Corrected note" --note-date 2026-04-07T13:
|
||||
bms notes delete 12345 999
|
||||
```
|
||||
|
||||
Features:
|
||||
- custom note dates supported for create and update
|
||||
- note CRUD exposed directly in the Python CLI
|
||||
### Lookups
|
||||
|
||||
```bash
|
||||
bms lookup statuses
|
||||
bms lookup priorities
|
||||
bms lookup types
|
||||
bms lookup sources
|
||||
```
|
||||
|
||||
### Templates
|
||||
|
||||
@@ -96,6 +85,27 @@ bms templates timelogs list
|
||||
|
||||
Templates are read-only.
|
||||
|
||||
## Audit logging
|
||||
|
||||
Only write operations are audited.
|
||||
Read operations are intentionally not logged.
|
||||
|
||||
Audit path:
|
||||
|
||||
```text
|
||||
~/.bms-actions/YYYY-MM-DD.jsonl
|
||||
```
|
||||
|
||||
Entry fields:
|
||||
- `timestamp`
|
||||
- `command`
|
||||
- `args_sanitized`
|
||||
- `result` or `error`
|
||||
- `status`
|
||||
- `revert_info` when available
|
||||
|
||||
Secrets are redacted before logging.
|
||||
|
||||
## Endpoints used
|
||||
|
||||
Auth:
|
||||
@@ -116,6 +126,7 @@ Tickets:
|
||||
|
||||
Notes:
|
||||
- `GET /v2/servicedesk/tickets/{ticketId}/notes`
|
||||
- `GET /v2/servicedesk/tickets/{ticketId}/notes/{noteId}`
|
||||
- `POST /v2/servicedesk/tickets/{ticketId}/notes`
|
||||
- `PUT /v2/servicedesk/tickets/{ticketId}/notes/{noteId}`
|
||||
- `DELETE /v2/servicedesk/tickets/{ticketId}/notes/{noteId}`
|
||||
@@ -125,22 +136,3 @@ Templates:
|
||||
- `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
|
||||
|
||||
Reference in New Issue
Block a user