Moodle Grading Backlog Sentinel for Kestra

id: moodle-grading-backlog-sentinel
namespace: company.team
description: |
  On a schedule, read-only fetch every assignment and every submitted piece of
  work from a Moodle site through its web service API (nothing is graded,
  changed or deleted) and classify the marking backlog as HEALTHY, WARNING,
  CRITICAL or UNREACHABLE. Log quiet runs and page Slack when students have
  been waiting too long for their work to be marked.

inputs:
  - id: moodle_url
    type: STRING
    defaults: "https://moodle.example.edu"
    displayName: "Moodle Site URL"
    description: "Base URL of the Moodle site, without a trailing slash."
  - id: grace_days
    type: INT
    defaults: 7
    displayName: "Grace Period (days)"
    description: "For assignments without a 'remind me to grade by' date, a
      submission becomes overdue for marking this many days after it was
      submitted."
  - id: warning_overdue
    type: INT
    defaults: 1
    displayName: "Warning Overdue Submissions"
    description: "At or above this many submissions overdue for marking, the check
      is classified WARNING."
  - id: critical_overdue
    type: INT
    defaults: 20
    displayName: "Critical Overdue Submissions"
    description: "At or above this many submissions overdue for marking, the check
      is classified CRITICAL."
  - id: critical_age_days
    type: INT
    defaults: 14
    displayName: "Critical Age (days)"
    description: "If any submission is this many days past its marking deadline, the
      check is classified CRITICAL whatever the count."

variables:
  ws_endpoint: "{{ inputs.moodle_url
    }}/webservice/rest/server.php?moodlewsrestformat=json&wstoken={{
    secret('MOODLE_TOKEN') }}"

triggers:
  - id: weekday_backlog_check
    type: io.kestra.plugin.core.trigger.Schedule
    description: Check the marking backlog on weekday mornings at 08:00, before
      teaching starts. Shipped disabled; enable it once moodle_url and the
      MOODLE_TOKEN secret point at a real site and a manual run has been
      verified.
    cron: "0 8 * * MON-FRI"
    timezone: Asia/Kolkata
    disabled: true
    inputs:
      moodle_url: "https://moodle.example.edu"

