Bifrost Integrations

https://docs.gobifrost.com
Admin
Bifrost Integrations is an open-source automation platform designed to democratize best-in-class...
Tokens:86,476
Snippets:827
Trust Score:4.5
Update:7 months ago
Show doc for...
Tokens:
Raw
### Setup and Debug Bifrost Self-Hosted

Source: https://docs.gobifrost.com/how-to-guides/local-dev/setup

Executes setup scripts and starts the Bifrost platform with hot reloading for self-hosted development. This allows for rapid iteration on the platform's code.

```bash
./setup.sh
./debug.sh
```

--------------------------------

### Verify Bifrost CLI Installation

Source: https://docs.gobifrost.com/how-to-guides/local-dev/setup

Checks if the Bifrost CLI has been installed correctly by running the 'help' command. This command should display available Bifrost CLI commands and options.

```bash
bifrost help
```

--------------------------------

### Example: HaloPSA Integration

Source: https://docs.gobifrost.com/how-to-guides/integrations/sdk-generation

A practical example of using a generated HaloPSA SDK to list and process tickets within a workflow.

```python
from modules import halopsa

@workflow
async def sync_tickets():
    # Auto-authenticated via HaloPSA integration
    tickets = await halopsa.list_tickets()

    for ticket in tickets:
        print(f"{ticket.id}: {ticket.summary}")

    return {"synced": len(tickets)}
```

--------------------------------

### Example: Slack Webhook Integration

Source: https://docs.gobifrost.com/how-to-guides/workflows/http-endpoints

A practical example of handling a Slack slash command webhook, including logging and returning a formatted response.

```python
from bifrost import workflow
import logging

logger = logging.getLogger(__name__)

@workflow(
    endpoint_enabled=True,
    allowed_methods=["POST"],
    public_endpoint=True
)
async def slack_command(payload: dict):
    """Handle Slack slash command."""
    command = payload.get("command")
    text = payload.get("text")
    user = payload.get("user_name")

    logger.info(f"Slack command: {command} from {user}")

    return {
        "response_type": "in_channel",
        "text": f"Processing: {text}"
    }
```

--------------------------------

### Complete User Creation Workflow Example

Source: https://docs.gobifrost.com/sdk-reference/sdk/bifrost-module

Demonstrates a complete workflow for creating a user. This example utilizes decorators for data providers and workflows, accesses configuration and context, calls an external API using aiohttp, and writes results to a file. It includes error handling and logging. Dependencies include 'bifrost', 'aiohttp', 'json', and 'logging'.

```python
from bifrost import workflow, data_provider, context, config, files
import aiohttp
import json
import logging


logger = logging.getLogger(__name__)


# Data provider - no context parameter needed
@data_provider(
    name="get_departments",
    description="List departments"
)
async def get_departments():
    return [
        {"label": "Engineering", "value": "eng"},
        {"label": "Sales", "value": "sales"}
    ]


# Workflow - parameters auto-inferred from function signature
@workflow(category="User Management")
async def create_user(
    email: str,
    name: str,
    department: str = "General"
):
    """Create a new user with department assignment."""


    logger.info("Creating user", extra={
        "email": email,
        "department": department,
        "org_id": context.org_id  # Access context via proxy
    })


    try:
        # Get config values (async!)
        api_url = await config.get("api_url")
        api_key = await config.get("api_key")  # Secrets retrieved same as config


        # Call external API
        headers = {"Authorization": f"Bearer {api_key}"}
        payload = {"email": email, "name": name, "department": department}


        async with aiohttp.ClientSession() as session:
            async with session.post(
                f"{api_url}/users",
                headers=headers,
                json=payload
            ) as resp:
                if resp.status == 201:
                    user = await resp.json()


                    # Write to file (async)
                    await files.write(
                        f"users/{user['id']}.json",
                        json.dumps(user, indent=2)
                    )


                    logger.info(f"User created: {user['id']}")
                    return {"success": True, "user_id": user["id"]}
                else:
                    error = await resp.text()
                    logger.error(f"API error: {error}")
                    return {"success": False, "error": error}


    except Exception as e:
        logger.error(f"Failed: {str(e)}", exc_info=True)
        return {"success": False, "error": str(e)}
```

--------------------------------

### Example Page with Data Fetching and Conditional Rendering

Source: https://docs.gobifrost.com/core-concepts/app-builder

An example of a page component that fetches data using `useWorkflowQuery` and displays it. It includes a loading state using a `Skeleton` component and renders a list of items within a `Card` component. The page structure incorporates scrolling content management.

```tsx
import {
  useWorkflowQuery, Skeleton, Card, CardContent
} from "bifrost";


export default function HomePage() {
  const { data, isLoading } = useWorkflowQuery("ef8cf1f2-b451-47f4-aee8-336f7cb21d33");


  if (isLoading) {
    return <Skeleton className="h-32 w-full" />;
  }


  return (
    <div className="flex flex-col h-full p-6 overflow-hidden">
      <h1 className="text-2xl font-bold mb-4 shrink-0">Dashboard</h1>
      <Card className="flex-1 min-h-0 overflow-auto">
        <CardContent>
          {data?.items?.map(item => (
            <div key={item.id}>{item.name}</div>
          ))}
        </CardContent>
      </Card>
    </div>
  );
}
```

