# openclaw-bms

Python-first OpenClaw skill for Kaseya BMS ticket and note workflows.

## Installation

```bash
python3 -m pip install -e .
```

Primary usage:

```bash
bms --help
```

Alternative direct module invocation:

```bash
python3 -m openclaw_bms --help
```

## Configuration

```bash
export BMS_TENANT="your-tenant"
export BMS_USERNAME="your-user"
export BMS_PASSWORD="your-password"
export BMS_MFA_CODE="123456"          # when needed
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"
```

## Core behavior

### Accounts and Locations

Locations are tied to accounts.

That means a location named `Main` under one account is a different object from `Main` under another account.
Always resolve locations in the context of an account.

Commands:

```bash
bms accounts
bms accounts --refresh
bms locations --account 12345
bms locations --account 12345 --refresh
```

Caching:
- accounts cached for 24 hours
- locations cached per account for 24 hours

### Ticket CRUD

List/search:

```bash
bms tickets list --status Open --assignee "Jane Doe"
```

Get:

```bash
bms tickets get 12345
```

Create:

```bash
bms tickets create \
  --title "Server down" \
  --details "Main server offline" \
  --account-id 123 \
  --location-id 456 \
  --status-id 1 \
  --priority-id 2 \
  --type-id 3 \
  --source-id 1 \
  --queue-id 9 \
  --open-date 2026-04-07T14:00:00+00:00
```

Create from template:

```bash
bms tickets create \
  --template-id 7 \
  --title "Override title" \
  --account-id 123 \
  --location-id 456 \
  --queue-id 9
```

Template create flow:
- fetch template
- merge template defaults with explicit CLI overrides
- validate required fields before the API call
- require either `queue-id` or `assignee-id`
- make exactly one create API call per invocation
- require a valid ticket ID in the response before reporting success

Patch:

```bash
bms tickets patch 12345 /StatusId 6
```

Assign:

```bash
bms tickets assign 12345 --details "Routing to tier 2" --type-id 1 --status-id 6 --queue-id 7
```

Delete:

```bash
bms tickets delete 12345
```

### Ticket Note CRUD

List notes:

```bash
bms notes list 12345
```

Add note with custom date:

```bash
bms notes add 12345 --message "Backfilled note" --note-date 2026-04-01T15:00:00+00:00
```

Update note with custom date:

```bash
bms notes update 12345 1001 --message "Corrected note" --note-date 2026-04-01T16:00:00+00:00
```

Delete note:

```bash
bms notes delete 12345 1001
```

### Lookups

```bash
bms lookup statuses
bms lookup priorities
bms lookup types
bms lookup sources
```

Notes:
- `types` maps to issue-type lookup in the public BMS v2 Swagger.
- `sources` is not exposed in the public BMS v2 Swagger; the command fails explicitly and expects tenant-specific source IDs.

### Templates

```bash
bms templates tickets list
bms templates tickets get 7
bms templates notes list
bms templates timelogs list
```

Templates are read-only.

## Audit logging

Write operations only are logged.
Reads are not logged.

Logged operations:
- auth login
- auth refresh
- ticket create
- ticket patch
- ticket delete
- ticket assign
- note add
- note update
- note delete

Log path:

```text
~/.bms-actions/YYYY-MM-DD.jsonl
```

Entry shape:
- `timestamp`
- `command`
- `args_sanitized`
- `result` or `error`
- `status`
- `revert_info` when available

Secrets are redacted:
- `BMS_PASSWORD`
- `BMS_MFA_CODE`
- tokens
- authorization headers

## Architecture

- Python standard library only
- console entry point via `pyproject.toml`
- no shell wrappers required
- service layer separated from CLI
- file-based cache for stable CRM data
- file-based audit log for write history and rollback context