tasks:
  - id: fetch_assignments
    type: io.kestra.plugin.core.http.Request
    description: Read every assignment the token's user can see, with its course and
      'remind me to grade by' date, through mod_assign_get_assignments. This is
      a GET; nothing in Moodle is changed.
    uri: "{{ render(vars.ws_endpoint) }}&wsfunction=mod_assign_get_assignments"
    method: GET
    options:
      allowFailed: true
      timeout:
        connectTimeout: PT10S
        readIdleTimeout: PT60S
    retry:
      type: constant
      interval: PT15S
      maxAttempts: 3
    allowFailure: true

  - id: fetch_submissions
    type: io.kestra.plugin.core.http.Request
    description: Read the submitted work for those assignments, with each
      submission's grading status, through mod_assign_get_submissions. Skipped
      when the assignment list could not be read, so the classification reports
      UNREACHABLE instead of guessing.
    runIf: "{{ outputs.fetch_assignments.code is defined and
      outputs.fetch_assignments.code == 200 and not
      (outputs.fetch_assignments.body contains 'exception') and
      (fromJson(outputs.fetch_assignments.body) |
      jq('[.courses[]?.assignments[]?] | length') | first) > 0 }}"
    uri: "{{ render(vars.ws_endpoint)
      }}&wsfunction=mod_assign_get_submissions&status=submitted&{{
      fromJson(outputs.fetch_assignments.body) |
      jq('[.courses[].assignments[].id] | to_entries | map(\"assignmentids[\" +
      (.key | tostring) + \"]=\" + (.value | tostring)) | join(\"&\")') | first
      }}"
    method: GET
    options:
      allowFailed: true
      timeout:
        connectTimeout: PT10S
        readIdleTimeout: PT60S
    retry:
      type: constant
      interval: PT15S
      maxAttempts: 3
    allowFailure: true

  - id: classify_backlog
    type: io.kestra.plugin.core.debug.Return
    description: Join submissions to their assignments, keep the work that is
      submitted but not yet marked, work out how late each one is against the
      assignment's marking deadline (or the grace period when none is set), and
      classify the backlog in one jq query. A missing response, a non-200 code,
      a Moodle exception body, no visible assignments, or no access to any
      submissions all become UNREACHABLE instead of looking healthy.
    format: >-
      {{ (outputs.fetch_assignments.code is not defined or
      outputs.fetch_assignments.code != 200 or outputs.fetch_assignments.body
      contains 'exception' or outputs.fetch_submissions is not defined or
      outputs.fetch_submissions.code is not defined or
      outputs.fetch_submissions.code != 200 or outputs.fetch_submissions.body
      contains 'exception') ?
      '{"status":"UNREACHABLE","assignments":0,"waiting":0,"overdue":0,"oldest_days":0,"no_access":0,"worst":"none"}'
      : ({'a': fromJson(outputs.fetch_assignments.body), 's':
      fromJson(outputs.fetch_submissions.body)} | jq(' .a as $a | .s as $s | ' ~
      (now() | timestamp) ~ ' as $now | ' ~ (inputs.grace_days * 86400) ~ ' as
      $grace | ([$a.courses[] | .shortname as $c | .assignments[] | {key: (.id |
      tostring), value: {course: $c, name: .name, gd: .gradingduedate}}] |
      from_entries) as $meta | [$s.assignments[] | (.assignmentid | tostring) as
      $id | .submissions[] | select(.status == "submitted" and (.gradingstatus
      == "notgraded" or .gradingstatus == "notmarked" or .gradingstatus ==
      "inmarking")) | $meta[$id] as $m | (if $m.gd > 0 then $m.gd else
      .timemodified + $grace end) as $deadline | {where: ($m.course + " / " +
      $m.name), late: ($now - $deadline)}] as $w | [$w[] | select(.late > 0)] as
      $o | ($meta | length) as $n | ($s.warnings | length) as $na | (if ($o |
      length) == 0 then 0 else ([$o[].late] | max) as $l | (($l - ($l % 86400))
      / 86400) end) as $age | {assignments: $n, waiting: ($w | length), overdue:
      ($o | length), oldest_days: $age, no_access: $na, worst: (if ($o | length)
      == 0 then "none" else ($o | group_by(.where) | map({k: .[0].where, c:
      length}) | max_by(.c) | .k + " (" + (.c | tostring) + ")") end), status:
      (if $n == 0 or $na >= $n then "UNREACHABLE" elif ($o | length) >= ' ~
      inputs.critical_overdue ~ ' or $age >= ' ~ inputs.critical_age_days ~ '
      then "CRITICAL" elif ($o | length) >= ' ~ inputs.warning_overdue ~ ' or
      $na > 0 then "WARNING" else "HEALTHY" end)} ') | first | toJson) }}

  - id: route_by_backlog
    type: io.kestra.plugin.core.flow.Switch
    description: Route to a quiet log when nothing is overdue for marking, an
      informational Slack message when some work is overdue, or a Slack page
      when the backlog is large or very old, or Moodle could not be read.
    value: "{{ fromJson(outputs.classify_backlog.value).status }}"
    cases:
      "HEALTHY":
        - id: log_healthy
          type: io.kestra.plugin.core.log.Log
          description: Log a quiet confirmation when no submission is past its marking
            deadline.
          message: "Moodle marking backlog healthy: {{
            fromJson(outputs.classify_backlog.value).waiting }} submission(s)
            waiting across {{
            fromJson(outputs.classify_backlog.value).assignments }}
            assignment(s), none past its marking deadline."
      "WARNING":
        - id: alert_warning_backlog
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          description: Post an informational Slack message when some submissions are past
            their marking deadline, or some assignments could not be read with
            the token's permissions.
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {
              "text": "Moodle marking backlog WARNING: {{ fromJson(outputs.classify_backlog.value).overdue }} submission(s) are past their marking deadline (oldest {{ fromJson(outputs.classify_backlog.value).oldest_days }} day(s) late), {{ fromJson(outputs.classify_backlog.value).waiting }} waiting in total. Biggest backlog: {{ fromJson(outputs.classify_backlog.value).worst }}. Assignments the token cannot read: {{ fromJson(outputs.classify_backlog.value).no_access }}. Execution {{ execution.id }}."
            }
      "CRITICAL":
        - id: alert_critical_backlog
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          description: Page Slack when the number of overdue submissions or the age of the
            oldest one crosses the critical line, which usually means feedback
            will miss the next deadline students depend on.
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {
              "text": "Moodle marking backlog CRITICAL: {{ fromJson(outputs.classify_backlog.value).overdue }} submission(s) are past their marking deadline, the oldest by {{ fromJson(outputs.classify_backlog.value).oldest_days }} day(s). Biggest backlog: {{ fromJson(outputs.classify_backlog.value).worst }}. Students are waiting for feedback. Execution {{ execution.id }}."
            }
      "UNREACHABLE":
        - id: alert_unreachable_moodle
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          description: Page Slack when Moodle could not be read at all, returned an error
            (for example an invalid or expired token), showed no assignments, or
            refused access to every assignment's submissions.
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {
              "text": "Moodle marking backlog UNREACHABLE: the web service at {{ inputs.moodle_url }} did not return usable assignment and submission data (site down, invalid or expired token, web services disabled, or the token's user cannot see any assignments). The marking backlog is unknown. Execution {{ execution.id }}."
            }
    defaults:
      - id: log_unclassified
        type: io.kestra.plugin.core.log.Log
        description: Log any classification outside the four known values, so a change
          in the jq query never fails silently.
        message: "Moodle marking backlog sentinel completed with an unexpected
          classification: {{ outputs.classify_backlog.value }}."

  - id: log_audit_result
    type: io.kestra.plugin.core.log.Log
    description: Record one audit line for every run, whichever branch fired, so the
      check's own history stays queryable even if Slack delivery fails.
    message: "Moodle marking backlog audit: site={{ inputs.moodle_url }}
      assignments_http={{ outputs.fetch_assignments.code ?? 'n/a' }}
      submissions_http={{ outputs.fetch_submissions.code ?? 'n/a' }} result={{
      outputs.classify_backlog.value }} execution={{ execution.id }}."

errors:
  - id: alert_flow_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    description: Alert Slack when the sentinel flow itself fails outright, so a
      broken check is never mistaken for an empty marking backlog.
    url: "{{ secret('SLACK_WEBHOOK') }}"
    payload: |
      {
        "text": "Moodle marking backlog sentinel flow {{ flow.id }} FAILED (execution {{ execution.id }}). The marking backlog at {{ inputs.moodle_url }} is unknown; check the task logs and the Moodle web service manually."
      }

outputs:
  - id: status
    type: STRING
    value: "{{ outputs.classify_backlog is defined ?
      fromJson(outputs.classify_backlog.value).status : 'UNREACHABLE' }}"
  - id: backlog
    type: JSON
    value: "{{ outputs.classify_backlog is defined ? outputs.classify_backlog.value
      : '{\"status\":\"UNREACHABLE\"}' }}"