--------------------------------

### Create User Workflow Example

Source: https://docs.gobifrost.com/sdk-reference/sdk/decorators

An example of a workflow function that creates a new user in the system. It takes email, name, and an optional department as parameters and returns the created user's ID.

```python
@workflow
async def create_user(email: str, name: str, department: str = "General"):
    """Create a new user in the system."""
    user = await create_in_db(email, name, department)
    return {"user_id": user.id}
```

--------------------------------

### Install Bifrost CLI using pip

Source: https://docs.gobifrost.com/how-to-guides/local-dev/setup

Installs the Bifrost Command Line Interface (CLI) using pip, the standard Python package installer. This method is an alternative to pipx.

```bash
pip install https://your-instance.gobifrost.com/api/cli/download
```

--------------------------------

### Install Bifrost SDK using pip

Source: https://docs.gobifrost.com/sdk-reference/sdk/external-sdk

Install the Bifrost SDK directly from your Bifrost instance using pip. This command fetches the SDK package from the specified URL.

```bash
pip install https://your-bifrost-instance.com/api/sdk/download
```

```bash
pip install http://localhost:3000/api/sdk/download
```

--------------------------------

### Install Bifrost CLI using pipx

Source: https://docs.gobifrost.com/how-to-guides/local-dev/setup

Installs the Bifrost Command Line Interface (CLI) using pipx, a tool for installing Python applications in isolated environments. This is the recommended method for CLI installation.

```bash
pipx install https://your-instance.gobifrost.com/api/cli/download
```

--------------------------------

### Create User Workflow with Options Example

Source: https://docs.gobifrost.com/sdk-reference/sdk/decorators

An example of the create_user workflow configured with specific category and tags using the @workflow decorator.

```python
@workflow(
    category="User Management",
    tags=["onboarding"]
)
async def create_user(email: str, name: str):
    """Create a new user in the system."""
    return {"success": True}
```

--------------------------------

### AI Tool Workflow Example

Source: https://docs.gobifrost.com/sdk-reference/sdk/decorators

An example of a workflow function designated as an AI tool using `is_tool=True`. This function looks up customer information by email.

```python
@workflow(
    is_tool=True
)
async def lookup_customer(email: str):
    """Look up a customer by email address and return their account details."""
    customer = await get_customer(email)
    return {"name": customer.name, "account": customer.id}
```

--------------------------------

### Example Support Agent Workflow Implementation

Source: https://docs.gobifrost.com/how-to-guides/ai/agents-and-chat

Demonstrates how to define multiple tool-enabled workflows for a support agent, allowing it to look up and update tickets dynamically.

```python
from bifrost import workflow

@workflow(
    is_tool=True,
    tool_description="Look up a support ticket by ID"
)
async def get_ticket(ticket_id: str):
    return {"id": ticket_id, "status": "open", "subject": "..."}

@workflow(
    is_tool=True,
    tool_description="Update the status of a support ticket"
)
async def update_ticket(ticket_id: str, status: str, note: str = ""):
    return {"success": True}
```

--------------------------------

### Watch and Sync Bifrost Workflows

Source: https://docs.gobifrost.com/how-to-guides/local-dev/setup

Starts a process that monitors the local workspace for changes and automatically synchronizes updated files to the Bifrost platform. This is useful for continuous development.

```bash
bifrost watch
```

--------------------------------

### Utilize SDK Modules

Source: https://docs.gobifrost.com/how-to-guides/workflows/writing-workflows

Provides examples of using Bifrost SDK modules for configuration management, OAuth authentication, and file system operations. Note that config and oauth operations are asynchronous.

```python
from bifrost import config, oauth, files

async def my_workflow():
    """Example workflow using SDK modules."""
    # Configuration (async)
    api_url = await config.get("api_url", default="https://api.example.com")
    await config.set("api_url", "https://api.example.com")

    # Secrets (stored encrypted in database)
    api_key = await config.get("api_key")
    await config.set("api_key", "secret_value", is_secret=True)

    # OAuth connection (async)
    conn = await oauth.get("microsoft")
    if conn:
        access_token = conn["access_token"]

    # File operations (synchronous)
    files.write("data/output.txt", "content", location="workspace")
    content = files.read("data/output.txt", location="workspace")
```

--------------------------------

### Example: Logging Webhook Details

Source: https://docs.gobifrost.com/how-to-guides/workflows/webhook-variables

An example Bifrost workflow that logs details about a received webhook event, including headers and body.

```APIDOC
## Example: Logging Webhook Details

```python
from bifrost import context, logger


@workflow()
async def audit_webhook():
    event = context.parameters["_event"]


    logger.info(f"Received {event['type']} event from {event['source_ip']}")
    logger.info(f"Headers: {event['headers']}")
    logger.info(f"Body: {event['body']}")


    return {"event_id": event["id"], "received_at": event["received_at"]}

