Aller au contenu

Hooks d’événement et planifiés

Un domaine peut embarquer sa propre automatisation. Un hook d’événement exécute un script Lua quand un document change quelque part. Un hook planifié en exécute un selon une planification cron. Les hooks vivent sur le document du domaineà : ils suivent le domaine quand vous le publiez ou l’exportez.

  • Chaque nouveau contrat mis en attente doit alerter un réviseur.
  • Un travail de consolidation doit tourner chaque nuit.
  • Un script doit réagir aux changements d’un autre domaine, dans les limites d’une attribution.
  • Le document du domaine. Vous déclarez les hooks en modifiant le document du domaine.
  • Les noms d’événements. Repérez les noms qui vous concernentà : created, updated, deleted, et le reste du vocabulaire des mutations.
  • Le bon outil. Les hooks tournent dans Facet. Pour appeler un système externe, passez par un webhook. Voir Webhooks sortants.

Ajoutez une entrée au tableau hooks du document du domaine. Un hook d’événement nomme une source et porte un scriptà :

{
"id": "alert-on-hold",
"kind": "event",
"source": { "domain": "accountancy", "doc_type": "Contract", "events": ["created"] },
"script": "local export = {}\n\nfunction export.on_event(ctx)\n if ctx.event.content.status == \"on_hold\" then\n ctx.error(\"Contract \" .. ctx.event.doc_id .. \" entered on-hold\")\n end\nend\n\nreturn export"
}
Élément Signification
id Unique dans le domaine.
source.domain Requis. Le domaine à observer.
source.doc_type Facultatif. Sans lui, le hook observe tous les doctypes du domaine.
source.events Facultatif. Sans lui, le hook se déclenche à chaque événement.

La valeur script est du texte Lua. Elle renvoie une table avec on_event (hooks d’événement) ou on_schedule (hooks planifiés), comme l’entrée ci-dessus.

Dans le script, vous lisez et écrivez des documents avec document.get, document.list, document.create et document.update, et vous prévenez des personnes avec notification.send. Les écritures issues des hooks sont marquées comme automatiséesà : un hook qui écrit ce qu’il observe ne peut pas boucler.

Un hook planifié remplace la source par une expression cron : cinq champs numériques, en UTC, avec des incréments / admis. Les macros comme @daily et le champ des secondes sont refusés. L’exemple ci-dessous montre une entrée planifiée complète.

Facet compile chaque script quand vous enregistrez le domaine. Un script qui ne compile pas, ou qui ne définit pas la bonne fonction, est refusé. Une modification prend effet au prochain événement ou au prochain passage planifié, sans redémarrage.

Une consolidation qui compte chaque nuit les contrats actifs dans un document Dashboard du domaine propriétaire. Déclarez le hook avec kind: "schedule" et schedule: "0 3 * * *". La valeur script est le texte ci-dessousà :

local export = {}
function export.on_schedule(ctx)
local ok, result = pcall(document.list, "Contract", { status = "active" })
if not ok then
ctx.error("roll-up failed: " .. tostring(result))
return
end
local ok2, doc = pcall(document.get, "Dashboard", "01JD5R6Y8K31N4TQZ9W2B5XDEF")
if not ok2 then
ctx.error("dashboard row missing: " .. tostring(doc))
return
end
local body = util.json_decode(doc.content)
body.open_contracts = result.total
document.update("Dashboard", "01JD5R6Y8K31N4TQZ9W2B5XDEF", body)
end
return export

La planification "0 3 * * *" l’exécute chaque jour à 03:00 UTC. Les lectures et les écritures restent dans le domaine propriétaire, donc aucune attribution n’est nécessaire.

Le hook ne se déclenche jamais.

Vérifiez la sourceà : le domaine doit être réel, le doctype doit exister, et une source étrangère exige une attribution active. Un hook tout neuf part aussi du moment présentà ; il ne rejoue pas les événements passés.

Le script échoue à l’exécution.

Le déclenchement journalise l’erreur et continue. Corrigez le script et enregistrez de nouveau le domaineà ; rien ne rejoue le déclenchement manqué.

Ma planification n’a pas tourné pendant une panne.

Un passage manqué est perdu. L’échéance suivante s’exécute normalement.