Students submit work in Moodle and then wait. Moodle shows each teacher their own "needs grading" count, but nobody sees the whole site: which courses are past their marking deadline, how old the oldest unmarked submission is, or whether the backlog is growing week after week. This blueprint turns two read-only Moodle web service calls into a scheduled marking backlog gate: mod_assign_get_assignments returns every assignment with its "remind me to grade by" date, mod_assign_get_submissions returns every submitted piece of work with its grading status, a single jq query works out what is overdue and by how much, and the result routes to a quiet log, an informational Slack note or a Slack page.

How it works

fetch_assignments (io.kestra.plugin.core.http.Request) calls mod_assign_get_assignments and receives every course the token's user is enrolled in, with each assignment's id, name and gradingduedate. This is a GET: nothing is changed. allowFailed: true, a timeout, three retries and allowFailure: true keep a network blip or an outage from aborting the flow.
fetch_submissions (io.kestra.plugin.core.http.Request) builds the assignmentids[] list from the first response and calls mod_assign_get_submissions with status=submitted, which returns each submission's timemodified and gradingstatus. A runIf skips it when the assignment list is missing, is a Moodle error, or is empty.
classify_backlog (io.kestra.plugin.core.debug.Return) first guards for a missing response, a non-200 code, and a Moodle exception body (Moodle reports an invalid token with HTTP 200), then joins submissions to assignments in one jq query. It keeps submissions that are submitted and not yet marked (notgraded, or notmarked/inmarking when the marking workflow is on), and treats one as overdue once the assignment's gradingduedate has passed, or grace_days after it was submitted when the assignment has no marking deadline. It returns the counts, the oldest overdue age in days, the assignment with the biggest backlog, the number of assignments the token could not read, and the status: no visible assignments or no access to any of them is UNREACHABLE; at least critical_overdue overdue, or one at least critical_age_days late, is CRITICAL; at least warning_overdue overdue, or some assignments unreadable, is WARNING; otherwise HEALTHY.
route_by_backlog (io.kestra.plugin.core.flow.Switch) branches on that status: HEALTHY logs a quiet confirmation, WARNING posts an informational Slack note, CRITICAL and UNREACHABLE each page Slack, and a defaults fallback logs any unexpected value.
log_audit_result (io.kestra.plugin.core.log.Log) writes one audit line per run with both HTTP codes and the full classification, independent of which branch fired.
The flow-level errors block alerts Slack separately if the flow fails outright, so a broken sentinel is never mistaken for an empty backlog.
The weekday_backlog_check trigger runs at 08:00 on weekdays and ships disabled: true, with moodle_url pinned in its inputs.

