Automatizări

Automatizările execută o instrucțiune conform unui program și livrează rezultatul ca sesiune chat obișnuită. Un rezumat zilnic de știri, o analiză săptămânală sau un raport lunar rulează fără interfață pe server, apare în lista de chat-uri și se deschide ca orice altă conversație.

Structură

O automatizare are un nume, instrucțiuni în text liber, unul sau mai multe declanșatoare, un model opțional (gol înseamnă Auto: modelul chat implicit la momentul execuției), o destinație și o preferință pentru notificări. Destinația stabilește rezultatul: Chat session (implicit) pune instrucțiunile în coadă ca o conversație, iar Work task pornește un sandbox izolat Work, cu instrucțiunile drept primul mesaj și, opțional, o politică nominalizată. Cu notificările activate, execuțiile eșuate apar și în centrul de notificări. Separat, activarea Rezultate automatizări în Settings → Notificări → Notificări prin e-mail vă trimite pe e-mail rezultatul fiecărei execuții, odată ce un administrator a configurat un server de e-mail de ieșire (vezi Notificări). Numele și instrucțiunile sunt criptate în repaus, iar automatizarea aparține creatorului ei.

Declanșatoarele folosesc modelul calendaristic — once, hourly, daily, weekly, monthly, yearly — și pot fi cel mult cinci. Următoarea execuție este cea mai apropiată apariție viitoare, calculată în fusul orar al serverului.

Declanșatoare de eveniment

Un al șaptelea tip, event, nu are deloc ceas: se declanșează când sosește una dintre notificările dumneavoastră.

{ "kind": "event", "event": "channel-mention", "match": "release" }

event poate fi orice tip de notificare cu excepția automation-failed — o rutină nu trebuie să se poată reporni singură din propriul ei anunț de eșec. match, opțional, este un test de subșir fără sensibilitate la majuscule pe titlul notificării; fără el, orice notificare de acel tip declanșează rutina.

Un declanșator de eveniment nu contribuie niciodată cu o oră de următoare execuție. O automatizare ale cărei declanșatoare sunt toate evenimente nu arată deci nicio execuție următoare: lista și dialogul de editare spun Rulează la … în loc. Combinarea unui declanșator de eveniment cu un program funcționează — declanșatoarele programate continuă să conducă ceasul.

Două limite îngrădesc raza de acțiune. O rutină se declanșează cel mult o dată pe minut din evenimente, oricât de aglomerat ar fi fluxul, iar propria notificare de eșec a unei execuții nu redeclanșează niciodată rutina care a produs-o.

Execuția primește ce a declanșat-o, adăugat la instrucțiunile ei:

---
Trigger payload (JSON):
{"event":"channel-mention","title":"...","body":"...","href":"..."}

Execuție

Planificatorul verifică programul la fiecare minut, în spatele unui lease de coordonare, astfel încât o singură replică să avanseze calendarele. Când sosește momentul, este înregistrată o execuție, este pus job-ul durabil automation.run.v1 în coadă, iar next_run_at avansează prin compare-and-set, astfel încât fiecare apariție să fie declanșată cel mult o dată. Job-ul creează o sesiune chat cu numele automatizării și trimite instrucțiunile prin același flux durabil ca celelalte conversații, inclusiv rutarea furnizorului, valorile implicite ale personajului și stocarea.

Dacă serverul a fost oprit, următoarea verificare rulează o singură dată apariția recentă și le omite pe cele mai vechi. Pauza elimină programarea; reluarea sau editarea o recalculează. Ștergerea elimină istoricul prin foreign-key cascade.

Starea provine din registrul durabil: succes după generarea chat-ului, eșec când job-ul ajunge dead-lettered și stalled când o execuție nu începe în 30 de minute.

Destinațiile Work folosesc ciclul de viață Work, nu job-ul chat. Execuția este legată de sarcină, reușește când agentul finalizează sau solicită intervenție și eșuează la eroare/anulare. Un e-mail de rezultat pentru o execuție cu destinație Work poartă rezumatul pe care l-a păstrat chiar execuția Work — același text pe care îl arată istoricul execuțiilor sarcinii — și revine la starea pe o linie a sarcinii când o execuție e mai veche decât rezumatele persistate. Accesul Work este verificat la declanșare; revocarea produce work-access-denied. Politica selectată este validată la salvare și limitele sale se aplică fiecărei sarcini. În Work rulează numai furnizori direcți, iar modelul trebuie să accepte instrumente.