```
```

--------------------------------

### Gobifrost Tables Scoping Examples

Source: https://docs.gobifrost.com/sdk-reference/sdk/tables-module

Illustrates how to scope tables in Gobifrost, covering organization scope (default), application scope, and global scope. Scoping determines the visibility and accessibility of tables.

```python
# Uses execution context org
table = await tables.create("customers")
```

```python
# Scoped to an app
table = await tables.create("app_data", app="app-uuid")
results = await tables.query("app_data", app="app-uuid")
```

```python
# Tables with scope="global" are platform-wide:
```

--------------------------------

### Configure Scheduled Workflows

Source: https://docs.gobifrost.com/how-to-guides/workflows/writing-workflows

Shows how to automate workflow execution using cron expressions. The example demonstrates setting a daily schedule and hiding the workflow from manual form execution.

```python
@workflow(
    execution_mode="scheduled",
    schedule="0 9 * * *",  # Daily at 9 AM UTC
    expose_in_forms=False   # Hide from manual execution
)
async def daily_report(context: ExecutionContext):
    report = await generate_report()
    await send_report(report)
    return {"status": "sent"}
```

--------------------------------

### Example Customer Service Tool Suite

Source: https://docs.gobifrost.com/how-to-guides/workflows/ai-tools

A collection of related tools for customer service workflows, including customer lookup, order retrieval, and refund processing, demonstrating how to chain tool functionality.

```python
from bifrost import workflow

@workflow(
    is_tool=True,
    tool_description="Look up customer by email to get their account details and history"
)
async def lookup_customer(email: str):
    customer = await get_customer(email)
    return {
        "id": customer.id,
        "name": customer.name,
        "email": customer.email,
        "tier": customer.tier,
        "total_orders": len(customer.orders)
    }

@workflow(
    is_tool=True,
    tool_description="Issue a refund for an order. Requires order ID and reason."
)
async def issue_refund(order_id: str, reason: str):
    result = await process_refund(order_id, reason)
    return {"success": True, "refund_id": result.id}
```

--------------------------------

### Support Bot Workflow Example - Python

Source: https://docs.gobifrost.com/how-to-guides/ai/knowledge-bases

Demonstrates building an AI-powered support bot using Bifrost workflows. It includes functions for answering questions by retrieving knowledge and for indexing frequently asked questions.

```python
from bifrost import workflow, ai, knowledge


@workflow
async def answer_question(question: str):
    # Direct RAG approach
    response = await ai.complete(
        question,
        knowledge=["faq", "docs"],
        system="Answer based on the provided context. If unsure, say so."
    )


    return {"answer": response.content}


@workflow
async def index_faq(question: str, answer: str):
    await knowledge.store(
        f"Q: {question}\nA: {answer}",
        namespace="faq",
        key=f"faq-{hash(question)}"
    )
    return {"status": "indexed"}
```

--------------------------------

### Implement Workflow Error Handling

Source: https://docs.gobifrost.com/troubleshooting/workflow-engine

Shows how to wrap workflow logic in try-except blocks to log failures and return structured error responses.

```python
from bifrost import workflow
import logging

logger = logging.getLogger(__name__)

@workflow
async def my_workflow(email: str):
    try:
        result = await some_api_call(email)
        return {"success": True, "data": result}
    except Exception as e:
        logger.error(f"API call failed: {e}")
        return {"success": False, "error": str(e)}
```

--------------------------------

### Integrations Manifest Definition

Source: https://docs.gobifrost.com/core-concepts/manifest-structure

Example of the integrations.yaml file, defining configuration schemas and OAuth provider details for external service connections.

```yaml
integrations:
  microsoft:
    id: "c3d4e5f6-a7b8-9012-cdef-123456789012"
    config_schema:
      - key: "tenant_id"
        type: "string"
        required: true
        description: "Azure AD tenant ID"
    oauth_provider:
      provider_name: "microsoft"
      oauth_flow_type: "authorization_code"
      scopes:
        - "https://graph.microsoft.com/.default"
```

--------------------------------

### Example automation script using Bifrost SDK

Source: https://docs.gobifrost.com/sdk-reference/sdk/external-sdk

A complete Python script demonstrating an external automation task. It fetches data from an external API using `httpx` and syncs it to the Bifrost workspace using file operations and configuration settings.

```python
#!/usr/bin/env python3
"""
External automation script using Bifrost SDK.
"""
import asyncio
import json
from bifrost import files, config


async def sync_data():
    """Sync external data to Bifrost workspace."""


    # Get API endpoint from config
    api_url = await config.get("external_api_url")


    # Fetch external data (using your own HTTP client)
    import httpx
    async with httpx.AsyncClient() as client:
        response = await client.get(f"{api_url}/data")
        data = response.json()


    # Write to Bifrost workspace
    await files.write(
        "data/external-sync.json",
        json.dumps(data, indent=2)
    )


    print(f"Synced {len(data)} records to workspace")


if __name__ == "__main__":
    asyncio.run(sync_data())
```

