System Events

System Events

The Veracity Learning LRS includes an event-driven plugin architecture that allows developers to extend the LRS, customize authentication and branding, intercept or transform incoming xAPI statements and documents, add custom analytics dashboards and VQL stages, and integrate with external systems. This guide explains how plugins work and documents all 125 registered events defined in utils/plugins/events.js.

How the Veracity LRS Plugin System Works

1. Plugin Scopes: System Plugins versus LRS Plugins

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.

2. Subscribing to Events and Event Dispatch Modes

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:

  • Single-Result / Notification Events (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.
  • Gather Events (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.

3. Read-Only Parameter Proxies versus noWrap

By 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.

4. State Persistence, Custom Routers, and Scheduled Jobs

  • Persisting Plugin State: Call 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.
  • Custom Express Routers: Create an 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').
  • Scheduled Background Tasks: Schedule recurring or one-off Agenda jobs using await this.every('10 minutes', 'mySignal', data) or await this.schedule(when, 'mySignal', data) and handle them with this.onInterval('mySignal', async (e, data) => { ... }).

Quick Navigation — Registered Events by Category

xAPI Statements, Documents, and Authentication

xAPIAuth

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: array
Positional parameters: [req, res] (unwrapped via pluginManager.noWrap)
Positional Arguments:
  1. arg[0] (object): The unwrapped Express request object
  2. arg[1] (object): The unwrapped Express response object
View Raw JSON Schema
{
"type": "array",
"description": "Positional parameters: [req, res] (unwrapped via pluginManager.noWrap)",
"items": [
{
"type": "object",
"description": "The unwrapped Express request object"
},
{
"type": "object",
"description": "The unwrapped Express response object"
}
]
}
Type: object | null
An xAPI Account object representing the authenticated caller, or null
Object Properties:
  • userid (string)[optional]
  • read (boolean)[optional]
  • write (boolean)[optional]
  • limitedRead (boolean)[optional]
  • advancedQueries (boolean)[optional]
  • lrsName (string)[optional]
View Raw JSON Schema
{
"type": [
"object",
"null"
],
"description": "An xAPI Account object representing the authenticated caller, or null",
"properties": {
"userid": {
"type": "string"
},
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"limitedRead": {
"type": "boolean"
},
"advancedQueries": {
"type": "boolean"
},
"lrsName": {
"type": "string"
}
},
"additionalProperties": true
}

stateDelete

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
Object Properties:
  • id (string)[required]
  • query (object)[required]
View Raw JSON Schema
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"query": {
"type": "object"
}
},
"required": [
"id",
"query"
],
"additionalProperties": false
}
Type: object
Object Properties:
  • id (string)[required]
  • query (object)[required]
View Raw JSON Schema
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"query": {
"type": "object"
}
},
"required": [
"id",
"query"
],
"additionalProperties": false
}

stateDeleted

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
Object Properties:
  • id (string)[required]
  • query (object)[required]
View Raw JSON Schema
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"query": {
"type": "object"
}
},
"required": [
"id",
"query"
],
"additionalProperties": false
}
None (null) — This event does not accept a return value.

stateQuery

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The URL query of the request
View Raw JSON Schema
{
"type": "object",
"description": "The URL query of the request"
}
Type: object
The modified URL query
View Raw JSON Schema
{
"type": "object",
"description": "The modified URL query"
}

stateQueryResult

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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
{
"description": "The value that was previously stored for this document"
}
The modified payload to send to the client
View Raw JSON Schema
{
"description": "The modified payload to send to the client"
}

stateReceived

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
Object Properties:
  • id (string)[required]
  • query (object)[required]
  • body (any)[required]
  • method (string)[required]
View Raw JSON Schema
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"query": {
"type": "object"
},
"body": {},
"method": {
"type": "string"
}
},
"required": [
"id",
"query",
"body",
"method"
],
"additionalProperties": false
}
Type: object
Object Properties:
  • id (string)[required]
  • query (object)[required]
  • body (any)[required]
  • method (string)[required]
View Raw JSON Schema
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"query": {
"type": "object"
},
"body": {},
"method": {
"type": "string"
}
},
"required": [
"id",
"query",
"body",
"method"
],
"additionalProperties": false
}

stateStored

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
Object Properties:
  • id (string)[required]
  • query (object)[required]
  • body (any)[required]
  • method (string)[required]
View Raw JSON Schema
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"query": {
"type": "object"
},
"body": {},
"method": {
"type": "string"
}
},
"required": [
"id",
"query",
"body",
"method"
],
"additionalProperties": false
}
None (null) — This event does not accept a return value.

activityProfileDelete

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
Object Properties:
  • id (string)[required]
  • query (object)[required]
View Raw JSON Schema
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"query": {
"type": "object"
}
},
"required": [
"id",
"query"
],
"additionalProperties": false
}
Type: object
Object Properties:
  • id (string)[required]
  • query (object)[required]
View Raw JSON Schema
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"query": {
"type": "object"
}
},
"required": [
"id",
"query"
],
"additionalProperties": false
}

activityProfileDeleted

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
Object Properties:
  • id (string)[required]
  • query (object)[required]
View Raw JSON Schema
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"query": {
"type": "object"
}
},
"required": [
"id",
"query"
],
"additionalProperties": false
}
None (null) — This event does not accept a return value.

activityProfileQuery

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The URL query of the request
View Raw JSON Schema
{
"type": "object",
"description": "The URL query of the request"
}
Type: object
The modified URL query
View Raw JSON Schema
{
"type": "object",
"description": "The modified URL query"
}

activityProfileQueryResult

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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
{
"description": "The value that was previously stored for this document"
}
The modified payload to send to the client
View Raw JSON Schema
{
"description": "The modified payload to send to the client"
}

activityProfileReceived

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
Object Properties:
  • id (string)[required]
  • query (object)[required]
  • body (any)[required]
  • method (string)[required]
View Raw JSON Schema
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"query": {
"type": "object"
},
"body": {},
"method": {
"type": "string"
}
},
"required": [
"id",
"query",
"body",
"method"
],
"additionalProperties": false
}
Type: object
Object Properties:
  • id (string)[required]
  • query (object)[required]
  • body (any)[required]
  • method (string)[required]
View Raw JSON Schema
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"query": {
"type": "object"
},
"body": {},
"method": {
"type": "string"
}
},
"required": [
"id",
"query",
"body",
"method"
],
"additionalProperties": false
}

activityProfileStored

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
Object Properties:
  • id (string)[required]
  • query (object)[required]
  • body (any)[required]
  • method (string)[required]
View Raw JSON Schema
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"query": {
"type": "object"
},
"body": {},
"method": {
"type": "string"
}
},
"required": [
"id",
"query",
"body",
"method"
],
"additionalProperties": false
}
None (null) — This event does not accept a return value.

agentProfileDelete

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
Object Properties:
  • id (string)[required]
  • query (object)[required]
View Raw JSON Schema
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"query": {
"type": "object"
}
},
"required": [
"id",
"query"
],
"additionalProperties": false
}
Type: object
Object Properties:
  • id (string)[required]
  • query (object)[required]
View Raw JSON Schema
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"query": {
"type": "object"
}
},
"required": [
"id",
"query"
],
"additionalProperties": false
}

agentProfileDeleted

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
Object Properties:
  • id (string)[required]
  • query (object)[required]
