# 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)