fluxuri de lucru n8n

AI-Corporate poate porni fluxuri de lucru n8n printr-un webhook de producție. Acest lucru este util atunci când doriți să porniți un proces automat în afara AI-Corporate, de exemplu crearea unui task, actualizarea unui înregistrări CRM, începerea unui flux de raportare sau transmiterea datelor dintr-un formular către un alt sistem.

Exemplu: articol de știri pe site-ul companiei

Să presupunem că organizația are un flux de lucru n8n care publică un articol de știri pe site-ul WordPress al companiei. În AI-Corporate completați atunci doar un scurt text, de exemplu câteva paragrafe despre un caz de client, un eveniment sau un reper intern. Cu acel text porniți fluxul de lucru în n8n.

fluxul de lucru n8n poate apoi, de exemplu:

1. să transforme scurtul text într-un text de bază folosind un nod LLM și un prompt care se potrivește tonului organizației;
2. să creeze o ilustrație potrivită cu un al doilea nod LLM, de exemplu în culorile brandului și într-un stil ilustrativ recognoscibil;
3. să pregătească sau să publice textul și poza ca articol de blog pe site-ul WordPress.

Așa lucrează AI-Corporate împreună cu n8n: în AI-Corporate utilizatorul alege fluxul de lucru și completează informațiile necesare. n8n efectuează apoi pașii automatizați și se asigură că articolul de știri ajunge bine pe site.

Ce face această integrare?

Porniți un flux de lucru n8n din vizualizarea fluxurilor de lucru. Doar webhook-ul de producție, POST și autentificarea prin header sunt obligatorii. Câmpurile și notificările din n8n sunt opționale și pot fi setate independent.

• Dacă fluxul de lucru nu are câmpuri, webhook-ul este apelat imediat.
• Dacă fluxul de lucru are câmpuri, se deschide mai întâi un formular. Utilizatorul completează câmpurile și apoi pornește fluxul de lucru cu butonul.
• Valorile completate sunt trimise ca JSON în body-ul POST către webhook-ul n8n.
• Fără notificări, AI-Corporate confirmă doar că fluxul de lucru a fost inițiat și continuă în n8n. Fereastra nu afișează un spinner și poate fi închisă imediat.
• Dacă acest lucru este activat în înregistrare, fluxul poate trimite pașii intermediar sau finalul înapoi către AI-Corporate.
• Dacă aprobarea este activată în înregistrare, utilizatorul poate face o alegere direct în AI-Corporate. Ulterior, n8n continuă de la pasul în așteptare.

Ce face această integrare?

Porniți un flux de lucru n8n din lista de fluxuri de lucru. Doar webhook-ul de producție, POST și autentificarea prin header sunt obligatorii. Câmpurile și notificările din n8n sunt opționale și pot fi setate independent.

• Dacă fluxul de lucru nu are câmpuri, webhook-ul este apelat imediat.
• Dacă fluxul de lucru are câmpuri, se deschide mai întâi un formular. Utilizatorul completează câmpurile și apoi pornește fluxul de lucru cu butonul.
• Valorile completate sunt trimise ca JSON în POST către webhook-ul n8n.
• Fără notificări, AI-Corporate confirmă doar că fluxul de lucru a fost inițiat și continuă în n8n. Fereastra nu afișează spinner și poate fi închisă imediat.
• Dacă înregistrarea a activat acest lucru, fluxul poate trimite pașii intermitenți sau finalul înapoi către AI-Corporate.
• Dacă aprobarea este activată în înregistrare, utilizatorul poate face o alegere direct în AI-Corporate. Ulterior, n8n continuă de la pasul în așteptare.

Crearea fluxului de lucru n8n în AI-Corporate

Un administrator înregistrează fluxul de lucru după cum urmează:

1. Accesați Asistenți.
2. Deschideți Fluxuri de lucru.
3. Alegeți Flux de lucru n8n nou.
4. Introduceți numele fluxului de lucru și URL-ul de producție n8n.
5. Configurați Autentificare header cu un nume de header și o valoare secretă a header-ului.
6. Bifați sub Notificări din n8n doar componentele care sunt efectiv construite în acest flux de lucru n8n: progres, aprobare și/sau finalul fluxului de lucru.
7. Adăugați eventual câmpurile care trebuie transmise în POST.
8. Salvați fluxul de lucru.

Toate cele trei opțiuni de notificare sunt pornite implicit. Dacă adăugați mai târziu callbacks sau o etapă de aprobare în n8n, actualizați și înregistrarea în AI-Corporate. Dialogul astfel știe dacă trebuie să afișeze doar o confirmare de start sau să aștepte semnale suplimentare.

