Package Information
Documentation
@trustportal/n8n-nodes-trustportal
An n8n community node for TrustPortal.
TrustPortal is a human-in-the-loop automation platform: business users submit forms in a portal, and
those submissions become queue items that robots and workflows act on. This node lets an n8n
workflow read and write that queue.
The node talks to a TrustPortal Agent — the same on-premise component Blue Prism, UiPath and
Power Automate already use — and the agent talks to TrustPortal. You need a TrustPortal instance and
a running agent; this package on its own is not enough.
Installation · Credentials · Operations ·
Development
Installation
The package is published on npm as@trustportal/n8n-nodes-trustportal,
under the trustportal npm organisation. Which route applies depends on where n8n runs:
| n8n | Route | Status |
|---|---|---|
| Self-hosted | From npm, in the n8n UI | Available. No server or container access needed. |
| n8n Cloud | From npm, as a verified node | Not yet: needs verification, which requires publishing from GitHub Actions with a provenance statement. |
| Self-hosted, no access to npm | From a tarball | Available. Fallback for air-gapped installs or a build that is not on npm. |
Pick the version that matches your agent. Node versions follow agent versions: agent 2.6.3 →@trustportal/n8n-nodes-trustportal@2.6.3. Install takes the latest version unless you type one,
and a newer node can offer form controls an older agent does not know.
The GitHub Actions and verification work described under
What CI produces, and what it cannot is a prerequisite for
n8n Cloud only. A self-hosted customer never needs it: n8n Cloud turns off unverified community
packages, self-hosted n8n allows them by default.
From npm (self-hosted): in n8n open Settings → Community nodes, choose Install, and type@trustportal/n8n-nodes-trustportal (or @trustportal/n8n-nodes-trustportal@<agent version>). n8n downloads it from the npm registry at run
time — no restart, no file to copy. Only an Owner or Admin can install community nodes. Your instance
needs N8N_COMMUNITY_PACKAGES_ENABLED=true, which is the default, and no Enterprise licence is
required — community nodes work on the free self-hosted edition. See n8n's
community nodes installation guide.
From npm (n8n Cloud): only once the node has been verified by n8n. Until then it does not appear
on n8n Cloud at all — unverified community nodes require self-hosting.
From a tarball, the fallback when n8n cannot reach npm or the build is not published. TheN8N CI job produces it (trustportal-n8n-nodes-trustportal-<version>.tgz): install it into the directory n8n
scans for community nodes, then restart n8n.
mkdir -p ~/.n8n/nodes
cd ~/.n8n/nodes
npm install /path/to/trustportal-n8n-nodes-trustportal-<version>.tgz --omit=dev
If n8n runs in Docker, copy the tarball in first and run the same commands inside the container —
the worked example is under Trying it in a local n8n.
Either way, the node then appears in the node panel as TrustPortal, and asks for a
TrustPortal Agent API credential.
Two operational notes:
- Hosting the package in your own registry is not a free-edition option. Pointing
N8N_COMMUNITY_PACKAGES_REGISTRYanywhere other than the public npm registry requires an
Enterprise licence. - A node installed from the GUI disappears on redeploy unless the n8n data directory (
.n8n) is
on a persistent volume, orN8N_REINSTALL_MISSING_PACKAGES=trueis set — it defaults tofalse.
This matters on Kubernetes and anywhere else containers are recreated routinely.
Credentials
The node uses one credential, TrustPortal Agent API, which you fill in once and every TrustPortal
node reuses:
| Field | What to put in it |
|---|---|
| Agent Base URL | Where the agent is listening. The default, http://127.0.0.1:31999, is right when n8n runs on the same machine as the agent. When it runs anywhere else — another container, another host — use the full URL. |
| Token (Not Required Yet) | Leave it empty. It is sent as a bearer token, but the agent does not check it yet — the field is here so that turning on authentication later is a value you type, not a new release. |
| Timeout (Seconds) | How long to wait for the agent before failing; 30 by default. It bounds every operation, the trigger's calls and the credential test, so an agent host that silently drops packets fails in seconds instead of leaving the execution hanging. A timeout set in a node's own Request Options still wins. |
Use Test on the credential to confirm n8n can reach the agent. It calls the agent's health
endpoint and tells you straight away if the URL is wrong or the agent is down.
The agent does not authenticate incoming requests. Anything that can reach its port can create
forms, message users, read, copy and delete queue items and register webhook subscriptions as the
agent's robot; the credential's token is not checked. The address it listens on is not set by the
agent itself but by its configuration in TrustPortal (the agent's API address and port), and the
Docker image is normally configured to listen on0.0.0.0:31999so that other containers can
reach it. So:
- On a single host, configure the agent to listen on
127.0.0.1and run n8n on that host.- In Docker, do not publish the agent's port (
-p), and keep it on a network that only n8n joins.- Never expose it beyond that until inbound authentication exists.
Callback hosts for the TrustPortal Trigger are allow-listed separately, so a subscription cannot
point the agent at an arbitrary host.
Operations
Ten resources, 75 operations. Each resource follows the same shape the agent exposes: a Create
Payload operation that builds the object, a Send that submits it, and get / update / delete by ID.
| Resource | Operations | Notes |
|---|---|---|
| Queue Item | 11 | Adds search by conditions, copy, get next, reply with form, reply with page, and delete by conditions. Search returns one n8n item per queue item. |
| Form Control | 23 | One operation per control type — text field, dropdown, table, attachment, and so on. |
| Message | 6 | Adds get many. |
| Action | 5 | |
| File | 5 | |
| Form | 5 | |
| Form Container | 5 | Accordions and tabs. |
| Menu Item | 5 | Entries in the portal's navigation bar that open a form or a page. |
| Page | 5 | |
| Tile | 5 | Tiles that open a form or a page, create a queue item, or follow a link. |
Four Queue Item operations — get by ID, delete by ID, reply with form, reply with page — take an
optional Secure Key, sent as the X-Secure-Key header. It is only needed when Enforce Secure Key
is on for that queue item.
Users, Virtual Roles, Transient Users and Access Tokens are deliberately not exposed.
Development
Requires Node.js 22 LTS. Node 25 is not supported: n8n's toolchain builds a native module that does
not compile against it.
npm install
npm run dev # runs n8n with this node, rebuilding as you edit
npm run lint
npm run build
Trying it in a local n8n
npm run dev is the quickest loop while writing code. To check the packaged node the way a customer
receives it, install the tarball into a throwaway n8n container:
# 1. Build and pack. Produces trustportal-n8n-nodes-trustportal-<version>.tgz.
npm install
npm run build
npm pack
# 2. Start n8n on http://localhost:5678
docker volume create tp-n8n-data
docker run -d --name tp-n8n -p 5678:5678 \
-e N8N_SECURE_COOKIE=false \
-e N8N_COMMUNITY_PACKAGES_ENABLED=true \
-e N8N_RUNNERS_ENABLED=true \
-v tp-n8n-data:/home/node/.n8n \
docker.n8n.io/n8nio/n8n
# 3. Install the tarball where n8n looks for community nodes
docker cp trustportal-n8n-nodes-trustportal-*.tgz tp-n8n:/tmp/
docker exec tp-n8n sh -c \
'mkdir -p /home/node/.n8n/nodes && cd /home/node/.n8n/nodes && npm install /tmp/trustportal-n8n-nodes-trustportal-*.tgz --omit=dev'
# 4. Restart so n8n picks it up
docker restart tp-n8n
Open http://localhost:5678, create the owner account n8n asks for, then add a TrustPortal node to
a workflow. It appears in the node panel under its own name, and asks for a TrustPortal Agent API
credential.
To confirm from the command line that n8n really loaded it, without clicking through the editor:
curl -s -c cookie.txt -X POST http://localhost:5678/rest/owner/setup \
-H 'Content-Type: application/json' \
-d '{"email":"admin@example.com","firstName":"A","lastName":"B","password":"ChangeMe2026"}'
curl -s -b cookie.txt http://localhost:5678/types/nodes.json | grep -o '@trustportal/n8n-nodes-trustportal[^"]*'
Reaching an agent from inside the container.
127.0.0.1inside the n8n container is the
container itself, not your machine. When the agent runs on your host, set the credential's Agent
Base URL tohttp://host.docker.internal:31999. The127.0.0.1default is for n8n installed
directly on the agent's host.
Tear down with docker rm -f tp-n8n && docker volume rm tp-n8n-data.
What CI produces, and what it cannot
The N8N job in .gitlab-ci.yml lints, builds and runs npm pack. Its artifact is the tarball,
because that is both what npm install <file> takes for a manual install and, byte for byte, whatnpm publish would upload.
It deliberately does not publish. n8n requires community nodes to be published through GitHub Actions
with a provenance attestation — a signature minted by GitHub's OIDC infrastructure during the publish
itself, which no other runner can produce. .github/workflows/publish.yml in this directory is that
workflow, waiting on the decision about where the package is published from.
Until then, releases are published by hand, without provenance (enough for self-hosted, not for
verification), by a member of the trustportal npm organisation: download the N8N job artifact
from the release tag's pipeline, then
npm publish ./trustportal-n8n-nodes-trustportal-<version>.tgz --access public
Check first that the tarball's version matches the agent release. npm never accepts the same version
twice.
The full route to a published, verified node — what goes on GitHub, how npm is wired to it, and the
submission checklist — is written up indocs/n8n-community-node-publishing.md in the agent-service repository.
Field naming
The agent's contract spells its JSON keys with spaces — "Queue Name", "Form Fields JSON" — which
it inherits from Blue Prism's data-item naming. Those strings appear as routing.send.property
values and are not display labels. Do not rewrite them to camelCase; the agent will stop
recognising the request.