Description

@deepidealab/n8n-nodes-tracira

This is an n8n community node for Tracira.

Tracira monitors AI outputs from your automations, evaluates them against rules, and lets you inspect results from inside n8n workflows.

n8n is a fair-code licensed workflow automation platform.

Installation

Follow the n8n community node installation guide.

Install package name:

@deepidealab/n8n-nodes-tracira

If you already installed the legacy unscoped package n8n-nodes-tracira, uninstall it and install the scoped package instead.

For local development:

npm install
npm run verify

Operations

The package ships two nodes: Tracira (actions) and Tracira Trigger (watch decisions).

Tracira Trigger

Starts a workflow the moment an output gets a verdict or a human decision in Tracira. Pick which events to watch – the default (approved / rejected / edited) fires once a human has decided, the usual choice for approval flows; flagged, pass, error, handled (Taken Over by a Human), and taught (Taught After the Fact) events are opt-in. The handled event fires when a reviewer records that a person took the task over outside Tracira and the AI output went unused, so a waiting workflow can stop expecting an approval that will never come. The taught event fires when a reviewer teaches the AI after an output already went out (approved, rejected, or auto-passed) – it never resumes a paused workflow, it only informs subscribed automations of the new feedback. Activating the workflow registers the trigger with Tracira automatically (visible under Integrations → Connected triggers); deactivating removes it. Decision events include the AI output and its metadata, so an approval workflow can deliver the approved reply with no extra lookup. When a reviewer edits an output, output already carries their corrected version, so a workflow that maps output needs no changes: it delivers what the human approved, never the version they replaced. correctedOutput and aiOutput are there when you need to tell the cases apart. Every event also carries the output’s context IDs (sessionId, subjectId, actorId) alongside the input the AI received, so a workflow can route the result back to the right conversation, customer, or record without a follow-up lookup. Files on the output arrive in attachments, each with a role (input or output), filename, contentType, key, an absolute url, and the label the sender gave the file (null when nobody named it): pass either identifier to Download a File to get the document itself, or to an attachment with source Already in Tracira to carry it onto the next version.

The typical human-in-the-loop pattern uses two workflows: workflow A submits the output (AI step → Send an Output, After Check set to Wait for a Human to Approve), and workflow B starts with the Tracira Trigger, filters on decision = approved, and delivers the output.

Tracira (actions)

The node supports the Output resource with these operations (named to match the Tracira Make app modules):

• Send an Output: Submit an AI output to Tracira and have it checked against your rules. One After Check choice decides what happens next: Wait for the Verdict (default), Do Not Wait, Just Log It (async, fire-and-forget), or Wait for a Human to Approve (which reveals the proposed-action and callback fields). Project Name and Task Name offer a searchable dropdown of your existing Tracira projects/tasks, or accept a new name typed manually.
• Get an Output: Fetch a single output by ID.
• Search Outputs: List outputs with filters such as status, project, task, and date range.
• Set a Decision: record a human decision on an output.

– Approve – the workflow proceeds with the output as it stands.
– Edit – the output was wrong. Either send the corrected version (I Have the Corrected Version), which the workflow acts on with nothing regenerated, or a comment (Ask the AI to Redo It), which is delivered to the downstream automation so it regenerates the output and resubmits it with the Send an Output operation’s Revision Of field set to the original output ID, forming a revision chain.
– Reject – the workflow does not proceed. Always inaction: it never means “do the opposite”. To reverse a call the AI made, use Edit with the corrected value.
– Take Over – a human handled it outside Tracira. The task is done and the AI output went unused. Records no teaching signal, because taking over is not a judgement that the AI was wrong.