Câmpuri

• Câmpurile sunt opționale.
• Fiecare câmp are un nume de câmp și un tip.
• Tipuri de câmp suportate: text scurt, text lung, număr, da/nu, dată, alegere unică și multiple alegeri.
• La Alegere unică și la Multiple alegeri adăugați opțiunile disponibile. Alegere unic este afișată ca o listă derulantă compactă; Multiple alegeri afișează casete de selectare. Valoarea sau valorile alese sunt trimise în body-ul JSON.
• Câmpurile obligatorii trebuie completate înainte de a porni fluxul de lucru.
• Numele câmpului devine cheia în body-ul JSON trimis către n8n.

Crearea unui flux de lucru compatibil în n8n

1. Creați în n8n un flux de lucru nou.
2. Adăugați ca prim nod un Webhook.
3. Acordați acestui nod exact numele Start workflow. Expresiile de test de mai jos folosesc acest nume.
4. Setați HTTP Method la POST.
5. Alegeți Autentificare: Header Auth și folosiți același nume de header și valoare secretă ca în AI-Corporate.
6. Setați Respond sau Response Mode la Immediately.
7. Copiați Production URL în câmpul n8n production-url în AI-Corporate. Nu utilizați test-url cu /webhook-test/.
8. Activați fluxul de lucru.

Datele primite sunt sub body; datele tehnice ale integrării se află sub body.integration. Ștergeți-le dintr-un nod Edit Fields-, Set- sau Code.

Exemplu de corp JSON

Dacă definiți câmpuri cu numele prompt, klantnaam, doelgroepen și datum, n8n poate primi de exemplu acest corp JSON. AI-Corporate adaugă automat obiectul integration.

{
  "prompt": "Faceți o scurtă rezumată a cererii.",
  "klantnaam": "Organizație de exemplu",
  "doelgroepen": ["angajați", "clienți"],
  "datum": "2026-09-22",
  "integration": {
    "runId": "document-id-chat",
    "tenant": "default",
    "callbackUrl": "https://europe-west1-ai-corporate.cloudfunctions.net/n8nWorkflowCallback",
    "callbackToken": "token-temporar-pentru-executie"
  }
}

Tokenul de callback este unic pentru fiecare execuție. Nu îl salvați în jurnale, configurații fixe sau alte sisteme.

Opțional: trimiterea progresului și a finalului

AI-Corporate poate afișa doar ceea ce returnează n8n. Folosiți aceste callback-uri doar dacă în înregistrare ați activat Raportarea progresului intermediar și/sau Raportarea finalului fluxului de lucru.

Configurați fiecare nod callback după cum urmează:

1. Alegeți Method: POST.

2. În URL, dați click pe Expression și introduceți:

   {{ $('Start workflow').first().json.body.integration.callbackUrl }}

3. Alegeți Authentication: None.

4. Activați Send Headers și adăugați următoarele headere.

5. Activați Send Body și alegeți Body Content Type: JSON și Specify Body: Using JSON.

Utilizați aceste headere:

Authorization: Bearer {{ $('Start workflow').first().json.body.integration.callbackToken }}
Content-Type: application/json

Trimiteți de exemplu acest mesaj când un pas începe:

{
  "tenant": "{{ $('Start workflow').first().json.body.integration.tenant }}",
  "runId": "{{ $('Start workflow').first().json.body.integration.runId }}",
  "eventId": "document-maken-gestart",
  "type": "progress",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "document_maken",
    "label": "Document maken"
  },
  "message": "Documentul este în curs de creere."
}

• Pentru fiecare eveniment în aceeași execuție, utilizați un eventId unic.

• Utilizați un label clar în olandeză pentru step.label; acest text este afișat în aplicație.

• Dacă ați activat Raportarea finalului fluxului de lucru, trimiteți la final întotdeauna type: "completed", type: "failed" sau type: "rejected".

• La completed, adăugați eventual un obiect output cu rezultatul.

• La failed, includeți un mesaj de eroare inteligibil. Execuția se oprește atunci și în aplicație.

Opțional: solicitarea aprobării în aplicație

Folosiți un nod n8n Wait cu On Webhook Call când fluxul de lucru poate continua doar după o alegere. Trimiteți înainte de nodul Wait un callback cu type: "approval_required":

Configurați nodul Wait la Resume: On Webhook Call, HTTP Method: POST și Authentication: Header Auth. Alegeți aceeași acreditare Header Auth ca la Start workflow. Adăugați după nodul Wait un nod Switch și verificați {{ $json.body.decision }}.