--------------------------------

### Authentication Methods for Generated SDKs

Source: https://docs.gobifrost.com/how-to-guides/integrations/sdk-generation

Examples showing how different authentication types (OAuth, API Key, Bearer Token, Basic Auth) are abstracted by the generated SDK.

```python
# OAuth
result = await api.get_users()

# API Key
result = await api.get_users()

# Bearer Token
result = await api.get_users()

# Basic Auth
result = await api.get_users()
```

--------------------------------

### Complete Bifrost Workflow and Provider Integration

Source: https://docs.gobifrost.com/sdk-reference/sdk/decorators

A comprehensive example demonstrating the integration of a data provider and a workflow within a single module, utilizing the context proxy for system information.

```python
from bifrost import workflow, data_provider, context
import logging

logger = logging.getLogger(__name__)

@data_provider(
    name="get_departments",
    description="Get available departments"
)
async def get_departments():
    """Fetch departments from system."""
    org_id = context.org_id
    return [
        {"label": "Engineering", "value": "eng"},
        {"label": "Sales", "value": "sales"},
        {"label": "Support", "value": "support"}
    ]

@workflow(category="User Management", tags=["onboarding"])
async def create_user(
    email: str,
    name: str,
    department: str = "General",
    send_welcome: bool = True
):
    """Create a new user in the system."""
    logger.info(f"Creating user: {email}", extra={
        "org_id": context.org_id,
        "user_id": context.user_id
    })

    user_id = await create_user_in_system(email, name, department)

    if send_welcome:
        await send_welcome_email(email, name)

    logger.info(f"User created: {user_id}")
    return {"user_id": user_id, "email": email}
```

--------------------------------

### Authenticate with Bifrost Instance

Source: https://docs.gobifrost.com/how-to-guides/local-dev/setup

Logs into a Bifrost instance using the CLI. This command opens a browser for authentication and saves credentials locally for automatic refresh. Replace the URL with your actual Bifrost instance URL.

```bash
bifrost login --url https://your-instance.gobifrost.com
```

--------------------------------

### Get Bifrost client and context

Source: https://docs.gobifrost.com/sdk-reference/sdk/external-sdk

Demonstrates how to obtain a Bifrost client instance and retrieve the developer context, which includes user and organization information. This is useful for more direct control over SDK interactions.

```python
from bifrost import get_client


client = get_client()


# Get developer context
context = client.get_context()
print(f"User: {context['user']['email']}")
print(f"Org: {context['organization']['name']}")
```

--------------------------------

### Pre-fill Fields via Query Parameters

Source: https://docs.gobifrost.com/how-to-guides/forms/creating-forms

Populate form fields automatically by passing values through the URL query string, accessible via the context object.

```text
/execute/form-id?email=user@example.com&dept=IT
```

--------------------------------

### Python Workflow Registration and Type Hinting Example

Source: https://docs.gobifrost.com/core-concepts/discovery-system

This Python code snippet demonstrates how to define a Bifrost workflow using the `@workflow` decorator and how to use type hints for parameters, which are essential for them to appear correctly in forms.

```python
@workflow
async def test(name: str, count: int = 1):
    """Example workflow."""
    pass

```

--------------------------------

### Manage configuration settings with Bifrost SDK

Source: https://docs.gobifrost.com/sdk-reference/sdk/external-sdk

Shows how to perform configuration operations asynchronously using the Bifrost SDK's `config` module. This includes getting, setting, setting secrets, listing, and deleting configuration values.

```python
import asyncio
from bifrost import config


async def main():
    # Get a config value
    value = await config.get("api_url")
    print(f"API URL: {value}")


    # Set a config value
    await config.set("my_setting", "my_value")


    # Set a secret (encrypted)
    await config.set("api_key", "secret123", is_secret=True)


    # List all config
    all_config = await config.list()
    print(all_config)


    # Delete a config
    await config.delete("old_setting")


asyncio.run(main())
```

--------------------------------

### Fetch User Context Workflow

Source: https://docs.gobifrost.com/how-to-guides/forms/visibility-rules

An example of a workflow that retrieves detailed user attributes, including department and specific permissions, for use in complex visibility expressions.

```python
@workflow(name="get_user_context")
async def get_user_context(context: ExecutionContext):
	user = await get_user_details(context, context.user_id)

	return {
		"is_manager": user.role == "manager",
		"department": user.department,
		"permissions": user.permissions
	}
```

--------------------------------

### Use Bifrost SDK Features Locally

Source: https://docs.gobifrost.com/how-to-guides/local-dev/setup

Demonstrates the usage of various Bifrost SDK modules (AI, Knowledge, Config) within a local Python environment. These calls interact with the remote Bifrost API using saved credentials.