View Raw JSON Schema
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"query": {
"type": "object"
}
},
"required": [
"id",
"query"
],
"additionalProperties": false
}
None (null) — This event does not accept a return value.

agentProfileQuery

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The URL query of the request
View Raw JSON Schema
{
"type": "object",
"description": "The URL query of the request"
}
Type: object
The modified URL query
View Raw JSON Schema
{
"type": "object",
"description": "The modified URL query"
}

agentProfileQueryResult

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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
{
"description": "The value that was previously stored for this document"
}
The modified payload to send to the client
View Raw JSON Schema
{
"description": "The modified payload to send to the client"
}

agentProfileReceived

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
Object Properties:
  • id (string)[required]
  • query (object)[required]
  • body (any)[required]
  • method (string)[required]
View Raw JSON Schema
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"query": {
"type": "object"
},
"body": {},
"method": {
"type": "string"
}
},
"required": [
"id",
"query",
"body",
"method"
],
"additionalProperties": false
}
Type: object
Object Properties:
  • id (string)[required]
  • query (object)[required]
  • body (any)[required]
  • method (string)[required]
View Raw JSON Schema
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"query": {
"type": "object"
},
"body": {},
"method": {
"type": "string"
}
},
"required": [
"id",
"query",
"body",
"method"
],
"additionalProperties": false
}

agentProfileStored

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
Object Properties:
  • id (string)[required]
  • query (object)[required]
  • body (any)[required]
  • method (string)[required]
View Raw JSON Schema
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"query": {
"type": "object"
},
"body": {},
"method": {
"type": "string"
}
},
"required": [
"id",
"query",
"body",
"method"
],
"additionalProperties": false
}
None (null) — This event does not accept a return value.

statementReceived

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
Object Properties:
  • statement (object)[required]
  • authority (object | null)[required]
  • meta (object | null)[required]
View Raw JSON Schema
{
"type": "object",
"properties": {
"statement": {
"type": "object"
},
"authority": {
"type": [
"object",
"null"
]
},
"meta": {
"type": [
"object",
"null"
]
}
},
"additionalProperties": false,
"required": [
"statement",
"authority",
"meta"
]
}
Type: object
Object Properties:
  • statement (object)[required]
  • authority (object | null)[required]
  • meta (object | null)[required]
View Raw JSON Schema
{
"type": "object",
"properties": {
"statement": {
"type": "object"
},
"authority": {
"type": [
"object",
"null"
]
},
"meta": {
"type": [
"object",
"null"
]
}
},
"additionalProperties": false,
"required": [
"statement",
"authority",
"meta"
]
}

statementBatchReceived

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
Object Properties:
  • statements (array)[required]
  • authority (object | null)[required]
  • meta (object | null)[required]
View Raw JSON Schema
{
"type": "object",
"properties": {
"statements": {
"type": "array",
"items": {
"type": "object"
}
},
"authority": {
"type": [
"object",
"null"
]
},
"meta": {
"type": [
"object",
"null"
]
}
},
"additionalProperties": false,
"required": [
"statements",
"authority",
"meta"
]
}
Type: object
Object Properties:
  • statements (array)[required]
  • authority (object | null)[required]
  • meta (object | null)[required]
View Raw JSON Schema
{
"type": "object",
"properties": {
"statements": {
"type": "array",
"items": {
"type": "object"
}
},
"authority": {
"type": [
"object",
"null"
]
},
"meta": {
"type": [
"object",
"null"
]
}
},
"additionalProperties": false,
"required": [
"statements",
"authority",
"meta"
]
}

statementBatchStored

Scope: LRS Dispatch: lrsEvent noWrap: true (Unwrapped Objects)

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: array
Array of stored xAPI statement documents
View Raw JSON Schema
{
"type": "array",
"description": "Array of stored xAPI statement documents",
"items": {
"type": "object"
}
}
None (null) — This event does not accept a return value.

statementQuery

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The original xAPI statement query parameters
View Raw JSON Schema
{
"type": "object",
"description": "The original xAPI statement query parameters"
}
Type: object
The modified xAPI statement query parameters
View Raw JSON Schema
{
"type": "object",
"description": "The modified xAPI statement query parameters"
}

statementQueryInternal

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The original internal MongoDB query
View Raw JSON Schema
{
"type": "object",
"description": "The original internal MongoDB query"
}
Type: object
The modified internal MongoDB query
View Raw JSON Schema
{
"type": "object",
"description": "The modified internal MongoDB query"
}

statementQueryResult

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The original statement query result payload
View Raw JSON Schema
{
"type": "object",
"description": "The original statement query result payload"
}
Type: object
The modified statement query result payload
View Raw JSON Schema
{
"type": "object",
"description": "The modified statement query result payload"
}

xapiRequest

Scope: System Dispatch: systemEvent noWrap: false (Read-Only Proxy)

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: object
Object Properties:
  • url (string)[required]
  • method (string)[required]
  • query (object)[required]
  • lrs (object)[required]
  • ip (string)[optional]
View Raw JSON Schema
{
"type": "object",
"properties": {
"url": {
"type": "string"
},
"method": {
"type": "string"
},
"query": {
"type": "object"
},
"lrs": {
"type": "object"
},
"ip": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"url",
"method",
"query",
"lrs"
]
}
None (null) — This event does not accept a return value.

Analytics, Dashboards, and VQL

getLRSDashboards

Scope: LRS Dispatch: emit noWrap: false (Read-Only Proxy)

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: object
The LRS model instance or Express request object
View Raw JSON Schema
{
"type": "object",
"description": "The LRS model instance or Express request object"
}
Type: object
A dashboard configuration object
Object Properties:
  • name (string)[required]
  • title (string)[optional]
  • category (string)[optional]
  • visible (boolean)[optional]
  • parameters (object)[optional]
View Raw JSON Schema
{
"type": "object",
"description": "A dashboard configuration object",
"properties": {
"name": {
"type": "string"
},
"title": {
"type": "string"
},
"category": {
"type": "string"
},
"visible": {
"type": "boolean"
},
"parameters": {
"type": "object"
}
},
"required": [
"name"
],
"additionalProperties": true
}

lrsDashboard

Scope: System Dispatch: systemGather noWrap: false (Read-Only Proxy)

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: array
Positional parameters: [lrs, params]
Positional Arguments:
  1. arg[0] (object): The LRS ODM model instance
  2. arg[1] (object): The dashboard parameters object
View Raw JSON Schema
{
"type": "array",
"description": "Positional parameters: [lrs, params]",
"items": [
{
"type": "object",
"description": "The LRS ODM model instance"
},
{
"type": "object",
"description": "The dashboard parameters object"
}
]
}
Type: object
A widget/graph configuration object
Object Properties:
  • handler (string)[required]
  • params (object)[optional]
View Raw JSON Schema
{
"type": "object",
"description": "A widget/graph configuration object",
"properties": {
"handler": {
"type": "string"
},
"params": {
"type": "object"
}
},
"required": [
"handler"
],
"additionalProperties": true
}

learnerDashboard

Scope: LRS Dispatch: lrsGather noWrap: false (Read-Only Proxy)

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: object
The dashboard parameters object
View Raw JSON Schema
{
"type": "object",
"description": "The dashboard parameters object"
}
Type: object
A widget/graph configuration object
Object Properties:
  • handler (string)[required]
  • params (object)[optional]
