Quick Start
Relevant source files
The following files were used as context for generating this wiki page:
The Quick Start guide provides the essential steps for integrating the flext-oracle-wms library into the FLEXT data integration platform. This library serves as an enterprise-grade Oracle Warehouse Management System (WMS) Cloud client, facilitating type-safe REST API operations, multi-method authentication, and automatic entity discovery.
The scope of this guide covers initial client configuration, environmental setup, and basic data operations such as querying entity records and handling execution results. It is designed to move developers from installation to a functional integration with Oracle WMS Cloud using the library's core interfaces.
Sources: README.md:5-7, src/README.md:43-45, src/flext_oracle_wms/README.md:104-106
Environment Configuration
Before initializing the client, the environment must be configured with valid Oracle WMS Cloud credentials. The library supports environment-driven settings that can be loaded via .env files or system exports.
| Variable | Description | Default/Requirement |
|---|---|---|
FLEXT_ORACLE_WMS_BASE_URL | Oracle WMS Cloud instance URL | Required |
FLEXT_ORACLE_WMS_USERNAME | Authentication username | Required |
FLEXT_ORACLE_WMS_PASSWORD | Authentication password | Required |
FLEXT_ORACLE_WMS_AUTH_METHOD | Method: basic, bearer, or api_key | basic |
FLEXT_LOG_LEVEL | Logging verbosity (e.g., debug, info) | info |
Sources: examples/README.md:73-81, examples/01_basic_usage.py:18-24, src/README.md:95-103
Client Initialization and Lifecycle
The primary entry point for the library is the FlextOracleWmsClient. Its lifecycle involves setting up configuration via FlextOracleWmsSettings, starting the client session, and ensuring proper termination with the stop() method.
Initialization Flow
This diagram illustrates the standard sequence for preparing the library for data operations.
The flow ensures that settings are validated via Pydantic before the client attempts a connection to the Oracle WMS Cloud API.
Sources: examples/03_complete_functionality_showcase.py:65-75, src/flext_oracle_wms/README.md:33-35, src/flext_oracle_wms/README.md:113-115
Code Example: Basic Setup
from flext_oracle_wms import FlextOracleWmsClient, FlextOracleWmsSettings
# 1. Configuration
settings = FlextOracleWmsSettings(
base_url="https://your-wms.oraclecloud.com",
username="your_user",
password="your_password"
)
# 2. Initialization
client = FlextOracleWmsClient(settings)
start_result = client.start()
if start_result.success:
# 3. Discovery
result = client.discover_entities()
if result.success:
print(f"Found {len(result.data)} entities")
# 4. Cleanup
client.stop()
Sources: examples/README.md:60-70, examples/01_basic_usage.py:134-148, examples/03_complete_functionality_showcase.py:228-241
Data Operations
The library provides high-level methods to interact with WMS entities. Every operation returns a Result object (following the r pattern for Railway-Oriented Programming), which encapsulates either the successful data payload or a detailed error message.
Entity Discovery
The client can dynamically introspect the Oracle WMS instance to find available entities (e.g., item, inventory, order_hdr). This is accomplished via the discover_entities() method.
Sources: src/flext_oracle_wms/README.md:120-125, examples/03_complete_functionality_showcase.py:82-85
Querying Records
Data retrieval is performed using get_entity_data(), which supports filtering, pagination (limits), and field selection.
The client handles the complexities of nested structure flattening to maintain compatibility with downstream systems like the Singer protocol.
Sources: src/flext_oracle_wms/README.md:65-67, src/README.md:38-39, examples/01_basic_usage.py:90-95
Error Handling
The library utilizes a comprehensive error hierarchy. Developers should handle both business logic failures (via the Result object) and infrastructure exceptions (via try-except blocks).
- Result Failures: Check
result.successorresult.failure. The error detail is stored inresult.error. - Exceptions: Catch
FlextOracleWmsErrorfor general library issues, or specific subclasses likeFlextOracleWmsConnectionErrorandFlextOracleWmsValidationError.
Sources: src/README.md:108-118, src/flext_oracle_wms/README.md:158-166, examples/01_basic_usage.py:114-125
Summary
The flext-oracle-wms library streamlines the integration process with Oracle WMS Cloud by providing a type-safe, declarative interface. By following the environment setup and client lifecycle patterns described here, developers can implement robust data pipelines that leverage enterprise features such as intelligent caching, connection pooling, and automatic entity discovery.
Sources: src/README.md:43-55, src/flext_oracle_wms/README.md:69-75