Initial commit: BMS skill with template support
This commit is contained in:
176
SKILL.md
Normal file
176
SKILL.md
Normal file
@@ -0,0 +1,176 @@
|
||||
# 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):
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
bms auth # Authenticate and cache token
|
||||
bms auth --status # Show token status / expiry
|
||||
```
|
||||
|
||||
### Listing Tickets
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
bms tickets get <ticketId> # Get full ticket details
|
||||
bms tickets get <ticketId> --json # Raw JSON
|
||||
```
|
||||
|
||||
### Creating Tickets
|
||||
|
||||
```bash
|
||||
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):
|
||||
|
||||
```bash
|
||||
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):
|
||||
|
||||
```bash
|
||||
bms tickets create --interactive
|
||||
```
|
||||
|
||||
### Updating Tickets
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
bms tickets assign <ticketId> --assignee-id 789 --note "Routing to tier 2"
|
||||
bms tickets assign <ticketId> --queue-id 3
|
||||
```
|
||||
|
||||
### Resolving Tickets
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
bms tickets delete <ticketId> # Delete single ticket
|
||||
bms tickets delete 123 456 789 # Delete multiple tickets
|
||||
```
|
||||
|
||||
### Lookup Tables (for getting valid IDs)
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
```bash
|
||||
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](https://api.bms.kaseya.com/swagger/index.html)
|
||||
- [BMS API Swagger JSON](https://api.bms.kaseya.com/swagger/v2/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)
|
||||
Reference in New Issue
Block a user