utils/plugins/events.js.Plugins are JavaScript classes placed in the ./plugins directory (or compiled into ./plugins_builtin). Every plugin extends one of two base classes depending on its scope:
LRSPlugin (./utils/plugins/lrsPlugin.js): Configured and enabled per LRS instance. Its constructor receives (lrs, dal, settings), giving it direct access to this.lrs (the LRS model), this.dal (the xAPI Data Access Layer for that LRS), this.odm (the LRS-level Mongoose ODM models), and this.settings (the administrator-configured settings for that plugin instance).SystemPlugin (./utils/plugins/systemPlugin.js): Configured at the global system level by a site administrator. Its constructor receives (odm, settings), where this.odm contains the system-level Mongoose models. Importantly, System plugins also receive all LRS-scoped events from every LRS on the server: when an LRS event is dispatched to a System plugin, the target lrs object is automatically prepended as the first argument after the event metadata object.Inside your plugin's constructor, subscribe to registered events using this.on(eventName, handler). The first parameter passed to every handler is the internal event wrapper e, followed by the event parameters documented below:
const LRSPlugin = require('./utils/plugins/lrsPlugin');
module.exports = class MyCustomPlugin extends LRSPlugin {
constructor(lrs, dal, settings) {
super(lrs, dal, settings);
// Example: Intercept a batch of incoming xAPI statements before storage
this.on('statementBatchReceived', async (event, batch) => {
// Since statementBatchReceived has noWrap = false, clone before mutating
const modified = JSON.parse(JSON.stringify(batch));
// ... inspect or transform modified.statements ...
return modified;
});
}
static get display() {
return { title: 'My Custom Plugin', description: 'Example LRS plugin' };
}
};
module.exports.pluginName = 'MyCustomPlugin';Events are dispatched by pluginManager in one of two ways:
lrsEvent / systemEvent): Executed sequentially across active plugins. If the event's resultSchema is null, it is a fire-and-forget notification and handlers must not return a truthy value (doing so will throw a validation error). If resultSchema is defined, a plugin may return a value matching that schema to override or supply the result.lrsGather / systemGather): Used when collecting lists of items from all active plugins (such as sidebar links, dashboard widgets, login links, or LTI actions). Every plugin's return value (or array of return values) is combined into a single array, and each element is validated against resultSchema using JSON Schema.noWrapBy default (noWrap = false), non-primitive arguments passed to plugin handlers are wrapped in a read-only ES6 Proxy so plugins cannot accidentally mutate shared host objects in place. If your plugin needs to return a modified object (for example, in statementBatchReceived or chartRender), clone the parameter first (e.g., via JSON.parse(JSON.stringify(arg))) and return the modified copy. When an event is registered with noWrap = true (such as preAuthReq, portal_preAuthReq, or statementBatchStored) or when specific properties are wrapped with pluginManager.noWrap(...) (such as xAPIAuth and ltiAction), the actual underlying objects (like Express req and res) are passed directly so you can invoke methods on them.
await this.getState() and await this.persistState(newState) (or getStateLocked() / releaseStateLocked() for concurrent updates) to store arbitrary JSON state on the plugin's database record.express.Router(), register it with this.setRouter('lrs' | 'system' | 'portal', router), and generate full URLs to your plugin's routes using this.getLink('/my-route', 'lrs').await this.every('10 minutes', 'mySignal', data) or await this.schedule(when, 'mySignal', data) and handle them with this.onInterval('mySignal', async (e, data) => { ... }).An xAPI transaction requires authorization. Receives unwrapped req and res objects; return an Account object or null.
Fired on every incoming xAPI HTTP request to authenticate the caller. Receives the unwrapped Express req and res objects (wrapped with pluginManager.noWrap). Authentication plugins (such as Basic Auth, JWT Bearer Auth, Okta Auth, or Portal Session Auth) inspect the Authorization header or session and return an xAPI Account instance (with read/write permissions and authority info) or null if authentication fails.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
arrayPositional parameters: [req, res] (unwrapped via pluginManager.noWrap)
Positional Arguments:
View Raw JSON Schema
|
Type:
object | nullAn xAPI Account object representing the authenticated caller, or null
Object Properties:
View Raw JSON Schema
|
An xAPI state document is about to be deleted
Fired when a DELETE request arrives for an xAPI State document, prior to deleting the document from storage. Receives an object containing the document id and URL query parameters, and allows a plugin to return a modified { id, query } object before deletion is executed.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectObject Properties:
View Raw JSON Schema
|
Type:
objectObject Properties:
View Raw JSON Schema
|
An xAPI state document was deleted
Fired after an xAPI State document has been deleted from storage. Receives an object containing the deleted document's id and the request query parameters. This is a notification event and does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectObject Properties:
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
An xAPI state document GET query was received
Fired when a GET request arrives for an xAPI State document, prior to building the lookup context and querying the database. Receives the URL req.query object and allows a plugin to return a modified query object.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe URL query of the request
View Raw JSON Schema
|
Type:
objectThe modified URL query
View Raw JSON Schema
|
An xAPI query result for a state document is being sent to a client
Fired when a single xAPI State document has been retrieved from storage and prepared for serving, immediately before sending the HTTP response. Receives the stored document payload and allows a plugin to return a transformed payload.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
The value that was previously stored for this document
View Raw JSON Schema
|
The modified payload to send to the client
View Raw JSON Schema
|
An xAPI state document was received via POST or PUT
Fired when an xAPI State document is received via POST or PUT, prior to ETag concurrency validation and storage. Receives { id, query, body, method } and allows a plugin (such as GDPR filtering) to inspect or return a modified { id, query, body, method } object.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectObject Properties:
View Raw JSON Schema
|
Type:
objectObject Properties:
View Raw JSON Schema
|
An xAPI state document was stored
Fired immediately after an xAPI State document has been saved to the LRS document storage via POST or PUT. Receives { id, query, body, method }. This is a post-storage notification event and does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectObject Properties:
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
An xAPI activityProfile document is about to be deleted
Fired when a DELETE request arrives for an xAPI Activity Profile document, prior to deleting the document from storage. Receives an object containing the document id and URL query parameters, and allows a plugin to return a modified { id, query } object before deletion is executed.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectObject Properties:
View Raw JSON Schema
|
Type:
objectObject Properties:
View Raw JSON Schema
|
An xAPI activityProfile document was deleted
Fired after an xAPI Activity Profile document has been deleted from storage. Receives an object containing the deleted document's id and the request query parameters. This is a notification event and does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectObject Properties:
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
An xAPI activityProfile document GET query was received
Fired when a GET request arrives for an xAPI Activity Profile document, prior to building the lookup context and querying the database. Receives the URL req.query object and allows a plugin to return a modified query object.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe URL query of the request
View Raw JSON Schema
|
Type:
objectThe modified URL query
View Raw JSON Schema
|
An xAPI query result for a activityProfile document is being sent to a client
Fired when a single xAPI Activity Profile document has been retrieved from storage and prepared for serving, immediately before sending the HTTP response. Receives the stored document payload and allows a plugin to return a transformed payload.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
The value that was previously stored for this document
View Raw JSON Schema
|
The modified payload to send to the client
View Raw JSON Schema
|
An xAPI activityProfile document was received via POST or PUT
Fired when an xAPI Activity Profile document is received via POST or PUT, prior to ETag concurrency validation and storage. Receives { id, query, body, method } and allows a plugin (such as GDPR filtering) to inspect or return a modified { id, query, body, method } object.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectObject Properties:
View Raw JSON Schema
|
Type:
objectObject Properties:
View Raw JSON Schema
|
An xAPI activityProfile document was stored
Fired immediately after an xAPI Activity Profile document has been saved to the LRS document storage via POST or PUT. Receives { id, query, body, method }. This is a post-storage notification event and does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectObject Properties:
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
An xAPI agentProfile document is about to be deleted
Fired when a DELETE request arrives for an xAPI Agent Profile document, prior to deleting the document from storage. Receives an object containing the document id and URL query parameters, and allows a plugin to return a modified { id, query } object before deletion is executed.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectObject Properties:
View Raw JSON Schema
|
Type:
objectObject Properties:
View Raw JSON Schema
|
An xAPI agentProfile document was deleted
Fired after an xAPI Agent Profile document has been deleted from storage. Receives an object containing the deleted document's id and the request query parameters. This is a notification event and does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectObject Properties:
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
An xAPI agentProfile document GET query was received
Fired when a GET request arrives for an xAPI Agent Profile document, prior to building the lookup context and querying the database. Receives the URL req.query object and allows a plugin to return a modified query object.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe URL query of the request
View Raw JSON Schema
|
Type:
objectThe modified URL query
View Raw JSON Schema
|
An xAPI query result for a agentProfile document is being sent to a client
Fired when a single xAPI Agent Profile document has been retrieved from storage and prepared for serving, immediately before sending the HTTP response. Receives the stored document payload and allows a plugin to return a transformed payload.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
The value that was previously stored for this document
View Raw JSON Schema
|
The modified payload to send to the client
View Raw JSON Schema
|
An xAPI agentProfile document was received via POST or PUT
Fired when an xAPI Agent Profile document is received via POST or PUT, prior to ETag concurrency validation and storage. Receives { id, query, body, method } and allows a plugin (such as GDPR filtering) to inspect or return a modified { id, query, body, method } object.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectObject Properties:
View Raw JSON Schema
|
Type:
objectObject Properties:
View Raw JSON Schema
|
An xAPI agentProfile document was stored
Fired immediately after an xAPI Agent Profile document has been saved to the LRS document storage via POST or PUT. Receives { id, query, body, method }. This is a post-storage notification event and does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectObject Properties:
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
An xAPI statement was received via PUT
Fired when a single xAPI statement is received via PUT /statements prior to batch processing and storage. Receives an object containing { statement, authority, meta } and allows the plugin to return a modified { statement, authority, meta } object to transform or enrich the statement before validation and storage.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectObject Properties:
View Raw JSON Schema
|
Type:
objectObject Properties:
View Raw JSON Schema
|
A batch of xAPI statements was received
Fired when a batch of xAPI statements is received (via POST /statements, PUT /statements, or upstream forwarding) prior to DAL storage. Receives { statements, authority, meta } and allows plugins (such as GDPR opt-out filtering, actor mapping, or statement rewriting) to filter, enrich, or replace the statements array before they are written to MongoDB.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectObject Properties:
View Raw JSON Schema
|
Type:
objectObject Properties:
View Raw JSON Schema
|
A batch of statements was stored in the LRS database
Fired asynchronously (throttled in batches) after statements have been validated and stored in the LRS MongoDB database. Receives the unwrapped array of stored statement documents (noWrap = true). Used by built-in and custom post-processing plugins including Canonical Mapping, Elasticsearch indexing, SQL mirroring, Webhooks, and Upstream forwarding. Does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
arrayArray of stored xAPI statement documents
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
An xAPI statement query was issued
Fired when a GET /statements query request arrives, before the xAPI query parameters are compiled into a MongoDB filter. Receives the original req.query object and allows a plugin to return a modified xAPI query object.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe original xAPI statement query parameters
View Raw JSON Schema
|
Type:
objectThe modified xAPI statement query parameters
View Raw JSON Schema
|
Internal logic for mapping the xAPI querystring to a MongoDB query
Fired inside the DAL during statement retrieval after the xAPI query parameters have been translated into an internal MongoDB query filter object. Plugins (such as Search-on-Stored) can return a modified MongoDB query object to alter how statements are matched or sorted.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe original internal MongoDB query
View Raw JSON Schema
|
Type:
objectThe modified internal MongoDB query
View Raw JSON Schema
|
The results of an xAPI statement query before being returned to the caller
Fired after an xAPI statement query has executed and before the result payload is sent to the client. Receives the result payload (either a single statement object or { statements: [...], more: "..." }) and allows a plugin to return a modified result payload.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe original statement query result payload
View Raw JSON Schema
|
Type:
objectThe modified statement query result payload
View Raw JSON Schema
|
A generic xAPI HTTP request was made
Fired on every HTTP request to any xAPI endpoint ("/xapi/*"). Receives an object containing the request URL, HTTP method, query parameters, target LRS object, and client IP address. Used for audit logging and traffic monitoring; does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectObject Properties:
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
Retrieve the list of dashboards available for an LRS
Used internally and by dashboard management plugins (such as Role-Based Dashboards) to retrieve the list of available built-in, plugin, and custom dashboards for a given LRS. Handlers return dashboard configuration objects containing the dashboard name, title, category, visibility, and parameter definitions.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe LRS model instance or Express request object
View Raw JSON Schema
|
Type:
objectA dashboard configuration object
Object Properties:
View Raw JSON Schema
|
Gather additional widget/graph definitions for the LRS Overview dashboard
Gathered when building the widget list for the main LRS Overview dashboard. Plugins can return one or more widget configuration objects (each specifying a processor handler name and params) to dynamically append custom charts to the LRS Overview dashboard.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
arrayPositional parameters: [lrs, params]
Positional Arguments:
View Raw JSON Schema
|
Type:
objectA widget/graph configuration object
Object Properties:
View Raw JSON Schema
|
Gather additional widget/graph definitions for the Learner/Agent Overview dashboard
Gathered when building the widget list for the Learner Overview dashboard (in both the Learner Portal and the LRS Agent/Learner dashboard view). Plugins can return widget configuration objects to append custom learner-level charts.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe dashboard parameters object
View Raw JSON Schema
|
Type:
objectA widget/graph configuration object
Object Properties:
View Raw JSON Schema
|
Gather additional widget/graph definitions for the Activity Overview dashboard
Gathered when computing the widget list for the Activity Overview dashboard. Receives the current dashboard parameters (including the selected activityId) and the canonical activity record from canonicalActivities. Plugins can return additional widget definitions tailored to that activity.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
arrayPositional parameters: [params, canonical]
Positional Arguments:
View Raw JSON Schema
|
Type:
objectA widget/graph configuration object
Object Properties:
View Raw JSON Schema
|
Modify an amCharts chart setup object before it is sent to the client
Fired after an analytic processor builds an amCharts chartSetup configuration object. Theme or styling plugins can inspect and return a modified copy of the amCharts configuration (for example, overriding color palettes, stroke widths, or fonts) before it is sent to the browser.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe original amCharts configuration object (chartSetup)
View Raw JSON Schema
|
Type:
objectThe modified amCharts configuration object
View Raw JSON Schema
|
Supply custom CSS when rendering analytics dashboards
Fired when rendering analytics dashboards to allow theme plugins to supply custom CSS styling. Return a CSS stylesheet string to override widget backgrounds, typography, borders, or chart container styles.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
None (null) — No parameters are passed to this event. |
Type:
stringCSS string to inject into the analytics view
View Raw JSON Schema
|
Returns a list of dashboards that are valid for the current user/lrs
Gathered by dashboard permission management plugins to determine which plugin-provided dashboards are authorized for a given scope ("lrs", "system", or "learner") and LRS instance (based on owner user ID, user tier, or LRS UUID). Returns allowed dashboard configuration objects.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
arrayPositional parameters: [scope, lrs]
Positional Arguments:
View Raw JSON Schema
|
Type:
objectObject Properties:
View Raw JSON Schema
|
Returns a list of dashboard parameters for the given dashboard and lrs
Used to retrieve or customize the list of dashboard parameter definitions for a specified dashboard and LRS. Returns parameter descriptor objects with a required name property.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
arrayPositional parameters: [dashboardName, lrs]
Positional Arguments:
View Raw JSON Schema
|
Type:
objectObject Properties:
View Raw JSON Schema
|
Returns a list of plugins that are valid for the current user/lrs
Gathered when an LRS administrator visits the "Add Plugin" page ("/ui/lrs/:id/plugins/add"). System permission plugins filter and return the list of plugin metadata objects ({ name, title, description, filename, buildIn }) that the given LRS is permitted to install.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
arrayPositional parameters: [scope, lrs]
Positional Arguments:
View Raw JSON Schema
|
Type:
objectObject Properties:
View Raw JSON Schema
|
Given the name of a plugin analytics processor, should it be allowed
Fired when enumerating custom plugin analytic processors for an LRS in the custom report/dashboard builder. Receives the scope ("lrs"), the processor handler name, and the LRS instance. Return true if the LRS is authorized to use the specified analytic processor.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
arrayPositional parameters: [scope, processorName, lrs]
Positional Arguments:
View Raw JSON Schema
|
Type:
booleanView Raw JSON Schema
|
The system is asking if a given plugin is allowed to be installed
Fired before installing/creating a plugin in an LRS or via the pluginConfig API to verify that the plugin is permitted for the target scope and LRS. Receives the pluginName string, scope ("lrs" or "system"), and LRS model instance. Return true to allow installation or false to reject with an authorization error.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
arrayPositional parameters: [pluginName, scope, lrs]
Positional Arguments:
View Raw JSON Schema
|
Type:
booleanWhether the plugin is allowed for the given scope and LRS
View Raw JSON Schema
|
The system is asking if a given dashboard is installed and enabled for an LRS
Fired when building the list of available dashboards for an LRS or learner scope to check whether a plugin-provided dashboard or custom dashboard is enabled for that LRS and scope. Receives the dashboard configuration object and the scope string. Return true if the dashboard should be included.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
arrayPositional parameters: [dashboardDef, scope]
Positional Arguments:
View Raw JSON Schema
|
Type:
booleanWhether the dashboard is installed and allowed for the LRS and scope
View Raw JSON Schema
|
The VQL system has run the $toCanonicalDisplay stage. You may replace the result, or supply your own canonical value
Fired during execution of the VQL $toCanonicalDisplay stage after the default canonical lookup has resolved an actor, verb, activity, activity type, profile, or template identifier. Receives the lookup mode, the identifier key, and the default canonical result object. A plugin can return a replacement object with a display string property (for example, to pseudonymize learner names or supply custom labels).
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
arrayPositional parameters: [mode, key, result]
Positional Arguments:
View Raw JSON Schema
|
Type:
objectObject Properties:
View Raw JSON Schema
|
Can any plugin provide a VQL stage parser class for this command
Fired by the VQL Planner when it encounters a processing stage command name that is not in the built-in stage registry. Receives the stageName string (e.g., "$myCustomStage"). A plugin can return a custom VQL command parser class (extending analytics/engine/parsers/command.js) to extend the VQL language.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
stringThe VQL stage command name (e.g. "$myStage")
View Raw JSON Schema
|
Type:
function | objectA VQL stage parser class extending analytics/engine/parsers/command.js
View Raw JSON Schema
|
Where should users be redirected to on successful site login
Fired immediately after a system-level user successfully logs into the management UI. If a plugin returns a URL string, the user's browser will be redirected to that URL instead of the default "/ui/users/home/" landing page.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe authenticated system User ODM model instance
View Raw JSON Schema
|
Type:
stringThe URL to redirect the user to on successful site login
View Raw JSON Schema
|
Where should users be redirected to on successful portal login
Fired immediately after a learner successfully logs into an LRS Learner Portal. If a plugin returns a URL string (such as an acknowledgment page or custom portal route), the learner is redirected there instead of the default portal home page.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe Learner/User model
View Raw JSON Schema
|
Type:
stringThe URL to redirect the learner to on successful portal login
View Raw JSON Schema
|
Add additional data to the portal head
Gathered when rendering Learner Portal pages (home, content launch, and public content views). Plugins can return an HTML string to inject custom stylesheets, scripts, or metadata into the portal <head>.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
object | nullThe current portal Learner/User object (if logged in)
View Raw JSON Schema
|
Type:
stringHTML content to insert into the portal <head>
View Raw JSON Schema
|
Fired when a UI request comes in, prior to authentication
Fired early in the "/ui" request pipeline before authentication checks are enforced. Receives the raw, unwrapped Express req and res objects (noWrap = true) so plugins can read/write session state or render custom responses (such as a mandatory login acknowledgment banner). Returning false halts the Express middleware chain so next() is not called.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
arrayPositional parameters: [req, res]
Positional Arguments:
View Raw JSON Schema
|
Type:
booleanReturn false to stop normal request processing when the plugin has handled the response; return true or undefined to continue
View Raw JSON Schema
|
Fired when a UI request comes in that requires authentication that is missing
Fired when an unauthenticated user hits the system login page ("/ui/users/login"). SSO plugins (such as OIDC, SAML, or CAC/PKI header auth) that are configured to override built-in authentication can return a redirect URL string to immediately send the user to the external Identity Provider.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
arrayPositional parameters: [req, res]
Positional Arguments:
View Raw JSON Schema
|
Type:
stringThe URL to redirect to
View Raw JSON Schema
|
Fired when a Learner Portal request comes in, prior to authentication
Fired early in the Learner Portal request pipeline prior to portal authentication. Receives the raw, unwrapped Express req and res objects (noWrap = true). Returning false stops normal request processing when the plugin has already sent a response or redirect.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
arrayPositional parameters: [req, res]
Positional Arguments:
View Raw JSON Schema
|
Type:
booleanReturn false to stop normal request processing when the plugin has handled the response; return true or undefined to continue
View Raw JSON Schema
|
Fired when a Learner Portal request comes in that requires authentication that is missing
Fired when an unauthenticated learner visits the Learner Portal login page. Portal SSO plugins (such as Google OAuth or OpenID Connect for Portal) can return a redirect URL string to initiate the external login flow instead of rendering the standard portal login form.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
arrayPositional parameters: [req, res]
Positional Arguments:
View Raw JSON Schema
|
Type:
stringThe URL to redirect to
View Raw JSON Schema
|
Render links on the Learner Portal login page
Gathered when rendering the Learner Portal login page to display external authentication links (such as "Login with Google" or "Login with OpenID"). Each plugin can return an object with text and href properties.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
object | nullThe current portal Learner/User object (if any)
View Raw JSON Schema
|
Type:
objectObject Properties:
View Raw JSON Schema
|
Render an item onto the main Learner Portal (when a learner is logged in)
Gathered when rendering the Learner Portal home page for a logged-in learner. Plugins can return custom content cards/sections (each with a title and HTML body) to display personalized links, role-assigned dashboards, or GDPR opt-out controls. Receives the logged-in Learner model instance.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
object | nullThe logged-in Learner ODM model instance
View Raw JSON Schema
|
Type:
objectObject Properties:
View Raw JSON Schema
|
Render an announcement onto the main Learner Portal (when a learner is logged in)
Gathered when rendering the Learner Portal home page to display alert or announcement banners to learners. Plugins return an object with a body string and a Bootstrap/UI alert type string (e.g., "info", "warning", "success", "danger").
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
object | nullThe logged-in Learner ODM model instance
View Raw JSON Schema
|
Type:
objectObject Properties:
View Raw JSON Schema
|
A learner password was reset
Fired when a learner's password is reset by an administrator or via the password reset flow. Receives the Learner ODM model instance. Does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe LRS learner ODM model instance
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
A learner requested a forgot-password reset key
Fired when a temporary password reset credential is generated for a learner via the forgot-password workflow. Receives the Learner ODM model instance. Does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe LRS learner ODM model instance
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
A learner was deleted from an LRS
Fired after a Learner account is deleted from an LRS. Receives the deleted Learner ODM model instance. Does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe deleted LRS learner ODM model instance
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
A learner submitted a self-asserted xAPI statement via the Learner Portal
Fired when a learner submits a self-asserted learning record via the Learner Portal prior to storing the generated xAPI statement. Receives the Learner ODM model instance and the constructed xAPI statement body. Does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
arrayPositional parameters: [learner, statementBody]
Positional Arguments:
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
A learner updated their own account profile in the Learner Portal
Fired after a learner updates their own profile details in the Learner Portal. Receives the updated Learner ODM model instance. Does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe updated LRS learner ODM model instance
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
A learner logged out of the Learner Portal
Fired when a learner logs out of the Learner Portal and their portal session is cleared. Receives the Learner ODM model instance. Does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe LRS learner ODM model instance
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
A learner successfully logged into the Learner Portal
Fired when a learner is successfully authenticated into the Learner Portal (either via a custom learnerLogin plugin or via standard local learner credentials). Receives the authenticated Learner model instance. Does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe authenticated LRS learner ODM model instance
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
Authenticate a learner logging into the Learner Portal using custom credentials
Fired during Learner Portal username/password authentication before querying the local LRS learner collection. A plugin can authenticate the credentials against an external directory (such as LDAP or an external database) and return a Learner-compatible model object.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
arrayPositional parameters: [username, password]
Positional Arguments:
View Raw JSON Schema
|
Type:
objectAuthenticated learner object supporting the interface of the LRS Learner Mongoose model
View Raw JSON Schema
|
Serialize a learner model instance into session storage
Fired by Passport when serializing an authenticated learner into the session cookie. Plugins using custom learner objects (from learnerLogin) can return a lightweight session identifier object; the LRS automatically attaches the lrs UUID property.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe LRS learner model instance being serialized
View Raw JSON Schema
|
Type:
objectSerialized session object representing the learner (must include an ID or differentiating field)
View Raw JSON Schema
|
Deserialize a learner session object back into a learner model instance
Fired by Passport on subsequent portal requests to deserialize the session identifier object back into a full learner model instance. If a plugin handles custom learners, it should return the hydrated learner object.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe serialized session object (containing uuid, email, type, lrs)
Object Properties:
View Raw JSON Schema
|
Type:
objectLearner object supporting the interface of the LRS Learner Mongoose model
View Raw JSON Schema
|
The LTI integration created a new learner. You can override the xAPI actor that is generated.
Fired during an LTI launch when a new learner account is automatically provisioned for the launching LMS user. By default, the LRS constructs an xAPI Agent using the learner's LTI email address and name. A plugin can return a valid xAPI Agent object from this event to override the default actor (for example, to use an LMS-specific account homePage and user_id instead of an mbox).
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
arrayPositional parameters: [learner, authbody]
Positional Arguments:
View Raw JSON Schema
|
Type:
objectAn xAPI Agent object to assign to the learner
Object Properties:
View Raw JSON Schema
|
Get available LTI action descriptors for LTI launch configuration
Gathered when an LMS instructor opens the LTI link configuration screen ("/lti/:nonce/configure"). Plugins can extend the built-in LTI launch modes by returning one or more action descriptors containing the action identifier, display label, and optional configuration form definition.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectObject Properties:
View Raw JSON Schema
|
Type:
objectAn LTI action descriptor
Object Properties:
View Raw JSON Schema
|
An LTI action occurred that was not handled by the built-in defaults
Fired during an LTI launch when the configured launchConfig.action does not match any of the built-in LTI actions. Receives an object containing unwrapped Express req, res, and launchConfig objects along with the LTI nonce and session context. The handling plugin should render or redirect the response and return true.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectObject Properties:
View Raw JSON Schema
|
Type:
booleanReturn true if the plugin handled the LTI action
View Raw JSON Schema
|
An LTI action requested its associated configuration form schema
Fired when an instructor selects a custom LTI action on the LTI configuration page and the UI requests the secondary settings form for that action ("/lti/:nonce/configure/form"). If the action belongs to your plugin, return a form schema object containing a fields array.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectObject Properties:
View Raw JSON Schema
|
Type:
objectForm schema object containing a fields array
Object Properties:
View Raw JSON Schema
|
Render a banner notice flag at the top of the UI
Gathered on every UI page render to display system-wide announcement or environment classification banners at the top of the interface. Plugins handling this event can return a banner configuration object specifying the environment label, message text, background color, and text color. Because this uses systemGather, multiple plugins may contribute banner notices.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
None (null) — No parameters are passed to this event. |
Type:
objectBanner notice configuration object
Object Properties:
View Raw JSON Schema
|
Branding customization for the full site title on the home page
Gathered by the Handlebars template engine when rendering the main home page <title> tag. A branding plugin can return a custom full title string for the installation. Output is sanitized before being rendered into the page title.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
None (null) — No parameters are passed to this event. |
Type:
stringThe full site title
View Raw JSON Schema
|
Branding customization for the short site title used with sub-page titles
Gathered by the template engine when rendering sub-page <title> tags (formatted as "<Short Title> | <Page Title>"). Return a short brand or organization name string to customize browser tab titles across the UI.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
None (null) — No parameters are passed to this event. |
Type:
stringThe short site title
View Raw JSON Schema
|
Branding customization for additional HTML injected into the site <head>
Gathered when rendering the <head> section of system UI pages. Plugins can return raw HTML markup (such as custom <script>, <style>, or analytics tracking tags) to be injected into the document head.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
None (null) — No parameters are passed to this event. |
Type:
stringHTML string to insert in <head>
View Raw JSON Schema
|
Branding customization for the <meta name="author"> tag
Gathered when rendering the <meta name="author"> tag in the document <head>. Return a string identifying the authoring organization or administrator of the LRS instance.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
None (null) — No parameters are passed to this event. |
Type:
stringAuthor metadata string
View Raw JSON Schema
|
Branding customization for the copyright footer section
Gathered to customize the copyright notice displayed in the footer of the LRS web interface. Return a plain text or inline string representing the copyright statement.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
None (null) — No parameters are passed to this event. |
Type:
stringCopyright text
View Raw JSON Schema
|
Branding customization for the contact info footer section
Gathered to populate the contact information section in the site footer. Plugins can return an HTML string containing support links, email addresses, or contact details.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
None (null) — No parameters are passed to this event. |
Type:
stringContact info HTML string
View Raw JSON Schema
|
Branding customization for the text displayed above the login form
Gathered when rendering the login screen to display an informational or legal banner above the login form. Return a string with the banner message.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
None (null) — No parameters are passed to this event. |
Type:
stringLogin banner text
View Raw JSON Schema
|
Branding customization returning the complete branding settings object
Gathered during React/NewUI page rendering to supply the complete set of branding customizations to the client-side layout in a single object. Includes titles, footer overrides, Terms of Service/Privacy URLs, helpdesk/documentation links, and the custom Material UI theme object.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
None (null) — No parameters are passed to this event. |
Type:
objectComplete site branding configuration object
Object Properties:
View Raw JSON Schema
|
List the pickers available to the statement viewer
Gathered by the Statement Viewer UI to discover available filter value pickers (such as autocomplete modal dialogs for actors, verbs, or activities). Plugins can register custom pickers by returning a descriptor object with the plugin UUID, display title, route path, and supported selection modes.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
None (null) — No parameters are passed to this event. |
Type:
objectStatement viewer picker descriptor
Object Properties:
View Raw JSON Schema
|
Render links on the system login page
Gathered when rendering the system login page ("/ui/users/login") to display additional login buttons or links (such as "Login with OpenID", "Login with SAML", or "Login with My Navy Portal"). Each plugin can return an object with text and href properties.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
None (null) — No parameters are passed to this event. |
Type:
objectObject Properties:
View Raw JSON Schema
|
Add an item to the admin tools menu
Gathered when rendering the System Administration home page ("/ui/admin/home"). System plugins that provide their own administrative UI routes can return a menu card descriptor ({ text, href, subtext }) to appear in the Admin Tools panel.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
None (null) — No parameters are passed to this event. |
Type:
objectObject Properties:
View Raw JSON Schema
|
Add an item to the features list under the banner on the LRS home page
Gathered when rendering an individual LRS home page ("/ui/lrs/:id"). LRS plugins can return feature link descriptors ({ text, href, subtext, icon }) to appear in the quick-access feature list beneath the LRS overview banner.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
None (null) — No parameters are passed to this event. |
Type:
objectObject Properties:
View Raw JSON Schema
|
Add a tool to the page of xAPI tools
Gathered when rendering the xAPI Tools page ("/ui/tools"). System plugins can return tool link descriptors ({ text, href, subtext }) to add custom utilities to the xAPI Tools directory.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
None (null) — No parameters are passed to this event. |
Type:
objectObject Properties:
View Raw JSON Schema
|
Add an item to the sidebar of an LRS
Gathered on every LRS management page to populate the "Plugins" section of the left navigation sidebar. Plugins can return a menu item object ({ text, href, id }) or a nested tree of menu items using the children array property.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
None (null) — No parameters are passed to this event. |
Type:
objectObject Properties:
View Raw JSON Schema
|
Add an item to the top menu bar
Gathered when rendering the top navigation bar of the system UI. System plugins can return menu item objects ({ text, href, children }) to add custom dropdowns or links to the top header.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
None (null) — No parameters are passed to this event. |
Type:
objectObject Properties:
View Raw JSON Schema
|
Add HTML to the system template in the <head>
Gathered in system templates to inject raw HTML tags (such as custom <meta>, <link>, or <script> elements) into the document <head>. Return a valid HTML string.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
None (null) — No parameters are passed to this event. |
Type:
stringView Raw JSON Schema
|
An xAPI content launch session was created and initiated
Fired when a learner or anonymous user initiates an xAPI content launch and the launch token record is saved in the LRS database. Receives the newly created launch ODM model instance. Does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe LRS launch ODM model instance
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
An xAPI content launch token was consumed by the content package
Fired when a launched e-learning package exchanges its one-time launch key for xAPI endpoint credentials and the launch session transitions to the active state. Receives the launch ODM model instance. Does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe LRS launch ODM model instance
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
An xAPI content launch session was terminated
Fired when an active xAPI content launch session is closed/terminated by the content player or learner. Receives the launch ODM model instance. Does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe LRS launch ODM model instance
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
A class was created in an LRS
Fired after a new Class ODM model is created and saved in an LRS. Receives the created class document. Does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe created LRS class ODM model instance
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
A class was edited in an LRS
Fired after an existing Class ODM model is updated and saved in an LRS. Receives the updated class document. Does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe edited LRS class ODM model instance
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
A class was deleted from an LRS
Fired after a Class ODM model is removed from an LRS. Receives the deleted class document. Does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe deleted LRS class ODM model instance
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
A course was created in an LRS
Fired after a new Course ODM model is created and saved in an LRS. Receives the created course document. Does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe created LRS course ODM model instance
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
A course was edited in an LRS
Fired after an existing Course ODM model is edited and saved in an LRS. Receives the updated course document. Does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe edited LRS course ODM model instance
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
A course was deleted from an LRS
Fired after a Course ODM model is deleted from an LRS. Receives the deleted course document. Does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe deleted LRS course ODM model instance
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
A content item was created in an LRS
Fired after a new Content item record is created and saved in an LRS. Receives the created content ODM model instance. Does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe created LRS content ODM model instance
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
A content item was edited in an LRS
Fired after an existing Content item record is modified and saved in an LRS. Receives the updated content ODM model instance. Does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe edited LRS content ODM model instance
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
A content item was deleted from an LRS
Fired after a Content item record is removed from an LRS. Receives the deleted content ODM model instance. Does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe deleted LRS content ODM model instance
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
An xAPI access key was created in an LRS
Fired after a new xAPI Access Key is created in an LRS. Receives the newly created key ODM model instance. Does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe created LRS xAPI key ODM model instance
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
An xAPI access key was edited in an LRS
Fired after an existing xAPI Access Key is modified in an LRS. Receives the updated key ODM model instance. Does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe edited LRS xAPI key ODM model instance
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
An xAPI access key was deleted from an LRS
Fired after an xAPI Access Key is deleted from an LRS. Receives the deleted key ODM model instance. Does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe deleted LRS xAPI key ODM model instance
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
All xAPI statements were cleared from an LRS
Fired when all xAPI statements (and canonical tables/Elasticsearch indices) are wiped from an LRS via the "Clear Statements" management action or API call. Plugins maintaining auxiliary statement indices or caches can use this hook to reset their state. Takes no parameters and accepts no return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
None (null) — No parameters are passed to this event. |
None (null) — This event does not accept a return value. |
All xAPI statement attachments were cleared from an LRS
Fired when all xAPI statement attachments are cleared from an LRS. Takes no parameters and accepts no return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
None (null) — No parameters are passed to this event. |
None (null) — This event does not accept a return value. |
All logs were cleared from an LRS
Fired when all LRS client/system logs are cleared from an LRS. Takes no parameters and accepts no return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
None (null) — No parameters are passed to this event. |
None (null) — This event does not accept a return value. |
All xAPI documents (state, activityProfile, agentProfile) were cleared from an LRS
Fired when all xAPI State, Activity Profile, and Agent Profile documents are cleared from an LRS. Takes no parameters and accepts no return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
None (null) — No parameters are passed to this event. |
None (null) — This event does not accept a return value. |
User permissions for an LRS were updated
Fired when user role/permission assignments on an LRS are updated and saved. Receives the updated permissions array from the LRS model. Does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
arrayThe updated permissions array on the LRS model
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
An LRS management API key was created
Fired when an LRS Management API Key (used for REST management and LTI OAuth) is created. Receives the created apikey ODM model instance. Does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe created LRS apikey ODM model instance
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
An LRS management API key was deleted
Fired when an LRS Management API Key is deleted. Receives the deleted apikey ODM model instance. Does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe deleted LRS apikey ODM model instance
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
An LRS is about to be deleted
Fired immediately before an LRS record is removed and its MongoDB database is dropped. Plugins can use this hook to clean up external resources or scheduled jobs associated with the LRS. Takes no parameters and accepts no return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
None (null) — No parameters are passed to this event. |
None (null) — This event does not accept a return value. |
An LRS configuration was edited
Fired after an LRS's general settings (such as title, description, strict mode, or xAPI compatibility level) are edited and saved. Receives the updated LRS ODM model instance. Does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe edited LRS ODM model instance
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
An upstream statement forwarding rule was created in an LRS
Fired after a new upstream LRS statement forwarding rule is created. Receives the created upstream ODM model instance. Does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe created LRS upstream ODM model instance
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
An upstream statement forwarding rule was disabled in an LRS
Fired when an upstream LRS statement forwarding rule is disabled. Receives the upstream ODM model instance. Does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe disabled LRS upstream ODM model instance
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
An upstream statement forwarding rule was edited in an LRS
Fired after an upstream LRS statement forwarding rule is edited and saved. Receives the updated upstream ODM model instance. Does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe edited LRS upstream ODM model instance
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
A course content package zip was uploaded to an LRS
Fired when an e-learning content package (.zip) is uploaded and extracted into an LRS. Receives the associated content ODM model instance. Does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe LRS content ODM model instance for the uploaded package
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
A plugin configuration is about to be deleted
Fired when a plugin configuration is removed from an LRS or the system. The base Plugin class automatically listens to this event to invoke the plugin's uninstall() lifecycle method and cancel any Agenda intervals. Receives the pluginConfig ODM model instance.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe pluginConfig ODM model instance being deleted
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
A plugin configuration was edited
Fired after a plugin's settings or display name are edited and saved. Receives the updated pluginConfig ODM model instance. Does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe edited pluginConfig ODM model instance
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
A new plugin configuration was created
Fired when a plugin is newly installed/added to an LRS or the system. The base Plugin class automatically listens to this event to invoke the plugin's install() lifecycle method. Receives the created pluginConfig ODM model instance.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe created pluginConfig ODM model instance
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
Performance tracking data is emitted
Fired throughout the application whenever an operational or performance metric is recorded (such as HTTP request counts, response times, VQL query execution times, statement storage counts, and user/learner logins). System plugins can listen to this event to aggregate telemetry, expose Prometheus/OpenTelemetry endpoints, or track internal health statistics. This is a fire-and-forget notification event and does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectMetric data point
Object Properties:
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
Something has changed in the system level database
Fired via Mongoose post-save and post-remove hooks whenever any system-level ODM document (such as users, LRS records, or system plugin configs) is saved or removed. Receives the operation ("save" or "remove"), the model name, and the document instance. Used primarily for audit logging and cache invalidation; no return value is accepted.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
arrayPositional parameters: [method, type, model]
Positional Arguments:
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
Something has changed in the LRS level database
Fired via Mongoose post-save and post-remove hooks whenever any LRS-scoped ODM document (such as keys, classes, courses, content, learners, profiles, or custom dashboards) is saved or removed. Receives the operation ("save" or "remove"), the model name, an LRS identifier string ("<_id>:<lrsName>"), and the document instance. Does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
arrayPositional parameters: [method, type, lrs, model]
Positional Arguments:
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
The system has started
Fired once when the Veracity LRS HTTP server has finished initializing and begins listening for connections. System plugins can use this hook to log startup audit events, warm caches, or verify external service connectivity. Does not take parameters or accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
None (null) — No parameters are passed to this event. |
None (null) — This event does not accept a return value. |
An HTTP request was received on the UI router
Fired on every authenticated or unauthenticated HTTP request to the "/ui" management router. Provides a summary object with the request URL, HTTP method, parsed query parameters, authenticated user (if any), and client IP address. Used for audit logging; does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectObject Properties:
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
An HTTP request was received on the LRS management API router
Fired on every HTTP request to the LRS-scoped management REST API. Provides an object containing the request URL, HTTP method, query object, management API key record, target LRS record, and client IP address. Used for audit logging; does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectObject Properties:
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
An HTTP request was received on the system management API router
Fired on every HTTP request to the system-level management REST API. Provides an object containing the request URL, HTTP method, query object, system API key record, and client IP address. Used for audit logging; does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectObject Properties:
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
A user account or session action happened
Fired whenever a notable user account or session lifecycle action occurs (including login success/failure, logout, password reset, account creation/deletion, locking/unlocking, enabling/disabling, TOS acceptance, and session creation/destruction). Receives positional arguments describing the action, user model, status string, and client IP address. Used by audit logging and notification plugins; does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
arrayPositional parameters: [action, user, status, ip]
Positional Arguments:
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
An access control check occurred
Fired whenever the role-based access control middleware evaluates whether a user holds a required permission on a target object. Receives the permission string, the target object/model, the user model, the boolean check result, and the client IP address. This is an audit notification event and cannot override the permission check result.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
arrayPositional parameters: [permission, object, user, hasperm, ip]
Positional Arguments:
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
An access control change occurred
Fired when a permission is granted or modified on a system or LRS model for a user. Receives the permission string, the target object/model, the user model, and an optional status/result value. Used for security auditing; does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
arrayPositional parameters: [permission, object, user, result]
Positional Arguments:
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
The system made an outgoing HTTP connection to an external service
Fired whenever the LRS makes an outbound HTTP/HTTPS request via its internal request wrapper (for example, webhooks, OIDC discovery, or upstream LRS forwarding). Receives the target URL and the resolved remote IP/port string. Used for security and network audit logging; does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
arrayPositional parameters: [url, ip]
Positional Arguments:
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
An LRS log entry or clientLog record was saved
Fired whenever an LRS-level log entry or clientLog document is saved (such as xAPI validation errors, script logs, or OIDC errors). Receives the log object containing type, message, and context. Used by LRS and system logging plugins; does not accept a return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
|
Type:
objectThe LRS clientLog ODM document or log entry object
Object Properties:
View Raw JSON Schema
|
None (null) — This event does not accept a return value. |
The system is shutting down
Fired during graceful server shutdown before stopping the Agenda job processor and closing HTTP connections. Plugins can use this hook to flush buffers or close external connections. Takes no parameters and accepts no return value.
Provided Parameters (paramSchema) |
Expected Return Value (resultSchema) |
|---|---|
None (null) — No parameters are passed to this event. |
None (null) — This event does not accept a return value. |