View Raw JSON Schema
{
"type": "object",
"description": "A widget/graph configuration object",
"properties": {
"handler": {
"type": "string"
},
"params": {
"type": "object"
}
},
"required": [
"handler"
],
"additionalProperties": true
}

activityDashboard

Scope: LRS Dispatch: lrsGather noWrap: false (Read-Only Proxy)

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: array
Positional parameters: [params, canonical]
Positional Arguments:
  1. arg[0] (object): The dashboard parameters object
  2. arg[1] (object | null): The canonical activity record from canonicalActivities
View Raw JSON Schema
{
"type": "array",
"description": "Positional parameters: [params, canonical]",
"items": [
{
"type": "object",
"description": "The dashboard parameters object"
},
{
"type": [
"object",
"null"
],
"description": "The canonical activity record from canonicalActivities"
}
]
}
Type: object
A widget/graph configuration object
Object Properties:
  • handler (string)[required]
  • params (object)[optional]
View Raw JSON Schema
{
"type": "object",
"description": "A widget/graph configuration object",
"properties": {
"handler": {
"type": "string"
},
"params": {
"type": "object"
}
},
"required": [
"handler"
],
"additionalProperties": true
}

chartRender

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The original amCharts configuration object (chartSetup)
View Raw JSON Schema
{
"type": "object",
"description": "The original amCharts configuration object (chartSetup)"
}
Type: object
The modified amCharts configuration object
View Raw JSON Schema
{
"type": "object",
"description": "The modified amCharts configuration object"
}

analyticsRender

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: string
CSS string to inject into the analytics view
View Raw JSON Schema
{
"type": "string",
"description": "CSS string to inject into the analytics view"
}

allowedDashboard

Scope: System Dispatch: systemGather noWrap: false (Read-Only Proxy)

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: array
Positional parameters: [scope, lrs]
Positional Arguments:
  1. arg[0] (string) (allowed: lrs, system, learner): The dashboard scope
  2. arg[1] (object): The LRS ODM model instance
View Raw JSON Schema
{
"type": "array",
"description": "Positional parameters: [scope, lrs]",
"items": [
{
"type": "string",
"enum": [
"lrs",
"system",
"learner"
],
"description": "The dashboard scope"
},
{
"type": "object",
"description": "The LRS ODM model instance"
}
]
}
Type: object
Object Properties:
  • name (string)[required]
View Raw JSON Schema
{
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
],
"additionalProperties": true
}

dashboardParams

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: array
Positional parameters: [dashboardName, lrs]
Positional Arguments:
  1. arg[0] (string): The dashboard name
  2. arg[1] (object): The LRS ODM model instance
View Raw JSON Schema
{
"type": "array",
"description": "Positional parameters: [dashboardName, lrs]",
"items": [
{
"type": "string",
"description": "The dashboard name"
},
{
"type": "object",
"description": "The LRS ODM model instance"
}
]
}
Type: object
Object Properties:
  • name (string)[required]
View Raw JSON Schema
{
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
],
"additionalProperties": true
}

allowedPlugins

Scope: System Dispatch: systemGather noWrap: false (Read-Only Proxy)

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: array
Positional parameters: [scope, lrs]
Positional Arguments:
  1. arg[0] (string) (allowed: lrs, system): The plugin scope
  2. arg[1] (object | null): The LRS ODM model instance
View Raw JSON Schema
{
"type": "array",
"description": "Positional parameters: [scope, lrs]",
"items": [
{
"type": "string",
"enum": [
"lrs",
"system"
],
"description": "The plugin scope"
},
{
"type": [
"object",
"null"
],
"description": "The LRS ODM model instance"
}
]
}
Type: object
Object Properties:
  • name (string)[required]
View Raw JSON Schema
{
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
],
"additionalProperties": true
}

isProcessorAllowed

Scope: System Dispatch: systemEvent noWrap: false (Read-Only Proxy)

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: array
Positional parameters: [scope, processorName, lrs]
Positional Arguments:
  1. arg[0] (string) (allowed: lrs, system): The processor scope
  2. arg[1] (string): The analytic processor handler name
  3. arg[2] (object): The LRS ODM model instance
View Raw JSON Schema
{
"type": "array",
"description": "Positional parameters: [scope, processorName, lrs]",
"items": [
{
"type": "string",
"enum": [
"lrs",
"system"
],
"description": "The processor scope"
},
{
"type": "string",
"description": "The analytic processor handler name"
},
{
"type": "object",
"description": "The LRS ODM model instance"
}
]
}
Type: boolean
View Raw JSON Schema
{
"type": "boolean"
}

isPluginAllowed

Scope: System Dispatch: systemEvent noWrap: false (Read-Only Proxy)

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: array
Positional parameters: [pluginName, scope, lrs]
Positional Arguments:
  1. arg[0] (string): The name of the plugin being checked
  2. arg[1] (string) (allowed: lrs, system): The plugin scope
  3. arg[2] (object | null): The LRS ODM model instance (when scope is lrs)
View Raw JSON Schema
{
"type": "array",
"description": "Positional parameters: [pluginName, scope, lrs]",
"items": [
{
"type": "string",
"description": "The name of the plugin being checked"
},
{
"type": "string",
"enum": [
"lrs",
"system"
],
"description": "The plugin scope"
},
{
"type": [
"object",
"null"
],
"description": "The LRS ODM model instance (when scope is lrs)"
}
]
}
Type: boolean
Whether the plugin is allowed for the given scope and LRS
View Raw JSON Schema
{
"type": "boolean",
"description": "Whether the plugin is allowed for the given scope and LRS"
}

isDashboardInstalled

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: array
Positional parameters: [dashboardDef, scope]
Positional Arguments:
  1. arg[0] (object): The dashboard configuration object
  2. arg[1] (string): The dashboard scope (e.g. lrs, learner, system)
View Raw JSON Schema
{
"type": "array",
"description": "Positional parameters: [dashboardDef, scope]",
"items": [
{
"type": "object",
"description": "The dashboard configuration object"
},
{
"type": "string",
"description": "The dashboard scope (e.g. lrs, learner, system)"
}
]
}
Type: boolean
Whether the dashboard is installed and allowed for the LRS and scope
View Raw JSON Schema
{
"type": "boolean",
"description": "Whether the dashboard is installed and allowed for the LRS and scope"
}

VQLCanonicalDisplay

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: array
Positional parameters: [mode, key, result]
Positional Arguments:
  1. arg[0] (string): The canonical lookup mode (e.g. actor.id, verb.id, object.id, object.definition.type)
  2. arg[1] (string): The identifier key being resolved
  3. arg[2] (object | null): The default canonical lookup result object
View Raw JSON Schema
{
"type": "array",
"description": "Positional parameters: [mode, key, result]",
"items": [
{
"type": "string",
"description": "The canonical lookup mode (e.g. actor.id, verb.id, object.id, object.definition.type)"
},
{
"type": "string",
"description": "The identifier key being resolved"
},
{
"type": [
"object",
"null"
],
"description": "The default canonical lookup result object"
}
]
}
Type: object
Object Properties:
  • display (string)[required]
  • id (string)[optional]
  • collection (string)[optional]
