179 lines
7.1 KiB
Markdown
179 lines
7.1 KiB
Markdown
# 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 accounts # List CRM accounts (Id, Name, Code)
|
|
bms locations --account 123 # List CRM locations for account 123
|
|
bms lookup ticket-types # Not exposed in public BMS v2 Swagger for all tenants
|
|
bms lookup sources # Not exposed in public BMS v2 Swagger for all tenants
|
|
```
|
|
|
|
### 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 `POST /v2/security/refreshtoken`.
|
|
- **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`, `bms accounts`, and `bms locations` 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. The public BMS v2 Swagger does not clearly expose a generic note-type lookup endpoint for all tenants, so you may need tenant-specific documentation or known values.
|
|
- **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)
|