• Flag an Output: Flag an already-checked output for human review, for example when an end-user reports an issue with an AI response. The output re-enters the pending-review queue and notification channels fire. Reason becomes the output’s explanation – the “why this needs you” text the reviewer reads – and Flagged By sets who they are told asked for it: An End-User Reported It or This Workflow Decided. Use this for flags your rules cannot express; rule-driven flags happen automatically at check time and write their own explanation.
• Update an Output: Change the details around an output already in Tracira, for when they only exist afterwards: a ticket number your CRM assigned a second later, a category a downstream step decided, the role a file turned out to play. Metadata rows merge into what is stored (only the keys you list change; an empty value removes that key), and Existing Metadata switches to Replace It With These when the listed keys should be the only ones left. File Labels renames a file already on the output: map its key (or url) and say what it is. Update Fields fills in a Session ID, Subject ID or Actor ID that was unknown at submit time. The output, its verdict and the human decision are never editable, and changing metadata does not re-run the rules: the verdict belongs to the output that was judged.
• Upload a File: Upload a large file (PDF, image, audio) directly to Tracira storage and get back a key. Use it for files over ~3 MB that exceed the request size limit; map a binary field (e.g. data). Supports up to 32 MB. Pass the returned key to the Send an Output operation’s Input Attachments or Output Attachments field.
• Download a File: Fetch a file already stored on an output and put it in a binary field, ready for an AI node to read. Map the url or key from an entry in the trigger’s attachments array (or from Get an Output). This is what closes the redo loop for document work: when a reviewer sends a parsed PDF back with a comment, the workflow no longer holds the original file, so it downloads it from Tracira, reruns the AI with the comment, and resubmits with Revision Of set.

The Send an Output operation also has Input Attachments (files the AI received) and Output Attachments (media the AI produced: generated images, synthesized audio, rendered documents) fields, each with four sources: Upload File (send a binary field inline with the request — keep under ~3 MB), From URL (a publicly accessible HTTPS URL), Tracira Upload (a key from the Upload a File operation, for large files), or Already in Tracira (the key or url of a file stored on an earlier output). Each attachment also takes an optional Label saying what the file is (Before photo, Signed contract): fill it in whenever an output carries more than one file, so the reviewer and your later steps can tell them apart without reading file names. It comes back on the trigger’s attachments entries. The label describes the file’s role in that output, so there is one moment to set it: not on Upload a File (the file does not belong to an output yet), but here on the attachment, whichever source you picked. With Already in Tracira it carries over from the output the file came from, like the filename, so fill it in only to change it; afterwards, use Update an Output. Already in Tracira is how a revision keeps the document it was judged on without uploading it a second time. The file is copied into the new output rather than shared with the old one, so deleting the earlier output never strips the file off the newer; each copy counts against your storage quota. AI Output accepts plain text or JSON (with JSON, data-field rules can target individual fields), and is required unless an Output Attachment carries a media-only output or a Proposed Action is supplied (action-only logs).

Setting After Check to Wait for a Human to Approve reveals the Action Name, Action Summary, Action Parameters (JSON), Callback URL, and Callback Events fields. Use them when your AI decides to run something with side effects (issue a refund, delete a record). Action Name and Action Summary are both required here: they are what the reviewer approves or rejects, so the summary must be a plain-language sentence describing exactly what will happen. Action Parameters (JSON) is optional and can be gated by data-field rules via paths like action.params.amount.

This choice holds the output in the review queue whatever your rules conclude. That distinction matters: an action describes what is being reviewed, while the rules answer is this wrong? In a workspace with no rule matching that project and task an output evaluates as pass, so without this the action would run unreviewed. Rules still run and their verdict is still recorded; they just no longer decide whether a person is asked. Set a Callback URL so the workflow resumes automatically after approval, or leave it blank and poll with the Tracira Trigger. You can also submit an action with no AI Output at all (an action-only log) when there is no message, only a step to approve.

Under Options, the Metadata field stores extra searchable context with the output (a subject line, a priority, a ticket ID). Add one row per field — a Key and a Value — instead of hand-writing JSON; empty values are dropped server-side. Metadata JSON remains for when the whole object comes from one upstream value, and the rows merge over it.

The Send an Output operation also has an optional Instructions Version field. Pass the Version returned by the Get Instructions operation (see the Instruction resource below), and the output links back to the exact instructions the AI ran with, so reviewers can open those instructions straight from the output and know which version produced it.

Instruction

The node supports the Instruction resource for hosting the AI’s instructions (its system prompt) inside Tracira, so the active version lives with the outputs it produced and a reviewer’s feedback can be turned into a new version.