```python
from bifrost import ai, knowledge, config


# AI completions
response = await ai.complete("Summarize this ticket")


# Knowledge store
await knowledge.store("Policy content...", namespace="policies")
results = await knowledge.search("refund policy", namespace="policies")


# Configuration
api_key = await config.get("external_api_key")
```

--------------------------------

### Create a Simple Bifrost Workflow

Source: https://docs.gobifrost.com/how-to-guides/local-dev/setup

Defines a basic Bifrost workflow function named 'hello_world' using Python. The workflow takes a 'name' parameter and returns a greeting message along with the organization ID from the context.

```python
from bifrost import workflow, context


@workflow
async def hello_world(name: str):
    """A simple example workflow."""
    return {"message": f"Hello, {name}!", "org": context.org_id}
```

--------------------------------

### Error Handling for Missing Secrets in Bifrost

Source: https://docs.gobifrost.com/how-to-guides/integrations/secrets-management

This example demonstrates how to gracefully handle cases where a required secret might be missing. It uses a try-except block to catch `KeyError` when calling `config.get` and provides a user-friendly error message.

```python
@workflow(name="safe_api_call")
async def safe_api_call(context: ExecutionContext):
    try:
        api_key = await config.get("api_key")
    except KeyError:
        return {
            "success": False,
            "error": "API key not configured",
            "action": "Add 'api_key' to Configuration in Settings"
        }


    # Use api_key...
    return {"success": True}
```

--------------------------------

### Clone Bifrost Repository

Source: https://docs.gobifrost.com/how-to-guides/local-dev/setup

Clones the Bifrost API repository from GitHub to contribute to the platform's development. This is part of the setup for self-hosted development.

```bash
git clone https://github.com/jackmusick/bifrost-api.git
cd bifrost-api
```

--------------------------------

### Create Hello World Workflow (Python)

Source: https://docs.gobifrost.com/getting-started/first-workflow

Defines a simple asynchronous workflow function named 'hello_world' using the Bifrost decorator. It accepts a 'name' parameter, logs an informational message, and returns a personalized greeting along with the input name. The decorator automatically infers workflow name, description, and parameters from the function signature and docstring.

```python
from bifrost import workflow
import logging


logger = logging.getLogger(__name__)


@workflow(category="Examples")
async def hello_world(name: str):
    """A simple greeting workflow."""
    logger.info(f"Generating greeting for {name}")
    greeting = f"Hello, {name}! Welcome to Bifrost."
    return {"greeting": greeting, "name": name}
```

--------------------------------

### GET /executions

Source: https://docs.gobifrost.com/sdk-reference/sdk/bifrost-module

Endpoints for retrieving workflow execution history and status.

```APIDOC
## GET /executions

### Description
Lists workflow executions with optional filtering by status or date.

### Method
GET

### Endpoint
/executions

### Query Parameters
- **workflow_name** (str) - Optional - Filter by workflow
- **status** (str) - Optional - Filter by status (e.g., Failed)
- **limit** (int) - Optional - Number of results to return

### Response
#### Success Response (200)
- **list[WorkflowExecution]** (array) - List of execution objects
```

--------------------------------

### Multi-Tenant Pattern for Integrations in Python

Source: https://docs.gobifrost.com/how-to-guides/integrations/creating-integrations

Illustrates the multi-tenant pattern in Bifrost, where a single integration can be used across multiple organizations by leveraging `integration.entity_id` for tenant-specific data.

```python
# Each org gets their own tenant automatically
integration = await integrations.get("HaloPSA")
tenant_id = integration.entity_id  # Org-specific
```

--------------------------------

### GET /tables/list

Source: https://docs.gobifrost.com/sdk-reference/sdk/tables-module

Retrieves a list of all tables available within the current scope.

```APIDOC
## GET tables.list()

### Description
List all tables in the current scope.

### Method
GET

### Parameters
#### Query Parameters
- **scope** (str) - Optional - None=context org, "global"=global, UUID=specific org
- **app** (str) - Optional - Filter by application UUID

### Response
#### Success Response (200)
- **list** (array) - List of TableInfo objects.

#### Response Example
[
  { "id": "uuid-1", "name": "customers" },
  { "id": "uuid-2", "name": "app_settings" }
]
```

--------------------------------

### Reset Environment

Source: https://docs.gobifrost.com/troubleshooting/workflow-engine

Performs a clean reset of the Bifrost environment by removing volumes and restarting services.

```bash
docker compose down -v
docker compose up
```

--------------------------------

### Display Context-Based Instructions

Source: https://docs.gobifrost.com/how-to-guides/forms/html-content

Conditionally renders instructional UI elements based on specific field selections made within the form.

```jsx
{
    context.field.request_type === "urgent" && (
        <div className="p-4 bg-red-50 border border-red-200 rounded-lg">
            <p className="text-red-900 font-semibold">⚠️ Important</p>
            <p className="text-sm text-red-800 mt-1">
                Urgent requests require manager approval before submission.
            </p>
        </div>
    );
}
```

--------------------------------

### Debug API Logs

Source: https://docs.gobifrost.com/troubleshooting/workflow-engine