What you get

A scheduled, read-only view of the marking backlog across every course the token's user can see, with no Moodle plugin to install.
A status output (HEALTHY / WARNING / CRITICAL / UNREACHABLE) other flows can gate on, and a backlog JSON output with assignments, waiting, overdue, oldest_days, no_access and worst.
Slack messages that say how many submissions are overdue, how late the oldest one is, and which assignment has the biggest backlog, for example BIO101 / Lab report 3 (4).
An audit log line on every run, so the backlog's history survives a Slack outage.

Who it's for

Heads of department and programme leads who want to know when feedback is falling behind, before students complain.
Academic quality and learning technology teams who run Moodle for a whole school, college or university.
Teams already using Kestra for data pipelines who want the same alerting for their learning platform.

Why orchestrate this with Kestra

Moodle's own grading reminders are per teacher and per assignment, and there is no built-in site-wide alert when marking falls behind. Kestra runs the same read-only check on a schedule, keeps every result in the execution history, classifies it in one typed status, and routes it to the right channel, while the Switch branches are ready to grow into real follow-up (a digest per department, a ticket for the course lead) without rewriting the check.

Prerequisites

A Moodle site (4.x or 5.x) with web services and the REST protocol enabled (Site administration > General > Web services).
A dedicated Moodle account with the non-editing teacher role in the courses to watch (it needs mod/assign:grade to see submissions), and a web service token for an external service that contains only mod_assign_get_assignments and mod_assign_get_submissions.
A Slack incoming webhook for the WARNING, CRITICAL, UNREACHABLE and flow-failure alerts.

Secrets

MOODLE_TOKEN: Moodle web service token for the monitoring account.
SLACK_WEBHOOK: Slack incoming webhook used for every alert branch and the flow-failure alert.

In Kestra OSS (no Enterprise secrets backend), secrets are supplied as environment variables prefixed SECRET_ and base64-encoded, then read in flows with {{ secret('NAME') }}, for example SECRET_MOODLE_TOKEN=$(echo -n '<token>' | base64).

Quick start

To try it without a production site, run Moodle locally (for example the official moodlehq/moodle-php-apache image or a PHP and PostgreSQL install), and create a course with a few students and an assignment.
In Site administration > Server > Web services, enable web services and the REST protocol, create an external service with the two functions above, and create a token for a monitoring account enrolled as non-editing teacher.
Add MOODLE_TOKEN and SLACK_WEBHOOK as secrets, set moodle_url, and run the flow once manually. The status output reads HEALTHY when nothing is past its marking deadline.
Set an assignment's "remind me to grade by" date in the past while it has ungraded submissions and run again: the status becomes WARNING and Slack receives the overdue count.
Enable weekday_backlog_check once pointed at the real site.

How to extend

Pass courseids[] to mod_assign_get_assignments to watch one faculty or programme instead of every course the token can see.
Group the overdue submissions by course in the jq query and send each department its own Slack channel through a ForEach.
Store status and overdue in the KV store and alert only when the backlog grows, not on every run.
Add the same pattern for quizzes with manually graded questions through mod_quiz_get_attempts style calls.

Inputs

moodle_url: type STRING, default "https://moodle.example.edu".
grace_days: type INT, default 7.
warning_overdue: type INT, default 1.
critical_overdue: type INT, default 20.
critical_age_days: type INT, default 14.

Outputs

status: one of HEALTHY, WARNING, CRITICAL, UNREACHABLE.
backlog: the full classification as JSON, for example {"assignments":4,"waiting":15,"overdue":7,"oldest_days":5,"no_access":0,"worst":"BIO101 / Lab report 3 (4)","status":"WARNING"}.

Pitfalls

Moodle web services take the token as the wstoken query parameter, so it is part of the request URL. Keep HTTP request logging off on any proxy in between, and use a dedicated account with the smallest role that can see submissions.
Moodle answers an invalid token, a missing permission or a disabled function with HTTP 200 and an exception body. The flow checks for that body explicitly, so these cases report UNREACHABLE instead of an empty, healthy-looking backlog.
Assignments the token's user cannot grade come back as warnings, not submissions. Some unreadable assignments raise WARNING; if none can be read, the check is UNREACHABLE.
mod_assign_get_submissions returns every submission for every listed assignment in one response. On a very large site, filter by course (see How to extend) to keep the response small.
The check only reads. It never grades, extends deadlines or messages students.