Update: Enhance Readme

cvp/accesspoint_config_generator/README.md

@@ -35,13 +35,13 @@ The Access Point config generator automates YAML playbook generation for existin
 
 ### Software Requirements
 
-| Component | Version |
-|-----------|---------|
-| Ansible | 2.13+ |
-| cisco.catalystcenter collection | 2.6.0 |
-| Python | 3.9+ |
-| Cisco Catalyst Center | 2.3.5.3+ |
-| catalystcentersdk | 2.10.10+ |
+| Component                       | Version  |
+| ------------------------------- | -------- |
+| Ansible                         | 2.13+    |
+| cisco.catalystcenter collection | 2.6.0    |
+| Python                          | 3.9+     |
+| Cisco Catalyst Center           | 2.3.5.3+ |
+| catalystcentersdk               | 2.10.10+ |
 
 ### Required Collections
 
@@ -79,12 +79,12 @@ accesspoint_config_generator/
 
 ### Basic Configuration
 
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `generate_all_configurations` | boolean | No | false | Workflow convenience flag. When true, the playbook omits module `config` |
-| `file_path` | string | No | auto-generated | Output file path for generated YAML |
-| `file_mode` | string | No | `overwrite` | File write mode: `overwrite` or `append` |
-| `global_filters` | dict | No | omitted | Workflow convenience wrapper mapped to module `config.global_filters` |
+| Parameter                       | Type    | Required | Default        | Description                                                               |
+| ------------------------------- | ------- | -------- | -------------- | ------------------------------------------------------------------------- |
+| `generate_all_configurations` | boolean | No       | false          | Workflow convenience flag. When true, the playbook omits module`config` |
+| `file_path`                   | string  | No       | auto-generated | Output file path for generated YAML                                       |
+| `file_mode`                   | string  | No       | `overwrite`  | File write mode:`overwrite` or `append`                               |
+| `global_filters`              | dict    | No       | omitted        | Workflow convenience wrapper mapped to module`config.global_filters`    |
 
 ### Global Filters
 
@@ -95,13 +95,15 @@ accesspoint_config_generator/
 - `accesspoint_provision_config_mac_list`
 
 Module filter priority:
+
 - `site_list` > `provision_hostname_list` > `accesspoint_config_list` > `accesspoint_provision_config_list` > `accesspoint_provision_config_mac_list`
 
 ---
 
 ## Getting Started
 
 ## Workflow Steps
+
 ## User Flow (3 Steps)
 
 ```mermaid
@@ -118,9 +120,31 @@ flowchart TD
   I --> J[Done]
 ```
 
-### Installation and Run (Aligned)
+### Installation and Run
+
+> Run all commands from **your own test project** (not from inside the collection source tree). Instead of hard-coding paths, define a few environment variables once, then copy-paste the commands below without editing.
+
+#### Step 0: Define reusable path variables (one time per shell)
+
+Set these once at the top of your shell session. Every command in this guide will use them, so you don't need to edit any paths later.
+
+```bash
+# Root of your test project (change this to your actual project directory)
+export PROJECT_DIR="$HOME/my-catc-project"
+
+# Root of the cisco.catalystcenter collection (contains tools/schemavalidation.sh)
+export COLLECTION_DIR="$HOME/catalystcenter-ansible"
+
+# Workflow input/config files (all resolved from PROJECT_DIR by default)
+export INVENTORY_PATH="$PROJECT_DIR/inventory/hosts.yaml"
+export PLAYBOOK_PATH="$PROJECT_DIR/playbook/accesspoint_config_generator.yml"
+export VARS_FILE_PATH="$PROJECT_DIR/vars/accesspoint_config_inputs.yml"
+export SCHEMA_FILE_PATH="$PROJECT_DIR/schema/accesspoint_config_schema.yml"
+```
+
+> Tip: Save these `export` lines in a file like `env.sh` inside your project, then run `source env.sh` at the start of each session.
 
