From 0540c141c571e6c42be4941ae11913d725e03900 Mon Sep 17 00:00:00 2001 From: Adam Weeks Date: Tue, 22 Jul 2025 18:24:00 -0400 Subject: [PATCH] Enhance README with comprehensive documentation and resource links for Webex BYODS --- README.md | 41 +++++++++++++++++++++++++++++++++++++---- 1 file changed, 37 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index f27eac5..1677e76 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,11 @@ # Webex BYO Data Source Management -This script manages Webex BYODS (Bring Your Own Data Source) system using the Webex Admin API. +This script manages [Webex BYODS (Bring Your Own Data Source)](https://developer.webex.com/create/docs/bring-your-own-datasource) system using the Webex Admin API. ## Main Script **`data-sources.py`** - Unified interface for all data source operations including: + - Listing and viewing existing data sources - Registering new data sources - Updating existing data source configurations @@ -21,12 +22,14 @@ This script manages Webex BYODS (Bring Your Own Data Source) system using the We ## Setup 1. Create and activate a virtual environment (recommended): + ```bash python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate ``` 2. Install the required dependencies: + ```bash pip install -r requirements.txt ``` @@ -38,25 +41,29 @@ This script manages Webex BYODS (Bring Your Own Data Source) system using the We ## Usage Run the data source manager: + ```bash python data-sources.py ``` **Features:** + - Automatically loads and displays all your data sources on startup -- Interactive menu to view/update existing data sources or register new ones +- Interactive menu to view/update existing data sources or register new ones - Real-time refresh capability - Unified interface for all operations - Saves operation records automatically - JWT token decoding for enhanced data source details **Menu Options:** + 1. **View/Update Data Sources**: Select any data source to view details and optionally update 2. **Register New Data Source**: Create a new data source with guided prompts 3. **Refresh Data Sources List**: Reload the current list from the API 4. **Quit**: Exit the application **Optional Flags:** + ```bash # Save the initial data sources list to a JSON file python data-sources.py --save-list @@ -78,23 +85,45 @@ When registering a new data source, the script will prompt for: ### Update Process When updating data sources, the process: + - Pre-fills current values as defaults (press Enter to keep) - Requires a new nonce for security (auto-generated UUID provided) - Allows updating token lifetime, URL, audience, subject, schema ID, and status - Confirms changes before applying - Saves operation records to JSON files automatically -## API Documentation +## Documentation and Resources + +### Comprehensive BYODS Guide + +- [Bring Your Own Data Source - Complete Developer Guide](https://developer.webex.com/create/docs/bring-your-own-datasource) - Comprehensive guide covering the entire BYODS framework + +### Getting Started + +- [Service Apps Guide](https://developer.webex.com/docs/service-apps) - Learn how to create and configure Service Apps +- [Webex Developer Portal](https://developer.webex.com/) - Create your Service App here +- [Developer Sandbox Guide](https://developer.webex.com/docs/developer-sandbox-guide) - Set up a sandbox environment for testing +- [Contact Center Sandbox](https://developer.webex-cx.com/sandbox) - For Contact Center specific use cases + +### API Documentation -For more information about the Webex Data Sources API, visit: - [Register a Data Source](https://developer.webex.com/admin/docs/api/v1/data-sources/register-a-data-source) - [Retrieve All Data Sources](https://developer.webex.com/admin/docs/api/v1/data-sources/retrieve-all-data-sources) - [Retrieve Data Source Details](https://developer.webex.com/admin/docs/api/v1/data-sources/retrieve-data-source-details) - [Update a Data Source](https://developer.webex.com/admin/docs/api/v1/data-sources/update-a-data-source) +- [Data Source Schemas API](https://developer.webex.com/docs/api/v1/data-sources/retrieve-all-data-source-schemas) - Browse available schemas + +### Security and Authentication + +- [JWT Debugger](https://jwt.io) - Tool for inspecting JWS tokens +- [JWS Token Verification Example (Java)](https://github.com/ralfschiffert/byodsJws) - Reference implementation for token validation +- [Cisco Public Key Endpoints](https://idbroker.webex.com/idb/oauth2/v2/keys/verificationjwk/) - US endpoint for JWS verification +- [EU Public Key Endpoint](https://idbroker-eu.webex.com/idb/oauth2/v2/keys/verificationjwk) - EU endpoint for JWS verification ## Response and Output Upon successful operations, you'll receive: + - Data Source ID (for registrations) - Status (active/disabled) - All configured parameters @@ -102,12 +131,14 @@ Upon successful operations, you'll receive: - Enhanced JWT token information (audience, subject, expiration) The script automatically saves all operation details to JSON files: + - **Successful registrations**: `data_source_registration_{ID}_{timestamp}.json` - **Successful updates**: `data_source_update_{ID}_{timestamp}.json` - **Failed operations**: `data_source_{operation}_failed_{timestamp}.json` - **Data source lists**: `data_sources_list_{timestamp}.json` (when using --save-list flag) These files contain: + - Operation timestamp - Original configuration used - Complete API response @@ -118,6 +149,7 @@ These files contain: ## Authentication The script requires a Service App access token with the following scopes: + - **Registration and Updates**: `spark-admin:datasource_write` - **Listing/Viewing**: `spark-admin:datasource_read` @@ -126,6 +158,7 @@ For full functionality, use a token that has both read and write scopes. ## Error Handling The script includes comprehensive error handling for: + - Missing or invalid access tokens - Network connection issues - API validation errors