DOCSEARCHbyAlgolia
Submit Docs

OpenBB Workspace Backends

repository·main·Indexed 41 days ago

https://github.com/openbb-finance/backends-for-openbb

Developer resources and integration patterns for connecting custom data sources to OpenBB Workspace. Includes guides for building FastAPI backends, configuring widgets via widgets.json and templates.json, and implementing various widget types such as Markdown, Table, Chart, Form, and PDF. Features a reference backend with a decorator-based registration pattern and examples for ArcticDB and ClickHouse Cloud integrations.

Tokens
39.8K
Snippets
115
Records
153
Agent score
53%

What's inside OpenBB

  1. Overview of Databricks Connector Apps and Datasets

    main

    The Databricks Connector backend provides five sample apps, each targeting a specific dataset domain within the built-in samples catalog. No manual data loading is required as these datasets are included in every Databricks workspace.

    AppDatasetHighlights
    NYC Taxisamples.nyctaxiMetric tiles, daily line chart, hourly column chart, raw trips table
    Bakehouse Salessamples.bakehouseProduct/city revenue, grouped product filter, markdown customer reviews
    Wanderbricks Travelsamples.wanderbricksMonthly bookings, top destinations, property types, country filter
    TPC-H Supply Chainsamples.tpchYearly revenue, revenue by nation and market segment, region filter
    Databricks SQL Explorerwhole catalogSchema/table browser plus an omni SQL widget for ad-hoc read-only queries

  3. Features of the Snowflake Connector Python Example

    main

    This backend implementation demonstrates two specific widget capabilities:

    1. Table Widget: Displays all views within a specified schema. This demonstrates how to use an endpoint to dynamically populate dropdown options.
    2. Line Chart Widget: Visualizes stock close prices sourced from the public Finance & Economics dataset.

  4. Explore OpenBB Backend implementation examples

    main

    The repository is organized into two main learning paths:

    • hello-world: A minimal implementation demonstrating how to add a single widget to OpenBB Workspace. Use this to learn the fundamental concepts.
    • reference-backend: A comprehensive collection of advanced examples. This includes complex widget implementations, advanced API integrations, and established best practices and patterns for OpenBB Workspace.

  5. What is the TradingView UDF Protocol?

    main

    The Universal Data Feed (UDF) protocol is TradingView's standardized API for connecting external data providers to TradingView charting widgets. To implement a backend adapter, you must provide several key endpoints that the widget calls to discover symbols, fetch metadata, and retrieve historical price data.

    Required UDF Endpoints:
1. `/udf/config`: Supported features, resolutions, and exchanges
2. `/udf/search`: Search for available trading pairs
3. `/udf/symbols`: Detailed information about a specific symbol
4. `/udf/history`: OHLCV (Open, High, Low, Close, Volume) data
5. `/udf/time`: Current server time for synchronization

  6. How the Widget Registration Pattern works

    main

    The template uses a decorator-based approach to register widgets. By using the @register_widget decorator, you combine the UI/UX configuration with the API endpoint implementation in a single step.

    This pattern:

    • Defines the widget's appearance and behavior in the OpenBB Workspace UI.
    • Automatically registers the widget configuration in the WIDGETS registry.
    • Links the UI configuration directly to its corresponding API endpoint.
    • Maintains a single source of truth for widget definitions.
    # Conceptual usage of the decorator pattern
@register_widget
def my_widget_endpoint():
    ...

  7. Configure templates via templates.json

    main

    The templates.json file defines pre-configured layouts and widget arrangements for the OpenBB Workspace UI. Templates can include multiple widgets with specific positions, pre-configured parameters, and custom layouts.

    Note on Template Creation: Templates are typically not created via code. Instead, you should configure your widgets and layouts directly in the OpenBB Workspace interface, then right-click and select "Export Template" to generate the configuration file for your backend.

  8. Configure Widget Auto-refresh and Parameters

    main

    Widgets can manage data freshness and user inputs through specific features:

    Auto-refresh

    • refetchInterval: The time duration between automatic refreshes.
    • staleTime: The duration after which data is considered stale.
    • runButton: Provides a manual refresh option for the user.

    Parameter Management

    • Shared Parameters: Allow multiple widgets to use the same input values.
    • Dependent Parameters: Parameters that change based on the value of another parameter.
    • Grouping & Validation: Organize parameters into groups and enforce validation rules.

    To push a parameter update back to Workspace (allowing one widget to drive a synced group), refer to the iframe & HtmlViewer parameter bridge example.

  9. How auto-configuration works via widgets.json

    main

    OpenBB Workspace uses the widgets.json definition to automatically configure iframe widgets. Two key fields enable seamless integration:

    1. endpoint: Sets the initial src for the iframe.
    2. storage.mcpUrl: Specifies the MCP server URL. When the widget mounts, Workspace automatically connects to this URL, making the associated tools immediately available to the user.

    Example JSON structure:

    "portfolio_iframe": {
  "type": "iframe",
  "endpoint": "http://localhost:8501",
  "storage": {
    "mcpUrl": "http://localhost:7769/mcp"
  }
}

  10. How OpenBB Workspace Data Integrations work

    main

    An OpenBB Workspace Data Integration allows you to connect external or internal data sources to widgets within OpenBB Workspace. The integration follows a standardized structure that enables Workspace widgets to read and display your data.

    To create a valid integration, your backend must satisfy four main requirements:

    1. JSON Data Format: Data must be returned in JSON format. If your JSON is nested, you can use the dataKey variable in your widgets.json to specify the path to the relevant data.
    2. widgets.json Endpoint: You must provide an endpoint that returns a widgets.json file. This file acts as a manifest, defining widget properties like name, description, category, type, and endpoint.
    3. CORS Enabled: If you are hosting your backend locally, you must enable Cross-Origin Resource Sharing (CORS) to allow OpenBB Workspace to make requests to your server.
    4. Authentication (Optional): If your backend requires authentication, OpenBB Pro allows you to configure query parameters or headers that will be sent with every request.

  11. How to trigger iframe auto-refresh using destructiveHint

    main

    By default, MCP tools are read-only and do not trigger an iframe reload in OpenBB Workspace. To ensure the UI reflects new state after a tool call (e.g., after a portfolio rebalance), you must mark the tool as mutating by setting destructiveHint=True in the ToolAnnotations.

    Implementation Pattern:

    from mcp.types import ToolAnnotations

# Read-only tools (default behavior: no refresh)
@mcp.tool()
def get_portfolio_holdings(...): ...

# Mutating tools (triggers iframe remount after execution)
@mcp.tool(annotations=ToolAnnotations(destructiveHint=True))
def rebalance_portfolio(): ...
    from mcp.types import ToolAnnotations

# Read-only tools — no annotation needed (default: no refresh)
@mcp.tool()
def get_portfolio_holdings(...): ...

# Mutating tools — opt in to iframe refresh
@mcp.tool(annotations=ToolAnnotations(destructiveHint=True))
def rebalance_portfolio(): ...