Workflowi n8n

AI-School może uruchamiać workflowy n8n za pośrednictwem produkcyjnego webhooka. Jest to przydatne, gdy chcesz uruchomić zautomatyzowany proces poza AI-School, na przykład utworzenie zadania, aktualizację rekordu CRM, rozpoczęcie flow raportowania albo przekazanie danych formularza do innego systemu.

Przykład: artykuł prasowy na stronie szkoły

Załóżmy, że szkoła utworzyła workflow n8n, który publikuje artykuł prasowy na stronie WordPress szkoły. W AI-School wpisujesz wtedy tylko krótki fragment tekstu, na przykład kilka zdań o tygodniu projektowym, dniu sportu lub dniu otwartym. Tym tekstem uruchamiasz workflow w n8n.

Workflow n8n może potem na przykład:

1. Z krótkiego tekstu stworzyć zgrabny tekst roboczy za pomocą węzła LLM i promptu dobrze dopasowanego do tonu szkoły.
2. Wygenerować pasującą ilustrację za pomocą drugiego węzła LLM, na przykład w kolorach szkoły i w rozpoznawalnym stylu ilustracyjnym.
3. Przygotować lub opublikować tekst i obraz jako wpis blogowy na stronie WordPress.

Tak współpracują AI-School i n8n: w AI-School użytkownik wybiera workflow i wypełnia potrzebne informacje. Następnie n8n wykonuje zautomatyzowane kroki i sprawia, że artykuł trafia na stronę.

Co robi ta integracja?

Uruchamiasz workflow n8n z poziomu przeglądu workflowów. Obowiązkowe są tylko produkcyjny webhook, POST i Header Auth. Pola oraz komunikaty zwrotne z n8n są opcjonalne i mogą być konfigurowane niezależnie od siebie.

• Jeśli workflow nie ma pól, webhook jest wywoływany od razu.
• Jeśli workflow ma pola, najpierw otwiera się formularz. Użytkownik wypełnia pola, a potem uruchamia workflow przyciskiem.
• Wprowadzone wartości są przesyłane jako JSON w POST-request do webhooka n8n.
• Bez komunikatów zwrotnych AI-School tylko potwierdza, że workflow został uruchomiony i dalej działa w n8n. Okno nie pokazuje spinnera i można je od razu zamknąć.
• Jeśli zostało to zaznaczone przy rejestracji, workflow może przesyłać do AI-School pośrednie kroki lub zakończenie.
• Jeśli zostało zaznaczone zatwierdzanie przy rejestracji, użytkownik może dokonać wyboru bezpośrednio w AI-School. n8n kontynuuje wtedy od kroku oczekującego.

Tworzenie workflow n8n w AI-School

Administrator rejestruje workflow w następujący sposób:

1. Przejdź do Asystenci.
2. Otwórz zakładkę Asystenci workflow.
3. W karcie u góry kliknij Nowy workflow i wybierz workflow n8n.
4. Wpisz nazwę workflow oraz produkcyjny URL n8n.
5. Skonfiguruj Header authentication z nazwą nagłówka i tajną wartością nagłówka.
6. W sekcji Komunikaty zwrotne z n8n zaznacz tylko te elementy, które rzeczywiście są zbudowane w tym workflow n8n: postęp, zatwierdzenie i/lub koniec workflow.
7. Opcjonalnie dodaj pola, które mają być przesyłane w POST-request.
8. Zapisz workflow.

Domyślnie wszystkie trzy opcje komunikatów zwrotnych są wyłączone. Jeśli później dodasz callbacki lub krok zatwierdzania w n8n, zaktualizuj też rejestrację w AI-School. Dzięki temu dialog wie, czy ma tylko pokazać potwierdzenie startu, czy czekać na dalsze sygnały.

Pola

• Pola są opcjonalne.
• Każde pole ma jedną nazwę pola i typ.
• Obsługiwane typy pól to krótki tekst, długi tekst, liczba, tak/nie, data, jeden wybór i wiele wyborów.
• Dla Jeden wybór i Wiele wyborów dodajesz dostępne opcje. Jeden wybór jest wyświetlany jako kompaktowa lista wyboru; Wiele wyborów pokazuje pola wyboru. Wybrana wartość lub wartości są przesyłane w body JSON.
• Pola wymagane muszą zostać wypełnione, zanim workflow będzie można uruchomić.
• Nazwa pola staje się kluczem w body JSON wysyłanym do n8n.

Tworzenie kompatybilnego workflow w n8n