• Get Instructions: Fetch the active AI instructions for a project and task. On the very first run for that project/task, the text in the optional Starter Instructions field is saved as version 1 and returned; after that the version stored in Tracira always wins and Starter Instructions is ignored. The returned Version can be passed to Send an Output‘s Instructions Version field to stamp each output with the instructions it ran under. Project Name and Task Name must match the ones used in Send an Output so the instructions and the outputs belong together.
• Update Instructions: Save a new version of the instructions and make it active. Put the full updated text in New Instructions (typically the output of an AI step that rewrote the current instructions to follow reviewer feedback). Optionally record the reviewer’s Comment (map the Comment from the Tracira Trigger, shown in the dashboard as the reason this version exists) and the Output ID the feedback came from (map the Output ID from the Trigger).

The node also supports the API resource with:

• Call: Make an arbitrary authenticated request to the Tracira API.

After Check (sync vs async)

By default After Check is Wait for the Verdict: Tracira evaluates inline and responds with the full { ok, id, status, verdict, confidenceScore, explanation } so you can branch on status or verdict in the same workflow execution. Evaluation is capped at 30 seconds.

Choose Do Not Wait, Just Log It for fire-and-forget logging: Tracira responds immediately with HTTP 202 and { ok, id, status: "pending" }, then evaluates in the background. Use this for high-volume logging where you don’t need the verdict inline. Wait for a Human to Approve also returns immediately, but holds the output in the review queue whatever the rules conclude, and (optionally) calls your Callback URL once a person decides.

Keeping this node in sync with the Tracira API

The Tracira Make custom app (make-app/ in the main repo) is the reference integration. When the Tracira API changes — new webhook fields, renamed endpoints, new status values — both the Make app and this n8n node must be updated together.

Credentials

Use the Tracira API credential.

You need a workspace webhook token from your Tracira dashboard:

1. Open Tracira.
2. Go to the integrations/token area of your workspace.
3. Copy the webhook token.
4. Paste it into the Workspace Token field in n8n.

The credential test calls GET /api/verify on Tracira and sends the token as an Authorization: Bearer header.

Compatibility

This package is being set up against the current n8n community-node tooling and Tracira API endpoints available as of March 7, 2026.

Usage

Typical pattern:

1. Run your AI step in n8n.
2. Send the model output to Tracira -> Output -> Send an Output.
3. Branch on the returned status, verdict, or confidenceScore.
4. Optionally query past outputs with Get an Output or Search Outputs.

Example workflow

An importable example workflow is available at examples/log-and-branch.workflow.json.

The example does this:

1. Starts from a manual trigger.
2. Submits an output to Tracira.
3. Branches with an If node based on the returned status.

Verification notes

This package is structured to align with n8n’s verification guidance:

• Built with the n8n-node toolchain.
• No runtime dependencies in package.json.
• No access to environment variables or file system from node code.
• MIT licensed.
• Published from GitHub Actions with npm provenance configured in .github/workflows/publish.yml.
• The published package is scanned with @n8n/scan-community-package after npm publication.

Maintainer release instructions are documented in PUBLISHING.md.

How n8n verification handles versions

The verified listing on n8n Cloud is pinned to one npm version with a tarball checksum – it does not follow npm’s latest automatically. Per n8n’s verification team: they pick up new npm versions themselves, run a quick review, and include the update in their next release cycle (or reach out with feedback). No Creator Portal resubmission is needed for updates – but the changes must be transparent in this GitHub repository (commits, tags, changelog matching the published package), otherwise they cannot verify the version update. The previously verified version stays live during review; self-hosted users installing by npm name get the latest npm version regardless. To see which version n8n currently has verified:

curl -s "https://api.n8n.io/api/community-nodes?filters%5BpackageName%5D%5B%24eq%5D=%40deepidealab%2Fn8n-nodes-tracira" | python3 -m json.tool

Look at npmVersion / nodeVersions in the response.

Checklist for adding a new node to this package

Every node class in this package must follow the conventions that got the existing nodes verified (several were explicit n8n review findings):

