Fluxuri de lucru n8n

AI-School poate porni fluxuri de lucru n8n printr-un webhook de producție. Acest lucru este util atunci când vrei să pornești din afara AI-School un proces automatizat, de exemplu crearea unei sarcini, actualizarea unei înregistrări CRM, pornirea unui flux de raportare sau trimiterea datelor dintr-un formular către un alt sistem.

Exemplu: articol de știri pe site-ul școlii

Să presupunem că școala a creat un flux de lucru n8n care publică un articol de știri pe site-ul WordPress al școlii. În AI-School completezi doar un scurt fragment de text, de exemplu câteva propoziții despre o săptămână de proiecte, o zi sportivă sau o zi a porților deschise. Cu acel text pornești fluxul de lucru în n8n.

Fluxul de lucru n8n poate apoi, de exemplu:

1. Să transforme textul scurt într-un draft elegant cu un nod LLM și un prompt potrivit tonului școlii.
2. Să genereze o ilustrație potrivită cu un al doilea nod LLM, de exemplu în culorile școlii și într-un stil ilustrativ recognoscibil.
3. Să pregătească sau să publice textul și imaginea ca articol de blog pe site-ul WordPress.

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

Ce face această integrare?

Pornești un flux de lucru n8n din prezentarea generală a fluxurilor de lucru. Sunt obligatorii doar webhook-ul de producție, POST și Header Auth. Câmpurile și feedback-ul din n8n sunt opționale și pot fi configurate independent unul de altul.

• 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 într-un request POST către webhook-ul n8n.
• Fără feedback, AI-School confirmă doar că fluxul de lucru a fost pornit și continuă în n8n. Fereastra nu afișează un spinner și poate fi închisă imediat.
• Dacă acest lucru a fost activat la înregistrare, fluxul de lucru poate trimite către AI-School pași intermediari sau finalizarea.
• Dacă aprobarea a fost activată la înregistrare, utilizatorul poate face o alegere direct în AI-School. Apoi n8n continuă de la pasul de așteptare.

Crearea unui flux de lucru n8n în AI-School

Un administrator înregistrează fluxul de lucru astfel:

1. Mergi la Asistenți.
2. Deschide fila Asistenți de flux de lucru.
3. În cardul de sus, dă clic pe Flux de lucru nou și alege Flux de lucru n8n.
4. Completează numele fluxului de lucru și URL-ul de producție n8n.
5. Configurează Header authentication cu un nume de header și o valoare secretă a headerului.
6. La Feedback din n8n, bifează doar componentele care există cu adevărat în acest flux de lucru n8n: progres, aprobare și/sau finalul fluxului de lucru.
7. Adaugă eventual câmpurile care trebuie trimise în request-ul POST.
8. Salvează fluxul de lucru.

Toate cele trei opțiuni de feedback sunt dezactivate implicit. Dacă adaugi mai târziu callback-uri sau un pas de aprobare în n8n, actualizează și înregistrarea în AI-School. Astfel, dialogul știe dacă trebuie să afișeze doar o confirmare de pornire sau dacă trebuie să aștepte și alte semnale.

Câmpuri

• Câmpurile sunt opționale.
• Fiecare câmp are un nume de câmp și un tip.
• Tipurile de câmp suportate sunt text scurt, text lung, număr, da/nu, dată, o singură alegere și mai multe alegeri.
• Pentru O singură alegere și Mai multe alegeri, adaugi opțiunile disponibile. O singură alegere este afișată ca o listă compactă de selecție; Mai multe alegeri afișează căsuțe de bifare. Valoarea sau valorile alese sunt trimise în body-ul JSON.
• Câmpurile obligatorii trebuie completate înainte ca fluxul de lucru să poată fi pornit.
• Numele câmpului devine cheia din body-ul JSON trimis către n8n.

Crearea unui flux de lucru compatibil în n8n

1. Creează un flux de lucru nou în n8n.
2. Adaugă ca prim nod un Webhook.
3. Denumește exact acest nod Start workflow. Exemplele de mai jos folosesc acest nume.
4. Setează HTTP Method pe POST.
5. La Authentication, alege Header Auth și selectează un credential Header Auth.
6. În acel credential, introdu același nume de header și aceeași valoare secretă ca în fluxul de lucru din AI-School.
7. Setează Respond sau Response Mode pe Immediately. Aplicația primește atunci imediat o confirmare de pornire cu succes, în timp ce n8n continuă să lucreze.
8. Copiază Production URL a nodului Webhook în câmpul n8n productie-url din AI-School. Nu folosi test-url-ul cu /webhook-test/.
9. Activează fluxul de lucru în n8n.

