Integrations

Databricks Risk Intelligence

How ML-scored risk signals flow from Databricks into the canvas, Risk Intelligence panel, and FlowGuide context.

What it does

EasyFlow's Databricks integration connects a Databricks SQL warehouse to the operational risk layer. ML scoring jobs in Databricks write structured risk signals into a Delta table. EasyFlow reads those signals hourly and surfaces them as live risk badges on canvas nodes, colored edge overlays on affected flow paths, a Risk Intelligence panel per tenant, and high-signal context for FlowGuide.

✦When Databricks is not configured, EasyFlow falls back to a local heuristic scorer that uses the same operational data already in the app. There is no broken state.

Architecture

The integration has four components.

Component	What it does
Databricks ML notebook	Hourly job that scores inventory, orders, suppliers, and shipments and writes results to easyflow.risk_signal_feed
lib/databricks.ts	SQL Statement API client — PAT auth, execute statement, async polling
lib/databricks-risk-cache.ts	In-process TTL cache (2h) that holds scored rows between ingest calls
/api/integrations/databricks/ingest	POST endpoint — pulls risk_signal_feed from Databricks and warms the cache
lib/canvas-risk.ts	Maps signals to canvas node types and propagates risk along affected edges

Data flows like this:

text

Operational data (ERP / events)
   ↓
Databricks ML scoring notebook (hourly)
   ↓
easyflow.risk_signal_feed (Delta table)
   ↓
POST /api/integrations/databricks/ingest
   ↓
In-process risk cache (2h TTL)
   ↓
Canvas nodes  ·  Edge overlay  ·  Risk Intelligence panel  ·  FlowGuide

The risk_signal_feed table

All risk signals share a common schema. Your Databricks ML jobs write rows here; EasyFlow reads them.

sql

CREATE TABLE IF NOT EXISTS easyflow.risk_signal_feed (
  tenant             STRING    NOT NULL,  -- EasyFlow tenant slug
  entity_type        STRING    NOT NULL,  -- inventory_sku | order | supplier | shipment
  entity_id          STRING    NOT NULL,
  entity_label       STRING,
  signal_type        STRING    NOT NULL,  -- stockout_risk | order_slip_risk | ...
  risk_level         STRING    NOT NULL,  -- low | medium | high | critical
  risk_score         DOUBLE    NOT NULL,  -- 0–99
  summary            STRING,
  recommended_action STRING,
  predicted_impact   STRING,
  metric_coverage    STRING,
  metric_fill_rate   STRING,
  metric_lead_time   STRING,
  computed_at        TIMESTAMP NOT NULL
)
USING DELTA
PARTITIONED BY (tenant);

ℹThe full DDL is in docs/databricks/risk_signal_feed.sql. A synthetic data notebook for demos is in docs/databricks/easyflow_risk_scorer.py — it generates realistic scored rows for all five EasyFlow tenants and can be scheduled hourly.

Five risk features

Feature	entity_type	What Databricks scores	What EasyFlow shows
Inventory risk forecasting	inventory_sku	Stockout risk, days of coverage, replenishment urgency	Risk badge on raw_material / inventory_control nodes, stockout summary in risk panel
Supplier delay / SLA scoring	supplier	Lead-time variability, fill rate, delay history, region instability	Risk badge on supplier nodes, delay probability in risk panel
Order / shipment delay prediction	order / shipment	Open orders likely to miss SLA, shipment exception risk	Risk badge on procurement / dispatch nodes, at-risk order count in risk panel
Operations KPI layer	overview	Warehouse utilisation, on-time delivery, approval backlog	KPI context in risk panel and FlowGuide answers
AI-ready risk table for FlowGuide	all	Daily or hourly scored table with top operational risks and explanation factors	FlowGuide uses this as high-signal context instead of raw operational tables

Configuration

Add three environment variables to apps/web/.env.local:

env

DATABRICKS_HOST=https://dbc-xxxxxxxx-xxxx.cloud.databricks.com
DATABRICKS_TOKEN=dapi...
DATABRICKS_WAREHOUSE_ID=abc123def456

# Optional — defaults shown
DATABRICKS_CATALOG=hive_metastore
DATABRICKS_SCHEMA=easyflow

✦Go to Integrations → Databricks in the app to check config status and run a live test connection. The Test connection button runs SELECT 1 against your SQL warehouse.

Ingest endpoint

Call this endpoint to pull the latest risk signals from Databricks into EasyFlow. In production, schedule it with a Vercel Cron or n8n trigger to run every hour.

bash

# Pull all tenants
curl -X POST https://your-easyflow.com/api/integrations/databricks/ingest

# Pull a specific tenant only
curl -X POST https://your-easyflow.com/api/integrations/databricks/ingest?tenant=acme-retail

Response field	What it means
ok	true if the pull succeeded
rowsIngested	Number of risk signal rows pulled from Databricks
tenantsUpdated	List of tenant slugs whose cache was updated

Canvas overlay

Once the cache is warm, the workflow canvas reads risk signals automatically and overlays them on the relevant nodes and edges.

Databricks entity_type	Canvas node type affected
supplier	Supplier nodes
inventory_sku	Raw Material + Inventory Control nodes
order	Procurement nodes
shipment	Dispatch nodes
overview	Warehouse nodes

Critical risk — red border glow, pulsing Databricks pill, inline summary strip
High risk — orange border glow, pulsing risk badge
Medium risk — yellow badge, no border glow
Affected edges — re-colored red / orange / yellow with ⚠ warning label, animated stroke
Canvas refreshes risk signals every 5 minutes automatically

FlowGuide context

FlowGuide (the AI assistant) automatically uses the latest Databricks risk signals as high-signal context when answering questions. You can ask:

Which SKUs are likely to stock out this week?
Which supplier is most likely to cause a disruption next?
Which orders are likely to slip their SLA?
What are the top operational risks right now?

ℹWhen Databricks data is present, FlowGuide answers are grounded in ML-scored risk rather than raw operational tables, which significantly improves answer quality and specificity.

Fallback behaviour

If Databricks is not configured or the ingest cache is cold, EasyFlow automatically falls back to the local heuristic risk scorer. The local scorer uses the same inventory, order, supplier, and shipment data already in the app and produces risk signals in an identical format. The canvas and FlowGuide work identically in both modes — the only difference is the data source and the provider field in the snapshot (local-heuristic vs databricks).

Webhook Reference

Managing Tenants