Imported from jeokrohn/ucmprovisioning (AGENTS.md). Install upstream with npx skills add jeokrohn/ucmprovisioning. Copyright stays with the author.

AGENTS.md

What this repo does

• Automates Cisco Unified CM provisioning from YAML config, centered on setup.py and UCMConfigurator.
• Primary flow is config-driven orchestration: config_*.yml -> UCMConfigurator methods -> SOAP/API calls.

Architecture and boundaries

• setup.py is the orchestration layer; most provisioning logic lives in UCMConfigurator methods (dial plan, LDAP, GDPR, IMP, routing, self-provisioning).
• ucmaxl/__init__.py is the core API adapter (AXLHelper) wrapping AXL SOAP operations and SQL helpers (sql_query, sql_update).
• ucmcontrolcenter/__init__.py handles service status/deploy/restart operations via Control Center SOAP.
• ucmris/__init__.py is a separate RIS SOAP helper (used by ristest.py), mostly for runtime device state queries.
• WSDLs are vendored under ucmaxl/WSDL/*, ucmcontrolcenter/WSDL/*, ucmris/WSDL/*; helpers can download WSDLs from CUCM if local version is missing.

Critical execution workflow

• Main execution is manual and selective in setup.py:main(): pick config_selector and uncomment only the provisioning steps you intend to run.
• Typical run command is: uv run python setup.py
• Start from an existing config (for schema and naming patterns use config_example.yml / config_pa_cvd_15.yml).
• Many operations are idempotent through add_update_* wrappers; repeated runs are expected, but some paths still do direct SQL updates.

Project-specific coding patterns

• Prefer using AXLHelper.add_update_* methods instead of raw service.* calls for create-or-update behavior.
• When extending APIs, follow existing get -> add/update fault handling style (zeep.exceptions.Fault with Item not valid).
• CUCM UUID handling is non-obvious: thick AXL often returns uppercase UUID in {}; code commonly normalizes via [1:-1].lower().
• sql_query returns list of ordered dict rows; many workflows rely on direct SQL joins (see create_dns_and_csfs, set_process_node_names).
• Data payloads intentionally mirror CUCM SOAP schemas as nested dicts (examples: create_self_provisioning, create_sip_routing).
• Boolean/enum values are often CUCM-specific strings ('true', 'false', 'T', 'Off', 'Default') rather than Python booleans.

Integrations and external dependencies

• Transport stack: requests session + zeep SOAP client with per-host sqlite cache in temp dir.
• CUCM endpoints in use:
  • AXL: https://<host>:8443/axl/
  • Control Center: https://<host>:8443/controlcenterservice2/services/ControlCenterServices
  • RIS: https://<host>:8443/realtimeservice2/services/RISService70
• Config drives credentials and topology (target, services, dialplan, ldap, routing, selfprovisioning).

Tooling and validation workflow

• Python target is >=3.13 (pyproject.toml); dependencies are managed with uv.
• Lint/format/type checks are repo-standard via pre-commit:
  • uv run ruff format .
  • uv run ruff check .
  • uv run mypy --follow-imports=silent --no-namespace-packages .
  • uv run pre-commit run --all-files
• There is no dedicated test suite in repo; validate changes with static checks plus a narrowly scoped provisioning run.

Safety notes for agent changes

• Treat config_*.yml and playground scripts as potentially sensitive; never introduce or persist real credentials.
• Prefer minimal, reversible changes in setup.py because methods perform live CUCM writes and service restarts.
• Preserve existing naming conventions for partitions/CSS/device pools (site/habit prefixes are semantically meaningful to dial plan logic).