-1. Create and activate a Python virtual environment, then install dependencies.
+#### Step 1: Create a Python virtual environment and install dependencies
 
 ```bash
 python3 -m venv .venv
@@ -129,32 +153,85 @@ pip install catalystcentersdk
 ansible-galaxy collection install cisco.catalystcenter --force
 ```
 
-2. Provide workflow inputs in either inventory (`inventory/demo_lab/hosts.yaml`) or the workflow `vars/` file.
+#### Step 2: Provide workflow inputs
+
+Edit either your inventory file (`$INVENTORY_PATH`) or your vars input file (`$VARS_FILE_PATH`) to provide the workflow inputs.
 
-3. Export Catalyst Center environment variables and run the playbook.
+#### Step 3: Export Catalyst Center credentials and run the playbook
 
 ```bash
 export HOSTIP=<catalyst-center-ip-or-fqdn>
 export CATALYST_CENTER_USERNAME=<username>
 export CATALYST_CENTER_PASSWORD='<password>'
-ansible-playbook -i ./inventory/demo_lab/hosts.yaml ./cvp/accesspoint_config_generator/playbook/accesspoint_config_generator.yml -vvvv
+
+ansible-playbook \
+  -i "$INVENTORY_PATH" \
+  "$PLAYBOOK_PATH" \
+  -vvvv
+```
+
+Or pass the vars input file explicitly via `--extra-vars`:
+
+```bash
+ansible-playbook \
+  -i "$INVENTORY_PATH" \
+  "$PLAYBOOK_PATH" \
+  --extra-vars "VARS_FILE_PATH=$VARS_FILE_PATH" \
+  -vvvv
+```
+
+> The `VARS_FILE_PATH` variable is already an absolute path from Step 0, so no further editing is needed.
+
+## Validate Input (Schema & Vars Validation)
+
+Before running the playbook, validate the input file against the schema using the `schemavalidation.sh` helper (a wrapper around `yamale`). It uses the variables defined in Step 0:
+
+- `-s` : path to the schema file (`$SCHEMA_FILE_PATH`)
+- `-v` : path to the vars input file (`$VARS_FILE_PATH`)
+
+```bash
+"$COLLECTION_DIR/tools/schemavalidation.sh" \
+  -s "$SCHEMA_FILE_PATH" \
+  -v "$VARS_FILE_PATH"
+```
+
+Expected output:
+
+```bash
+(pyats) bash-4.4$ "$COLLECTION_DIR/tools/schemavalidation.sh" \
+  -s "$SCHEMA_FILE_PATH" \
+  -v "$VARS_FILE_PATH"
+$SCHEMA_FILE_PATH
+$VARS_FILE_PATH
+yamale  -s $SCHEMA_FILE_PATH  $VARS_FILE_PATH
+Validating $VARS_FILE_PATH...
+Validation success! 👍
 ```
 
+If `yamale` is not installed in your active environment:
+
+```bash
+pip install yamale
+```
 
 ## Operations
 
 ### Generate Operations (state: gathered)
 
 1. **Generate all AP configurations**
+
 - Set `generate_all_configurations: true`, or omit `global_filters` entirely.
 
 2. **Generate by site list**
+
 - Use `global_filters.site_list`.
 
 3. **Generate by AP hostname filters**
+
 - Use `global_filters.provision_hostname_list` or `global_filters.accesspoint_config_list`.
 
 4. **Generate by combined hostname/MAC filters**
+
 - Use `global_filters.accesspoint_provision_config_list` or `global_filters.accesspoint_provision_config_mac_list`.
 
 ---
@@ -193,3 +270,4 @@ accesspoint_config:
 
 - `accesspoint_playbook_config_generator` expects `config.global_filters` when filtering is used.
 - This workflow omits module `config` when `generate_all_configurations: true` is set or when `global_filters` is omitted or empty.