1. Codex, twice: an inline codex block in the node description and a .node.json file next to the node. The node field must be fully qualified (@deepidealab/n8n-nodes-tracira.), and the category must be Analytics – n8n silently drops the unsupported AI category (0.8.1 review finding).
2. Error handling: wrap HTTP failures in NodeApiError so the status code and response body survive into the n8n UI – in execute() and in trigger webhookMethods (attach/detach/checkExists). Bare re-throws were a 0.8.1 review finding; the require-node-api-error lint rule also flags bare throw error of a catch parameter even when instanceof-guarded – use throw error instanceof NodeOperationError ? error : new NodeApiError(...).
3. Icons: tracira.svg + tracira.dark.svg copied into the node’s own folder (icon paths are relative to the node file).
4. usableAsTool: set true on every node class, triggers included. Do NOT try to exempt the node-usable-as-tool rule with an eslint-disable comment: the verification scanner lints with allowInlineConfig: false, so disable comments are ignored and the package fails review (0.9.2 review finding). A trigger is never actually invoked as a tool, so the property is inert there, and the type only permits true.
5. Trigger nodes: name them Trigger / Trigger, add activationMessage and eventTriggerDescription, keep the registration id in getWorkflowStaticData('node'), and make checkExists verify against the API (Tracira auto-prunes dead subscriptions, so a stale local id must re-register).
6. Register the node in package.json → n8n.nodes (the dist/...js path) – the build does not do this for you.
7. Field naming and order: manager-friendly labels matching the Make custom app (“Input Text”, “Input Attachments”, “AI Output”, “Output Attachments”), ordered as the story of the output: project/task → what the AI received → what it produced → behaviour. Renaming a displayName is free; never rename a parameter name – that breaks existing workflows.
8. Add a default to every parameter object the scanner can see – including each mode object inside a resourceLocator’s modes array (default: '' on the list and name modes; 0.9.2 review finding).
9. Verify locally with npm run verify (lint + scanner ESLint + build; needs Node 22+). npm run scan:source alone reproduces the verification scanner’s ESLint pass against the working tree – npm run lint does NOT match it (see PUBLISHING.md). The full published-package scan runs in CI post-publish.

Releasing a new version

1. Make changes, bump package.json version, update CHANGELOG.md.
2. Commit and push to main.
3. Run gh release create vX.Y.Z --title "vX.Y.Z" --notes "..." — this triggers the GitHub Actions publish workflow automatically.
4. The workflow builds, publishes to npm with provenance, and runs the n8n package scan.

Do not publish manually from a local machine — provenance requires the GitHub Actions trusted publisher.

Resources

• n8n community nodes documentation
• Tracira
• Tracira API schema

Version history

0.18.0

Two things that were fixed at submit time are now editable afterwards. A new Update an Output operation writes metadata onto an output already in Tracira (merging by default, so only the keys you list change), fills in a Session ID, Subject ID or Actor ID that was not known yet, and relabels its files. Input Attachments and Output Attachments gained a Label field, and the trigger’s attachments entries now carry it, so an output holding three photos says which is the before and which is the after instead of leaving a reviewer to read file names. The output itself, its verdict and the human decision stay immutable, and editing metadata does not re-run the rules. Requires the Tracira API change that adds PATCH /api/logs/{id} and accepts label on attachments; against an older API the update returns 404 and labels are ignored.

0.17.0

Files can now come back out of Tracira, not just go in. The Tracira Trigger carries an attachments array on every event, each entry holding the file’s key and an absolute url. A new Download a File operation turns either into binary data, and Input Attachments / Output Attachments gained an Already in Tracira source that re-attaches a stored file by key. Together they close the redo loop for document work: when a reviewer sends a parsed PDF back with a comment, the workflow downloads the original from Tracira, reruns the AI, and resubmits with Revision Of set, without ever having held the file itself. Re-attached files are copied into the new output, so deleting an earlier output cannot strip the file off a later one. Requires the Tracira API change that serves media to a workspace token and accepts { source: "stored", key } on POST /api/logs; against an older API the download returns 401 and a stored re-attach is rejected.

0.16.1

Removed usableAsTool from the Tracira Trigger node: a webhook trigger cannot be invoked as an AI-agent tool, and declaring it polluted n8n’s tool picker. Reported by n8n’s review of 0.16.0. No behaviour change, and the Tracira action node is still usable as a tool.

0.16.0