View Raw JSON Schema
{
"type": "object",
"properties": {
"display": {
"type": "string"
},
"id": {
"type": "string"
},
"collection": {
"type": "string"
}
},
"required": [
"display"
],
"additionalProperties": true
}

vqlStage

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: string
The VQL stage command name (e.g. "$myStage")
View Raw JSON Schema
{
"type": "string",
"description": "The VQL stage command name (e.g. \"$myStage\")"
}
Type: function | object
A VQL stage parser class extending analytics/engine/parsers/command.js
View Raw JSON Schema
{
"type": [
"function",
"object"
],
"description": "A VQL stage parser class extending analytics/engine/parsers/command.js"
}

Authentication, Sessions, and Portal

siteLoginRedirect

Scope: System Dispatch: systemEvent noWrap: false (Read-Only Proxy)

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: object
The authenticated system User ODM model instance
View Raw JSON Schema
{
"type": "object",
"description": "The authenticated system User ODM model instance"
}
Type: string
The URL to redirect the user to on successful site login
View Raw JSON Schema
{
"type": "string",
"description": "The URL to redirect the user to on successful site login"
}

portalLoginRedirect

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The Learner/User model
View Raw JSON Schema
{
"type": "object",
"description": "The Learner/User model"
}
Type: string
The URL to redirect the learner to on successful portal login
View Raw JSON Schema
{
"type": "string",
"description": "The URL to redirect the learner to on successful portal login"
}

portalHeader

Scope: LRS Dispatch: lrsGather noWrap: false (Read-Only Proxy)

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 | null
The current portal Learner/User object (if logged in)
View Raw JSON Schema
{
"type": [
"object",
"null"
],
"description": "The current portal Learner/User object (if logged in)"
}
Type: string
HTML content to insert into the portal <head>
View Raw JSON Schema
{
"type": "string",
"description": "HTML content to insert into the portal <head>"
}

preAuthReq

Scope: System Dispatch: systemEvent noWrap: true (Unwrapped Objects)

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: array
Positional parameters: [req, res]
Positional Arguments:
  1. arg[0] (object): The unwrapped Express request object
  2. arg[1] (object): The unwrapped Express response object
View Raw JSON Schema
{
"type": "array",
"description": "Positional parameters: [req, res]",
"items": [
{
"type": "object",
"description": "The unwrapped Express request object"
},
{
"type": "object",
"description": "The unwrapped Express response object"
}
]
}
Type: boolean
Return false to stop normal request processing when the plugin has handled the response; return true or undefined to continue
View Raw JSON Schema
{
"type": "boolean",
"description": "Return false to stop normal request processing when the plugin has handled the response; return true or undefined to continue"
}

loginRequiredRedirect

Scope: System Dispatch: systemEvent noWrap: false (Read-Only Proxy)

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: array
Positional parameters: [req, res]
Positional Arguments:
  1. arg[0] (object): The Express request object
  2. arg[1] (object): The Express response object
View Raw JSON Schema
{
"type": "array",
"description": "Positional parameters: [req, res]",
"items": [
{
"type": "object",
"description": "The Express request object"
},
{
"type": "object",
"description": "The Express response object"
}
]
}
Type: string
The URL to redirect to
View Raw JSON Schema
{
"type": "string",
"description": "The URL to redirect to"
}

portal_preAuthReq

Scope: LRS Dispatch: lrsEvent noWrap: true (Unwrapped Objects)

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: array
Positional parameters: [req, res]
Positional Arguments:
  1. arg[0] (object): The unwrapped Express request object
  2. arg[1] (object): The unwrapped Express response object
View Raw JSON Schema
{
"type": "array",
"description": "Positional parameters: [req, res]",
"items": [
{
"type": "object",
"description": "The unwrapped Express request object"
},
{
"type": "object",
"description": "The unwrapped Express response object"
}
]
}
Type: boolean
Return false to stop normal request processing when the plugin has handled the response; return true or undefined to continue
View Raw JSON Schema
{
"type": "boolean",
"description": "Return false to stop normal request processing when the plugin has handled the response; return true or undefined to continue"
}

portal_loginRequiredRedirect

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: array
Positional parameters: [req, res]
Positional Arguments:
  1. arg[0] (object): The Express request object
  2. arg[1] (object): The Express response object
View Raw JSON Schema
{
"type": "array",
"description": "Positional parameters: [req, res]",
"items": [
{
"type": "object",
"description": "The Express request object"
},
{
"type": "object",
"description": "The Express response object"
}
]
}
Type: string
The URL to redirect to
View Raw JSON Schema
{
"type": "string",
"description": "The URL to redirect to"
}
Scope: LRS Dispatch: lrsGather noWrap: false (Read-Only Proxy)

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 | null
The current portal Learner/User object (if any)
View Raw JSON Schema
{
"type": [
"object",
"null"
],
"description": "The current portal Learner/User object (if any)"
}
Type: object
Object Properties:
  • text (string)[optional]
  • href (string)[optional]
View Raw JSON Schema
{
"type": "object",
"properties": {
"text": {
"type": "string"
},
"href": {
"type": "string",
"format": "url"
}
}
}

portalSection

Scope: LRS Dispatch: lrsGather noWrap: false (Read-Only Proxy)

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 | null
The logged-in Learner ODM model instance
View Raw JSON Schema
{
"type": [
"object",
"null"
],
"description": "The logged-in Learner ODM model instance"
}
Type: object
Object Properties:
  • body (string)[required]
  • title (string)[required]
View Raw JSON Schema
{
"type": "object",
"properties": {
"body": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"body",
"title"
],
"additionalProperties": false
}

portalNotice

Scope: LRS Dispatch: lrsGather noWrap: false (Read-Only Proxy)

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 | null
The logged-in Learner ODM model instance
View Raw JSON Schema
{
"type": [
"object",
"null"
],
"description": "The logged-in Learner ODM model instance"
}
Type: object
Object Properties:
  • body (string)[required]
  • type (string)[required]
View Raw JSON Schema
{
"type": "object",
"properties": {
"body": {
"type": "string"
},
"type": {
"type": "string"
}
},
"required": [
"type",
"body"
],
"additionalProperties": false
}

learnerResetPassword

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The LRS learner ODM model instance
View Raw JSON Schema
{
"type": "object",
"description": "The LRS learner ODM model instance"
}
None (null) — This event does not accept a return value.

learnerForgotPassword

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The LRS learner ODM model instance
View Raw JSON Schema
{
"type": "object",
"description": "The LRS learner ODM model instance"
}
None (null) — This event does not accept a return value.

learnerDeleted

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The deleted LRS learner ODM model instance
View Raw JSON Schema
{
"type": "object",
"description": "The deleted LRS learner ODM model instance"
}
None (null) — This event does not accept a return value.

learnerSelfAssert

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: array
Positional parameters: [learner, statementBody]
Positional Arguments:
  1. arg[0] (object): The LRS learner ODM model instance
  2. arg[1] (object): The self-asserted xAPI statement object
View Raw JSON Schema
{
"type": "array",
"description": "Positional parameters: [learner, statementBody]",
"items": [
{
"type": "object",
"description": "The LRS learner ODM model instance"
},
{
"type": "object",
"description": "The self-asserted xAPI statement object"
}
]
}
None (null) — This event does not accept a return value.

