Add External Dynamic Lists documentation and models

This commit introduces new documentation and models for managing External Dynamic Lists (EDLs) in the SDK, enhancing capabilities to handle IP, domain, URL, IMSI, and IMEI lists. Updates include new md files, index entries, and release notes detailing EDLs configuration, methods, and best practices.

docs/about/release-notes.md

@@ -1,3 +1,8 @@
+## Version 0.3.4
+
+- Added support for External Dynamic Lists
+- Added support for Auto Tag Actions (not yet supported by API)
+
 ## Version 0.3.3
 
 - Added support for URL Categories

docs/sdk/config/objects/external_dynamic_lists.md

@@ -0,0 +1,374 @@
+# External Dynamic Lists Configuration Object
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Core Methods](#core-methods)
+3. [EDL Model Attributes](#edl-model-attributes)
+4. [Exceptions](#exceptions)
+5. [Basic Configuration](#basic-configuration)
+6. [Usage Examples](#usage-examples)
+    - [Creating EDLs](#creating-edls)
+    - [Retrieving EDLs](#retrieving-edls)
+    - [Updating EDLs](#updating-edls)
+    - [Listing EDLs](#listing-edls)
+    - [Deleting EDLs](#deleting-edls)
+7. [Managing Configuration Changes](#managing-configuration-changes)
+    - [Performing Commits](#performing-commits)
+    - [Monitoring Jobs](#monitoring-jobs)
+8. [Error Handling](#error-handling)
+9. [Best Practices](#best-practices)
+10. [Full Script Examples](#full-script-examples)
+11. [Related Models](#related-models)
+
+## Overview
+
+The `ExternalDynamicLists` class provides functionality to manage External Dynamic Lists (EDLs) in Palo Alto Networks' Strata
+Cloud Manager. This class inherits from `BaseObject` and provides methods for creating, retrieving, updating, and deleting
+EDLs of various types including IP, Domain, URL, IMSI, and IMEI lists with configurable update intervals.
+
+## Core Methods
+
+| Method     | Description                | Parameters                                    | Return Type                            |
+|------------|----------------------------|-----------------------------------------------|----------------------------------------|
+| `create()` | Creates a new EDL         | `data: Dict[str, Any]`                        | `ExternalDynamicListsResponseModel`    |
+| `get()`    | Retrieves an EDL by ID    | `edl_id: str`                                 | `ExternalDynamicListsResponseModel`    |
+| `update()` | Updates an existing EDL   | `edl: ExternalDynamicListsUpdateModel`       | `ExternalDynamicListsResponseModel`    |
+| `delete()` | Deletes an EDL            | `edl_id: str`                                 | `None`                                 |
+| `list()`   | Lists EDLs with filtering | `folder: str`, `**filters`                    | `List[ExternalDynamicListsResponseModel]` |
+| `fetch()`  | Gets EDL by name          | `name: str`, `folder: str`                    | `ExternalDynamicListsResponseModel`    |
+
+## EDL Model Attributes
+
+| Attribute           | Type         | Required     | Description                                 |
+|--------------------|--------------|--------------|---------------------------------------------|
+| `name`             | str          | Yes          | Name of EDL (max 63 chars)                  |
+| `id`               | UUID         | Yes*         | Unique identifier (*response only)          |
+| `type`             | TypeUnion    | Yes          | EDL type configuration                      |
+| `url`              | str          | Yes          | Source URL for EDL content                  |
+| `description`      | str          | No           | Description (max 255 chars)                 |
+| `exception_list`   | List[str]    | No           | List of exceptions                          |
+| `auth`             | AuthModel    | No           | Authentication credentials                   |
+| `recurring`        | RecurringUnion| Yes          | Update schedule configuration               |
+| `folder`           | str          | Yes**        | Folder location (**one container required)  |
+| `snippet`          | str          | Yes**        | Snippet location (**one container required) |
+| `device`           | str          | Yes**        | Device location (**one container required)  |
+
+## Exceptions
+
+| Exception                    | HTTP Code | Description                    |
+|------------------------------|-----------|--------------------------------|
+| `InvalidObjectError`         | 400       | Invalid EDL data or format     |
+| `MissingQueryParameterError` | 400       | Missing required parameters    |
+| `NameNotUniqueError`         | 409       | EDL name already exists        |
+| `ObjectNotPresentError`      | 404       | EDL not found                  |
+| `ReferenceNotZeroError`      | 409       | EDL still referenced           |
+| `AuthenticationError`        | 401       | Authentication failed          |
+| `ServerError`                | 500       | Internal server error          |
+
+## Basic Configuration
+
+<div class="termy">
+
+<!-- termynal -->
+```python
+from scm.client import Scm
+from scm.config.objects import ExternalDynamicLists
+
+# Initialize client
+client = Scm(
+    client_id="your_client_id",
+    client_secret="your_client_secret",
+    tsg_id="your_tsg_id"
+)
+
+# Initialize EDL object
+edls = ExternalDynamicLists(client)
+```
+
+</div>
+
+## Usage Examples
+
+### Creating EDLs
+
+<div class="termy">
+
+<!-- termynal -->
+```python
+# IP-based EDL with daily updates
+ip_edl_config = {
+    "name": "malicious-ips",
+    "folder": "Texas",
+    "type": {
+        "ip": {
+            "url": "https://threatfeeds.example.com/ips.txt",
+            "description": "Known malicious IPs",
+            "recurring": {
+                "daily": {
+                    "at": "03"
+                }
+            },
+            "auth": {
+                "username": "user123",
+                "password": "pass123"
+            }
+        }
+    }
+}
+
+# Create IP EDL
+ip_edl = edls.create(ip_edl_config)
+
+# Domain-based EDL with hourly updates
+domain_edl_config = {
+    "name": "blocked-domains",
+    "folder": "Texas",
+    "type": {
+        "domain": {
+            "url": "https://threatfeeds.example.com/domains.txt",
+            "description": "Blocked domains list",
+            "recurring": {
+                "hourly": {}
+            },
+            "expand_domain": True
+        }
+    }
+}
+
+# Create domain EDL
+domain_edl = edls.create(domain_edl_config)
+```
+
+</div>
+
+### Retrieving EDLs
+
+<div class="termy">
+
+<!-- termynal -->
+```python
+# Fetch by name and folder
+edl = edls.fetch(name="malicious-ips", folder="Texas")
+print(f"Found EDL: {edl.name}")
+
+# Get by ID
+edl_by_id = edls.get(edl.id)
+print(f"Retrieved EDL: {edl_by_id.name}")
+```
+
+</div>
+
+### Updating EDLs
+
+<div class="termy">
+
+<!-- termynal -->
+```python
+# Fetch existing EDL
+existing_edl = edls.fetch(name="malicious-ips", folder="Texas")
+
+# Update attributes
+existing_edl.description = "Updated malicious IP list"
+existing_edl.type.ip.recurring = {
+    "five_minute": {}
+}
+
+# Perform update
+updated_edl = edls.update(existing_edl)
+```
+
+</div>
+
+### Listing EDLs
+
+<div class="termy">
+
+<!-- termynal -->
+```python
+# List with direct filter parameters
+filtered_edls = edls.list(
+    folder='Texas',
+    types=['ip', 'domain']
+)
+
+# Process results
+for edl in filtered_edls:
+    print(f"Name: {edl.name}")
+    if hasattr(edl.type, 'ip'):
+        print(f"Type: IP, URL: {edl.type.ip.url}")
+    elif hasattr(edl.type, 'domain'):
+        print(f"Type: Domain, URL: {edl.type.domain.url}")
+
+# Define filter parameters as dictionary
+list_params = {
+    "folder": "Texas",
+    "types": ["url"]
+}
+
+# List with filters as kwargs
+filtered_edls = edls.list(**list_params)
+```
+
+</div>
+
+### Deleting EDLs
+
+<div class="termy">
+
+<!-- termynal -->
+```python
+# Delete by ID
+edl_id = "123e4567-e89b-12d3-a456-426655440000"
+edls.delete(edl_id)
+```
+
+</div>
+
+## Managing Configuration Changes
+
+### Performing Commits
+
+<div class="termy">
+
+<!-- termynal -->
+```python
+# Prepare commit parameters
+commit_params = {
+    "folders": ["Texas"],
+    "description": "Updated EDL configurations",
+    "sync": True,
+    "timeout": 300  # 5 minute timeout
+}
+
+# Commit the changes
+result = edls.commit(**commit_params)
+
+print(f"Commit job ID: {result.job_id}")
+```
+
+</div>
+
+### Monitoring Jobs
+
+<div class="termy">
+
+<!-- termynal -->
+```python
+# Get status of specific job
+job_status = edls.get_job_status(result.job_id)
+print(f"Job status: {job_status.data[0].status_str}")
+
+# List recent jobs
+recent_jobs = edls.list_jobs(limit=10)
+for job in recent_jobs.data:
+    print(f"Job {job.id}: {job.type_str} - {job.status_str}")
+```
+
+</div>
+
+## Error Handling
+
+<div class="termy">
+
+<!-- termynal -->
+```python
+from scm.exceptions import (
+    InvalidObjectError,
+    MissingQueryParameterError,
+    NameNotUniqueError,
+    ObjectNotPresentError,
+    ReferenceNotZeroError
+)
+
+try:
+    # Create EDL configuration
+    edl_config = {
+        "name": "test-edl",
+        "folder": "Texas",
+        "type": {
+            "ip": {
+                "url": "https://example.com/ips.txt",
+                "description": "Test IP list",
+                "recurring": {
+                    "daily": {
+                        "at": "03"
+                    }
+                }
+            }
+        }
+    }
+
+    # Create the EDL
+    new_edl = edls.create(edl_config)
+
+    # Commit changes
+    result = edls.commit(
+        folders=["Texas"],
+        description="Added test EDL",
+        sync=True
+    )
+
+    # Check job status
+    status = edls.get_job_status(result.job_id)
+
+except InvalidObjectError as e:
+    print(f"Invalid EDL data: {e.message}")
+except NameNotUniqueError as e:
+    print(f"EDL name already exists: {e.message}")
+except ObjectNotPresentError as e:
+    print(f"EDL not found: {e.message}")
+except ReferenceNotZeroError as e:
+    print(f"EDL still in use: {e.message}")
+except MissingQueryParameterError as e:
+    print(f"Missing parameter: {e.message}")
+```
+
+</div>
+
+## Best Practices
+
+1. **EDL Configuration**
+    - Use descriptive names
+    - Set appropriate update intervals
+    - Configure authentication when needed
+    - Validate source URLs
+    - Monitor update status
+
+2. **Container Management**
+    - Always specify exactly one container
+    - Use consistent container names
+    - Validate container existence
+    - Group related EDLs
+
+3. **Update Scheduling**
+    - Choose appropriate intervals
+    - Consider source update frequency
+    - Stagger updates for multiple EDLs
+    - Monitor update success
+    - Handle failures gracefully
+
+4. **Performance**
+    - Use appropriate pagination
+    - Cache frequently accessed EDLs
+    - Monitor EDL sizes
+    - Consider update impact
+    - Implement retry logic
+
+5. **Security**
+    - Validate source URLs
+    - Use HTTPS where possible
+    - Secure credentials
+    - Monitor for malicious content
+    - Regular audits
+
+## Full Script Examples
+
+Refer to
+the [external_dynamic_lists.py example](https://github.com/cdot65/pan-scm-sdk/blob/main/examples/scm/config/objects/external_dynamic_lists.py).
+
+## Related Models
+
+- [ExternalDynamicListsCreateModel](../../models/objects/external_dynamic_lists_models.md#Overview)
+- [ExternalDynamicListsUpdateModel](../../models/objects/external_dynamic_lists_models.md#Overview)
+- [ExternalDynamicListsResponseModel](../../models/objects/external_dynamic_lists_models.md#Overview)

docs/sdk/config/objects/index.md

@@ -36,6 +36,10 @@ Manage application filters definitions, including their characteristics and asso
 
 Manage application group definitions, including their characteristics and associated members.
 
+### [External Dynamic Lists](external_dynamic_lists.md)
+
+Manage EDLs.
+
 ### [Service](service.md)
 
 Manage service definitions, including their characteristics and associated protocols / ports.