Michael Chihlas
bea34229d6
Add CW security roles reference docs and PSA ticket management plan. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
64 lines
2.7 KiB
Markdown
64 lines
2.7 KiB
Markdown
# ConnectWise integration docs
|
|
|
|
Reference material for ResolutionFlow's ConnectWise Manage integration.
|
|
This folder pairs a **human-editable source** (the XLSX) with two
|
|
**generated artifacts** (YAML + Markdown). Code reads the YAML; humans
|
|
read the Markdown; edits happen in the XLSX.
|
|
|
|
## Files
|
|
|
|
| File | Role | Edit? |
|
|
|------|------|-------|
|
|
| `api-member-security-roles.md` | Human-readable reference — browse on GitHub, link in PRs, onboard new contributors. | Generated — do not edit |
|
|
| `api-member-security-roles.yaml` | Machine-readable source of truth — imported by integration code, queried by Claude Code when writing permission checks. | Generated — do not edit |
|
|
| `source/Security_Roles_Matrix_11132017.xlsx` | Canonical source. The matrix as published by ConnectWise (with any corrections we've applied). | Yes — this is the editing surface |
|
|
| `source/generate_role_docs.py` | Regenerates the YAML and Markdown from the XLSX. Deterministic. | Only if the matrix schema itself changes |
|
|
| `source/requirements.txt` | Python deps for the generator (`openpyxl`, `PyYAML`). | Only when bumping deps |
|
|
|
|
## Regeneration workflow
|
|
|
|
After editing the XLSX:
|
|
|
|
```bash
|
|
cd docs/integrations/connectwise/source
|
|
pip install -r requirements.txt
|
|
python generate_role_docs.py \
|
|
--source Security_Roles_Matrix_11132017.xlsx \
|
|
--out-yaml ../api-member-security-roles.yaml \
|
|
--out-md ../api-member-security-roles.md
|
|
```
|
|
|
|
Commit all three files together (XLSX, YAML, MD). The diff on the YAML
|
|
is what reviewers should scrutinize — it is the source of truth for code.
|
|
|
|
## Querying the YAML from integration code
|
|
|
|
The YAML groups permissions by module and action. Example — checking
|
|
what `Inquire: ALL` means for Service Desk → Service Tickets:
|
|
|
|
```python
|
|
import yaml
|
|
from pathlib import Path
|
|
|
|
doc = yaml.safe_load(
|
|
Path("docs/integrations/connectwise/api-member-security-roles.yaml").read_text()
|
|
)
|
|
levels = doc["modules"]["Service Desk"]["actions"]["Service Tickets"]["inquire"]["levels"]
|
|
print(levels["ALL"])
|
|
```
|
|
|
|
This is the pattern `ConnectWiseAuthManager` and the proxy authorization
|
|
layer should use when the required permission level for a given API
|
|
endpoint needs to be documented or validated against an assigned role.
|
|
|
|
## Conventions
|
|
|
|
- **Levels are ordered most-to-least privileged:** `ALL`, `MY`, `MINE`, `NONE`.
|
|
- **Verbs are always in this order:** `add`, `edit`, `delete`, `inquire`.
|
|
- **`Not applicable` notes** in a verb's cell mean the meaningful level
|
|
is documented under another verb (almost always `inquire`) — the
|
|
generator preserves these as `note:` fields rather than inventing
|
|
placeholder levels.
|
|
- **The XLSX is the single source of input.** Never hand-edit the YAML
|
|
or Markdown; your changes will be overwritten on the next regeneration.
|