Description

Librus dla n8n

Pobieraj wiadomości z Librus Synergia i uruchamiaj automatyzacje po otrzymaniu nowych wiadomości albo po zmianach w terminarzu. Paczka zawiera dwa węzły, dostępne na wspólnej karcie Librus: akcje pobierania wiadomości oraz zdarzenia wyzwalające workflow — Nowa wiadomość, Nowe wydarzenie w terminarzu i Zmiana wydarzenia w terminarzu.

To nieoficjalna, eksperymentalna integracja do samodzielnie hostowanego n8n. Nie jest dostępna w n8n Cloud. Instancja n8n musi korzystać z Node.js 24 lub nowszego.

> 💼 Chcesz zlecić budowę automatyzacji? Zleć audyt, budowę lub utrzymanie automatyzacji n8n firmie AiAdvisors, prowadzonej przez autora n8n-mcp i n8n-skills.

Instalacja

1. W n8n przejdź do Settings → Community nodes → Install.
2. Wklej pełną nazwę paczki, razem ze znakiem @:

   @czlonkowski/n8n-nodes-librus
   

3. Zatwierdź instalację. W edytorze workflow wyszukaj Librus.

Jeśli widzisz błąd Failed to check package version existence, sprawdź nazwę: czlonkowski/n8n-nodes-librus bez początkowego @ jest niepoprawne. Paczka w npm.

Połączenie z Librusem

W wybranym węźle utwórz dane uwierzytelniające Librus — dane logowania i wpisz login oraz hasło używane do logowania w Synergii. Login może różnić się od adresu e-mail konta LIBRUS.

Zapisz dane i sprawdź połączenie. Jeśli pojawi się ACTION_REQUIRED, zaloguj się w serwisie Librus, uzupełnij wymagane potwierdzenia i ponów próbę w n8n.

Dane logowania są przechowywane jako credentials w n8n. Węzeł nie zwraca hasła ani ciasteczek sesji w wynikach.

Proxy

Librus może nie przyjmować połączeń z adresów centrów danych. Wtedy każde zapytanie kończy się błędem TRANSPORT_ERROR z przyczyną w rodzaju ETIMEDOUT, choć z domowego komputera Librus działa. W takim przypadku wpisz w danych uwierzytelniających pole Proxy, np. http://użytkownik:hasło@proxy.example.pl:3128. Cały ruch do Librusa, również test połączenia, pójdzie wtedy przez to proxy.