learnerSelfUpdate

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The updated LRS learner ODM model instance
View Raw JSON Schema
{
"type": "object",
"description": "The updated LRS learner ODM model instance"
}
None (null) — This event does not accept a return value.

learnerLogout

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The LRS learner ODM model instance
View Raw JSON Schema
{
"type": "object",
"description": "The LRS learner ODM model instance"
}
None (null) — This event does not accept a return value.

learnerLoggedIn

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The authenticated LRS learner ODM model instance
View Raw JSON Schema
{
"type": "object",
"description": "The authenticated LRS learner ODM model instance"
}
None (null) — This event does not accept a return value.

learnerLogin

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: array
Positional parameters: [username, password]
Positional Arguments:
  1. arg[0] (string): The learner username or email address
  2. arg[1] (string): The plaintext password
View Raw JSON Schema
{
"type": "array",
"description": "Positional parameters: [username, password]",
"items": [
{
"type": "string",
"description": "The learner username or email address"
},
{
"type": "string",
"description": "The plaintext password"
}
]
}
Type: object
Authenticated learner object supporting the interface of the LRS Learner Mongoose model
View Raw JSON Schema
{
"type": "object",
"description": "Authenticated learner object supporting the interface of the LRS Learner Mongoose model"
}

learnerSerialize

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The LRS learner model instance being serialized
View Raw JSON Schema
{
"type": "object",
"description": "The LRS learner model instance being serialized"
}
Type: object
Serialized session object representing the learner (must include an ID or differentiating field)
View Raw JSON Schema
{
"type": "object",
"description": "Serialized session object representing the learner (must include an ID or differentiating field)"
}

learnerDeserialize

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The serialized session object (containing uuid, email, type, lrs)
Object Properties:
  • email (string)[optional]
  • uuid (string)[optional]
  • type (string)[optional]
  • lrs (string)[optional]
View Raw JSON Schema
{
"type": "object",
"description": "The serialized session object (containing uuid, email, type, lrs)",
"properties": {
"email": {
"type": "string"
},
"uuid": {
"type": "string"
},
"type": {
"type": "string"
},
"lrs": {
"type": "string"
}
},
"additionalProperties": true
}
Type: object
Learner object supporting the interface of the LRS Learner Mongoose model
View Raw JSON Schema
{
"type": "object",
"description": "Learner object supporting the interface of the LRS Learner Mongoose model"
}

LTI Integration

LTI_learner_actor_created

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: array
Positional parameters: [learner, authbody]
Positional Arguments:
  1. arg[0] (object): The Learner ODM model instance
  2. arg[1] (object): The LTI transaction launch parameters (authbody)
View Raw JSON Schema
{
"type": "array",
"description": "Positional parameters: [learner, authbody]",
"items": [
{
"type": "object",
"description": "The Learner ODM model instance"
},
{
"type": "object",
"description": "The LTI transaction launch parameters (authbody)"
}
]
}
Type: object
An xAPI Agent object to assign to the learner
Object Properties:
  • objectType (string)[optional] (values: Agent)
  • name (string)[optional]
  • mbox (string)[optional]
  • mbox_sha1sum (string)[optional]
  • openid (string)[optional]
  • account (object)[optional]
View Raw JSON Schema
{
"type": "object",
"description": "An xAPI Agent object to assign to the learner",
"properties": {
"objectType": {
"type": "string",
"enum": [
"Agent"
]
},
"name": {
"type": "string"
},
"mbox": {
"type": "string"
},
"mbox_sha1sum": {
"type": "string"
},
"openid": {
"type": "string"
},
"account": {
"type": "object",
"properties": {
"homePage": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"homePage",
"name"
]
}
}
}

getLTIActions

Scope: LRS Dispatch: lrsGather noWrap: false (Read-Only Proxy)

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: object
Object Properties:
  • req (object)[required]
  • res (object)[required]
  • launchConfig (object)[required]
  • nonce (string)[required]
  • session (object)[required]
View Raw JSON Schema
{
"type": "object",
"properties": {
"req": {
"type": "object"
},
"res": {
"type": "object"
},
"launchConfig": {
"type": "object"
},
"nonce": {
"type": "string"
},
"session": {
"type": "object"
}
},
"required": [
"req",
"res",
"launchConfig",
"nonce",
"session"
],
"additionalProperties": false
}
Type: object
An LTI action descriptor
Object Properties:
  • action (string)[required]
  • display (string)[optional]
  • form (object)[optional]
View Raw JSON Schema
{
"type": "object",
"description": "An LTI action descriptor",
"properties": {
"action": {
"type": "string"
},
"display": {
"type": "string"
},
"form": {
"type": "object"
}
},
"required": [
"action"
],
"additionalProperties": true
}

ltiAction

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
Object Properties:
  • req (object)[required] — Unwrapped Express request object
  • res (object)[required] — Unwrapped Express response object
  • launchConfig (object)[required] — Unwrapped LTI launchConfig ODM model instance
  • nonce (string)[required]
  • session (object)[required] — LTI session context
View Raw JSON Schema
{
"type": "object",
"properties": {
"req": {
"type": "object",
"description": "Unwrapped Express request object"
},
"res": {
"type": "object",
"description": "Unwrapped Express response object"
},
"launchConfig": {
"type": "object",
"description": "Unwrapped LTI launchConfig ODM model instance"
},
"nonce": {
"type": "string"
},
"session": {
"type": "object",
"description": "LTI session context"
}
},
"required": [
"req",
"res",
"launchConfig",
"nonce",
"session"
],
"additionalProperties": false
}
Type: boolean
Return true if the plugin handled the LTI action
View Raw JSON Schema
{
"type": "boolean",
"description": "Return true if the plugin handled the LTI action"
}

getLTIForm

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
Object Properties:
  • req (object)[required]
  • res (object)[required]
  • launchConfig (object)[required]
  • nonce (string)[required]
  • session (object)[required]
  • action (string)[required]
View Raw JSON Schema
{
"type": "object",
"properties": {
"req": {
"type": "object"
},
"res": {
"type": "object"
},
"launchConfig": {
"type": "object"
},
"nonce": {
"type": "string"
},
"session": {
"type": "object"
},
"action": {
"type": "string"
}
},
"required": [
"req",
"res",
"launchConfig",
"nonce",
"session",
"action"
],
"additionalProperties": false
}
Type: object
Form schema object containing a fields array
Object Properties:
  • title (string)[optional]
  • submitText (string)[optional]
  • fields (array)[required]
View Raw JSON Schema
{
"type": "object",
"description": "Form schema object containing a fields array",
"properties": {
"title": {
"type": "string"
},
"submitText": {
"type": "string"
},
"fields": {
"type": "array",
"items": {
"type": "object"
}
}
},
"required": [
"fields"
],
"additionalProperties": true
}

Branding and UI Customization

bannerNotice

Scope: System Dispatch: systemGather noWrap: false (Read-Only Proxy)

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: object
Banner notice configuration object
Object Properties:
  • id (string)[optional]
  • env (string)[optional]
  • message (string)[optional]
  • backgroundColor (string)[optional]
  • textColor (string)[optional]
View Raw JSON Schema
{
"type": "object",
"description": "Banner notice configuration object",
"properties": {
"id": {
"type": "string"
},
"env": {
"type": "string"
},
"message": {
"type": "string"
},
"backgroundColor": {
"type": "string"
},
"textColor": {
"type": "string"
}
},
"additionalProperties": true
}