Datele din AI-School se află în n8n sub body. Datele de integrare se află astfel sub body.integration. Nu șterge aceste date într-un nod Edit Fields, Set sau Code. Exemplele de mai jos le citesc de fiecare dată direct din nodul Start workflow.

Exemplu de body JSON

Dacă definești câmpurile cu numele prompt, klantnaam, doelgroepen și datum, n8n primește, de exemplu, acest body JSON. AI-School adaugă automat obiectul integration.

{
  "prompt": "Creează un scurt rezumat al solicitării.",
  "klantnaam": "Organizație exemplu",
  "doelgroepen": ["angajați", "părinți"],
  "datum": "2026-09-22",
  "integration": {
    "runId": "chat-document-id",
    "tenant": "default",
    "callbackUrl": "https://europe-west1-ai-school-pro.cloudfunctions.net/n8nWorkflowCallback",
    "callbackToken": "token-temporar-pentru-această-execuție"
  }
}

Tokenul de callback aparține unei singure execuții. Nu-l salva în loguri, configurări permanente sau alte sisteme.

Opțional: trimiterea progresului și a finalizării

AI-School poate afișa doar ceea ce raportează n8n. Folosește aceste callback-uri numai dacă la înregistrare ai activat Raportează progresul intermediar și/sau Raportează sfârșitul fluxului de lucru.

Configurarea nodului HTTP Request

1. Adaugă un nod HTTP Request și numește-l, de exemplu, Raportează progresul.

2. Setează Method pe POST.

3. La URL, apasă pe Expression.

4. Lipește exact această expresie:

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

5. La Authentication, alege None. Tokenul temporar va fi adăugat ca header în pasul următor.

6. Activează Send Headers și adaugă aceste două headere:

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

7. Activează Send Body.

8. Alege Body Content Type: JSON și Specify Body: Using JSON.

9. Lipește JSON-ul de mai jos în câmpul JSON:

{
  "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": "Creare document"
  },
  "message": "Documentul este creat."
}

10. Alege Execute step în timp ce testezi fluxul de lucru prin aplicație. Nodul ar trebui să primească status 200.

Copiază acest nod HTTP Request pentru fiecare mesaj de status. Pentru fiecare copie, ajustează cel puțin eventId, step.id, step.label și message.

Configurarea callback-ului final

Dacă Raportează sfârșitul fluxului de lucru este activat, la finalul fiecărei rute posibile trebuie să existe un callback final. Folosește type: "completed" la succes, type: "failed" pentru o eroare pe care o gestionezi tu și type: "rejected" când utilizatorul respinge fluxul de lucru.

Pentru o execuție reușită, body-ul poate arăta astfel:

{
  "tenant": "{{ $('Start workflow').first().json.body.integration.tenant }}",
  "runId": "{{ $('Start workflow').first().json.body.integration.runId }}",
  "eventId": "workflow-afgerond",
  "type": "completed",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "afronding",
    "label": "Flux de lucru finalizat"
  },
  "message": "Fluxul de lucru a fost finalizat.",
  "output": {
    "resultaat": "Descriere scurtă sau link către rezultat"
  }
}

Folosește pentru fiecare callback dintr-o execuție un eventId diferit. Folosește întotdeauna și un step.label clar: acest text îl vede utilizatorul în fereastra de execuție.

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

Configurarea nodului Wait

1. Adaugă un nod Wait în punctul în care este necesară aprobarea.
2. La Resume, alege On Webhook Call.
3. Setează HTTP Method pe POST.
4. La Authentication, alege Header Auth.
5. Selectează același credential Header Auth ca la nodul Start workflow.
6. Înainte de nodul Wait, plasează o copie a nodului HTTP Request configurat anterior și numește-l Cere aprobare.
7. Folosește în acest nod același URL dinamic și aceleași headere. Înlocuiește doar body-ul JSON cu:

{
  "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": "Verificare document"
  },
  "approval": {
    "question": "Poate continua fluxul de lucru?",
    "context": "Verifică mai întâi documentul generat.",
    "resumeUrl": "{{ $execution.resumeUrl }}",
    "choices": [
      { "value": "approve", "label": "Aprobare" },
      { "value": "reject", "label": "Respingere" }
    ]
  }
}