{
  "tenant": "{{ $('Start workflow').first().json.body.integration.tenant }}",
  "runId": "{{ $('Start workflow').first().json.body.integration.runId }}",
  "eventId": "controle-document",
  "type": "approval_required",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "controle_document",
    "label": "Document verificat"
  },
  "approval": {
    "question": "Se poate continua fluxul de lucru?",
    "context": "Verificați documentul generat.",
    "resumeUrl": "{{ $execution.resumeUrl }}",
    "choices": [
      { "value": "approve", "label": "Aprobă" },
      { "value": "reject", "label": "Respinge" }
    ]
  }
}

Utilizatorul vede opțiunile în fereastra de execuție. După o alegere, nodul Wait va primi în afară de altele și decision. Apoi puteți utiliza, de exemplu, un nod Switch pentru a decide următorul pas.

O valoare de alegere poate conține doar litere, cifre, _ și -. Eticheta poate conține text lizibil normal.

Configurarea URL-ului de callback de producție

URL-ul de callback de producție pentru AI-Corporate este:

https://europe-west1-ai-corporate.cloudfunctions.net/n8nWorkflowCallback

Nu lipiți acest URL ca text fix în fiecare nod callback. Alegeți în câmpul URL al nodului HTTP Request Expression și folosiți:

{{ $('Start workflow').first().json.body.integration.callbackUrl }}

AI-Corporate furnizează în modul automat URL-ul de producție pentru fiecare start. URL-ul fix de mai sus este utilizat pentru a verifica în timpul testării dacă expresia se referă către AI-Corporate și nu către AI-School sau AI-Public.

Funcțiile triggerCustomN8nWorkflow, triggerN8nWorkflow și resumeN8nWorkflow sunt apelate de aplicație în sine. Nu este necesar să le setați în n8n.

Gestionarea erorilor

Trimiteți erori așteptate cu un callback de tip failed. Pentru erori neașteptate de nod, creați de asemenea un Flux de erori central:

1. Creați un flux de lucru nou cu un nod Error Trigger.

2. Adăugați apoi un nod HTTP Request cu Method: POST.

3. Completați în URL această adresă de producție fixă:

   https://europe-west1-ai-corporate.cloudfunctions.net/n8nWorkflowExecutionFailed

4. Alegeți Authentication: None și adăugați header-ul n8n-handihow-name cu valoarea secretă implicită a administratorului platformei.

5. Alegeți un corp JSON și introduceți:

{
  "executionId": "{{ $json.execution.id }}",
  "workflowId": "{{ $json.workflow.id }}",
  "workflowName": "{{ $json.workflow.name }}",
  "lastNode": "{{ $json.execution.lastNodeExecuted }}",
  "message": "{{ $json.execution.error.message }}"
}

6. Activați Fluxul de erori.
7. Deschideți setările fluxului obișnuit și selectați-l la Error Workflow.

Trimiteți imediat după Start workflow cel puțin un callback cu executionId: "{{ $execution.id }}". Doar atunci poate AI-Corporate să asocieze o eroare neașteptată execuției corecte.

Limitări importante

• Doar declanșatoare webhook sunt suportate.
• Doar URL-uri webhook de producție sunt suportate.
• URL-urile de webhook de test cu /webhook-test/ sunt respinse.
• Doar POST este suportat.
• Doar autentificare generic header este suportată.
• Valoarea header-ului este tratată ca secret în aplicație.
• Token-urile de callback și URL-urile de resume sunt procesate doar pe server și nu sunt direct accesibile utilizatorilor.
• Tenant-ul este determinat pe server din utilizatorul autentificat, nu dintr-o valoare pe care browser-ul o trimite.

Atribuții problemelor

• 404 sau webhook neînregistrat: activați fluxul în n8n și folosiți URL-ul de producție.
• Eroare de autentificare: verificați dacă numele header-ului și valoarea sunt exact aceleași în ambele sisteme.
• Date lipsă: verificați dacă numele câmpurilor din aplicație corespund cheilor pe care n8n le așteaptă.
• Nicio cerere în n8n: verificați dacă fluxul începe cu un webhook trigger și utilizează POST.
• Fereastra de execuție rămâne în lucru: dacă ați activat „Raportarea finalului fluxului de lucru”, verificați dacă n8n trimite un callback final completed, failed sau rejected. Dacă nu așteptați notificări, dezactivați toate cele trei opțiuni la înregistrare.
• Nicio progresie vizibilă: verificați dacă Raportarea progresului intermediar este activată la înregistrare, sau dacă obiectul integration este păstrat și dacă fiecare callback are un eventId unic.
• Butoanele de aprobare nu funcționează: verificați nodul Wait, resumeUrl, autentificarea header și caracterele permise în choices[].value.