Skip to content

Framework Components

BeaPro is organized into focused modules, each responsible for a specific aspect of the automation lifecycle.

bot.py: Main Orchestrator

The entry point of the automation. It coordinates the full execution flow:

  1. Calls initialize() to set up the environment
  2. Iterates through data source items
  3. Calls process_item(item) for each item
  4. Handles exceptions automatically
  5. Calls finalize() to clean up and report results

You generally do not need to modify bot.py: your automation logic goes in framework/process.py.

/process.py: Automation Logic

This is where you add your automation steps.

The process_item(item) function is called once per item in your data source. Access item fields using dictionary keys:

def process_item(item):
    name = item['name']
    email = item['email']
    # ... your automation steps here

/state.py: State Management

Manages the shared execution state used across all modules:

  • Success and error counters
  • Current item being processed
  • Bot instances (WebBot, DesktopBot)
  • Interruption checking
  • Task status computation (SUCCESS, FAILED, PARTIALLY_COMPLETED)

The STATE object is imported wherever shared state is needed.

/exceptions.py: Exception Types

Defines three custom exception types that control how the execution loop responds to errors:

Exception When to Use Behavior
BusinessException Validation errors, invalid data, expected failures Logs the error, continues to the next item
SystemException Technical failures, application crashes Logs the error, restarts initialization, continues
InterruptException Orchestrator interruption request Logs a warning, stops execution gracefully 
from framework.exceptions import BusinessException, SystemException

if not item.get('email'):
    raise BusinessException("Missing email address")

if not app_is_running():
    raise SystemException("Target application is not responding")

/datasources.py: Data Sources

Provides two ready-to-use data source classes and a base class for custom implementations.

CSVSource

Reads items from a CSV file, returning each row as a dictionary keyed by column header.

  • Generates a result CSV with STATUS, MESSAGE, and TIMESTAMP columns
  • Reports success and failure per item automatically

DatapoolSource

Fetches items from a BotCity Datapool in the Orchestrator.

  • Reports item status back to the Orchestrator automatically
  • Supports the full Datapool lifecycle

Custom Data Sources

Extend BaseSource and implement __iter__, __next__, report_success, and report_error to connect to any database, API, or external system.

/initialize.py: Initialization

Sets up the automation environment at the start of each run and after a restart triggered by a SystemException:

  • Creates output/ and temp/ folders
  • Configures logging
  • Initializes WebBot or DesktopBot
  • Opens the target application and performs any required login steps

Customize init_webbot() to configure browser settings:

bot = WebBot()
bot.headless = False
bot.browser = Browser.CHROME # Example

/finalize.py: Finalization

Runs at the end of every execution to gracefully wrap up:

  • Closes browsers and open applications
  • Uploads result files (logs, CSVs, screenshots) to BotCity Orchestrator
  • Sends the final task status report (SUCCESS, FAILED, or PARTIALLY_COMPLETED)

/status_handling.py: Exception Handlers

Contains the handlers invoked by bot.py when each exception type occurs:

  • Logs errors with full context
  • Sends alerts to BotCity Orchestrator (ERROR for failures, WARN for interruptions)
  • Captures screenshots on errors and saves them to temp/
  • Reports success or failure back to the data source

Customize these handlers to add email notifications, external database updates, retry logic, or any business-specific alerting.

/logger.py: Logging

Configures dual logging output for every run:

  • File logs: Written to output/Log_BotCity_task-{task_id}_date-{timestamp}.log
  • Orchestrator logs: Streamed in real time to the BotCity Orchestrator Execution Log

Log entries include timestamps, module names, and function names for easy tracing and debugging.

Output Files

All output files are written to the output/ folder and automatically uploaded to BotCity Orchestrator as Result Files at the end of execution.

File Description
Log_BotCity_task-{id}_date-{ts}.log Full execution log with timestamps
CSV_BotCity_task-{id}_date-{ts}.csv Original data plus STATUS, MESSAGE, and TIMESTAMP columns if a CSV is used
temp/*.png Screenshots captured automatically on exceptions