+- Run all commands from your own test project. Define the path variables from [Step 0](#step-0-define-reusable-path-variables-one-time-per-shell) once per shell (or `source` them from a saved `env.sh`), then copy-paste the commands as-is — no manual path editing required.

cvp/ansible_vault_update/README.md

@@ -24,14 +24,6 @@ passwords_details:
 - password_key: testuser2password
   password_value: 'testuser2@123'
 
-## Executing the playbook to add variables and encrypt to the playbook:
-
-ansible-playbook -i host_inventory cvp/ansible_vault_update/playbook/ansible_vault_update_playbook.yml --extra-vars "VARS_FILE_PATH=../vars/ansible_vault_update_inputs.yml"
-
-
-## Removing variables from ansible vault
-
-ansible-playbook -i host_inventory cvp/ansible_vault_update/playbook/delete_ansible_vault_update_playbook.yml --extra-vars "VARS_FILE_PATH=../vars/ansible_vault_update_inputs.yml"
 ## Workflow Steps
 ## User Flow (3 Steps)
 
@@ -49,9 +41,32 @@ flowchart TD
   I --> J[Done]
 ```
 
-### Installation and Run (Aligned)
+### Installation and Run
+
+> Run all commands from **your own test project** (not from inside the collection source tree). Instead of hard-coding paths, define a few environment variables once, then copy-paste the commands below without editing.
+
+#### Step 0: Define reusable path variables (one time per shell)
+
+Set these once at the top of your shell session. Every command in this guide will use them, so you don't need to edit any paths later.
+
+```bash
+# Root of your test project (change this to your actual project directory)
+export PROJECT_DIR="$HOME/my-catc-project"
+
+# Root of the cisco.catalystcenter collection (contains tools/schemavalidation.sh)
+export COLLECTION_DIR="$HOME/catalystcenter-ansible"
+
+# Workflow input/config files (all resolved from PROJECT_DIR by default)
+export INVENTORY_PATH="$PROJECT_DIR/inventory/hosts.yaml"
+export PLAYBOOK_PATH="$PROJECT_DIR/playbook/ansible_vault_update_playbook.yml"
+export DELETE_PLAYBOOK_PATH="$PROJECT_DIR/playbook/delete_ansible_vault_update_playbook.yml"
+export VARS_FILE_PATH="$PROJECT_DIR/vars/ansible_vault_update_inputs.yml"
+export SCHEMA_FILE_PATH="$PROJECT_DIR/schema/ansible_vault_update_schema.yml"
+```
+
+> Tip: Save these `export` lines in a file like `env.sh` inside your project, then run `source env.sh` at the start of each session.
 
-1. Create and activate a Python virtual environment, then install dependencies.
+#### Step 1: Create a Python virtual environment and install dependencies
 
 ```bash
 python3 -m venv .venv
@@ -60,35 +75,109 @@ pip install catalystcentersdk
 ansible-galaxy collection install cisco.catalystcenter --force
 ```
 
-2. Provide workflow inputs in either inventory (`inventory/demo_lab/hosts.yaml`) or the workflow `vars/` file.
+#### Step 2: Provide workflow inputs
 
-3. Export Catalyst Center environment variables and run the playbook.
+Edit either your inventory file (`$INVENTORY_PATH`) or your vars input file (`$VARS_FILE_PATH`) to provide the workflow inputs.
+
+#### Step 3: Export Catalyst Center credentials and run the playbook
 
 ```bash
 export HOSTIP=<catalyst-center-ip-or-fqdn>
 export CATALYST_CENTER_USERNAME=<username>
 export CATALYST_CENTER_PASSWORD='<password>'
-ansible-playbook -i ./inventory/demo_lab/hosts.yaml ./cvp/ansible_vault_update/playbook/ansible_vault_update_playbook.yml -vvvv
+
+ansible-playbook \
+  -i "$INVENTORY_PATH" \
+  "$PLAYBOOK_PATH" \
+  -vvvv
+```
+
+Or pass the vars input file explicitly via `--extra-vars`:
+
+```bash
+ansible-playbook \
+  -i "$INVENTORY_PATH" \
+  "$PLAYBOOK_PATH" \
+  --extra-vars "VARS_FILE_PATH=$VARS_FILE_PATH" \
+  -vvvv
+```
+
+> The `VARS_FILE_PATH` variable is already an absolute path from Step 0, so no further editing is needed.
+
+## Executing the playbook to add variables and encrypt to the playbook
+
+```bash
+ansible-playbook \
+  -i "$INVENTORY_PATH" \
+  "$PLAYBOOK_PATH" \
+  --extra-vars "VARS_FILE_PATH=$VARS_FILE_PATH"
+```
+
+## Removing variables from ansible vault
+
+```bash
+ansible-playbook \
+  -i "$INVENTORY_PATH" \
+  "$DELETE_PLAYBOOK_PATH" \
+  --extra-vars "VARS_FILE_PATH=$VARS_FILE_PATH"
+```
+
+## Validate Input (Schema & Vars Validation)
+
+Before running the playbook, validate the input file against the schema using the `schemavalidation.sh` helper (a wrapper around `yamale`). It uses the variables defined in Step 0:
+
+- `-s` : path to the schema file (`$SCHEMA_FILE_PATH`)
+- `-v` : path to the vars input file (`$VARS_FILE_PATH`)
+
+```bash
+"$COLLECTION_DIR/tools/schemavalidation.sh" \
+  -s "$SCHEMA_FILE_PATH" \
+  -v "$VARS_FILE_PATH"
+```
+
+Expected output:
+
+```bash
+(pyats) bash-4.4$ "$COLLECTION_DIR/tools/schemavalidation.sh" \
+  -s "$SCHEMA_FILE_PATH" \
+  -v "$VARS_FILE_PATH"
+$SCHEMA_FILE_PATH
+$VARS_FILE_PATH
+yamale  -s $SCHEMA_FILE_PATH  $VARS_FILE_PATH
+Validating $VARS_FILE_PATH...
+Validation success! 👍
+```
+
+If `yamale` is not installed in your active environment:
+
+```bash
+pip install yamale
 ```
 
 ## Inventory / group_vars Example
 
 You can also run this workflow without `VARS_FILE_PATH` by moving the sample workflow data into inventory, `host_vars`, or `group_vars`.
 
-1. Create an inventory vars file such as `inventory/group_vars/all.yml` or `inventory/host_vars/<host>.yml`.
-2. Copy the sample workflow data from `cvp/ansible_vault_update/vars/ansible_vault_update_inputs.yml` into that inventory vars file.
+1. Create an inventory vars file such as `$PROJECT_DIR/inventory/group_vars/all.yml` or `$PROJECT_DIR/inventory/host_vars/<host>.yml`.
+2. Copy the sample workflow data from `$VARS_FILE_PATH` into that inventory vars file.
 3. Keep the same top-level variable name in inventory: `passwords_details`.
 4. Run the playbook without `VARS_FILE_PATH`:
 
 ```bash
-ansible-playbook -i <inventory-file> cvp/ansible_vault_update/playbook/ansible_vault_update_playbook.yml -vvvv
+ansible-playbook \
+  -i "$INVENTORY_PATH" \
+  "$PLAYBOOK_PATH" \
+  -vvvv
 ```
-## VARS_FILE_PATH Path Resolution
 
-Ansible resolves `VARS_FILE_PATH` relative to the playbook directory, not the current working directory.
+## VARS_FILE_PATH
+
+Always provide `VARS_FILE_PATH` as an **absolute path**. The simplest way is to define it once in [Step 0](#step-0-define-reusable-path-variables-one-time-per-shell), for example:
+
+```bash
+export VARS_FILE_PATH="$PROJECT_DIR/vars/ansible_vault_update_inputs.yml"
+```
 
-Use either of these forms:
+Then reference it as `"$VARS_FILE_PATH"` in every command — no manual path editing required.
 
-- Relative to the playbook: `../vars/ansible_vault_update_inputs.yml`
-- Fully resolved from the repo root: `${PWD}/cvp/ansible_vault_update/vars/ansible_vault_update_inputs.yml`