Commands to inspect Docker container logs for errors or import failures during runtime.

```bash
docker compose logs api | grep -i error
docker compose logs api | grep -i import
```

--------------------------------

### MCP Workflow for App Creation

Source: https://docs.gobifrost.com/sdk-reference/app-builder/code-apps

This section outlines the sequence of MCP (Meta-Content Platform) tools used to build and publish an application. It details the steps from initial app metadata creation to content updates and final publishing, emphasizing the workflow for integrating with the platform.

```plaintext
1. create_app (name, slug)
2. list_workflows → get IDs
3. replace_content → _layout.tsx
4. replace_content → pages/index.tsx
5. Preview at /apps/{slug}
6. publish_app (when user requests)
```

--------------------------------

### GET /api/content/search

Source: https://docs.gobifrost.com/how-to-guides/ai/agents-and-chat

Performs a regex-based search across workspace files to facilitate precision code editing.

```APIDOC
## GET /api/content/search

### Description
Searches through project files using regex patterns to locate specific code segments or entities.

### Method
GET

### Endpoint
/api/content/search

### Parameters
#### Query Parameters
- **query** (string) - Required - The regex pattern to search for.
- **entity_type** (string) - Optional - Filter by app_file, workflow, or module.

### Request Example
GET /api/content/search?query=def+get_customer&entity_type=workflow

### Response
#### Success Response (200)
- **results** (array) - List of matching files and line numbers.

#### Response Example
{
  "results": [
    {
      "file": "workflows/customer.py",
      "line": 12,
      "context": "async def get_customer(email: str):"
    }
  ]
}
```

--------------------------------

### Create User with License - Python

Source: https://docs.gobifrost.com/how-to-guides/workflows/writing-workflows

Demonstrates creating a user and assigning a license in a chained operation. It logs the progress of each step and returns the user ID and assigned license SKU. This function relies on `create_user` and `assign_license` helper functions.

```python
async def create_user_with_license(context: ExecutionContext, email: str, sku: str):
    # Step 1
    logger.info("Creating user...")
    user = await create_user(email)


    # Step 2
    logger.info("Assigning license...")
    await assign_license(user.id, sku)


    return {"user_id": user.id, "license": sku}
```

--------------------------------

### Forms Manifest Definition

Source: https://docs.gobifrost.com/core-concepts/manifest-structure

Example of the forms.yaml file, which registers form entities and defines their associated access control roles.

```yaml
forms:
  Create User:
    id: "b8c9d0e1-f2a3-4567-1234-567890123457"
    path: "forms/b8c9d0e1-f2a3-4567-1234-567890123457.form.yaml"
    roles:
      - "c9d0e1f2-a3b4-5678-2345-678901234568"
    access_level: "role_based"
```

--------------------------------

### Access Execution Context

Source: https://docs.gobifrost.com/sdk-reference/sdk/bifrost-module

Demonstrates how to use the context proxy to retrieve metadata about the current user, organization, and execution without passing parameters.

```python
from bifrost import context

@workflow
async def my_workflow(name: str):
    org_id = context.org_id
    user_email = context.email
    is_admin = context.is_platform_admin
```

--------------------------------

### Workflows Manifest Definition

Source: https://docs.gobifrost.com/core-concepts/manifest-structure

Example of the workflows.yaml file structure, which registers workflow functions, data providers, and their associated metadata.

```yaml
workflows:
  create_user:
    id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    path: "create_user.py"
    function_name: "create_user"
    type: "workflow"
    category: "User Management"
    tags:
      - onboarding
    endpoint_enabled: false
    timeout_seconds: 1800
  get_departments:
    id: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
    path: "data_providers/departments.py"
    function_name: "get_departments"
    type: "data_provider"
```

--------------------------------

### Configure Workflow Timeouts and Parallelism

Source: https://docs.gobifrost.com/troubleshooting/workflow-engine

Techniques for managing long-running tasks by increasing timeout thresholds and utilizing asyncio.gather for parallel execution.

```python
@workflow(timeout_seconds=1800)
async def long_running_task():
    pass

import asyncio

@workflow
async def import_users(users: list):
    tasks = [create_user(user) for user in users]
    await asyncio.gather(*tasks)
```

--------------------------------

### Utilize Generated Python SDK

Source: https://docs.gobifrost.com/core-concepts/integrations

Demonstrates using an auto-generated Python client that handles authentication automatically based on the configured integration.

```python
# Generated SDK auto-authenticates via integration
from modules import example_api

result = await example_api.list_resources()  # Auth handled automatically
```

--------------------------------

### Define Integration Configuration Schema

Source: https://docs.gobifrost.com/core-concepts/integrations

Provides an example of the JSON-based schema structure used to define required and optional configuration fields for an integration.

```json
[
    {"key": "base_url", "type": "string", "required": True},
    {"key": "api_key", "type": "secret", "required": True},
    {"key": "timeout", "type": "int", "required": False}
]
```

--------------------------------

### Events Manifest Definition

Source: https://docs.gobifrost.com/core-concepts/manifest-structure

