Automatizálások

Az automatizálások ütemezés szerint hajtanak végre egy utasítást, az eredményt pedig normál beszélgetésként adják át. A napi hírösszefoglaló, a heti áttekintés vagy a havi jelentés felület nélkül fut a szerveren, megjelenik a beszélgetéslistában, és ugyanúgy nyitható meg, mint bármely más beszélgetés.

Felépítés

Egy automatizálásnak neve, szabad szöveges utasítása, egy vagy több eseményindítója, opcionális modellje (az üres érték Auto: a futáskor érvényes alapértelmezett Chat-modell), célja és értesítési beállítása van. A cél határozza meg az eredményt: a Chat session (alapértelmezett) beszélgetésként állítja sorba az utasítást, míg a Work task egy elszigetelt Work környezetet indít, első üzenetként az utasítással és opcionálisan egy elnevezett házirenddel. Bekapcsolt értesítéseknél a sikertelen futások az értesítési postaládában is megjelennek, így a hibák akkor is elérik, ha az Automatizálások lap be van zárva. Ettől külön, a Settings → Notifications → E-mail-értesítések alatt bekapcsolt Automation results minden futás kimenetelét elküldi e-mailben, miután egy rendszergazda beállította a kimenő levelezőszervert (lásd: Értesítések). A név és az utasítás nyugalmi állapotban titkosított, az automatizálás pedig a létrehozójához tartozik.

Az eseményindítók a naptármodellt használják — once, hourly, daily, weekly, monthly, yearly —, és legfeljebb öten lehetnek. A következő futás a szerver időzónájában számított legközelebbi jövőbeli előfordulás.

Eseményindítók

Egy hetedik fajtának, az event-nek egyáltalán nincs órája: akkor sül el, amikor az egyik értesítése megérkezik.

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

Az event bármilyen értesítéstípus lehet az automation-failed kivételével — egy rutin nem indíthatja újra magát a saját hibaértesítéséből. Az opcionális match egy kis- és nagybetűt nem megkülönböztető részszöveg-egyezés az értesítés címére; nélküle az adott típus minden értesítése elindítja a rutint.

Egy eseményindító soha nem ad következő futási időpontot. Egy automatizálás, amelynek minden eseményindítója event, ezért nem mutat következő futást: a lista és a szerkesztő párbeszédablak ehelyett azt írja: Runs when …. Az eseményindító és egy ütemezés keverése rendben van — az ütemezett eseményindítók továbbra is vezérlik az órát.

Két korlát szabja meg a hatókört. Egy rutin legfeljebb percenként egyszer sül el eseményekből, bármilyen forgalmas is a stream, és egy futás saját hibaértesítése soha nem indítja újra azt a rutint, amely létrehozta.

A futás megkapja, ami elindította, az utasításaihoz fűzve:

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

Végrehajtás

Az ütemező percenként ellenőriz egy koordinációs lease mögött, hogy csak egy replika léptesse előre az ütemezéseket. Az időpont elérésekor rögzíti a futást, sorba állítja az automation.run.v1 tartós feladatot, és compare-and-set művelettel előrelépteti a next_run_at értéket, így minden előfordulás legfeljebb egyszer indul el. A feladat az automatizálás nevével létrehoz egy Chat-munkamenetet, majd ugyanazon a tartós folyamaton vezeti át az utasítást, mint a többi beszélgetést, beleértve a szolgáltatói útvonalválasztást, a persona alapértékeit és a tárolást.

Ha a szerver leállt, a következő ellenőrzés egyszer futtatja a legutóbbi előfordulást, a régebbieket pedig kihagyja. A szüneteltetés törli az ütemezést; a folytatás vagy szerkesztés újraszámítja. A törlés foreign-key cascade segítségével eltávolítja az előzményeket.

Az állapot a tartós naplóból származik: siker a beszélgetés létrejötte után, hiba, ha a feladat dead-lettered állapotba kerül, és stalled, ha egy futás 30 percen belül nem indul el.