Rutine pentru agenți

O automatizare Work poate fi legată de o sarcină existentă prin workTaskId, la fel ca secțiunea Routines din panoul agentului. Fiecare apariție pornește o execuție în spațiul de lucru și conversația existente, cu modelul, furnizorul și politica runtime ale sarcinii; câmpurile echivalente ale automatizării nu se aplică. Legătura este validată la salvare. O sarcină ștearsă produce work-task-missing, iar una deja activă sau cu preview pornit produce work-task-busy, în loc să aștepte.

Declanșatoare webhook

Dincolo de program, o automatizare poate fi declanșată de un sistem extern — un pipeline CI, un serviciu cron, automatizarea locuinței. În dialogul de editare al automatizării, Webhook trigger → Enable generează un secret pentru automatizarea respectivă; se stochează doar SHA-256 al lui, așa că textul în clar este afișat exact o dată. Rotirea secretului îl invalidează imediat pe cel anterior, iar dezactivarea webhook-ului închide la loc endpoint-ul.

Sistemul extern declanșează automatizarea cu:

curl -X POST https://your-host/api/automations/<automationId>/webhook \
  -H "Authorization: Bearer lwh_..."

(X-Libre-Webhook-Secret: lwh_... funcționează ca antet alternativ.) Răspunsul este 202 cu id-ul execuției puse în coadă — aceeași cale de rulare manuală ca Run now, deci execuțiile se încheie, notifică și apar în istoric identic. Compararea secretului se face în timp constant, o automatizare inexistentă și un secret greșit răspund identic (fără oracol pentru id-uri de automatizare), iar o automatizare suspendată răspunde 409: spre deosebire de Run now al proprietarului, un apelant extern nu poate declanșa peste o pauză.

Un obiect JSON în corpul cererii intră în execuție ca payload de declanșare, astfel încât rutina poate vedea la ce reacționează:

curl -X POST https://your-host/api/automations/<automationId>/webhook \
  -H "Authorization: Bearer lwh_..." \
  -H "Content-Type: application/json" \
  -d '{"commit":"abc123","branch":"main"}'

Payload-ul este adăugat la instrucțiunile pe care le execută rularea, sub un titlu Trigger payload (JSON): — deopotrivă pentru execuții chat, sarcini Work noi și rutine legate de o sarcină. Sunt purtate numai obiecte JSON (array-urile și scalarii sunt ignorați), iar un payload a cărui formă serializată depășește 4000 de caractere este eliminat, nu trunchiat, cu un avertisment în logul serverului. O declanșare fără corp se comportă exact ca înainte.

API

Toate endpoint-urile în afară de declanșarea prin webhook necesită autentificare și operează numai asupra automatizărilor apelantului; declanșarea prin webhook se autentifică în schimb cu secretul automatizării.

Metodă	Rută	Scop
GET	/api/automations	Listează automatizările
POST	/api/automations	Creează o automatizare
GET	/api/automations/occurrences?from=&to=	Apariții viitoare
GET	/api/automations/runs	Istoricul execuțiilor
GET	/api/automations/runs/summary	Nevăzute + grupuri pe 30 de zile
POST	/api/automations/runs/seen	Marchează execuțiile încheiate ca văzute
GET	/api/automations/:automationId	Citește o automatizare
PUT	/api/automations/:automationId	Actualizează o automatizare
DELETE	/api/automations/:automationId	Șterge o automatizare
POST	/api/automations/:automationId/pause	Suspendă programul
POST	/api/automations/:automationId/resume	Reia programul
POST	/api/automations/:automationId/run	Rulează imediat (202 cu id)
POST	/api/automations/:automationId/webhook	Declanșează prin secret (202)
POST	/api/automations/:automationId/webhook-secret	Generează/rotește secretul
DELETE	/api/automations/:automationId/webhook-secret	Dezactivează webhook-ul

Un utilizator poate păstra cel mult 50 de automatizări. Numele sunt limitate la 200 de caractere, iar instrucțiunile la 20.000.