resolutionflow/docs/connectwise/CW_Security_Roles

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:

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:

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.