====== LMS Automation Rules ======

===== Overview =====

LMS Automation Rules let administrators configure event-driven automations without writing code. Each rule defines:

  - A **Trigger** — the learner event that fires the rule
  - A **Condition** (optional) — a filter on event context (e.g. score >= 80)
  - An **Action** — what happens when the trigger fires and the condition passes

Rules are evaluated asynchronously — matched rules are enqueued to ''LMSRuleQueue'' and executed by the ''lms_rule_worker'' cron job.

===== Managing Rules =====

  - Navigate to **Admin → LMS Automation Rules**
  - Click **Add Rule** and configure trigger, condition, and action
  - Toggle rules on / off with the enable button
  - The **30d** column shows fired / skipped / error counts for the past 30 days
  - Use **Re-queue** on a dead-letter entry to retry a failed delivery

Cross-navigation: [[developer:webhooks|Workflow Webhooks]] → Admin → Workflow Webhooks

===== Supported Triggers =====

^ Trigger ^ Status ^ Notes ^
| ''lesson.completed'' | **Live** | Fires when a learner marks a lesson complete |
| ''badge.earned'' | Available | Fires when an Open Badge is issued |
| ''workflow.completed'' | Available | Fires when a workflow instance reaches End |
| ''user.created'' | Available | Fires on new account registration |
| ''certificate.awarded'' | Available | Fires when a course certificate is issued |
| ''deadline.approaching'' | Available | Cron-based deadline reminder |
| ''course.enrolled'' | Available | Fires on course enrolment |
| ''course.completed'' | Available | Fires on full course completion |
| ''path.completed'' | Available | Fires on learning path completion |
| ''cohort.joined'' | Available | Fires when a learner joins a cohort |
| ''quiz.passed'' | Pending | Quiz pass event not yet wired |
| ''quiz.failed'' | Pending | Quiz fail event not yet wired |

"Available" triggers appear in the rule editor. "Pending" triggers appear greyed-out; creating rules for them is possible but they will not fire until the underlying event dispatch is wired.

===== Conditions =====

^ Operator ^ Description ^ Required context key ^
| (none) | Always fires | — |
| ''score_gte'' | Score >= threshold | ''intScore'' |
| ''score_lt'' | Score < threshold | ''intScore'' |
| ''is_first_completion'' | Only the first time this rule fires for this learner | — |

===== Actions =====

^ Action type ^ Description ^ Config keys ^
| ''send_email'' | Email the learner or a fixed address | ''to'', ''subject'', ''body'' |
| ''award_badge'' | Issue an Open Badge to the learner | ''badge_id'' |
| ''notify_manager'' | Email notification to the association admin | ''subject'', ''body'' |
| ''webhook'' | HTTP POST to an external URL | ''url'', ''secret'' |
| ''enrol_course'' | Enrol the learner on a course | ''course_id'' |
| ''add_to_cohort'' | Add the learner to a cohort | ''cohort_id'' |

===== Webhook Action Payload =====

When the action type is ''webhook'', the rule engine POSTs:

<code json>
{
  "event":           "lesson.completed",
  "timestamp":       "2026-05-23T14:00:00+01:00",
  "intLessonId":     42,
  "strLessonTitle":  "Introduction to PHP",
  "intAssociationId": 7
}
</code>

Signed with ''X-WF-Signature: sha256=...'' if a secret is configured. See [[developer:webhooks|Webhooks]] for verification code. Note: learner login IDs are **not** included (GDPR data minimisation).

===== Execution Flow =====

<code>
Learner event fires
  → fn_Platform_Event_Fire()       [lib/libgeneral/fn_general_events.php]
  → fn_LMSRule_Dispatch()          [lib/liblmsrule/fn_lmsrule_dispatch.php]
     → Evaluate condition
     → fn_LMSRule_Enqueue()        INSERT INTO LMSRuleQueue
          ↓
cron/jobs/lms_rule_worker.php  (runs every minute)
  → fn_LMSRule_ExecAction()        send email / issue badge / POST webhook / etc.
  → UPDATE LMSRuleQueue status
  → INSERT INTO LMSRuleLog
</code>

===== Related Pages =====

  * [[developer:webhooks|Webhooks]] — Workflow Webhooks and Collection API Webhooks
  * [[developer:cookbook-webhooks|Cookbook — Receiving Webhooks]]
  * [[admin:badges|Open Badges]] — ''award_badge'' action
  * [[educator:workflow|Workflow Canvas]] — ''workflow.completed'' trigger