1. W n8n utwórz nowy workflow.
2. Jako pierwszy node dodaj Webhook.
3. Nadaj temu node’owi dokładnie nazwę Start workflow. Poniższe przykłady używają tej nazwy.
4. Ustaw HTTP Method na POST.
5. Wybierz przy Authentication opcję Header Auth i wybierz credential Header Auth.
6. W tym credentialu wpisz tę samą nazwę nagłówka i tę samą tajną wartość co w workflow w AI-School.
7. Ustaw Respond lub Response Mode na Immediately. Aplikacja otrzyma wtedy od razu pomyślne potwierdzenie startu, podczas gdy n8n będzie pracować dalej.
8. Skopiuj Production URL z node’a Webhook do pola n8n produkcyjny url w AI-School. Nie używaj testowego URL-a z /webhook-test/.
9. Aktywuj workflow w n8n.

Dane z AI-School znajdują się w n8n pod body. Dane integracyjne są więc dostępne pod body.integration. Nie usuwaj tych danych w node’ach Edit Fields, Set ani Code. Poniższe przykłady odczytują je bezpośrednio z node’a Start workflow.

Przykład body JSON

Jeśli zdefiniujesz pola o nazwach prompt, klantnaam, doelgroepen i datum, n8n otrzyma na przykład takie body JSON. AI-School automatycznie dodaje obiekt integration.

{
  "prompt": "Stwórz krótkie podsumowanie zgłoszenia.",
  "klantnaam": "Przykładowa organizacja",
  "doelgroepen": ["pracownicy", "rodzice"],
  "datum": "2026-09-22",
  "integration": {
    "runId": "chat-document-id",
    "tenant": "default",
    "callbackUrl": "https://europe-west1-ai-school-pro.cloudfunctions.net/n8nWorkflowCallback",
    "callbackToken": "tymczasowy-token-dla-tego-uruchomienia"
  }
}

Token callbacka należy do jednego uruchomienia. Nie zapisuj go w logach, stałej konfiguracji ani w innych systemach.

Opcjonalnie: przesyłanie postępu i zakończenia

AI-School może wyświetlać tylko to, co zwróci n8n. Używaj tych callbacków tylko wtedy, gdy przy rejestracji włączyłeś Zgłaszaj pośredni postęp i/lub Zgłaszaj koniec workflow.

Konfiguracja node’a HTTP Request

1. Dodaj node HTTP Request i nazwij go na przykład Zgłoś postęp.

2. Ustaw Method na POST.

3. Kliknij przy URL opcję Expression.

4. Wklej dokładnie ten expression:

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

5. Wybierz przy Authentication opcję None. Tymczasowy token zostanie dodany w następnym kroku jako nagłówek.

6. Włącz Send Headers i dodaj te dwa nagłówki:

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

7. Włącz Send Body.

8. Wybierz Body Content Type: JSON i Specify Body: Using JSON.

9. Wklej poniższy JSON do pola 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": "Tworzenie dokumentu"
  },
  "message": "Dokument jest tworzony."
}

10. Wybierz Execute step podczas testowania workflow przez aplikację. Node powinien zwrócić status 200.

Skopiuj ten node HTTP Request dla każdego komunikatu statusu. W każdej kopii zmień co najmniej eventId, step.id, step.label i message.

Konfiguracja ostatniego callbacka

Jeśli włączono Zgłaszaj koniec workflow, na końcu każdej możliwej ścieżki musi znajdować się ostatni callback. Użyj type: "completed" przy sukcesie, type: "failed" dla błędu, który obsługujesz samodzielnie, oraz type: "rejected" gdy użytkownik odrzuci workflow.

Dla udanego wykonania body może wyglądać tak:

{
  "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": "Workflow zakończony"
  },
  "message": "Workflow został zakończony.",
  "output": {
    "resultaat": "Krótki opis lub link do wyniku"
  }
}

W ramach jednego uruchomienia używaj dla każdego callbacka innego eventId. Zawsze używaj też czytelnego step.label: ten tekst użytkownik widzi w oknie wykonania.

Opcjonalnie: proszenie o zatwierdzenie w aplikacji

Konfiguracja node’a Wait

1. W miejscu, w którym potrzebne jest zatwierdzenie, dodaj node Wait.
2. Wybierz przy Resume opcję On Webhook Call.
3. Ustaw HTTP Method na POST.
4. Wybierz przy Authentication opcję Header Auth.
5. Wybierz ten sam credential Header Auth co dla node’a Start workflow.
6. Przed node’em Wait umieść kopię wcześniej skonfigurowanego node’a HTTP Request i nazwij ją Poproś o zatwierdzenie.
7. Użyj w tym node’ie tego samego dynamicznego URL-a i tych samych nagłówków. Zastąp jedynie body JSON przez:

{
  "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": "Sprawdzenie dokumentu"
  },
  "approval": {
    "question": "Czy workflow może kontynuować?",
    "context": "Najpierw sprawdź wygenerowany dokument.",
    "resumeUrl": "{{ $execution.resumeUrl }}",
    "choices": [
      { "value": "approve", "label": "Zatwierdź" },
      { "value": "reject", "label": "Odrzuć" }
    ]
  }
}

