Implementation:OpenHands OpenHands CommonRoomSync
| Knowledge Sources | |
|---|---|
| Domains | Data_Sync, Analytics |
| Last Updated | 2026-02-11 21:00 GMT |
Overview
Standalone sync script that exports user engagement metrics from OpenHands conversations to the Common Room community analytics platform.
Description
The common_room_sync module queries recent conversations from the database, fetches user details from Keycloak in batches, and registers both users and their conversation activity in Common Room via its REST API. It implements exponential backoff retry logic, rate limiting (2 requests/second), and comprehensive error tracking with custom exception classes (DatabaseError, CommonRoomAPIError, KeycloakClientError).
Usage
Run this script as a periodic background job (e.g., via cron) to synchronize user engagement data. It processes conversations created within the last N minutes (default 60) and syncs them to Common Room.
Code Reference
Source Location
- Repository: OpenHands
- File: enterprise/sync/common_room_sync.py
- Lines: 1-562
Signature
def get_recent_conversations(minutes: int = 60) -> List[Dict[str, Any]]: ...
async def get_users_from_keycloak(user_ids: Set[str]) -> Dict[str, Dict[str, Any]]: ...
async def register_user_in_common_room(
user_data: Dict, api_key: str
) -> bool: ...
async def register_conversation_activity(
user_id: str, activity: Dict
) -> bool: ...
def retry_with_backoff(func, *args, **kwargs) -> Any: ...
async def retry_with_backoff_async(func, *args, **kwargs) -> Any: ...
Import
# Standalone script, not typically imported
# Run directly: python enterprise/sync/common_room_sync.py
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| minutes | int | No | Lookback window in minutes (default 60) |
| COMMON_ROOM_API_KEY | env var | Yes | API key for Common Room |
| KEYCLOAK_SERVER_URL | env var | Yes | Keycloak server URL |
Outputs
| Name | Type | Description |
|---|---|---|
| get_recent_conversations() | List[Dict] | Conversations created within the lookback window |
| register_user_in_common_room() | bool | Success/failure of user registration |
| register_conversation_activity() | bool | Success/failure of activity registration |
Usage Examples
# Run as standalone script
# python enterprise/sync/common_room_sync.py
# Or import individual functions
from enterprise.sync.common_room_sync import get_recent_conversations
# Fetch conversations from last 30 minutes
conversations = get_recent_conversations(minutes=30)