branding-siteFullTitle

Scope: System Dispatch: systemGather noWrap: false (Read-Only Proxy)

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: string
The full site title
View Raw JSON Schema
{
"type": "string",
"description": "The full site title"
}

branding-siteShortTitle

Scope: System Dispatch: systemGather noWrap: false (Read-Only Proxy)

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: string
The short site title
View Raw JSON Schema
{
"type": "string",
"description": "The short site title"
}

branding-siteAdditionalHead

Scope: System Dispatch: systemGather noWrap: false (Read-Only Proxy)

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: string
HTML string to insert in <head>
View Raw JSON Schema
{
"type": "string",
"description": "HTML string to insert in <head>"
}

branding-siteMetaAuthor

Scope: System Dispatch: systemGather noWrap: false (Read-Only Proxy)

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: string
Author metadata string
View Raw JSON Schema
{
"type": "string",
"description": "Author metadata string"
}
Scope: System Dispatch: systemGather noWrap: false (Read-Only Proxy)

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: string
Copyright text
View Raw JSON Schema
{
"type": "string",
"description": "Copyright text"
}

branding-siteContactInfo

Scope: System Dispatch: systemGather noWrap: false (Read-Only Proxy)

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: string
Contact info HTML string
View Raw JSON Schema
{
"type": "string",
"description": "Contact info HTML string"
}

branding-siteLoginBanner

Scope: System Dispatch: systemGather noWrap: false (Read-Only Proxy)

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: string
Login banner text
View Raw JSON Schema
{
"type": "string",
"description": "Login banner text"
}

branding-all

Scope: System Dispatch: systemGather noWrap: false (Read-Only Proxy)

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: object
Complete site branding configuration object
Object Properties:
  • siteShortTitle (string)[optional]
  • siteFullTitle (string)[optional]
  • siteAdditionalHead (string)[optional]
  • siteMetaAuthor (string)[optional]
  • siteCopyright (string)[optional]
  • siteContactInfo (string)[optional]
  • siteLoginBanner (string)[optional]
  • sitePrivacyURL (string)[optional]
  • siteTOSUrl (string)[optional]
  • siteTOS (string)[optional]
  • userManualUrl (string)[optional]
  • helpdeskUrl (string)[optional]
  • knowledgeBaseUrl (string)[optional]
  • videoUrl (string)[optional]
  • overrideFooter (string)[optional]
  • siteTheme (string | object)[optional]
View Raw JSON Schema
{
"type": "object",
"description": "Complete site branding configuration object",
"properties": {
"siteShortTitle": {
"type": "string"
},
"siteFullTitle": {
"type": "string"
},
"siteAdditionalHead": {
"type": "string"
},
"siteMetaAuthor": {
"type": "string"
},
"siteCopyright": {
"type": "string"
},
"siteContactInfo": {
"type": "string"
},
"siteLoginBanner": {
"type": "string"
},
"sitePrivacyURL": {
"type": "string"
},
"siteTOSUrl": {
"type": "string"
},
"siteTOS": {
"type": "string"
},
"userManualUrl": {
"type": "string"
},
"helpdeskUrl": {
"type": "string"
},
"knowledgeBaseUrl": {
"type": "string"
},
"videoUrl": {
"type": "string"
},
"overrideFooter": {
"type": "string"
},
"siteTheme": {
"type": [
"string",
"object"
]
}
},
"additionalProperties": true
}

getStatementViewerPickers

Scope: LRS Dispatch: lrsGather noWrap: false (Read-Only Proxy)

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: object
Statement viewer picker descriptor
Object Properties:
  • uuid (string)[required]
  • title (string)[required]
  • path (string)[required]
  • supportedModes (array)[required]
View Raw JSON Schema
{
"type": "object",
"description": "Statement viewer picker descriptor",
"properties": {
"uuid": {
"type": "string"
},
"title": {
"type": "string"
},
"path": {
"type": "string"
},
"supportedModes": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"uuid",
"title",
"path",
"supportedModes"
],
"additionalProperties": true
}
Scope: System Dispatch: systemGather noWrap: false (Read-Only Proxy)

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: object
Object Properties:
  • text (string)[optional]
  • href (string)[optional]
View Raw JSON Schema
{
"type": "object",
"properties": {
"text": {
"type": "string"
},
"href": {
"type": "string",
"format": "url"
}
}
}

adminTools

Scope: System Dispatch: systemGather noWrap: false (Read-Only Proxy)

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: object
Object Properties:
  • text (string)[required]
  • href (string)[required]
  • subtext (string)[required]
View Raw JSON Schema
{
"type": "object",
"properties": {
"text": {
"type": "string"
},
"href": {
"type": "string"
},
"subtext": {
"type": "string"
}
},
"required": [
"text",
"href",
"subtext"
],
"additionalProperties": false
}
Scope: LRS Dispatch: lrsGather noWrap: false (Read-Only Proxy)

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: object
Object Properties:
  • text (string)[required]
  • href (string)[required]
  • subtext (string)[required]
  • icon (string)[optional]
View Raw JSON Schema
{
"type": "object",
"properties": {
"text": {
"type": "string"
},
"href": {
"type": "string"
},
"subtext": {
"type": "string"
},
"icon": {
"type": "string"
}
},
"required": [
"text",
"href",
"subtext"
],
"additionalProperties": false
}

xapiTools

Scope: System Dispatch: systemGather noWrap: false (Read-Only Proxy)

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: object
Object Properties:
  • text (string)[required]
  • href (string)[required]
  • subtext (string)[required]
View Raw JSON Schema
{
"type": "object",
"properties": {
"text": {
"type": "string"
},
"href": {
"type": "string"
},
"subtext": {
"type": "string"
}
},
"required": [
"text",
"href",
"subtext"
],
"additionalProperties": false
}

lrsSidebar

Scope: LRS Dispatch: lrsGather noWrap: false (Read-Only Proxy)

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: object
Object Properties:
  • text (string)[required]
  • href (string)[required]
  • id (string)[required]
  • children (array)[optional]
View Raw JSON Schema
{
"type": "object",
"id": "$MENUITEM",
"properties": {
"text": {
"type": "string"
},
"href": {
"type": "string"
},
"id": {
"type": "string"
},
"children": {
"type": "array",
"items": {
"$ref": "$MENUITEM"
}
}
},
"required": [
"text",
"href",
"id"
],
"additionalProperties": false
}

headerMenu

Scope: System Dispatch: systemGather noWrap: false (Read-Only Proxy)

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: object
Object Properties:
  • text (string)[required]
  • href (string)[required]
  • children (array)[optional]
View Raw JSON Schema
{
"type": "object",
"id": "$MENUITEM",
"properties": {
"text": {
"type": "string"
},
"href": {
"type": "string"
},
"children": {
"type": "array",
"items": {
"$ref": "$MENUITEM"
}
}
},
"required": [
"text",
"href"
],
"additionalProperties": false
}
Scope: System Dispatch: systemGather noWrap: false (Read-Only Proxy)

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: string
View Raw JSON Schema
{
"type": "string"
}

LRS Entity and Content Lifecycle

launchInitiated

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The LRS launch ODM model instance
View Raw JSON Schema
{
"type": "object",
"description": "The LRS launch ODM model instance"
}
None (null) — This event does not accept a return value.

