Connect outcome sources

A support agent’s outcomes live in a helpdesk (Connect your helpdesk). Every other agent’s outcomes live somewhere else: a coding agent’s in GitHub, an ops agent’s in Jira or Linear, a sales agent’s in HubSpot or Salesforce, and a back-office agent’s often only in your data warehouse. These connectors pull those facts on a schedule and turn them into the universal task outcomes — task_succeeded, reworked, human_intervention, time_to_outcome — that the Business KPIs read.

At a glance

Before you save: field mapping and a five-record preview

Every connector form shows How provider fields become outcomes: which field on the provider’s record becomes which outcome kind, and the rule applied. Below it, Preview 5 records fetches up to five records with the settings you typed and shows exactly what each one maps to — the record, its correlation key, and every outcome it produces.

Nothing is saved by a preview — not the connector, not the credential, not an outcome. The credential you typed is used for that one fetch only. When you edit a saved connector, the preview uses the stored credential unless you type a new one. A stored credential is only ever sent to the base URL it was saved with: to preview a saved connector against a different base URL, type the credential again.

Add a source with the API

The same steps work over the API with a company admin key (a project nk_live_… key cannot manage connectors). Preview first, then save the same body:

cat > source.json <<'JSON'
{
  "provider": "snowflake",
  "name": "Claims outcomes",
  "baseUrl": "https://acme-analytics.snowflakecomputing.com",
  "credential": "<programmatic access token>",
  "options": {
    "warehouse": "ANALYTICS_WH",
    "role": "ANALYTICS_READER",
    "correlationType": "external",
    "cursorColumn": "updated_at",
    "query": "SELECT claim_id AS correlation_key, 'task_succeeded' AS kind, status = 'APPROVED' AS value, decided_at AS occurred_at, updated_at FROM claims.decisions WHERE updated_at > :since"
  },
  "enabled": true
}
JSON
 
# Map up to five records without saving anything
curl -sf -X POST "$NEENS_BASE_URL/api/outcome-inlets/preview" \
  -H "Authorization: Bearer $NEENS_API_KEY" -H "Content-Type: application/json" \
  -d @source.json
 
# Save the connector (the response never includes the credential)
curl -sf -X POST "$NEENS_BASE_URL/api/outcome-inlets" \
  -H "Authorization: Bearer $NEENS_API_KEY" -H "Content-Type: application/json" \
  -d @source.json

A GitHub source takes no credential and no baseUrl; it names the VCS installation instead:

{
  "provider": "github",
  "name": "storefront PRs",
  "options": {
    "vcsInstallationId": "<id from Settings → VCS installations>",
    "repo": "acme/storefront",
    "agentLogins": "my-agent[bot]",
    "correlationType": "external"
  },
  "enabled": true
}

GET /api/outcome-inlets/providers lists every provider’s option names, default base URL and field mapping.

A connector saved with Enabled unchecked does not sync on its schedule. The form says so, and the list shows a notice with an Enable now button. Sync now still runs a one-off pull. Each row in the list shows its Status (OK, Partial, Error or Never run), its Match counts (for example 1,240 outcomes · 97.6% matched) and an Enabled switch, with Test, Sync now, Edit and Delete.

What gets skipped, and why

A connector never guesses. Three things are counted and shown on the connector row instead:

A signal the provider does not let Neens see is left out rather than reported as “no”: human intervention is only reported when the agent’s identity is known (see each provider below), and a truncated history never becomes “no human stepped in”. Outcomes that resolve to no task yet are kept and retried, as with every outcome — see Business outcomes.

GitHub — coding agents

A coding agent’s unit of work is a pull request. The GitHub connector reads the repository’s pull requests with the GitHub App installation you already set up under Settings → VCS installations, so there is no second credential.

A revert is found two ways: a pull request created with GitHub’s Revert button (its description names the reverted PR), and a commit on the base branch whose message carries git’s standard “This reverts commit …” line. An open PR has no outcome yet; the KPI’s no-outcome timeout decides when it counts as abandoned.

span.set_attribute("neens.task.id", "https://github.com/acme/storefront/pull/4182")

Jira and Linear — ops and internal-tooling agents

For agents whose unit of work is an issue: closed, reopened, or handed to a person.

HubSpot and Salesforce — sales and GTM agents

For agents that book meetings, create opportunities or move deals forward.

A warehouse query — any agent, any system

When the outcome lives in a back-office system with no API — a claims platform, an ERP, an internal tool — but lands in your warehouse, write one query that returns one row per outcome. Neens runs it on the connector’s schedule against Snowflake or BigQuery.

Filter on :since. Neens binds the time of the last sync there as a query parameter — it is never pasted into your SQL — and only fetches rows newer than it, oldest first, a bounded number per sync. Choose updated_at as the Cursor column when rows are corrected in place, so a correction is picked up again.

A claims-processing agent, recording whether each claim went straight through, whether a person had to touch it, and whether it was reprocessed:

SELECT c.claim_id                    AS correlation_key,
       'task_succeeded'              AS kind,
       c.status = 'APPROVED'         AS value,
       c.decided_at                  AS occurred_at,
       c.updated_at                  AS updated_at
FROM   claims.decisions c
WHERE  c.decided_by_agent
  AND  c.updated_at > :since
UNION ALL
SELECT c.claim_id, 'human_intervention', c.manual_review_count > 0, c.decided_at, c.updated_at
FROM   claims.decisions c
WHERE  c.decided_by_agent
  AND  c.updated_at > :since
UNION ALL
SELECT r.claim_id, 'reworked', TRUE, r.reprocessed_at, r.reprocessed_at
FROM   claims.reprocessing r
WHERE  r.reprocessed_at > :since

Troubleshooting