Declarative Configuration Example
Relevant source files
The following files were used as context for generating this wiki page:
The Declarative Configuration Example demonstrates a high-level, simplified approach to integrating with Oracle WMS Cloud. This pattern focuses on massive code reduction by utilizing a declarative API catalog and type-safe settings to manage entity discovery, data retrieval, and specialized warehouse operations like LPN (License Plate Number) creation.
This architecture leverages the FlextOracleWmsApi catalog and FlextOracleWmsSettings to provide a consistent interface for developers, abstracting away the underlying REST complexities into a structured, model-driven workflow.
Sources: examples/tests/test_declarative_example.py:1-10, src/flext_oracle_wms/README.md:52-60
Architecture and Components
The declarative approach relies on a central client that consumes validated settings and maps them to an internal catalog of predefined API endpoints.
Core Components
- FlextOracleWmsSettings: A Pydantic-based configuration model that validates connection parameters such as
base_url,api_version, and authentication credentials. - FlextOracleWmsUtilitiesClient (Client): The primary executor for declarative commands. It manages the lifecycle of the connection (
start()/stop()) and provides methods likediscover_entities()andget_entity_data(). - FlextOracleWmsApi Catalog: A collection of
FLEXT_ORACLE_WMS_APISthat defines the method, path, and category for each Oracle WMS endpoint.
The following diagram illustrates the lifecycle of a declarative client session:
Configuration Management
Configuration is handled through FlextOracleWmsSettings, which supports environment-driven setup and validation. This ensures that all required parameters are present before the client attempts a connection.
Configuration Parameters
| Parameter | Type | Description |
|---|---|---|
base_url | String | The root URL of the Oracle WMS Cloud instance. |
username | String | Authentication username. |
password | String | Authentication password. |
api_version | String | LGF API version (e.g., "LGF_V10"). |
timeout | Integer | Request timeout in seconds. |
max_retries | Integer | Number of retry attempts for failed requests. |
verify_ssl | Boolean | Whether to verify SSL certificates. |
Sources: examples/tests/test_declarative_example.py:82-90, examples/02_configuration.py:100-112
Environment Loading Logic
The implementation typically uses a utility function to parse .env files, extracting specific keys like ORACLE_WMS_BASE_URL and ORACLE_WMS_USERNAME to populate the settings model.
Sources: examples/tests/test_declarative_example.py:31-60
Entity Operations
The declarative client provides high-level methods to interact with standard Oracle WMS entities such as company, facility, and item.
Entity Discovery and Querying
The client uses the discover_entities() method to fetch all available WMS entities. Data retrieval is then performed via get_entity_data(), which supports filtering and pagination.
Specialized Functionality
Beyond generic queries, the declarative client supports specific business operations:
- LPN Management: Creating License Plate Numbers via
create_lpn(lpn_nbr, qty). - Tracking Updates: Updating OBLPN tracking numbers via
update_oblpn_tracking_number(oblpn_id, tracking_number).
Sources: examples/tests/test_declarative_example.py:125-135, src/flext_oracle_wms/_utilities/client.py:126-130, src/flext_oracle_wms/_utilities/client.py:220-227
Error Handling Patterns
The declarative system uses the FlextResult pattern (referred to as r) for railway-oriented programming. Instead of traditional exception catching for business logic, methods return a Result object that indicates success or failure.
| Method | Expected Failure Scenario | Source Reference |
|---|---|---|
call_api | Unknown API name provided | test_unknown_api_call |
get_entity_data | Invalid entity name (e.g., "xyz") | test_invalid_entity_name |
start | Invalid credentials or unreachable URL | showcase_1_client_initialization |
Sources: tests/unit/test_declarative.py:190-205, examples/03_complete_functionality_showcase.py:77-85
Conclusion
The Declarative Configuration Example provides a robust template for building Oracle WMS integrations. By centralizing API definitions in a catalog and enforcing strict configuration validation, the library ensures that complex warehouse operations are reduced to simple, type-safe method calls. This approach significantly lowers the barrier for developers to interact with the 320+ entities available within the Oracle WMS ecosystem.
Sources: examples/tests/test_declarative_example.py:4-7, src/flext_oracle_wms/README.md:120-130