launchConsumed

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The LRS launch ODM model instance
View Raw JSON Schema
{
"type": "object",
"description": "The LRS launch ODM model instance"
}
None (null) — This event does not accept a return value.

launchTerminated

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The LRS launch ODM model instance
View Raw JSON Schema
{
"type": "object",
"description": "The LRS launch ODM model instance"
}
None (null) — This event does not accept a return value.

classCreated

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The created LRS class ODM model instance
View Raw JSON Schema
{
"type": "object",
"description": "The created LRS class ODM model instance"
}
None (null) — This event does not accept a return value.

classEdited

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The edited LRS class ODM model instance
View Raw JSON Schema
{
"type": "object",
"description": "The edited LRS class ODM model instance"
}
None (null) — This event does not accept a return value.

classDeleted

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The deleted LRS class ODM model instance
View Raw JSON Schema
{
"type": "object",
"description": "The deleted LRS class ODM model instance"
}
None (null) — This event does not accept a return value.

courseCreated

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The created LRS course ODM model instance
View Raw JSON Schema
{
"type": "object",
"description": "The created LRS course ODM model instance"
}
None (null) — This event does not accept a return value.

courseEdited

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The edited LRS course ODM model instance
View Raw JSON Schema
{
"type": "object",
"description": "The edited LRS course ODM model instance"
}
None (null) — This event does not accept a return value.

courseDeleted

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The deleted LRS course ODM model instance
View Raw JSON Schema
{
"type": "object",
"description": "The deleted LRS course ODM model instance"
}
None (null) — This event does not accept a return value.

contentCreated

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The created LRS content ODM model instance
View Raw JSON Schema
{
"type": "object",
"description": "The created LRS content ODM model instance"
}
None (null) — This event does not accept a return value.

contentEdited

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The edited LRS content ODM model instance
View Raw JSON Schema
{
"type": "object",
"description": "The edited LRS content ODM model instance"
}
None (null) — This event does not accept a return value.

contentDeleted

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The deleted LRS content ODM model instance
View Raw JSON Schema
{
"type": "object",
"description": "The deleted LRS content ODM model instance"
}
None (null) — This event does not accept a return value.

xAPIKeyCreated

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The created LRS xAPI key ODM model instance
View Raw JSON Schema
{
"type": "object",
"description": "The created LRS xAPI key ODM model instance"
}
None (null) — This event does not accept a return value.

xAPIKeyEdited

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The edited LRS xAPI key ODM model instance
View Raw JSON Schema
{
"type": "object",
"description": "The edited LRS xAPI key ODM model instance"
}
None (null) — This event does not accept a return value.

xAPIKeyDeleted

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The deleted LRS xAPI key ODM model instance
View Raw JSON Schema
{
"type": "object",
"description": "The deleted LRS xAPI key ODM model instance"
}
None (null) — This event does not accept a return value.

lrsStatementsCleared

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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.

lrsAttachmentsCleared

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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.

lrsLogsCleared

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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.

lrsDocsCleared

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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.

lrsPermissionsEdited

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: array
The updated permissions array on the LRS model
View Raw JSON Schema
{
"type": "array",
"description": "The updated permissions array on the LRS model",
"items": {
"type": "object"
}
}
None (null) — This event does not accept a return value.

apiKeyCreated

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The created LRS apikey ODM model instance
View Raw JSON Schema
{
"type": "object",
"description": "The created LRS apikey ODM model instance"
}
None (null) — This event does not accept a return value.

apiKeyDeleted

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The deleted LRS apikey ODM model instance
View Raw JSON Schema
{
"type": "object",
"description": "The deleted LRS apikey ODM model instance"
}
None (null) — This event does not accept a return value.

lrsDeleted

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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.

lrsEdited

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The edited LRS ODM model instance
View Raw JSON Schema
{
"type": "object",
"description": "The edited LRS ODM model instance"
}
None (null) — This event does not accept a return value.

upstreamCreated

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The created LRS upstream ODM model instance
View Raw JSON Schema
{
"type": "object",
"description": "The created LRS upstream ODM model instance"
}
None (null) — This event does not accept a return value.

upstreamDisabled

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The disabled LRS upstream ODM model instance
View Raw JSON Schema
{
"type": "object",
"description": "The disabled LRS upstream ODM model instance"
}
None (null) — This event does not accept a return value.

upstreamEdited

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The edited LRS upstream ODM model instance
View Raw JSON Schema
{
"type": "object",
"description": "The edited LRS upstream ODM model instance"
}
None (null) — This event does not accept a return value.

contentUploaded

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The LRS content ODM model instance for the uploaded package
View Raw JSON Schema
{
"type": "object",
"description": "The LRS content ODM model instance for the uploaded package"
}
None (null) — This event does not accept a return value.

pluginDeleted

Scope: LRS / System Dispatch: event noWrap: false (Read-Only Proxy)

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: object
The pluginConfig ODM model instance being deleted
View Raw JSON Schema
{
"type": "object",
"description": "The pluginConfig ODM model instance being deleted"
}
None (null) — This event does not accept a return value.

pluginEdited

Scope: LRS / System Dispatch: event noWrap: false (Read-Only Proxy)

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: object
The edited pluginConfig ODM model instance
View Raw JSON Schema
{
"type": "object",
"description": "The edited pluginConfig ODM model instance"
}
None (null) — This event does not accept a return value.

pluginCreated

Scope: LRS / System Dispatch: event noWrap: false (Read-Only Proxy)

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: object
The created pluginConfig ODM model instance
View Raw JSON Schema
{
"type": "object",
"description": "The created pluginConfig ODM model instance"
}
None (null) — This event does not accept a return value.

System Lifecycle, Logging, and Metrics

metric

Scope: System Dispatch: systemEvent noWrap: false (Read-Only Proxy)

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: object
Metric data point
Object Properties:
  • name (string)[required]
  • mode (string)[required] (values: inc, avg)
  • value (number)[required]
View Raw JSON Schema
{
"type": "object",
"description": "Metric data point",
"properties": {
"name": {
"type": "string"
},
"mode": {
"type": "string",
"enum": [
"inc",
"avg"
]
},
"value": {
"type": "number"
}
},
"required": [
"name",
"mode",
"value"
],
"additionalProperties": false
}
None (null) — This event does not accept a return value.

systemODMEvent

Scope: System Dispatch: systemEvent noWrap: false (Read-Only Proxy)

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: array
Positional parameters: [method, type, model]
Positional Arguments:
  1. arg[0] (string) (allowed: save, remove): The database action performed
  2. arg[1] (string): The system ODM model name
  3. arg[2] (object): The Mongoose document instance that was saved or removed
View Raw JSON Schema
{
"type": "array",
"description": "Positional parameters: [method, type, model]",
"items": [
{
"type": "string",
"enum": [
"save",
"remove"
],
"description": "The database action performed"
},
{
"type": "string",
"description": "The system ODM model name"
},
{
"type": "object",
"description": "The Mongoose document instance that was saved or removed"
}
]
}
None (null) — This event does not accept a return value.

LRSODMEvent

