Data Programs
A data program is a named, stored, agent-authored JS script that fetches,
joins, filters, or aggregates provider or app data, and is rendered by a
dashboard panel. It is the generic answer to "I can query this once in chat —
now make it a panel other people can see, that refreshes on its own."
There is no new credential machinery here. A data program is exactly a
run-code script (same providerFetch / providerFetchAll /
providerSearchAll / appAction / workspace* globals you already use for
ad-hoc analysis) plus two things: a stored, named identity, and a small
emit(rows, schema) contract so the result can be cached and charted. Read
provider-api first if you have not already — data programs assume you know
provider-api-catalog / provider-api-docs / provider-api-request.
When to reach for this vs. a canned action
- The common case (won/lost by pipeline, a standard date-range rollup) already
has a first-class action (
hubspot-deals, etc.) — use that.
- A one-time chat question — just query it with
run-code or
provider-api-request and answer directly. Don't save a program for
something you'll never look at again.
- A cohort needs an arbitrary property filter, an IN-search over custom
values, or a join against a second provider, and the user (or a
dashboard) will want to see it again with fresh data — that's a data
program.
Authoring workflow
- Prototype in chat first. Write the fetch/join/aggregate logic as a
normal
run-code script and confirm it returns the rows you expect.
- Wrap it to call
emit(rows, schema) exactly once at the end instead of
returning/printing the result (see contract below).
- Save it with
save-data-program:save-data-program(
name: "risk-meeting-cohort", // stable slug, unique per your account
title: "Risk Meeting — HubSpot cohort",
description: "...",
code: "<the run-code script text>",
defaultParams: { riskStatuses: ["Churn Risk"] }, // optional
refreshMode: "ttl", // "ttl" | "manual"
refreshTtlMs: 900000, // optional, floor 60000
background: false, // true for slow multi-minute joins
)
This dry-runs the code with defaultParams before persisting and
rejects the save with a structured error if it fails — a broken program is
never stored. On success it returns
{ programId, rowCount, columns, sampleRows }: use that as your proof the
program actually produces the rows you expect before telling the user it's
ready.
- Bind a dashboard panel to it. Panels reference programs through the
"program" source; the panel's sql field carries a JSON descriptor
instead of a query string:{ "programId": "dp_...", "params": { "riskStatuses": ["Churn Risk"] } }
The panel renders through the exact same chart/table components as every
other panel source — it only ever receives { rows, schema }.
- Iterate without re-saving with
preview-data-program(code, params?) —
same dry-run path, no persisted row. Use this while tuning a script before
calling save-data-program again.
- Refresh on demand with
run-data-program(programId, params?, forceRefresh?, includeRows?) — this is what the agent calls to get a
compact proof-of-result (rowCount, columns, sampleRows) without
waiting for a panel view. Pass includeRows: true only when you need the
full (capped) row set back in context.
- Read without running with
get-data-program(programId, includeRows?).
Its lastRun is the newest finished run, never one still queued, and when
that run failed, lastGoodRun holds the newest successful one.
The sandbox surface
Inside a data program you get exactly the run-code globals, plus one
addition:
providerFetch(provider, path, init?), providerFetchAll(...),
providerSearchAll(...) — the same generic provider-access helpers used for
ad-hoc analysis. See provider-api for the pagination/search option shapes.
appAction(name, params), webFetch, workspace* Resources helpers — same
as run-code.
params — a frozen global object: the params passed into this run
(defaultParams merged by the caller, or whatever was passed to
run-data-program / the panel descriptor). Read it, never mutate it.
emit(rows, schema?) — call this exactly once, at the end, with your
result. A second call throws. schema is optional —
{ name: string, type: string }[] — inferred automatically from the first
50 rows when omitted (a column is "json" if rows disagree on primitive
type, otherwise "number" / "string" / "boolean"). console.log remains
completely free for debugging; it never interferes with emit() parsing and
is captured separately as a truncated log tail on the run record.
Caps enforced on every run (not configurable per-program):
| Limit |
Value |
| Max emitted rows |
10,000 (rows beyond this are dropped, truncated: true) |
| Max emitted result size |
4 MiB (rows dropped from the end to fit; a single row over 4 MiB is a hard result_too_large failure — nothing to safely keep) |
| Max active programs per app |
200 (archive unused ones to free room) |
| Minimum refresh TTL |
60,000 ms |
| Run rows kept per (program, params) |
5 most recent (older ones are pruned automatically) |
Truncation is always honest: a partial result comes back with
truncated: true, never a silent drop.
Caching and refresh model
Every (programId, paramsHash) pair (params are canonicalized and hashed, so
equivalent param objects share a cache entry) has its own run history. What
happens on each call to runDataProgram / a panel view:
| Situation |
Behavior |
Fresh cache hit (younger than refreshTtlMs, or refreshMode: "manual" with any prior success) |
Returns cached rows instantly, cacheHit: true |
| Cache is older than the TTL |
Re-executes synchronously (panel views get a 25s budget; agent/manual calls get 120s), replacing the cache on success |
refreshMode: "manual" |
Never auto-refreshes; only forceRefresh: true (a panel's Refresh sends it) re-runs it |
| No cache yet |
Executes synchronously like a normal first fetch |
background: true program, no fresh cache |
Serves the last good run immediately with stale: true and enqueues a durable background execution (10-minute budget); the next call finalizes it if it has completed |
| Background run has just finished |
The next read finalizes it, even while older rows are fresh, and serves its rows as a fresh hit, queueing nothing until the TTL lapses or a refresh is forced; a failed one answers reads with its failure for that same window |
| Background program, execution still running, no prior success |
background_pending failure — the panel shows an explicit "running in background" error card, never a blank chart |
Execution fails (timeout, sandbox error, bad emit() shape) |
Failure result with a structured error code; if a previous successful run exists, it is attached as lastGoodRun so the panel can stale-serve instead of going blank |
Program was archived (delete-data-program) |
Explicit archived failure — panels show "This data program was archived", never a silent blank |
Use background: true only for programs that routinely take longer than the
foreground budget (multi-provider joins over large cohorts, deep pagination).
Everything else should stay foreground — it is simpler to reason about and
serves fresh data faster.
Error codes
| Code |
Meaning |
What to do |
program_not_found |
No program with that id |
Check the id via list-data-programs |
access_denied |
Caller can't see this program |
Don't leak existence; ask the owner to share it |
archived |
Program was soft-deleted |
Repoint the panel or unarchive by resaving under the same name |
timeout |
Didn't finish within the run's budget |
Reduce scope, page in fewer items, or mark background: true |
emit_missing |
Script never called emit(...) |
Add the emit(rows, schema?) call at the end |
emit_shape_invalid |
emit() args weren't (array-of-plain-objects, optional-schema-array) |
Fix the shape; check for a stray second emit() call |
result_too_large |
A single row (or the whole result) exceeds the byte cap |
Trim large string fields before emitting |
program_error |
The script threw; the message is the thrown error's, and panels show it |
Read the thrown message; guard optional provider fields |
sandbox_error |
The sandbox itself failed, not the script; panels show a fixed message |
Retry; a repeat failure is a platform problem, not the script |
run_code_unavailable |
The run-code module isn't available in this build |
Not something a program author can fix |
background_pending |
Background program has no result yet |
Wait and retry, or check lastGoodRun if present |
Every failure is a structured { code, message }, never a bare string — treat
code as the thing to branch on, message as the thing to show a human.
Security notes
- Credentials are always the viewer's, never the author's. When a shared
program's panel is viewed,
providerFetch inside it resolves auth using the
viewing user's own configured provider credentials — not the program
author's. A teammate missing a HubSpot key sees a HubSpot auth error on that
panel, not someone else's data.
- Only share programs you trust. Because execution uses the viewer's
credentials, only bind to or view a shared data program if you trust its
code — it runs with your own access, exactly like opening someone else's
extension.
- Data programs are org-internal only, never public. Unlike dashboards,
a data program can never be shared publicly — sharing is restricted to
members of your org. This is a hard invariant, not a default.
- Raw provider tokens never reach the model or the browser. The only thing
that ever leaves the sandbox is the
{ rows, schema } your emit() call
produces — the same trust boundary as every other dashboard panel source.
- The actions that execute or mutate stored code (
save-data-program,
preview-data-program, run-data-program, delete-data-program) are not
callable from the sandboxed extensions/iframe bridge — only from the agent
or the server-rendered panel path.
Worked example: Risk Meeting (HubSpot x Pylon)
This is the reference example installed by the ensure-risk-meeting-dashboard
action (templates/analytics/actions/ensure-risk-meeting-dashboard.ts), which
idempotently upserts both programs below and installs the built-in two-panel
"Risk Meeting" dashboard. It demonstrates the three capabilities a hardcoded action can't
anticipate for every customer: an arbitrary HubSpot property IN-search, a
batched multi-hop association join, and a join against a second, unrelated
provider.
risk-meeting-cohort.js — HubSpot deals in a configurable risk_status
cohort, resolved to their company domain, joined against Pylon account
sentiment by domain:
// params: { riskStatuses?: string[], enterpriseOnly?: boolean }
const DEFAULT_RISK_STATUSES = [
"On the Radar",
"Churn Risk",
"Confirmed Churn",
"No Save Attempted",
];
const riskStatuses =
Array.isArray(params.riskStatuses) && params.riskStatuses.length > 0
? params.riskStatuses
: DEFAULT_RISK_STATUSES;
const HIGH_RISK_SENTIMENTS = ["frustrated", "high_risk_detractor"];
function chunk(items, size) {
const out = [];
for (let i = 0; i < items.length; i += size)
out.push(items.slice(i, i + size));
return out;
}
async function main() {
// 1. Arbitrary property IN-search + open-close-date filter — not
// expressible through the canned hubspot-deals filters.
const dealSearch = await providerFetchAll(
"hubspot",
"/crm/v3/objects/deals/search",
{
method: "POST",
body: {
filterGroups: [
{
filters: [
{
propertyName: "risk_status",
operator: "IN",
values: riskStatuses,
},
{
propertyName: "closedate",
operator: "GT",
value: String(Date.now()),
},
],
},
],
properties: [
"dealname",
"risk_status",
"risk_summary",
"risk_category",
"hs_next_step",
"churn_notes",
"total_contract_value",
"customer_success_owner",
"dealstage",
"closedate",
],
limit: 100,
},
itemsPath: "results",
pagination: {
cursorBodyPath: "after",
nextCursorPath: "paging.next.after",
maxPages: 20,
},
},
);
const deals = dealSearch.items || [];
const dealIds = deals.map((d) => d && d.id).filter(Boolean);
// 2. Batched deal -> company association (100 per call). The raw
// association rows never leave this program.
const companyByDeal = {};
for (const batch of chunk(dealIds, 100)) {
if (batch.length === 0) continue;
const assoc = await providerFetch(
"hubspot",
"/crm/v3/associations/deals/companies/batch/read",
{ method: "POST", body: { inputs: batch.map((id) => ({ id })) } },
);
for (const r of (assoc && assoc.results) || []) {
const dealId = r && r.from && r.from.id;
const companyId =
r && Array.isArray(r.to) && r.to.length > 0 ? r.to[0].id : null;
if (dealId && companyId) companyByDeal[dealId] = companyId;
}
}
// 3. Batched company -> domain lookup.
const companyIds = Array.from(new Set(Object.values(companyByDeal))).filter(
Boolean,
);
const domainByCompany = {};
for (const batch of chunk(companyIds, 100)) {
if (batch.length === 0) continue;
const companies = await providerFetch(
"hubspot",
"/crm/v3/objects/companies/batch/read",
{
method: "POST",
body: { inputs: batch.map((id) => ({ id })), properties: ["domain"] },
},
);
for (const r of (companies && companies.results) || []) {
const domain =
r && r.properties && r.properties.domain
? String(r.properties.domain).toLowerCase()
: null;
if (r && r.id && domain) domainByCompany[r.id] = domain;
}
}
// 4. A second, unrelated provider — zero bespoke glue action required.
const pylonAccounts = await providerFetchAll("pylon", "/accounts", {
itemsPath: "data",
pagination: {
cursorParam: "cursor",
nextCursorPath: "pagination.cursor",
maxPages: 20,
},
});
const sentimentByDomain = {};
for (const account of pylonAccounts.items || []) {
if (!account) continue;
const domain =
typeof account.domain === "string" ? account.domain.toLowerCase() : null;
if (!domain) continue;
if (
params.enterpriseOnly &&
account.account_profile !== "Enterprise Active Customer"
)
continue;
if (account.general_sentiment)
sentimentByDomain[domain] = account.general_sentiment;
}
// 5. Join + emit. csm_name is computed HERE — never baked into a generic
// hubspot-deals action.
const rows = deals.map((deal) => {
const props = (deal && deal.properties) || {};
const dealId = deal && deal.id;
const companyId = dealId ? companyByDeal[dealId] : null;
const domain = companyId ? domainByCompany[companyId] : null;
const sentiment = domain ? sentimentByDomain[domain] || null : null;
return {
deal_id: dealId || null,
deal_name: props.dealname || null,
risk_status: props.risk_status || null,
risk_summary: props.risk_summary || null,
risk_category: props.risk_category || null,
next_step: props.hs_next_step || null,
churn_notes: props.churn_notes || null,
arr: Number(props.total_contract_value || 0),
csm_name: props.customer_success_owner || null,
dealstage: props.dealstage || null,
closedate: props.closedate || null,
domain: domain || null,
pylon_sentiment: sentiment,
cross_source_flag: Boolean(
domain && HIGH_RISK_SENTIMENTS.includes(sentiment),
),
};
});
emit(rows, [
{ name: "deal_id", type: "string" },
{ name: "deal_name", type: "string" },
{ name: "risk_status", type: "string" },
{ name: "risk_summary", type: "string" },
{ name: "risk_category", type: "string" },
{ name: "next_step", type: "string" },
{ name: "churn_notes", type: "string" },
{ name: "arr", type: "number" },
{ name: "csm_name", type: "string" },
{ name: "dealstage", type: "string" },
{ name: "closedate", type: "string" },
{ name: "domain", type: "string" },
{ name: "pylon_sentiment", type: "string" },
{ name: "cross_source_flag", type: "boolean" },
]);
}
await main();
risk-meeting-pylon-early-warning.js — the complementary "support signal
outrunning CRM signal" view: enterprise Pylon accounts already flagged at-risk
by sentiment that have not yet shown up in the HubSpot cohort above (a
same-shape HubSpot domain lookup, minus the Pylon domain set — see
templates/analytics/seeds/data-programs/risk-meeting-pylon-early-warning.js
for the full script). This is the third validation capability: excluding one
provider's cohort from another's, entirely inside one program.
Both programs are installed and kept up to date by
ensure-risk-meeting-dashboard — an idempotent action that upserts each
program by its stable name and installs the read-only, built-in two-panel
"Risk Meeting" dashboard (builtin-risk-meeting) whose panels use
source: "program". Installing the dashboard requires no
HubSpot/Pylon credentials up front; provider auth resolves per-viewer only
when a panel is actually rendered or run-data-program is called.
Related skills
provider-api — the catalog/docs/request/staging actions a data program's
providerFetch* calls are built on.
dashboard-management — creating and laying out the dashboard a program's
panel lives on.
cross-source-analysis — identity-stitching discipline (stable id + email,
de-duplication, provenance) for joins like the one above.
security — credential handling and access-scoping invariants this
primitive relies on.
1---2name: data-programs-23description: >-4 Save a run-code fetch/join/aggregate script as a refreshable data source panels bind to. Use when a provider-api-request or run-code analysis should become a live panel.5metadata:6 source: https://skillmd.com/skills/builderio/data-programs-27---89# Data Programs1011A **data program** is a named, stored, agent-authored JS script that fetches,12joins, filters, or aggregates provider or app data, and is rendered by a13dashboard panel. It is the generic answer to "I can query this once in chat —14now make it a panel other people can see, that refreshes on its own."1516There is no new credential machinery here. A data program is exactly a17`run-code` script (same `providerFetch` / `providerFetchAll` /18`providerSearchAll` / `appAction` / `workspace*` globals you already use for19ad-hoc analysis) plus two things: a stored, named identity, and a small20`emit(rows, schema)` contract so the result can be cached and charted. Read21`provider-api` first if you have not already — data programs assume you know22`provider-api-catalog` / `provider-api-docs` / `provider-api-request`.2324## When to reach for this vs. a canned action2526- The common case (won/lost by pipeline, a standard date-range rollup) already27 has a first-class action (`hubspot-deals`, etc.) — use that.28- A one-time chat question — just query it with `run-code` or29 `provider-api-request` and answer directly. Don't save a program for30 something you'll never look at again.31- A cohort needs an arbitrary property filter, an IN-search over custom32 values, or a join against a second provider, **and** the user (or a33 dashboard) will want to see it again with fresh data — that's a data34 program.3536## Authoring workflow37381. **Prototype in chat first.** Write the fetch/join/aggregate logic as a39 normal `run-code` script and confirm it returns the rows you expect.402. **Wrap it to call `emit(rows, schema)` exactly once** at the end instead of41 returning/printing the result (see contract below).423. **Save it** with `save-data-program`:43 ```44 save-data-program(45 name: "risk-meeting-cohort", // stable slug, unique per your account46 title: "Risk Meeting — HubSpot cohort",47 description: "...",48 code: "<the run-code script text>",49 defaultParams: { riskStatuses: ["Churn Risk"] }, // optional50 refreshMode: "ttl", // "ttl" | "manual"51 refreshTtlMs: 900000, // optional, floor 6000052 background: false, // true for slow multi-minute joins53 )54 ```55 This **dry-runs the code with `defaultParams` before persisting** and56 rejects the save with a structured error if it fails — a broken program is57 never stored. On success it returns58 `{ programId, rowCount, columns, sampleRows }`: use that as your proof the59 program actually produces the rows you expect before telling the user it's60 ready.614. **Bind a dashboard panel to it.** Panels reference programs through the62 `"program"` source; the panel's `sql` field carries a JSON descriptor63 instead of a query string:64 ```json65 { "programId": "dp_...", "params": { "riskStatuses": ["Churn Risk"] } }66 ```67 The panel renders through the exact same chart/table components as every68 other panel source — it only ever receives `{ rows, schema }`.695. **Iterate without re-saving** with `preview-data-program(code, params?)` —70 same dry-run path, no persisted row. Use this while tuning a script before71 calling `save-data-program` again.726. **Refresh on demand** with `run-data-program(programId, params?,73forceRefresh?, includeRows?)` — this is what the agent calls to get a74 compact proof-of-result (`rowCount`, `columns`, `sampleRows`) without75 waiting for a panel view. Pass `includeRows: true` only when you need the76 full (capped) row set back in context.777. **Read without running** with `get-data-program(programId, includeRows?)`.78 Its `lastRun` is the newest _finished_ run, never one still queued, and when79 that run failed, `lastGoodRun` holds the newest successful one.8081## The sandbox surface8283Inside a data program you get exactly the `run-code` globals, plus one84addition:8586- `providerFetch(provider, path, init?)`, `providerFetchAll(...)`,87 `providerSearchAll(...)` — the same generic provider-access helpers used for88 ad-hoc analysis. See `provider-api` for the pagination/search option shapes.89- `appAction(name, params)`, `webFetch`, `workspace*` Resources helpers — same90 as `run-code`.91- `params` — a **frozen** global object: the params passed into this run92 (`defaultParams` merged by the caller, or whatever was passed to93 `run-data-program` / the panel descriptor). Read it, never mutate it.94- `emit(rows, schema?)` — call this **exactly once**, at the end, with your95 result. A second call throws. `schema` is optional —96 `{ name: string, type: string }[]` — inferred automatically from the first97 50 rows when omitted (a column is `"json"` if rows disagree on primitive98 type, otherwise `"number"` / `"string"` / `"boolean"`). `console.log` remains99 completely free for debugging; it never interferes with `emit()` parsing and100 is captured separately as a truncated log tail on the run record.101102Caps enforced on every run (not configurable per-program):103104| Limit | Value |105| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |106| Max emitted rows | 10,000 (rows beyond this are dropped, `truncated: true`) |107| Max emitted result size | 4 MiB (rows dropped from the end to fit; a single row over 4 MiB is a hard `result_too_large` failure — nothing to safely keep) |108| Max active programs per app | 200 (archive unused ones to free room) |109| Minimum refresh TTL | 60,000 ms |110| Run rows kept per (program, params) | 5 most recent (older ones are pruned automatically) |111112Truncation is always honest: a partial result comes back with113`truncated: true`, never a silent drop.114115## Caching and refresh model116117Every `(programId, paramsHash)` pair (params are canonicalized and hashed, so118equivalent param objects share a cache entry) has its own run history. What119happens on each call to `runDataProgram` / a panel view:120121| Situation | Behavior |122| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |123| Fresh cache hit (younger than `refreshTtlMs`, or `refreshMode: "manual"` with any prior success) | Returns cached rows instantly, `cacheHit: true` |124| Cache is older than the TTL | Re-executes synchronously (panel views get a 25s budget; agent/manual calls get 120s), replacing the cache on success |125| `refreshMode: "manual"` | Never auto-refreshes; only `forceRefresh: true` (a panel's Refresh sends it) re-runs it |126| No cache yet | Executes synchronously like a normal first fetch |127| `background: true` program, no fresh cache | Serves the last good run immediately with `stale: true` and enqueues a durable background execution (10-minute budget); the _next_ call finalizes it if it has completed |128| Background run has just finished | The next read finalizes it, even while older rows are fresh, and serves its rows as a fresh hit, queueing nothing until the TTL lapses or a refresh is forced; a failed one answers reads with its failure for that same window |129| Background program, execution still running, no prior success | `background_pending` failure — the panel shows an explicit "running in background" error card, never a blank chart |130| Execution fails (timeout, sandbox error, bad `emit()` shape) | Failure result with a structured error code; if a previous successful run exists, it is attached as `lastGoodRun` so the panel can stale-serve instead of going blank |131| Program was archived (`delete-data-program`) | Explicit `archived` failure — panels show "This data program was archived", never a silent blank |132133Use `background: true` only for programs that routinely take longer than the134foreground budget (multi-provider joins over large cohorts, deep pagination).135Everything else should stay foreground — it is simpler to reason about and136serves fresh data faster.137138## Error codes139140| Code | Meaning | What to do |141| ---------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------- |142| `program_not_found` | No program with that id | Check the id via `list-data-programs` |143| `access_denied` | Caller can't see this program | Don't leak existence; ask the owner to share it |144| `archived` | Program was soft-deleted | Repoint the panel or unarchive by resaving under the same name |145| `timeout` | Didn't finish within the run's budget | Reduce scope, page in fewer items, or mark `background: true` |146| `emit_missing` | Script never called `emit(...)` | Add the `emit(rows, schema?)` call at the end |147| `emit_shape_invalid` | `emit()` args weren't `(array-of-plain-objects, optional-schema-array)` | Fix the shape; check for a stray second `emit()` call |148| `result_too_large` | A single row (or the whole result) exceeds the byte cap | Trim large string fields before emitting |149| `program_error` | The script threw; the message is the thrown error's, and panels show it | Read the thrown message; guard optional provider fields |150| `sandbox_error` | The sandbox itself failed, not the script; panels show a fixed message | Retry; a repeat failure is a platform problem, not the script |151| `run_code_unavailable` | The run-code module isn't available in this build | Not something a program author can fix |152| `background_pending` | Background program has no result yet | Wait and retry, or check `lastGoodRun` if present |153154Every failure is a structured `{ code, message }`, never a bare string — treat155`code` as the thing to branch on, `message` as the thing to show a human.156157## Security notes158159- **Credentials are always the viewer's, never the author's.** When a shared160 program's panel is viewed, `providerFetch` inside it resolves auth using the161 _viewing_ user's own configured provider credentials — not the program162 author's. A teammate missing a HubSpot key sees a HubSpot auth error on that163 panel, not someone else's data.164- **Only share programs you trust.** Because execution uses the viewer's165 credentials, only bind to or view a shared data program if you trust its166 code — it runs with your own access, exactly like opening someone else's167 extension.168- **Data programs are org-internal only, never public.** Unlike dashboards,169 a data program can never be shared publicly — sharing is restricted to170 members of your org. This is a hard invariant, not a default.171- Raw provider tokens never reach the model or the browser. The only thing172 that ever leaves the sandbox is the `{ rows, schema }` your `emit()` call173 produces — the same trust boundary as every other dashboard panel source.174- The actions that execute or mutate stored code (`save-data-program`,175 `preview-data-program`, `run-data-program`, `delete-data-program`) are not176 callable from the sandboxed extensions/iframe bridge — only from the agent177 or the server-rendered panel path.178179## Worked example: Risk Meeting (HubSpot x Pylon)180181This is the reference example installed by the `ensure-risk-meeting-dashboard`182action (`templates/analytics/actions/ensure-risk-meeting-dashboard.ts`), which183idempotently upserts both programs below and installs the built-in two-panel184"Risk Meeting" dashboard. It demonstrates the three capabilities a hardcoded action can't185anticipate for every customer: an arbitrary HubSpot property IN-search, a186batched multi-hop association join, and a join against a second, unrelated187provider.188189**`risk-meeting-cohort.js`** — HubSpot deals in a configurable `risk_status`190cohort, resolved to their company domain, joined against Pylon account191sentiment by domain:192193```js194// params: { riskStatuses?: string[], enterpriseOnly?: boolean }195const DEFAULT_RISK_STATUSES = [196 "On the Radar",197 "Churn Risk",198 "Confirmed Churn",199 "No Save Attempted",200];201const riskStatuses =202 Array.isArray(params.riskStatuses) && params.riskStatuses.length > 0203 ? params.riskStatuses204 : DEFAULT_RISK_STATUSES;205const HIGH_RISK_SENTIMENTS = ["frustrated", "high_risk_detractor"];206207function chunk(items, size) {208 const out = [];209 for (let i = 0; i < items.length; i += size)210 out.push(items.slice(i, i + size));211 return out;212}213214async function main() {215 // 1. Arbitrary property IN-search + open-close-date filter — not216 // expressible through the canned hubspot-deals filters.217 const dealSearch = await providerFetchAll(218 "hubspot",219 "/crm/v3/objects/deals/search",220 {221 method: "POST",222 body: {223 filterGroups: [224 {225 filters: [226 {227 propertyName: "risk_status",228 operator: "IN",229 values: riskStatuses,230 },231 {232 propertyName: "closedate",233 operator: "GT",234 value: String(Date.now()),235 },236 ],237 },238 ],239 properties: [240 "dealname",241 "risk_status",242 "risk_summary",243 "risk_category",244 "hs_next_step",245 "churn_notes",246 "total_contract_value",247 "customer_success_owner",248 "dealstage",249 "closedate",250 ],251 limit: 100,252 },253 itemsPath: "results",254 pagination: {255 cursorBodyPath: "after",256 nextCursorPath: "paging.next.after",257 maxPages: 20,258 },259 },260 );261 const deals = dealSearch.items || [];262 const dealIds = deals.map((d) => d && d.id).filter(Boolean);263264 // 2. Batched deal -> company association (100 per call). The raw265 // association rows never leave this program.266 const companyByDeal = {};267 for (const batch of chunk(dealIds, 100)) {268 if (batch.length === 0) continue;269 const assoc = await providerFetch(270 "hubspot",271 "/crm/v3/associations/deals/companies/batch/read",272 { method: "POST", body: { inputs: batch.map((id) => ({ id })) } },273 );274 for (const r of (assoc && assoc.results) || []) {275 const dealId = r && r.from && r.from.id;276 const companyId =277 r && Array.isArray(r.to) && r.to.length > 0 ? r.to[0].id : null;278 if (dealId && companyId) companyByDeal[dealId] = companyId;279 }280 }281282 // 3. Batched company -> domain lookup.283 const companyIds = Array.from(new Set(Object.values(companyByDeal))).filter(284 Boolean,285 );286 const domainByCompany = {};287 for (const batch of chunk(companyIds, 100)) {288 if (batch.length === 0) continue;289 const companies = await providerFetch(290 "hubspot",291 "/crm/v3/objects/companies/batch/read",292 {293 method: "POST",294 body: { inputs: batch.map((id) => ({ id })), properties: ["domain"] },295 },296 );297 for (const r of (companies && companies.results) || []) {298 const domain =299 r && r.properties && r.properties.domain300 ? String(r.properties.domain).toLowerCase()301 : null;302 if (r && r.id && domain) domainByCompany[r.id] = domain;303 }304 }305306 // 4. A second, unrelated provider — zero bespoke glue action required.307 const pylonAccounts = await providerFetchAll("pylon", "/accounts", {308 itemsPath: "data",309 pagination: {310 cursorParam: "cursor",311 nextCursorPath: "pagination.cursor",312 maxPages: 20,313 },314 });315 const sentimentByDomain = {};316 for (const account of pylonAccounts.items || []) {317 if (!account) continue;318 const domain =319 typeof account.domain === "string" ? account.domain.toLowerCase() : null;320 if (!domain) continue;321 if (322 params.enterpriseOnly &&323 account.account_profile !== "Enterprise Active Customer"324 )325 continue;326 if (account.general_sentiment)327 sentimentByDomain[domain] = account.general_sentiment;328 }329330 // 5. Join + emit. csm_name is computed HERE — never baked into a generic331 // hubspot-deals action.332 const rows = deals.map((deal) => {333 const props = (deal && deal.properties) || {};334 const dealId = deal && deal.id;335 const companyId = dealId ? companyByDeal[dealId] : null;336 const domain = companyId ? domainByCompany[companyId] : null;337 const sentiment = domain ? sentimentByDomain[domain] || null : null;338 return {339 deal_id: dealId || null,340 deal_name: props.dealname || null,341 risk_status: props.risk_status || null,342 risk_summary: props.risk_summary || null,343 risk_category: props.risk_category || null,344 next_step: props.hs_next_step || null,345 churn_notes: props.churn_notes || null,346 arr: Number(props.total_contract_value || 0),347 csm_name: props.customer_success_owner || null,348 dealstage: props.dealstage || null,349 closedate: props.closedate || null,350 domain: domain || null,351 pylon_sentiment: sentiment,352 cross_source_flag: Boolean(353 domain && HIGH_RISK_SENTIMENTS.includes(sentiment),354 ),355 };356 });357358 emit(rows, [359 { name: "deal_id", type: "string" },360 { name: "deal_name", type: "string" },361 { name: "risk_status", type: "string" },362 { name: "risk_summary", type: "string" },363 { name: "risk_category", type: "string" },364 { name: "next_step", type: "string" },365 { name: "churn_notes", type: "string" },366 { name: "arr", type: "number" },367 { name: "csm_name", type: "string" },368 { name: "dealstage", type: "string" },369 { name: "closedate", type: "string" },370 { name: "domain", type: "string" },371 { name: "pylon_sentiment", type: "string" },372 { name: "cross_source_flag", type: "boolean" },373 ]);374}375376await main();377```378379**`risk-meeting-pylon-early-warning.js`** — the complementary "support signal380outrunning CRM signal" view: enterprise Pylon accounts already flagged at-risk381by sentiment that have **not yet** shown up in the HubSpot cohort above (a382same-shape HubSpot domain lookup, minus the Pylon domain set — see383`templates/analytics/seeds/data-programs/risk-meeting-pylon-early-warning.js`384for the full script). This is the third validation capability: excluding one385provider's cohort from another's, entirely inside one program.386387Both programs are installed and kept up to date by388`ensure-risk-meeting-dashboard` — an idempotent action that upserts each389program by its stable `name` and installs the read-only, built-in two-panel390"Risk Meeting" dashboard (`builtin-risk-meeting`) whose panels use391`source: "program"`. Installing the dashboard requires no392HubSpot/Pylon credentials up front; provider auth resolves per-viewer only393when a panel is actually rendered or `run-data-program` is called.394395## Related skills396397- `provider-api` — the catalog/docs/request/staging actions a data program's398 `providerFetch*` calls are built on.399- `dashboard-management` — creating and laying out the dashboard a program's400 panel lives on.401- `cross-source-analysis` — identity-stitching discipline (stable id + email,402 de-duplication, provenance) for joins like the one above.403- `security` — credential handling and access-scoping invariants this404 primitive relies on.