LifterLMS Custom Reports: How to Build the Reports You Actually Need
When the built-in LifterLMS reporting is not enough: where the data lives, four ways to build custom reports, and a complete plugin that adds a…
Read articleLifterLMS engagements award achievements, award certificates and send emails when a student does something: enrolls, completes a lesson, passes a quiz, finishes a course. The built-in list covers the common moments. A LifterLMS custom engagement trigger lets you add your own, such as "reached 50% of a course", "completed their profile" or "submitted a project in another system", and configure the reward in the normal admin screen.
This guide is for developers. It explains how the engagement engine decides what to award, shows how to register new triggers with the filters LifterLMS provides, and how to award a certificate or achievement directly from code when a configurable trigger is more than you need. All hooks were checked against LifterLMS 10.3.
If you are new to engagements, start with our overview of LifterLMS engagements and automated emails, then come back here.
An engagement is an llms_engagement post with four settings in the Engagement Settings box: Triggering Event, an optional related post (such as Select a Course), Engagement Type with Select an Engagement, and Engagement Delay in days. They are saved as post meta: _llms_trigger_type, _llms_engagement_trigger_post, _llms_engagement_type, _llms_engagement and _llms_engagement_delay.
At runtime the LLMS_Engagements class does four things:
lifterlms_engagement_actions filter. The defaults include lifterlms_lesson_completed, lifterlms_course_completed, lifterlms_quiz_passed, llms_user_enrolled_in_course and lifterlms_user_registered.lifterlms_external_engagement_query_arguments filter.lifterlms_engagement_award_achievement, lifterlms_engagement_award_certificate and lifterlms_engagement_send_email.The labels in the Triggering Event dropdown come from llms_get_engagement_triggers(), which is filterable with lifterlms_engagement_triggers. So a complete custom trigger needs a label, a hook to listen to, and a parser for that hook.
| Built-in trigger | Related post |
|---|---|
| Student creates a new account | None |
| Student enrolls in a course / purchases a course | Course |
| Student completes a lesson, section, course or course track | Lesson, section, course or track |
| Student completes, passes or fails a quiz | Quiz |
| Student enrolls in or purchases a membership | Membership |
| Student Purchases an Access Plan | Access plan |
What is missing are progress milestones, inactivity, profile or onboarding steps, events in other systems (a CRM stage, a live class attended, a form submitted), and combinations such as "completed all three courses in a track before a date". The source even contains a commented-out "days since last login" trigger marked as a to-do. Those are the cases for custom triggers.
The plugin below adds two triggers. "Student completes their profile" has no related post. "Student reaches 50% of a course" is tied to a course, so admins can choose a specific course or leave it blank for any course.
<?php
/**
* Plugin Name: LLMSX Custom Engagement Triggers
*/
defined( 'ABSPATH' ) || exit;
// 1. Add the triggers to the "Triggering Event" dropdown.
add_filter(
'lifterlms_engagement_triggers',
function ( $triggers ) {
$triggers['llmsx_profile_completed'] = 'Student completes their profile';
$triggers['llmsx_course_halfway'] = 'Student reaches 50% of a course';
return $triggers;
}
);
// 2. Show the "Select a Course" field for the course-based trigger.
add_filter(
'llms_engagement_controller_values_course',
function ( $values ) {
$values[] = 'llmsx_course_halfway';
return $values;
}
);
// 3. Save the chosen course. Core only stores it for its own triggers.
add_action(
'save_post_llms_engagement',
function ( $post_id ) {
$nonce = isset( $_POST['lifterlms_meta_nonce'] ) ? sanitize_text_field( wp_unslash( $_POST['lifterlms_meta_nonce'] ) ) : '';
if ( ! wp_verify_nonce( $nonce, 'lifterlms_save_data' ) ) {
return;
}
if ( 'llmsx_course_halfway' !== get_post_meta( $post_id, '_llms_trigger_type', true ) ) {
return;
}
$course_id = isset( $_POST['_faux_engagement_trigger_post_course'] ) ? absint( $_POST['_faux_engagement_trigger_post_course'] ) : 0;
update_post_meta( $post_id, '_llms_engagement_trigger_post', $course_id ? $course_id : 'any' );
},
20
);
// 4. Make the engagement engine listen to our action hooks.
add_filter(
'lifterlms_engagement_actions',
function ( $hooks ) {
$hooks[] = 'llmsx_profile_completed';
$hooks[] = 'llmsx_course_halfway';
return $hooks;
}
);
// 5. Translate each hook's arguments into trigger type, user and related post.
add_filter(
'lifterlms_external_engagement_query_arguments',
function ( $parsed, $action, $args ) {
if ( in_array( $action, array( 'llmsx_profile_completed', 'llmsx_course_halfway' ), true ) ) {
$parsed['trigger_type'] = $action;
$parsed['user_id'] = absint( $args[0] );
$parsed['related_post_id'] = isset( $args[1] ) ? absint( $args[1] ) : '';
}
return $parsed;
},
10,
3
);
Step 3 is easy to miss. The engagement meta box only saves the related post for core trigger types; for anything else it stores an empty value. An engagement with an empty related post never matches an event that carries a post ID, so without this step a course-based custom trigger silently does nothing.
Your parser runs for every listened hook, so check $action and return $parsed unchanged for anything that is not yours.
Registering a trigger tells LifterLMS what to listen for. You still need to fire the action at the right moment. This example fires the halfway trigger once per course from the core lifterlms_lesson_completed action, and the profile trigger the first time the account form is saved with a phone number:
<?php
// Fire "llmsx_course_halfway" once, the first time a student passes 50%.
add_action(
'lifterlms_lesson_completed',
function ( $user_id, $lesson_id ) {
$lesson = llms_get_post( $lesson_id );
$course_id = $lesson ? absint( $lesson->get( 'parent_course' ) ) : 0;
if ( ! $course_id ) {
return;
}
$flag = 'llmsx_halfway_' . $course_id;
if ( get_user_meta( $user_id, $flag, true ) ) {
return;
}
$progress = llms_get_student( $user_id )->get_progress( $course_id, 'course', false );
if ( $progress >= 50 ) {
update_user_meta( $user_id, $flag, 1 );
do_action( 'llmsx_course_halfway', $user_id, $course_id );
}
},
20,
2
);
// Fire "llmsx_profile_completed" once, when the account form is first saved with a phone number.
add_action(
'lifterlms_user_updated',
function ( $user_id, $posted_data, $location ) {
if ( 'account' !== $location || empty( $posted_data['llms_phone'] ) ) {
return;
}
if ( ! get_user_meta( $user_id, 'llmsx_profile_completed', true ) ) {
update_user_meta( $user_id, 'llmsx_profile_completed', 1 );
do_action( 'llmsx_profile_completed', $user_id );
}
},
10,
3
);
Two points matter for reliability:
Events from other systems work the same way. A webhook receiver, a form plugin hook or a scheduled job calls do_action( 'llmsx_your_trigger', $user_id, $post_id ), and the engagement engine does the rest. For inactivity triggers, run a daily Action Scheduler job that finds students who have not logged in for a set number of days and fires your action for each one.
Sometimes you do not need an admin-configurable trigger. You know exactly which certificate to award and when: an instructor approves a project, or a student completes a course in an external system. Call the engagement handler directly:
<?php
/**
* Award a certificate template to a student from code.
*
* Runs the same checks as an engagement: the user and template must exist,
* the template must be published, the student must be enrolled in the
* related course, and the same certificate is not awarded twice.
*/
function llmsx_award_certificate( $user_id, $template_id, $course_id ) {
$result = LLMS_Engagement_Handler::handle_certificate(
array( $user_id, $template_id, $course_id, null )
);
if ( is_array( $result ) ) {
foreach ( $result as $error ) {
llms_log( $error->get_error_message(), 'llmsx-awards' );
}
return false;
}
return $result; // An LLMS_User_Certificate instance.
}
LLMS_Engagement_Handler::handle_achievement() takes the same arguments for achievements. The fourth argument is the engagement post ID; null is accepted for awards that do not come from an engagement, as when an admin awards a certificate manually. Awards made this way appear on the student's dashboard and in reporting like any other.
Do not create llms_my_certificate posts with wp_insert_post(). The handler also writes the link row in wp_lifterlms_user_postmeta, runs the duplicate check, copies the template's settings and fires the hooks that send notifications.
A few more filters are useful once custom triggers are in place:
llms_proccess_{$type}_engagement (note the spelling) lets you veto an award or email just before it is processed, for example to skip certificates for staff accounts. Return an array of WP_Error objects to block it.llms_earned_{$type}_dupcheck changes the duplicate rule, for example to allow a yearly recertification of the same template.lifterlms_engagement_types and lifterlms_external_engagement_handler_arguments let you add a new engagement type altogether, such as posting to Slack or tagging a contact in a CRM, handled by your own action.Our LifterLMS hooks and filters guide covers the wider hook system these sit in, and the code reference on the LifterLMS Developer Hub documents each class.
trigger_type and user_id._llms_engagement_trigger_post on the engagement post.lifterlms_engagement_award_* actions and confirm WP-Cron is running.Yes, with a small receiver: a REST route or webhook endpoint that verifies the request and calls your custom action. The LifterLMS REST API can also enroll students and update progress, which fires core triggers.
Yes. The trigger is independent of the engagement type, so the same trigger can send an email, award an achievement or award a certificate, depending on how the engagement is configured.
They use public filters and actions, not edits to core files, so they survive updates. Keep them in a small custom plugin and retest after major releases.
List the moments in your students' journey that deserve recognition but have no built-in trigger, and start with the one that matters most to completion. Build it as a small plugin, test it on staging with a real student account, then expose it to your team through the normal engagement screen.
If you want a set of custom triggers, rewards tied to external systems, or a full gamification layer, our LifterLMS plugin development team builds them to survive updates. Contact us with the moments you want to reward.
When the built-in LifterLMS reporting is not enough: where the data lives, four ways to build custom reports, and a complete plugin that adds a…
Read article
How to build a custom LifterLMS payment gateway: the order lifecycle, the LLMS_Payment_Gateway methods you implement, a hosted-checkout skeleton with…
Read article
Every shortcode in LifterLMS 10.3 core, grouped by job, with its real attributes, defaults and a working example, plus when to use a block instead…
Read articleSkip the trial and error. Get specialist LifterLMS help and ship faster.