• Obsługiwane są proxy HTTP i HTTPS (http:// lub https://) z tunelowaniem CONNECT. Proxy SOCKS nie jest obsługiwane.
• Nieprawidłowy adres zatrzymuje węzeł błędem PROXY_INVALID, zanim wyśle jakiekolwiek zapytanie. Węzeł nie połączy się wtedy po cichu bezpośrednio.
• Znaki specjalne w użytkowniku i haśle zakoduj procentowo (np. @ jako %40).
• Błąd połączenia przez proxy ma dopisek przez proxy. Adres proxy nie pojawia się w komunikatach ani logach węzła.
• Po zmianie proxy węzeł loguje się ponownie.

Pobieranie wiadomości

W węźle Librus wybierz Wiadomość → Pobierz wiadomości.

| Ustawienie | Działanie |
| — | — |
| Status odczytania → Wszystkie | Wszystkie wiadomości. |
| Status odczytania → Nieprzeczytane | Tylko nieprzeczytane. |
| Status odczytania → Przeczytane | Tylko przeczytane. |
| Limit | Maksymalna liczba wiadomości pasujących do filtra. |
| Pobierz wszystkie | Wszystkie pasujące wiadomości, w granicach limitu stron. |
| Dołącz treść | Dołączenie treści wiadomości. |
| Zakres treści → Podgląd | Skrócony podgląd z listy; może urwać się w środku zdania. |
| Zakres treści → Pełna treść | Pełna treść ze szczegółów wiadomości. |

Każda wiadomość jest osobnym elementem danych z polami m.in. messageId, senderName, topic, sendDate, readDate i isAnyFileAttached. Po włączeniu treści wynik zawiera także content oraz contentSource (preview lub full).

Aby pobrać pełną treść, włącz Dołącz treść i wybierz Pełną treść. Pobranie szczegółów może oznaczyć wiadomość jako przeczytaną w Librusie. W jednym wykonaniu można pobrać pełną treść maksymalnie 50 wiadomości.

Jeśli znasz ID wiadomości, wybierz Wiadomość → Pobierz treść wiadomości i podaj ID wiadomości. Ta operacja zwraca messageId, content i contentSource: "full".

Automatyzacja po nowej wiadomości

1. Wyszukaj Librus, wybierz zdarzenie Nowa wiadomość i zapisane dane logowania.
2. Ustaw Poll Times, np. Every X → 5 → Minutes. Węzeł sprawdza skrzynkę cyklicznie; powiadomienie pojawi się po kolejnym sprawdzeniu.
3. Ręcznie przetestuj węzeł. Zwróci jedną obecną wiadomość jako próbkę; pusta skrzynka nie zwróci danych.
4. Dodaj dalsze kroki i opublikuj/aktywuj workflow.

Pierwsze automatyczne sprawdzenie zapamiętuje obecną skrzynkę bez uruchamiania workflow dla starych wiadomości. Kolejne sprawdzenia wykrywają nowe ID, również gdy wiadomość została już przeczytana w aplikacji Librusa. Zmiana statusu starej wiadomości nie uruchamia triggera ponownie. Ręczne testy nie zmieniają tej historii.

Trigger domyślnie zwraca metadane i skrócony podgląd. Aby dołączyć pełną treść, dodaj po nim Librus → Pobierz treść wiadomości i ustaw ID wiadomości na:

{{ $json.messageId }}

Przykładowy workflow: Librus — Nowa wiadomość → Librus (Pobierz treść wiadomości) → wybrany kanał powiadomień. Jeśli wystarczy temat i podgląd, pomiń Pobierz treść wiadomości.

Automatyzacja po zmianach w terminarzu

1. Wyszukaj Librus Trigger i wybierz zdarzenie Nowe wydarzenie w terminarzu albo Zmiana wydarzenia w terminarzu oraz zapisane dane logowania.
2. Ustaw Liczba miesięcy do przodu — ile miesięcy po bieżącym miesiącu sprawdzać (0–6, domyślnie 1). Każdy dodatkowy miesiąc to jedno kolejne zapytanie do Librusa; wydarzeń spoza tego zakresu węzeł nie wykryje.
3. Opcjonalnie wypełnij Rodzaje wydarzeń listą rodzajów po przecinku (np. Sprawdzian, Kartkówka), dopasowywaną bez rozróżniania wielkości liter. Puste pole przepuszcza wszystkie wydarzenia. Wydarzenie o nieznanym rodzaju zawsze przechodzi przez filtr — dotyczy to też usuniętych wydarzeń, których szczegółów węzeł nie zdążył jeszcze pobrać — żeby filtr nigdy nie zgubił odwołanego sprawdzianu.
4. Ustaw Poll Times na co najmniej 15 minut.
5. Ręcznie przetestuj węzeł. Zwróci do pięciu najbliższych wydarzeń z bieżącego miesiąca jako próbkę (changeType: "sample") i nie zmieni historii. Próbka celowo pomija filtr Rodzaje wydarzeń — dzięki temu odczytasz z wyniku prawdziwe wartości pola rodzaj i wpiszesz je do filtra, a wąski filtr nie zwróci pustej próbki wyglądającej na zepsute połączenie.
6. Dodaj dalsze kroki i opublikuj/aktywuj workflow.

Pierwsze automatyczne sprawdzenie zapamiętuje obecny terminarz bez uruchamiania workflow dla już istniejących wydarzeń. Kolejne sprawdzenia porównują terminarz z zapamiętanym stanem:

• Nowe wydarzenie w terminarzu uruchamia się, gdy w terminarzu pojawi się wydarzenie, którego wcześniej nie było.
• Zmiana wydarzenia w terminarzu uruchamia się dla edycji istniejącego wydarzenia (np. zmiana opisu albo przeniesienie na inny dzień) oraz dla wydarzeń, które zniknęły z terminarza — usunięcie lub odwołanie wydarzenia trafia na to samo zdarzenie co zmiana (changeType: "removed"), a nie na osobne zdarzenie.

Każdy element zawiera m.in. changeType, eventKey, eventId, route, date, subject, teacher, description, rodzaj, room, addedAt, details, changedFields oraz previous; dla nowych wydarzeń te dwa ostatnie pola są puste (changedFields: [], previous: null), a przy zmianach niosą listę zmienionych pól i poprzednią wersję, przy usunięciach zaś poprzednią wersję.

Wykrywanie zmian opiera się wyłącznie na tym, co pokazuje siatka terminarza — na dacie, tekście komórki, nauczycielu i opisie. Edycja widoczna tylko na stronie szczegółów wydarzenia (np. sama zmiana sali) nie wywoła zdarzenia zmiany, dopóki nie zajdzie razem z inną, widoczną w siatce edycją. Usunięcie wydarzenia nigdy nie niesie pola details (jest null) — to, co zniknęło, opisuje pole previous.

Pobieranie wydarzeń z terminarza

Wybierz Terminarz → Pobierz wydarzenia, żeby jednorazowo odczytać wpisy z terminarza, np. do zasilenia kalendarza istniejącymi wydarzeniami.

• Liczba kolejnych miesięcy (0–6, domyślnie 2) — ile miesięcy po bieżącym sprawdzić.
• Tylko nadchodzące (domyślnie włączone) — pomija wpisy z datą wcześniejszą niż dzisiejsza według czasu polskiego.

Każdy element ma te same pola co zdarzenia triggera terminarza, z changeType: "existing", changedFields: [] i previous: null. Szczegóły wpisu (rodzaj, sala, nauczyciel, opis ze strony wydarzenia) są pobierane dla maksymalnie 50 wpisów w jednym wykonaniu; pozostałe mają tylko dane z siatki i details: null.

Ograniczenia i rozwiązywanie problemów

• Oznaczanie jako nieprzeczytane lub przeczytane, wysyłanie, usuwanie i pobieranie załączników nie są obsługiwane. Odczyt pełnej treści może sam zmienić status wiadomości w Librusie.
• SCAN_INCOMPLETE: zwiększ ustawienie Maksymalna liczba stron (domyślnie 20, maksymalnie 50). W operacji Pobierz wiadomości możesz też ograniczyć liczbę wyników. Trigger musi sprawdzić całą skrzynkę; niepełny skan nie aktualizuje jego historii.
• FULLCONTENTLIMIT: wyłącz Pobierz wszystkie i ustaw Limit na 50 lub mniej.
• Błąd dalszego kroku workflow: ponów nieudane wykonanie w n8n. Kolejne sprawdzenie triggera nie wyemituje tej samej wiadomości ponownie. Przy równoległych wykonaniach lub wielu instancjach możliwe są duplikaty.
• Historia triggera obejmuje do 10 000 ID. Po osiągnięciu limitu utwórz nowy trigger, który zapamięta aktualną skrzynkę jako stan początkowy. Zmiana konta lub utrata zapisanej historii również ustala nowy stan początkowy.
• Wiadomość usunięta lub przeniesiona poza skrzynkę pomiędzy sprawdzeniami może nie zostać wykryta.

Integracja korzysta z nieoficjalnych tras Librusa. Długotrwałe działanie harmonogramu i wpływ pobierania listy na status odczytania wymagają jeszcze weryfikacji. Treść wiadomości trafia do danych wykonania workflow — jej przechowywaniem zarządzają ustawienia historii n8n.

Pomoc

Błędy i propozycje zgłaszaj w GitHub Issues. Nie umieszczaj w zgłoszeniach loginów, haseł, ciasteczek ani treści prawdziwych wiadomości.

Instrukcje pracy nad kodem: dokumentacja deweloperska.

Licencja

MIT. Projekt nie jest powiązany z firmą LIBRUS ani przez nią zatwierdzony. Informacje o autorstwie i źródłach.