Scope: System Dispatch: systemEvent noWrap: false (Read-Only Proxy)

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: array
Positional parameters: [method, type, lrs, model]
Positional Arguments:
  1. arg[0] (string) (allowed: save, remove): The database action performed
  2. arg[1] (string): The LRS ODM model name
  3. arg[2] (string): The LRS identifier string in the format "<_id>:<lrsName>"
  4. arg[3] (object): The Mongoose document instance that was saved or removed
View Raw JSON Schema
{
"type": "array",
"description": "Positional parameters: [method, type, lrs, model]",
"items": [
{
"type": "string",
"enum": [
"save",
"remove"
],
"description": "The database action performed"
},
{
"type": "string",
"description": "The LRS ODM model name"
},
{
"type": "string",
"description": "The LRS identifier string in the format \"<_id>:<lrsName>\""
},
{
"type": "object",
"description": "The Mongoose document instance that was saved or removed"
}
]
}
None (null) — This event does not accept a return value.

systemStartup

Scope: System Dispatch: systemEvent noWrap: false (Read-Only Proxy)

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.

uiRequest

Scope: System Dispatch: systemEvent noWrap: false (Read-Only Proxy)

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: object
Object Properties:
  • url (string)[required]
  • method (string)[required]
  • query (object)[required]
  • user (object | null)[optional]
  • ip (string)[optional]
View Raw JSON Schema
{
"type": "object",
"properties": {
"url": {
"type": "string"
},
"method": {
"type": "string"
},
"query": {
"type": "object"
},
"user": {
"type": [
"object",
"null"
]
},
"ip": {
"type": "string"
}
},
"required": [
"url",
"method",
"query"
],
"additionalProperties": false
}
None (null) — This event does not accept a return value.

LRSAPIRequest

Scope: System Dispatch: systemEvent noWrap: false (Read-Only Proxy)

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: object
Object Properties:
  • url (string)[required]
  • method (string)[required]
  • query (object)[required]
  • key (object | null)[optional]
  • lrs (object | null)[optional]
  • ip (string)[optional]
View Raw JSON Schema
{
"type": "object",
"properties": {
"url": {
"type": "string"
},
"method": {
"type": "string"
},
"query": {
"type": "object"
},
"key": {
"type": [
"object",
"null"
]
},
"lrs": {
"type": [
"object",
"null"
]
},
"ip": {
"type": "string"
}
},
"required": [
"url",
"method",
"query"
],
"additionalProperties": false
}
None (null) — This event does not accept a return value.

systemAPIRequest

Scope: System Dispatch: systemEvent noWrap: false (Read-Only Proxy)

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: object
Object Properties:
  • url (string)[required]
  • method (string)[required]
  • query (object)[required]
  • key (object | null)[optional]
  • ip (string)[optional]
View Raw JSON Schema
{
"type": "object",
"properties": {
"url": {
"type": "string"
},
"method": {
"type": "string"
},
"query": {
"type": "object"
},
"key": {
"type": [
"object",
"null"
]
},
"ip": {
"type": "string"
}
},
"required": [
"url",
"method",
"query"
],
"additionalProperties": false
}
None (null) — This event does not accept a return value.

systemUserEvent

Scope: System Dispatch: systemEvent noWrap: false (Read-Only Proxy)

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: array
Positional parameters: [action, user, status, ip]
Positional Arguments:
  1. arg[0] (string): The action that occurred (e.g. login, logout, created, deleted, locked, unlocked, disabled, enabled, resetPassword, reset password, set must reset, acceptsTOS, unverify, session created, session destroyed)
  2. arg[1] (object | string | null): The User ODM model instance (or null/empty string when no user is associated)
  3. arg[2] (string): The status or additional detail of the action (e.g. success, failed, locked, disabled, unvalidated)
  4. arg[3] (string): The client IP address
View Raw JSON Schema
{
"type": "array",
"description": "Positional parameters: [action, user, status, ip]",
"items": [
{
"type": "string",
"description": "The action that occurred (e.g. login, logout, created, deleted, locked, unlocked, disabled, enabled, resetPassword, reset password, set must reset, acceptsTOS, unverify, session created, session destroyed)"
},
{
"type": [
"object",
"string",
"null"
],
"description": "The User ODM model instance (or null/empty string when no user is associated)"
},
{
"type": "string",
"description": "The status or additional detail of the action (e.g. success, failed, locked, disabled, unvalidated)"
},
{
"type": "string",
"description": "The client IP address"
}
]
}
None (null) — This event does not accept a return value.

permissionCheck

Scope: System Dispatch: systemEvent noWrap: false (Read-Only Proxy)

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: array
Positional parameters: [permission, object, user, hasperm, ip]
Positional Arguments:
  1. arg[0] (string): The permission string being checked
  2. arg[1] (object): The target object/model being accessed
  3. arg[2] (object): The User ODM model instance
  4. arg[3] (boolean): Whether the user had the requested permission
  5. arg[4] (string): The client IP address
View Raw JSON Schema
{
"type": "array",
"description": "Positional parameters: [permission, object, user, hasperm, ip]",
"items": [
{
"type": "string",
"description": "The permission string being checked"
},
{
"type": "object",
"description": "The target object/model being accessed"
},
{
"type": "object",
"description": "The User ODM model instance"
},
{
"type": "boolean",
"description": "Whether the user had the requested permission"
},
{
"type": "string",
"description": "The client IP address"
}
]
}
None (null) — This event does not accept a return value.

permissionsGrant

Scope: System Dispatch: systemEvent noWrap: false (Read-Only Proxy)

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: array
Positional parameters: [permission, object, user, result]
Positional Arguments:
  1. arg[0] (string): The permission string being granted or modified
  2. arg[1] (object): The target object/model whose permissions are being modified
  3. arg[2] (object): The User ODM model instance
  4. arg[3] (string | boolean): Optional result or status of the permission change
View Raw JSON Schema
{
"type": "array",
"description": "Positional parameters: [permission, object, user, result]",
"items": [
{
"type": "string",
"description": "The permission string being granted or modified"
},
{
"type": "object",
"description": "The target object/model whose permissions are being modified"
},
{
"type": "object",
"description": "The User ODM model instance"
},
{
"type": [
"string",
"boolean"
],
"description": "Optional result or status of the permission change"
}
]
}
None (null) — This event does not accept a return value.

externalConnections

Scope: System Dispatch: systemEvent noWrap: false (Read-Only Proxy)

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: array
Positional parameters: [url, ip]
Positional Arguments:
  1. arg[0] (string): The requested external URL
  2. arg[1] (string): The remote address and port (or "No Connection")
View Raw JSON Schema
{
"type": "array",
"description": "Positional parameters: [url, ip]",
"items": [
{
"type": "string",
"description": "The requested external URL"
},
{
"type": "string",
"description": "The remote address and port (or \"No Connection\")"
}
]
}
None (null) — This event does not accept a return value.

LRSLogSaved

Scope: LRS Dispatch: lrsEvent noWrap: false (Read-Only Proxy)

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: object
The LRS clientLog ODM document or log entry object
Object Properties:
  • type (string)[optional]
  • message (string)[optional]
  • context (object)[optional]
View Raw JSON Schema
{
"type": "object",
"description": "The LRS clientLog ODM document or log entry object",
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"context": {
"type": "object"
}
},
"additionalProperties": true
}
None (null) — This event does not accept a return value.

systemStop

Scope: System Dispatch: systemEvent noWrap: false (Read-Only Proxy)

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.