Package Information
Documentation
@cleverflows/n8n-nodes-cleverflows
Building block for connecting n8n flows to Cleverflows without hand-built webhooks, HTTP callbacks or resume webhooks. It implements the Cleverflows automation contract (protocol v1), described in the Cleverflows help under Set up workflows and Set up agents.
| Node | What it does |
|---|---|
| Cleverflows Trigger | Receives a workflow run or an agent task, checks the auth header, outputs record/values, configValues, knowledge, connectionsByProvider, agent goal/instructions/actions/memory, and cf (callback context). |
| Cleverflows | Report Progress (agents), Complete (result), Fail, Cancel. Sets token, ids and executionId. |
| Cleverflows Wait | Review, approval of an action (agents), form (workflow runs and agents) or question (agents); parks the execution on its signed waiting URL and continues with the answer in decision (approved, revise, rejected, answered, timeout) plus feedback, editedPayload, answers. Branch with a Switch on {{ $json.decision }}. One output on purpose: older n8n versions only pass resume data to the first output. Further review rounds get <key>_2, <key>_3 … |
Forms (0.1.6)
Wait For → Form asks a person for structured answers, in workflow runs (shown under Reviews) and agent tasks (shown in the task). Cleverflows checks the definition strictly: unknown field types or properties are rejected with HTTP 400, all texts are shown as plain text, links only with http/https. Never ask for passwords or credentials in a form, use connections for that.
{
"title": "Confirm the offer",
"recipient": "customer",
"remindAfterMinutes": 1440,
"expiresInMinutes": 4320,
"fields": [
{ "key": "price_ok", "label": "Price of 1,200 EUR confirmed", "type": "boolean", "required": true },
{ "key": "topics", "label": "Topics for the newsletter", "type": "multiselect", "options": ["Spring", "Events", "Team"], "max": 2 },
{ "key": "start", "label": "Start date", "type": "date", "min": "2026-12-01" },
{ "key": "budget", "label": "Budget", "type": "number", "min": 0 },
{ "key": "brief", "label": "Briefing", "type": "file", "accept": ["application/pdf"], "maxSizeMb": 10 }
]
}
- Field types:
text,textarea,number,date(YYYY-MM-DD),select,multiselect,boolean,url,file. - Per field:
key,label,type,required,options(text or{value,label}),placeholder,help,default,min/max(number, date, number of choices),minLength/maxLength(text),accept/maxSizeMb(file, up to 25 MB; PDF, PNG, JPG, GIF, WebP, TXT, CSV, Word, Excel, PowerPoint). - Per form:
title,description,submitLabel,recipient(customer= people of the organization, default;agency= only the agency),expiresInMinutes,remindAfterMinutes, optionali18nwith translations per language (de,en,es,fr:title,description,submitLabel,fields.<key>.{label, help, placeholder, options}); everyone sees the form in their own language. - The answer continues with
decision: "answered"andanswers(one entry per field key, empty optional fields arenull; files as{ name, size, type, url }with a download link valid for 7 days). In workflow runs the form can also be declined: the flow continues withdecision: "rejected"andfeedback, and Cleverflows ends the run.
Follow-up workflow records (0.1.7)
Complete in a workflow run can hand entries to the follow-up workflow set in Cleverflows (e.g. topics from a planning run to a blog post workflow). Set Options → Records to an array like [{"table": "handoff", "values": {"topic": "…", "description": "…"}}]. The entries arrive in the input table of the follow-up workflow with status In review and need an approval there. Agents keep using Records for the tables granted to them.
Connection test (0.1.9)
- The test under Connections → Automation in Cleverflows (
{ "test": true }) is answered by the Cleverflows Trigger with 200{ "ok": true, "test": true }once the token is accepted. No execution starts. Cleverflows shows "authentication confirmed". A wrong token still gets 401.
Review deadline and reserved keys (0.1.8)
- Cleverflows Wait sends its wait time (Max Wait) along. Cleverflows closes an open review no later than that, so a review never stays open after the waiting execution is gone. Without a limit, reviews expire after 7 days by default (the same as the default Max Wait of 168 h).
- The checkpoint key
result_reviewis reserved: Cleverflows uses it for the review of finished results and does not resume the flow for it. The node refuses it before anything is sent, Cleverflows answers it with 400 (CHECKPOINT_KEY_RESERVED). - A
cancelledorfailedreport while a review is open ends the run and closes the review.
Upgrading to 0.1.5
Breaking change: Cleverflows Wait now has one output instead of four (Approved, Revise, Rejected, Timed Out). Older n8n versions (e.g. 2.9) only pass the answer to the first output, so the other branches were lost silently.
After updating, existing flows keep only the connection of the former Approved output; the connections of Revise, Rejected and Timed Out are removed. Add a Switch node after each Cleverflows Wait node, with rules on {{ $json.decision }}:
Rule (decision equals) |
Connect to what was on |
|---|---|
approved |
Approved |
revise |
Revise |
rejected |
Rejected |
timeout |
Timed Out |
answered (questions) |
Answered |
The bundled examples (examples/) already use this pattern.
Setup
- Install the package (Settings → Community Nodes, once published; until then
npm packhere andnpm install <tgz>in~/.n8n/nodes, then restart n8n). - Create the Cleverflows credential with the same auth as in Cleverflows under Connections → Automation (e.g. header
X-API-Key+ token). - Add Cleverflows Trigger, activate the flow and enter its production URL as webhook in Cleverflows (workflow settings, agent configuration, template or agency default).
- Keep the
cffield in items between trigger and the report/wait nodes, or set "Cleverflows Context" to{{ $('Cleverflows Trigger').item.json.cf }}.
Examples to import: examples/workflow-run-review.json, examples/agent-task.json, forms: examples/workflow-run-form.json, examples/agent-task-form.json.
Expressions
- Callback context when items were replaced:
{{ $('Cleverflows Trigger').item.json.cf }} - Result JSON from a previous node:
{{ $json.article }}(n8n expressions are case-sensitive)
Publishing
- First version once by hand:
npm login, thennpm publish --access publicin this folder (owner of the npm organisationcleverflows). - On npmjs.com → package settings → Trusted Publishers: GitHub Actions, repository
intrio/n8n-nodes-cleverflows, workflowpublish.yml. - Later versions: bump
version, push a tag with the same value (e.g.0.1.1);.github/workflows/publish.ymllints, tests and publishes with provenance (required by n8n).
Development
npm install
npm test # build + unit tests of the protocol logic
npm run lint # n8n community node linter (strict, n8n Cloud rules)