Example of the events.yaml file, which configures event sources like webhooks and schedules, including their workflow subscriptions.

```yaml
events:
  daily_sync:
    id: "d4e5f6a7-b8c9-0123-def0-123456789013"
    source_type: "schedule"
    cron_expression: "0 6 * * *"
    timezone: "America/New_York"
    schedule_enabled: true
    subscriptions:
      - id: "e5f6a7b8-c9d0-1234-ef01-234567890124"
        workflow_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        is_active: true
  halopsa_tickets:
    id: "f6a7b8c9-d0e1-2345-f012-345678901235"
    source_type: "webhook"
    adapter_name: "halopsa"
    subscriptions:
      - id: "a7b8c9d0-e1f2-3456-0123-456789012346"
        workflow_id: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
        event_type: "ticket.created"
        input_mapping:
          ticket_id: "$.id"
```

--------------------------------

### Define Data Providers

Source: https://docs.gobifrost.com/troubleshooting/workflow-engine

Configures data providers for UI dropdowns. The function must return a list of dictionaries with 'label' and 'value' keys.

```python
from bifrost import data_provider

@data_provider(name="get_departments", description="List departments")
async def get_departments():
    return [
        {"label": "Engineering", "value": "eng"},
        {"label": "Sales", "value": "sales"}
    ]
```

--------------------------------

### Handle Errors and Logging

Source: https://docs.gobifrost.com/how-to-guides/workflows/writing-workflows

Demonstrates how the execution engine handles exceptions and how to use Python's logging module to provide visibility into workflow progress.

```python
import logging
from bifrost import workflow

logger = logging.getLogger(__name__)

@workflow
async def process_data(items: list):
    """Process a list of data items."""
    logger.debug("Starting detailed processing...")
    logger.info(f"Processing {len(items)} items...")
    logger.warning("Item 5 failed, continuing...")
    logger.error("Critical failure detected")
```

--------------------------------

### Get Integration Configuration

Source: https://docs.gobifrost.com/sdk-reference/sdk/integrations-module

Retrieves integration details including OAuth tokens and configuration values. It supports scoping by organization or platform-level defaults.

```python
async def get(
    name: str,
    scope: str | None = None,
) -> IntegrationData | None

# Example usage:
integration = await integrations.get("Microsoft_Graph")
if integration:
    token = integration.oauth.access_token
    tenant_id = integration.config.get("tenant_id")
```

--------------------------------

### Render Personalized Welcome Message

Source: https://docs.gobifrost.com/how-to-guides/forms/startup-workflows

An HTML snippet using React-like syntax to display personalized customer information fetched from the workflow context.

```html
<div className="p-6 bg-blue-50 rounded-lg border border-blue-200 mb-4">
  <h2 className="font-bold text-xl mb-2">
    Hi {context.workflow.customer_name}! 👋
  </h2>
  <p className="text-gray-700">
    Thank you for purchasing {context.workflow.product_name}.
    We'd love to hear about your experience!
  </p>
</div>
```

--------------------------------

### Get All Users with Pagination

Source: https://docs.gobifrost.com/how-to-guides/integrations/microsoft-graph

Retrieves all users from the system, handling pagination for large datasets. Returns a list of users and their count.

```APIDOC
## GET /users

### Description
Retrieves all users from the system, handling pagination for large datasets.

### Method
GET

### Endpoint
https://graph.microsoft.com/v1.0/users

### Query Parameters
- **$top** (integer) - Optional - The number of results to return per page. Defaults to 100.

### Response
#### Success Response (200)
- **users** (array) - A list of user objects.
- **count** (integer) - The total number of users retrieved.

#### Response Example
```json
{
  "users": [
    {
      "displayName": "Adele Vance",
      "mail": "AdeleV@contoso.onmicrosoft.com",
      "id": "..."
    }
  ],
  "count": 1000
}
```
```

--------------------------------

### Manage Bifrost Credentials

Source: https://docs.gobifrost.com/how-to-guides/local-dev/setup

Provides commands for managing authentication credentials for the Bifrost CLI. 'login' authenticates and saves credentials, while 'logout' clears them.

```bash
bifrost login --url https://your-instance.gobifrost.com  # Authenticate
bifrost logout                                            # Clear credentials
```

--------------------------------

### Get Model Information

Source: https://docs.gobifrost.com/sdk-reference/sdk/ai-module

Retrieves details about the currently configured LLM provider and model. This is useful for debugging and understanding the active AI configuration.

```python
async def get_model_info() -> dict[str, Any]
```

```python
info = await ai.get_model_info()
print(f"Using {info['provider']}/{info['model']}")
```

--------------------------------

### Safe Get User

Source: https://docs.gobifrost.com/how-to-guides/integrations/microsoft-graph

Safely retrieves a user by ID, handling common errors like user not found or insufficient permissions.

