chore: bump version and changelog (v0.1.0.0)
Add CW security roles reference docs and PSA ticket management plan. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
63
docs/connectwise/CW_Security_Roles/README.md
Normal file
63
docs/connectwise/CW_Security_Roles/README.md
Normal file
@@ -0,0 +1,63 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user