Wait for a Human to Approve now actually waits. The choice previously sent the output asynchronously and left the rules to decide whether anyone was asked, so in a workspace with no rule matching that project and task the output passed and the workflow ran the action unreviewed, with nothing reporting an error. The operation now sends requireApproval, which queues the output for a person whatever the rules conclude; the rules still run and their verdict is still recorded. Action Name and Action Summary are now required within that choice, since an approval request with neither gave the reviewer nothing to judge. Requires the Tracira API change that accepts requireApproval on POST /api/logs; against an older API the field is ignored and the previous behaviour applies. Only affects steps set to Wait for a Human to Approve.

0.15.0

Flag an Output gains a Flagged By choice: An End-User Reported It or This Workflow Decided. It sets who the reviewer is told asked for the review, so a workflow that flags on its own logic no longer shows up as an end-user complaint. Workflows saved before this fall back to An End-User Reported It, the behaviour the operation always had, so no existing workflow changes.

0.14.1

Send an Output → Options → Metadata: a key/value rows field for output metadata, so you add one Key/Value row per field instead of hand-writing a JSON string (which rendered as a tall, wrapped expression box). Metadata JSON stays for when the whole object comes from one upstream value; the rows merge over it, so existing workflows are unaffected. Display/UX addition only, no change to what gets stored.

0.14.0

Renamed the Check an Output operation to Send an Output, so the display name reflects what the builder does: they send an output to Tracira, and Tracira checks it against your rules. The old name implied checking has to happen at submit time, which conflicts with the async Do Not Wait, Just Log It default. Display name only — the internal operation value stays log, so existing workflows keep working without edits. Matches the Tracira app and the Make custom app.

0.13.1

Tracira Trigger: new Taught After the Fact (taught) opt-in event. It fires when a reviewer teaches the AI after an output already went out (approved, rejected, or auto-passed); it never resumes a paused workflow, it only informs subscribed automations of the new feedback. The event was already emitted by Tracira but could not be selected here.

0.13.0

Breaking: the Send an Output operation replaces the Wait for Verdict toggle and the Options → Proposed Action / Callback URL / Callback Events fields with a single After Check choice: Wait for the Verdict, Do Not Wait, Just Log It, or Wait for a Human to Approve. The approval choice reveals Action Name, Action Summary, Action Parameters (JSON), Callback URL, and Callback Events as top-level fields. Existing Log steps that set Wait for Verdict or the old action/callback options must be reconfigured. AI Output now accepts JSON (data-field rules can target individual fields) and can be omitted entirely for action-only logs.

0.5.0

Wait for Verdict is now on by default and promoted to a top-level field on the Log operation — the node waits for the evaluation result so you can branch on it immediately. Turn it off for fire-and-forget logging (async, HTTP 202). Behavior change: existing Log steps that relied on the previous async default will now wait for the verdict.

0.4.0

Add the Flag operation to the Log resource — flag an evaluated log for human review when an end-user reports an issue, matching the Make custom app.

0.3.1

Add Sync mode and Callback Events options to the Log operation, matching the Make custom app.

0.3.0

Rename terminology to match Tracira API: Execution→Log, Flow→Project, Check→Task. API paths updated from /executions to /logs. Breaking change — existing workflows must update the resource value and field names.

0.2.1

Bring the n8n node surface back in line with the Make app by adding Set Decision and Make API Call, and make the decision endpoint token-authenticated for automation clients.

0.2.0

Move the package to the @deepidealab npm scope so the node is published under the business organization instead of a personal npm account.

0.1.8

Add codex categories and search aliases to improve Tracira discoverability in the editor node picker.

0.1.7

Remove the invalid Developer Tools node category so Tracira remains visible in the editor on self-hosted n8n.

0.1.6

Replace newer declarative node features with a plain execute-style implementation for broader self-hosted n8n compatibility.

0.1.5

Reduce node-description metadata to older-safe fields for self-hosted n8n compatibility.

0.1.4

Use a current npm CLI in the publish workflow to satisfy npm trusted publishing requirements.

0.1.3

Force GitHub Actions to publish via npm trusted publishing instead of any inherited token environment.

0.1.2

Allow GitHub Actions trusted publishing while continuing to block accidental local publishes.

0.1.1

First GitHub Actions release with npm provenance and trusted publishing.

0.1.0

Initial Tracira node setup with execution logging and read operations.