Conectează Cere aprobare cu nodul Wait. Utilizatorul va vedea apoi butoanele în AI-School. Resume-url-ul secret nu este oferit browserului; serverul trimite în siguranță alegerea către nodul Wait.

Procesarea alegerii după nodul Wait

1. Adaugă după nodul Wait un nod Switch.

2. Folosește ca valoare de verificat:

   {{ $json.body.decision }}

3. Creează, de exemplu, o rută pentru approve și una pentru reject.

4. Încheie fiecare rută cu un callback potrivit de tip completed, rejected sau failed.

O valoare de alegere poate conține doar litere, cifre, _ și -. Eticheta poate conține însă text obișnuit, lizibil.

Configurarea URL-ului de callback de producție

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

https://europe-west1-ai-school-pro.cloudfunctions.net/n8nWorkflowCallback

Nu lipi acest URL ca text fix în fiecare nod de callback. În câmpul URL al nodului HTTP Request, alege Expression și folosește:

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

Astfel, AI-School furnizează automat la fiecare pornire URL-ul corect de producție. URL-ul fix de mai sus îl folosești doar ca să verifici în timpul testării că expresia indică spre AI-School.

Callable-urile triggerCustomN8nWorkflow, triggerN8nWorkflow și resumeN8nWorkflow sunt apelate de aplicație însăși. Nu trebuie să setezi aceste URL-uri în n8n.

Trimiterea erorilor neașteptate

Un callback obișnuit failed funcționează doar dacă fluxul de lucru ajunge la nodul HTTP Request respectiv. Pentru erori neașteptate ale nodurilor, folosește în plus un n8n Error Workflow central.

Crearea unui Error Workflow central

1. Creează în n8n un flux de lucru separat cu numele AI-School - fouten terugsturen.

2. Adaugă un nod Error Trigger.

3. Adaugă apoi un nod HTTP Request.

4. Setează Method pe POST.

5. Completează la URL acest URL fix de producție:

   https://europe-west1-ai-school-pro.cloudfunctions.net/n8nWorkflowExecutionFailed

6. Alege Authentication: None.

7. Activează Send Headers și adaugă:

   Name	Value
   n8n-handihow-name	valoarea standard secretă pe care o primești de la administratorul platformei
   Content-Type	application/json

8. Activează Send Body, alege JSON și lipește acest body:

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

9. Activează Error Workflow-ul.
10. Deschide setările fluxului de lucru obișnuit și selectează acest nou Error Workflow la Error Workflow.

După Start workflow, trimite întotdeauna cel puțin un callback de progres cu executionId: "{{ $execution.id }}". Astfel, aplicația știe la ce execuție aparține o eroare neașteptată n8n.

Limitări importante

• Sunt suportate doar trigger-ele de tip webhook.
• Sunt suportate doar URL-urile webhook de producție.
• URL-urile de test cu /webhook-test/ sunt respinse.
• Este suportat doar POST.
• Este suportată doar autentificarea generică prin header.
• Valoarea headerului este tratată ca secretă în aplicație.
• Tokenurile de callback și URL-urile de reluare sunt procesate doar server-side și nu sunt disponibile direct utilizatorilor.
• Tenantul este stabilit server-side pe baza utilizatorului autentificat, nu pe baza unei valori trimise de browser.

Depanare

• 404 sau webhook nelistat: activează fluxul de lucru în n8n și folosește URL-ul de producție.
• Eroare de autentificare: verifică dacă numele și valoarea headerului sunt identice în ambele sisteme.
• Date lipsă: verifică dacă numele câmpurilor din aplicație corespund cu cheile pe care le așteaptă n8n.
• Niciun request în n8n: verifică dacă fluxul de lucru începe cu un webhook trigger și folosește POST.
• Fereastra de execuție rămâne în așteptare: dacă ai activat Raportează sfârșitul fluxului de lucru, verifică dacă n8n trimite un ultim callback completed, failed sau rejected. Dacă nu aștepți feedback, dezactivează toate cele trei opțiuni la înregistrare.
• Niciun progres vizibil: verifică dacă Raportează progresul intermediar este activat la înregistrare, dacă obiectul integration este păstrat și dacă fiecare callback are un eventId unic.
• Butoanele de aprobare nu funcționează: verifică nodul Wait, resumeUrl, autentificarea prin header și caracterele permise în choices[].value.