A Work-célok a Work életciklusát használják a Chat-feladat helyett. A futás a feladathoz kapcsolódik, sikeres, ha az ügynök befejezi vagy beavatkozást kér, és hiba vagy megszakítás esetén sikertelen. Egy Work-célú futás kimeneti e-mailje a Work-futás által magától eltárolt összefoglalót hordozza — amivel az ügynök zárta, ugyanaz a szöveg, amit a feladat futási előzménye mutat —, és a feladat egysoros állapotára esik vissza, ha egy futás korábbi, mint a tárolt összefoglalók bevezetése. A Work-hozzáférést indításkor ellenőrzi; a visszavonás eredménye work-access-denied. A kiválasztott házirendet mentéskor ellenőrzi, korlátai minden feladatra vonatkoznak. A Work csak közvetlen szolgáltatókat futtat, a modellnek pedig támogatnia kell az eszközöket.

Ügynökrutinok

Egy Work-automatizálás a workTaskId segítségével meglévő feladathoz köthető, ahogy az ügynökpanel Routines szakaszában is. Minden előfordulás a meglévő munkatérben és beszélgetésben indít futást a feladat modelljével, szolgáltatójával és futtatási házirendjével; az automatizálás megfelelő mezői ilyenkor nem érvényesek. A kapcsolatot mentéskor ellenőrzi. Törölt feladatnál work-task-missing, már futó feladatnál vagy élő előnézetnél pedig várakozás helyett work-task-busy keletkezik.

Webhook-eseményindítók

Az ütemezésen túl egy automatizálást külső rendszer is elindíthat — CI-folyamat, cron-szolgáltatás, otthoni automatizálás. Az automatizálás szerkesztőablakában a Webhook trigger → Enable automatizálásonkénti titkot generál; ebből csak a SHA-256 lenyomat tárolódik, így a nyílt szöveg pontosan egyszer jelenik meg. A titok cseréje azonnal érvényteleníti a korábbit, a webhook kikapcsolása pedig ismét lezárja a végpontot.

A külső rendszer így indítja el az automatizálást:

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

(Alternatív fejlécként az X-Libre-Webhook-Secret: lwh_... is működik.) A válasz 202 a sorba állított futás azonosítójával — ugyanaz a kézi indítási útvonal, mint a Run now, így a futások ugyanúgy zárulnak le, értesítenek és jelennek meg az előzményekben. A titok összehasonlítása állandó idejű, a nem létező automatizálás és a hibás titok azonos választ ad (nincs automatizálás-azonosító orákulum), a szüneteltetett automatizálás pedig 409 választ ad: a tulajdonos Run now gombjától eltérően külső hívó nem indíthat futást a szüneten át.

A kérés törzsében egy JSON-objektum trigger payloadként utazik be a futásba, így a rutin láthatja, mire reagál:

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

A payload a futás által végrehajtott utasításokhoz fűződik, egy Trigger payload (JSON): cím alatt — chat-futásokhoz, új Work-feladatokhoz és feladathoz kötött rutinokhoz egyaránt. Csak JSON-objektumok kerülnek át (tömbök és skalárok figyelmen kívül maradnak), és egy olyan payload, amelynek szerializált formája meghaladja a 4000 karaktert, csonkolás helyett eldobódik, figyelmeztetéssel a szerverlogban. A törzs nélküli indítás pontosan úgy viselkedik, mint korábban.

API

A webhookos indítás kivételével minden végpont hitelesítést igényel, és csak a hívó automatizálásain működik; a webhookos indítás ehelyett az automatizálás titkával hitelesít.

Metódus	Útvonal	Cél
GET	/api/automations	Automatizálások listázása
POST	/api/automations	Automatizálás létrehozása
GET	/api/automations/occurrences?from=&to=	Jövőbeli előfordulások
GET	/api/automations/runs	Futási előzmények
GET	/api/automations/runs/summary	Nem látott + 30 napos csoportok
POST	/api/automations/runs/seen	Befejezett futások megjelölése látottként
GET	/api/automations/:automationId	Automatizálás beolvasása
PUT	/api/automations/:automationId	Automatizálás frissítése
DELETE	/api/automations/:automationId	Automatizálás törlése
POST	/api/automations/:automationId/pause	Ütemezés szüneteltetése
POST	/api/automations/:automationId/resume	Ütemezés folytatása
POST	/api/automations/:automationId/run	Azonnali futtatás (202 és id)
POST	/api/automations/:automationId/webhook	Indítás titokkal (202)
POST	/api/automations/:automationId/webhook-secret	Titok létrehozása/cseréje
DELETE	/api/automations/:automationId/webhook-secret	Webhook kikapcsolása

Egy felhasználó legfeljebb 50 automatizálást tarthat meg. A nevek legfeljebb 200, az utasítások 20 000 karakteresek lehetnek.