Package Information
Documentation
@jerrytlaan/n8n-nodes-frame
Native acties en een afzonderlijke pollingtrigger voor FRAME API v1, met bestaand FRAME-artwork (rood in licht thema, wit in donker thema).
Voor self-hosted n8n. Er zijn geen runtime-dependencies buiten de door n8n geleverden8n-workflow peer. Het pakket is voor self-hosted n8n; er is geen productie-installatie uitgevoerd.
Installeren
Gebruik de meegeleverde jerrytlaan-n8n-nodes-frame-0.3.0.tgz op de server/container
waar jouw self-hosted n8n draait. Maak eerst een backup en plan een herstart.
Dit zijn instructies; de oplevering voert ze niet uit.
mkdir -p ~/.n8n/nodes
cd ~/.n8n/nodes
npm install /absoluut/pad/jerrytlaan-n8n-nodes-frame-0.3.0.tgz --omit=dev
Herstart n8n en zoek in de nodekiezer op FRAME. Bij Docker is ~/.n8n de persistente
gebruikersmap binnen de container; plaats het pakket daar of bouw het mee in je eigen image.
Gebruik de n8n-gebruiker en niet een willekeurige host-gebruikersmap.
Communitynodes moeten zijn toegestaan. n8n Cloud accepteert dit ongeverifieerde pakket niet
via dezelfde handmatige installatieroute.
Het openbare pakket installeer je via Settings → Community nodes worden geïnstalleerd met@jerrytlaan/n8n-nodes-frame@0.3.0. De broncodebundel bevat de publicatievoorbereiding.
Aansluiten
- Voeg een FRAME-node toe en selecteer of maak de credential FRAME API.
- Gebruik de zakelijke FRAME API-sleutel. Het pakket maakt zelf geen sleutel aan.
- Test de credential: dit leest uitsluitend
GET /me. - Kies bijvoorbeeld Projecten → Project aan planning overdragen, Pakwerk of Uren.
- Vul de getoonde benoemde velden in. Alleen werkelijk gestructureerde argumenten gebruiken JSON.
- Alle Onderdelen (Geavanceerd) houdt de volledige resourcecatalogus en live veldmapping toegankelijk.
De basis staat vast op https://frame.expoteam.com/api/v1. De sleutel gaat alsAuthorization: Bearer … in de header, nooit in URL of workflowparameter. Redirects staan uit.
Scopes, actorrechten, projectrechten, kolomrechten en procesregels blijven door FRAME afgedwongen.
Handelingen
| Resource/handeling | Invoer en resultaat |
|---|---|
| Account / Sleutelgegevens | Leest /me: actor, scopes en verloopgegevens |
| Schema | Alle resources, één resource of bedrijfsfunctieschema |
| Zoeken / lijst ophalen | Zoekterm en exacte filters als JSON-object; paginering via hasMore en nextOffset |
| Eén record ophalen | Alle sleutelvelden als JSON, ook bij samengestelde sleutels |
| Aanmaken | Schrijfbare velden uit het actuele schema |
| Wijzigen | Sleutel, actuele versie en alleen bewust te wijzigen velden |
| Exact zoeken of aanmaken | Bedrijven/contacten; expliciete Create If Missing, standaard uit |
| Project met bedrijf/contact klaarzetten | Projectvelden plus exacte bedrijf/contactkeuzes en optionele bronidentiteit |
| Bestaand project aan bron koppelen | Bewust beoordeeld existingProjectId en volledige bronidentiteit |
| Bedrijfsfunctie uitvoeren | Bestaande functie uit /schema/actions en alleen haar benoemde argumenten |
De aangeleverde catalogus bevat 96 resources, 866 velden en 64 bedrijfsfuncties. De 64 benoemde actieformulieren zijn gebaseerd op deze catalogus. Het actuele schema wordt vóór uitvoering opnieuw gelezen en bepaalt welke argumenten en rechten jouw sleutel kan gebruiken. Een onbekende
schemavorm stopt met een fout. De tests controleren alle catalogusdefinities met synthetische veldwaarden, zonder productiegegevens.
De bestaande FRAME Dropbox-demo blijft als tweede node beschikbaar, standaard uitsluitend als mapplan.
Deze node gebruikt bij bewust aanzetten de bestaande ingebouwde Dropbox-credential en vaste Dropbox API-host.
Alleen DEMO-projectnummers en paden onder /FRAME API Demo zijn mogelijk; ontbrekende mappen worden zonder
autorename aangemaakt en exact teruggelezen. Er zijn geen Dropbox-verzoeken uitgevoerd in deze oplevering.
Er worden geen workflows automatisch geïmporteerd of geactiveerd.
FRAME Trigger (polling)
Kies FRAME Trigger en stel het n8n-pollingschema, onderdeel en event in. Ondersteund:
nieuwe matches, gewijzigde matches of beide voor bedrijven, contacten, projecten,
projectevents, integratie-events, pakwerk-events en werkplaats-events.
De aangeleverde API biedt leesbare eventresources, maar geen gedocumenteerde webhookregistratie.
Dit is daarom polling: geen realtime webhook of garantie dat iedere tussenliggende wijziging wordt gezien.
De eerste automatische controle legt uitsluitend een nulmeting vast. Historische records starten geen workflows.
Handmatig testen toont maximaal vijf voorbeelden en verandert de opgeslagen nulmeting niet.
Volgende controles vergelijken primaire sleutels en versietokens. Ongewijzigde matches worden niet opnieuw
uitgestuurd; de opgeslagen toestand bevat gehashte sleutels en versies, geen volledige records.
De uitvoer bevat $json._frame.trigger.event (new of changed), observedAt en previousVersion.
De gewone recordvelden en $json._frame.version blijven beschikbaar voor vervolgstappen.
Exacte filters beperken de selectie. Standaard maximaal 1.000, instelbaar tot 5.000 records per volledige
controle. Bij een limiet, API-fout of ongeldige paginering stopt de controle zonder toestand bij te werken.
Na wijziging van resource, filters, eventkeuze of credential-ID volgt een nieuwe nulmeting.
Deletes worden niet uitgezonden. Een record dat de selectie verlaat en later terugkomt, telt opnieuw als
nieuwe match. Wijzigingen tussen twee controles kunnen samenvallen; dit is geen auditlog of exactly-once queue.
Beoordeel retries/idempotentie van vervolgstappen zelfstandig. De API biedt alleen exacte filters en
offsetpaginering; een volledige scan is nodig. Gebruik gerichte selecties en een passend interval.
De voorbeelden zijn inactief en bevatten geen credentials. Schrijvende voorbeeldstappen staan uit.
Velden invullen
Map Fields From Schema toont Nederlandse labels met het echte veld-ID en enums.
Niet-schrijfbare velden worden niet aangeboden. JSON Object is beschikbaar voor complexe mapping,
arrays en expliciete null; ook deze invoer wordt aan hetzelfde actuele schema getoetst.
- UUID’s zijn strings;
bigintennumericblijven exacte strings. - Booleans zijn echte
true/false, arrays echte arrays, JSON-velden echte JSON-waarden. - Datums zijn
YYYY-MM-DD; tijdstippen ISO 8601 met tijdzone. - Een ontbrekend updateveld blijft behouden.
nullwist alleen nullable velden. - Een JSON-veld wordt volledig vervangen, niet diep samengevoegd.
- Relaties gebruiken echte FRAME-ID’s. Een HubSpot-ID is geen FRAME-ID.
List/get/create/update/resolvers geven één n8n-item per record terug. De recordvelden staan direct
op $json; versie staat op $json._frame.version. Resolverinformatie zoals resolved.created,companyId en contactId blijft in _frame bewaard. Iedere uitvoer is aan zijn invoeritem gekoppeld.
Schemaleesacties en /me behouden hun antwoordobject.
Schrijven en herhalen
Write Identity (schrijfverzoek herkennen) is verplicht. Gebruik een stabiele, unieke
bron-eventidentiteit per bedoelde handeling, bijvoorbeeld een webhook-event-ID plus object-ID.
De node leidt daar deterministisch een UUIDv5 van af, apart per resource en handeling/functie.
Gebruik bij meerdere bronitems een eigen identiteit per item. Gebruik geen huidige tijd of willekeurige UUID
als een event over meerdere uitvoeringen opnieuw kan worden aangeboden.
Bij een onzekere uitkomst: dezelfde identiteit en exact dezelfde body herhalen, of eerst de
bronbinding controleren. Een nieuwe bewuste wijziging krijgt een nieuwe identiteit. Het pakket
herhaalt writes niet automatisch. Houd dezelfde identiteit ook bij n8n Retry On Fail.POST /get leest alleen en krijgt geen idempotency-header.
Een update vraagt het actuele 64-hex versietoken uit get/list. Bij VERSION_CONFLICT: opnieuw lezen,
verschil beoordelen en pas daarna een nieuwe bewuste wijziging uitvoeren.
Een resolver overschrijft een bestaande match niet. Een nieuw contact vraagt een FRAME Company ID.
Een bestaand contact behoudt zijn primaire bedrijf. Bronidentiteit bestaat altijd uit system,accountId en externalId samen. Legacy projectbinding gebeurt uitsluitend via de aparte handeling.
Paginering en fouten
Eén pagina: limit 1–100 en offset 0–100000. Return All volgt de door FRAME opgegeven nextOffset,
met maximaal 50.000 records. Bij overschrijding stopt de node expliciet: kies gerichtere filters.
Per uitvoeritem blijven hasMore en nextOffset beschikbaar in _frame.
De node doseert verzoeken binnen één uitvoering op circa 115 per minuut. Parallelle uitvoeringen delen
wel dezelfde serverlimiet. Bij 429 toont de node Retry-After (standaard 60 seconden). Er is geen stille
retry, overschrijving of fallback naar een sterkere credential. Fouten tonen machinecode en handelingsadvies,
zonder oorspronkelijke requestconfig, sleutel of volledige payload.
Ontwikkelen en controleren
Node.js 22.22 of hoger, npm en TypeScript. De lockfile legt gebruikte versies vast.
npm ci --ignore-scripts
npm run build
npm run lint
npx tsc --noEmit
npm test
npm pack --dry-run
npm pack
Build/lint gebruiken de officiële n8n node-CLI. Het lintprofiel bevat gerichte uitzonderingen:
aangeleverde rasterlogo’s, UNLICENSED en ontbrekend openbaar auteursemailadres; daarnaast gebruikt de
compatibele Dropbox-demo uitsluitend de bekende ingebouwde Dropbox-credential en wordt die demonstratienode
niet als AI-tool aangeboden. Dit pakket claimt geen n8n Cloud-verificatie.
Er wordt geen MIT-licentie of fictief emailadres toegevoegd om een check te laten slagen.
De afzonderlijke broncodebundel bevat de dekkings- en validatierapportage.
Voor ontwikkeling met een aparte n8n-testinstance: raadpleeg de officiële
lokale testinstructies.
Gebruik daarvoor een geïsoleerde gebruikersmap en testcredentials, zonder bestaande workflows.
Migratie vanuit de aangeleverde 0.1.0
De npm-naam is met toestemming gewijzigd van @expoteam/n8n-nodes-frame naar@jerrytlaan/n8n-nodes-frame. Bij import van een oude workflow moet je uitsluitend de volgende
node-types in een kopie van de workflow-export aanpassen:
| Oud type | Nieuw type |
|---|---|
@expoteam/n8n-nodes-frame.frame |
@jerrytlaan/n8n-nodes-frame.frame |
@expoteam/n8n-nodes-frame.frameDropboxDemo |
@jerrytlaan/n8n-nodes-frame.frameDropboxDemo |
Het meegeleverde veilige voorbeeld gebruikt de nieuwe types. Bestaande workflows worden nooit
automatisch aangepast. Test een geïmporteerde kopie eerst in een aparte omgeving.
De node-namen frame en frameDropboxDemo en credentialnaam frameApi blijven gelijk.
Bestaande FRAME-nodes met typeVersion: 1 behouden hun oorspronkelijke interface. Nieuwe nodes gebruiken standaard typeVersion: 2 met native actieformulieren. Zet bestaande nodes niet automatisch om: configureer en vergelijk eerst een kopie. De nieuwe trigger heet frameTrigger (versie 1).
De oude velden recordId, recordKey, projectName, projectNumber, requestKey, bedrijfs-/contactobjecten
en actions/action blijven ondersteund. Een bestaande requestKey houdt exact dezelfde oorspronkelijke
UUID; stap bij retries niet over op een andere sleutel. Alleen oorspronkelijke configuraties met een lege
requestKey behouden de oude uitvoering/node/item-fallback. Nieuwe configuraties vragen een expliciete
stabiele identiteit. De oude credentialparameter baseUrl kan de host niet meer veranderen: requests
én credentialtest zijn vastgepind op FRAME.
Het aangeleverde pakket was private en UNLICENSED. Deze distributie blijft UNLICENSED; er wordt geen
MIT-licentie of overdracht van auteursrechten toegevoegd. npm-publicatie is geen n8n-verificatie.


