Saved Scripts
The saved script feature can be used to store scripts in the VQL or JavaScript format. These scripts can be attached to the read or write functions of an access key, or the outgoing data that is sent via forwarding rule. In the future, more areas of the xAPI data flow will support scripts.
Whenever a Scripting allows you fine grained control of what data will be sent to an upstream, or what data can be read or written by an access key. In addition to filtering the dataset to remove items, you can also transform the statements.
Whether written in JS or VQL, the script must return an array of valid xAPI statements, or an empty array. In VQL mode, each xAPI statement is processed through the VQL pipeline and the results collected into an array, so the array return type is implicit. However, you must ensure that the logic in the query does not modify the incoming data such that is is no longer valid xAPI.
Whenever a script generates an error, the input array is passed without modification. This means that an error in your script will never cause data loss. However, if you are relying on a script to anonymize or control data access, a script error might expose data. Script errors can be reviewed in the Logs section of the LRS.
VQL Mode
VQL mode is preferable because it's performance is 4 times greater than JS mode.
The below example filters the data. When statements are received, if they are any "actor.name" other than "Rob C", they will pass, either to the upstream, to the database (when attached to the write command on an access key), or the the API results (when attached to 'read');
{
filter:{
"actor.name":{
$ne:"Rob C"
}
},
process:[
]
}
You can also append additional data. This adds an extension to all statements. Note that we must manually escape this extension name
{
filter:{
},
process:[
{
$addFields:{
"context.extensions.http://myExtension*`*com":"Some Value"
}
}
]
}
You can reference existing values, and modify them with expressions. This script makes the actor anonymous in a deterministic way.
{
filter:{
},
process:[
{
$addFields:{
"actor":{
"account":{
"homePage":"http://anonymous.com",
"name":{
$hash:"$actor"
}
}
}
}
}
]
}
You can use a switch expression to conditionally apply some transformation. This script makes the actor anonymous when the actor.name property is "Rob C". Otherwise, the actor is left as is.
{
filter:{
},
"process":[
{
"$addFields":{
"actor":{
"$switch":{
"branches": [
{
"case": { $eq: ["$actor.name", "Rob C"] }, then: { "account":{
"homePage":"http://anonymous.com",
"name":{
$hash:"$actor"
}
}}
},
],
"default": "$actor"
}
}
}
}
]
}
Due to security considerations, Javascript mode is no longer available
Javascript Mode
Some logic can be difficult to express in VQL. You may write imperative JavaScript. JavaScript executed by our servers runs in a sandbox JavaScript interpreter. Because of this important security consideration, execution can have low performance. If performance is a concern, rewrite your logic in VQL. The JS environment has no access to any global state, npm modules, external scripts, HTTP, DOM or any other resources - it can only be used to express logic over strings, objects and numbers.
When writing JS scripts, there are 2 special case variables to be aware of:
- $input - this is the array of input statements
- $output - this is the resulting array. You must populate this with an array value
We do expose a very limited set of functions to the interpreter for your convenance. You can use normal JS language features like Math.random or Array.isArray
- $hash - compute a hash from any JS object
- $uuid - generate a random UUID
The below example filters the data. When statements are received, if they are any "actor.name" other than "Rob C", they will pass, either to the upstream, to the database (when attached to the write command on an access key), or the the API results (when attached to 'read'):
{
let out = [];
for(let i in $input)
{
if($input[i].actor.name !== "Rob C")
{
out.push($input[i])
}
}
$output = out;
}
You can also append additional data. This adds an extension to all statements. Note that we must manually escape this extension name, and that for simplicity's sake, this example destroys the existing extensions.
{
let out = [];
for(let i in $input)
{
$input[i].context = {
extensions: {
"http://myExtension*`*com" : "Some Value"
}
}
out.push($input[i])
}
$output = out;
}
You can reference existing values and modify them with expressions. This script makes the actor anonymous in a deterministic way.
{ let out = []; for(let i in $input) { $input[i].actor = { account:{ homePage:"http://anonymous.com", name: $hash($input[i].actor) } } out.push($input[i]) } $output = out; }
Related Articles
VQL
(VQL) Veracity Query Language VQL is a language for representative queries over xAPI statements and how they should be processed and rendered. It underlies the Veracity Learning LRS in several places, including the xAPI and dashboard components. ...The Learner Portal
The Learner Portal is not available in the downloadable Lite version of Veracity. Veracity Learning LRS is primarily a Learning Record Store for xAPI data, we do have a few basic Learning Management System features. Because xAPI can replace some ...Custom Dashboards, Graphs and Analytics Processors
Veracity Learning offers several ways to generate custom dashboards. At the most basic level, you can place widgets (graphs or tables) on a dashboard page. Each widget is customizable with a set of options like what actor, what object or what verb to ...