Statement Forwarding

Details of a statement forwarding configuration.

It is accessible through the following HTTP interfaces:

SCHEMA

Name	Description

Name	Description
_id	The unique id of the document.
createdAt	When the document was created.
updatedAt	When the document was updated.
description	The name of this statement forwarder.
lrs_id	The id of the store that Learning Locker will forward statements for.
active	If this statement forwarder is currently active.
configuration	The configuration for this statement forwarder See configuration.
owner	Id of the user who created this statement forwarder.
query	A JSON Mongo query string - only statements which match this query will be forwarded. e.g. `'{"statement.verb.id":"http://adlnet.gov/expapi/verbs/completed"}'`
isPublic	If false then this statement forwarder is only available to the owner and users with org/all/statementForwarding/view scope, otherwise it’s available to everyone in the organisation with permission.

CONFIGURATION

The configuration for the statement forwarding request.

Name	Description

Name	Description
protocol	http, https. The protocol to forward statements to.
url	The url to forward statement to.
authType	no auth, token, basic auth. The auth method to use.
secret	If authType is token, this is the token which will be sent with the request.
basicUsername	If authType is basic auth, this is the basic auth username.
basicPassword	If authType is basic auth, this is the basic auth password.
maxRetries	The number of times the statement forwarder will retry before giving up.
headers	A json array encoded as a string which contains additional headers to send with the request.

EXAMPLE MODEL

{
  "_id" : "59c8d14b0d82b3864a450604",
  "createdAt" : "2017-09-25T09:50:03.880Z",
  "updatedAt" : "2017-11-06T14:07:27.212Z",
  "owner" : "59198183d8ea540933227030",
  "query" : "{}",
  "organisation" : "59c209c4ad95fd50960c0362",
  "isPublic" : false,
  "configuration" : {
      "authType" : "no auth",
      "protocol" : "https",
      "url" : "example.org/endpoint",
      "maxRetries" : 10,
      "headers" : "{\"Test-Header-Key\":\"Test-Header-Value\"}",
      "secret" : "Dave"
  },
  "__v" : 0,
  "active" : true,
  "description" : "Statement forwarder"
}

[ENTERPRISE]: FORWARDING TO AWS KINESIS

Note: Only available in Enterprise editions of Learning Locker

To create a statement forward configured for AWS Kinesis Firehose, configure the record with this modified data structure:

  "configuration" : {
    "protocol" : "Kinesis",
    "authType" : "no auth"
  },
  "kinesisOptions" : {
    "streamName" : "KinesisFirehoseName", // The immutable name of the Kinesis Firehose configured in AWS
    "awsClientKey" : "xxxxxxxxxxxx", // AWS client access key with appropriate permission
    "awsClientSecret" : "xxxxxxxxxxxx", // AWS client secret key
    "awsRegion" : "us-east-1" // AWS Kinesis Firehose region
  },

PERMISSIONS

In order for Learning Locker to successfully write to the Kinesis Firehose, please ensure that the IAM user (attributed to the key/secret) has the minimum permissions in its policy (as shown below). When using the example below, please replace region, account-id, and KinesisFirehoseName with your details in the Resource array.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "firehose:PutRecord",
            ],
            "Resource": [
                "arn:aws:firehose:region:account-id:deliverystream/KinesisFirehoseName"
            ]
        }
    ]
}

MOCK TEST

The following example shows how to run a mock request for a single statement being forwarded to a downstream endpoint.

In this example, the statement forwarding is using https protocol, using basic auth as auth type. Other protocol or cred types should work similarly.

Endpoint test:

Set up an endpoint which allows basic auth authentication. This is the endpoint that will receive the statement payload when it is forwarded. E.g., https://yourendpoint.com/any-path-or-port
Using Postman, prepare the following request using POST. Note YOUR_BASIC_AUTH is the base64 encoded version of YOUR_USERNAME:YOUR_PASSWORD. In the Body tab in Postman, ensure to select raw and JSON as the type.

The payload here is a simplified statement, to mimic what will be sent during forwarding:*
Click send. If your endpoint is robust it should receive the statement payload as in the request above, and in Postman the request should indicate to be successful (2xx status)**.

Integrated test:

Set up a statement forward (Data->Statement Forwarding) in the UI.
Leave the Query Builder as is and activate this statement forward. This means the filter is left empty and any statements will be forwarded to this particular forward.
Send a statement to the LRS (using our existing Postman Collection on inserting a new statement).
Assuming there is no backlog, the statements should instantly arrive and complete the forwarding queue. Locate this statement in Data->Source and expand the statement. Check the completedForwardingQueue should contain 1 entry (the statement forward’s ID).
Check your endpoint, at this point it should receive the statement that just arrived*.

*Currently supporting sending full statement document as an option.

**For example, if your endpoint returns a 4xx status, this will be accumulated in the failed requests and will trigger deactivation of statement forward (in most situations, if configured accordingly).