Połącz Poproś o zatwierdzenie z node’em Wait. Użytkownik zobaczy potem przyciski w AI-School. Tajny resume-url nie jest przekazywany do przeglądarki; serwer bezpiecznie przesyła wybór do node’a Wait.

Obsługa wyboru po node’ie Wait

1. Po node’ie Wait dodaj node Switch.

2. Jako sprawdzaną wartość użyj:

   {{ $json.body.decision }}

3. Utwórz na przykład trasę dla approve i trasę dla reject.

4. Każdą trasę zakończ odpowiednim callbackiem completed, rejected lub failed.

Wartość wyboru może zawierać tylko litery, cyfry, _ i -. Etykieta może zawierać zwykły czytelny tekst.

Ustawienie produkcyjnego callback-url

Produkcjny callback-url dla AI-School to:

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

Nie wklejaj tego URL-a jako stałego tekstu w każdym callback node. W polu URL node’a HTTP Request wybierz Expression i użyj:

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

AI-School automatycznie przekazuje przy każdym uruchomieniu właściwy produkcyjny URL. Stały URL powyżej służy tylko do sprawdzenia podczas testów, czy expression wskazuje na AI-School.

Callable triggerCustomN8nWorkflow, triggerN8nWorkflow i resumeN8nWorkflow są wywoływane przez samą aplikację. Nie musisz ustawiać tych URL-i w n8n.

Zgłaszanie nieoczekiwanych błędów

Zwykły callback failed działa tylko wtedy, gdy workflow dotrze do odpowiedniego node’a HTTP Request. W przypadku nieoczekiwanych błędów node’ów użyj dodatkowo centralnego n8n Error Workflow.

Tworzenie centralnego Error Workflow

1. Utwórz w n8n osobny workflow o nazwie AI-School - zwracanie błędów.

2. Dodaj node Error Trigger.

3. Następnie dodaj node HTTP Request.

4. Ustaw Method na POST.

5. W polu URL wpisz ten stały produkcyjny URL:

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

6. Wybierz Authentication: None.

7. Włącz Send Headers i dodaj:

   Name	Value
   n8n-handihow-name	tajna wartość domyślna, którą otrzymasz od administratora platformy
   Content-Type	application/json

8. Włącz Send Body, wybierz JSON i wklej to body:

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

9. Aktywuj Error Workflow.
10. Otwórz ustawienia zwykłego workflow i w sekcji Error Workflow wybierz ten nowy Error Workflow.

Bezpośrednio po Start workflow zawsze wysyłaj co najmniej jeden callback postępu z executionId: "{{ $execution.id }}". Dzięki temu aplikacja wie, do którego wykonania należy nieoczekiwany błąd n8n.

Ważne ograniczenia

• Obsługiwane są tylko webhook triggers.
• Obsługiwane są tylko produkcyjne webhook URL-e.
• Testowe webhook URL-e z /webhook-test/ są odrzucane.
• Obsługiwany jest tylko POST.
• Obsługiwana jest tylko ogólna autoryzacja nagłówkiem.
• Wartość nagłówka jest traktowana w aplikacji jako sekret.
• Tokeny callbacków i resume-url są przetwarzane tylko po stronie serwera i nie są bezpośrednio dostępne dla użytkowników.
• Tenant jest ustalany po stronie serwera na podstawie zalogowanego użytkownika, a nie na podstawie wartości przesyłanej przez przeglądarkę.

Rozwiązywanie problemów

• 404 lub webhook nie jest zarejestrowany: aktywuj workflow w n8n i użyj produkcyjnego URL-a.
• Błąd autoryzacji: sprawdź, czy nazwa nagłówka i wartość w obu systemach są dokładnie takie same.
• Brakujące dane: sprawdź, czy nazwy pól w aplikacji odpowiadają kluczom, których oczekuje n8n.
• Brak requestu w n8n: sprawdź, czy workflow zaczyna się od triggera webhook i używa POST.
• Okno wykonania pozostaje otwarte: jeśli włączyłeś Zgłaszaj koniec workflow, sprawdź, czy n8n wysyła ostatni callback completed, failed lub rejected. Jeśli nie oczekujesz żadnych komunikatów zwrotnych, wyłącz wszystkie trzy opcje przy rejestracji.
• Brak widocznego postępu: sprawdź, czy Zgłaszaj pośredni postęp jest włączone przy rejestracji, czy obiekt integration jest zachowany oraz czy każdy callback ma unikalny eventId.
• Przyciski zatwierdzania nie działają: sprawdź node Wait, resumeUrl, autoryzację nagłówkiem oraz dozwolone znaki w choices[].value.