```APIDOC
## GET /users/{user_id}

### Description
Safely retrieves a user by their ID, with built-in error handling for common scenarios.

### Method
GET

### Endpoint
https://graph.microsoft.com/v1.0/users/{user_id}

### Parameters
#### Path Parameters
- **user_id** (string) - Required - The ID of the user to retrieve.

### Response
#### Success Response (200)
- **success** (boolean) - True if the user was found.
- **user** (object) - The user object containing user details.

#### Error Response
- **success** (boolean) - False if an error occurred.
- **error** (string) - A message describing the error (e.g., "User not found", "Insufficient permissions").
```

--------------------------------

### Infrastructure Health and Port Management

Source: https://docs.gobifrost.com/troubleshooting/workflow-engine

Commands to verify service status, check API health, view logs, and identify port conflicts for Bifrost services.

```bash
docker compose ps
curl http://localhost:3000/api/health
docker compose logs -f
lsof -i :3000
lsof -i :5432
```

--------------------------------

### Advanced Scheduled Workflow with External API

Source: https://docs.gobifrost.com/how-to-guides/workflows/scheduled-workflows

An example of a scheduled workflow that performs external HTTP requests using httpx, includes timeout configurations, and utilizes logging.

```python
from bifrost import workflow, config
import httpx
import logging

logger = logging.getLogger(__name__)

@workflow(
    schedule="0 8 * * 1-5",  # Weekdays at 8 AM UTC
    timeout_seconds=300,
    category="Reports"
)
async def send_daily_summary():
    """Send daily summary email to team."""
    logger.info("Starting daily summary")

    metrics = await gather_metrics()

    webhook_url = await config.get("slack_webhook")
    async with httpx.AsyncClient() as client:
        await client.post(webhook_url, json={
            "text": f"Daily Summary: {metrics['total_tasks']} tasks completed"
        })

    return {"sent": True, "metrics": metrics}
```

--------------------------------

### Null Safety and Optional Chaining in Gobifrost

Source: https://docs.gobifrost.com/how-to-guides/forms/visibility-rules

Illustrates how to handle potentially missing data using null checks and optional chaining in Gobifrost. This ensures robustness by preventing errors when accessing properties or calling methods on undefined or null values, and provides default values when necessary.

```javascript
// Safe check
context.workflow.department && context.workflow.department === "engineering";


// Optional chaining
context.workflow.department?.length >
    0(
        // Default value
        context.workflow.role || "user"
    ) ===
    "admin";
```

--------------------------------

### Retrieve Merged Integration Configuration

Source: https://docs.gobifrost.com/core-concepts/integrations

Demonstrates how to fetch an integration and access configuration values that have been merged from global defaults and organization-specific overrides.

```python
from bifrost import integrations

# Get merged configuration
integration = await integrations.get("HaloPSA")
base_url = integration.config.get("base_url")  # Merged from defaults + org
tenant_id = integration.entity_id               # Org-specific
```

--------------------------------

### Conditional Visibility and Dynamic Content

Source: https://docs.gobifrost.com/how-to-guides/forms/context-field-references

Examples of using context properties to control field visibility and render dynamic HTML content within the form builder.

```javascript
// Visibility expressions
context.field.is_manager === true;
context.field.department === "engineering";
context.workflow.is_admin === true;
context.query.customer_id !== null;

// HTML content rendering
<div className="p-4 bg-blue-50 rounded-lg">
  <p>Email: {context.field.email}</p>
  <p>Department: {context.field.department}</p>
</div>;

{context.workflow.is_premium && (
  <div className="p-4 bg-gold-50 rounded-lg">
    <p>Premium features enabled</p>
  </div>
)}
```

--------------------------------

### Integrate External APIs in Workflows

Source: https://docs.gobifrost.com/core-concepts/integrations

Shows how to build a workflow that retrieves an integration, extracts OAuth tokens and configuration, and performs an authenticated HTTP request using httpx.

```python
from bifrost import workflow, integrations
import httpx

@workflow
async def sync_data():
    # Get integration with merged config and OAuth
    integration = await integrations.get("ExternalAPI")

    if not integration:
        return {"error": "Integration not configured"}

    # Use OAuth token
    headers = {}
    if integration.oauth:
        headers["Authorization"] = f"Bearer {integration.oauth.access_token}"

    # Use config values
    base_url = integration.config.get("base_url")

    async with httpx.AsyncClient() as client:
        response = await client.get(f"{base_url}/data", headers=headers)
        return response.json()
```

--------------------------------

### Implement Dynamic Data Providers

Source: https://docs.gobifrost.com/how-to-guides/workflows/writing-workflows

Explains how to create a data provider to populate dropdowns and how to inject these values into a workflow using the @param decorator.

```python
from bifrost import data_provider

@data_provider(
    name="get_departments",
    description="List departments"
)
async def get_departments():
    return [
        {"label": "Engineering", "value": "eng"},
        {"label": "Sales", "value": "sales"}
    ]

@workflow
@param("department", data_provider="get_departments")
async def assign_user(department: str, user_email: str):
    """Assign user to department."""
    return {"assigned_to": department}
```
Tokens:
Raw