...
Connection HTTP Interface via http://www.example.org/api/connection/statementforwarding.
REST HTTP Interface via http://www.example.org/api/v2/statementforwarding.
SCHEMA
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. |
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 |
---|---|
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
Code Block |
---|
{ "_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" } |
...
Code Block |
---|
{ "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 ofYOUR_USERNAME:YOUR_PASSWORD
. In the Body tab in Postman, ensure to selectraw
andJSON
as the type.
The payload here is a simplified statement, to mimic what will be sent during forwarding:*Code Block POST https://yourendpoint.com/any-path-or-port Authorization: Basic YOUR_BASIC_AUTH Content-Type: application/json [ { "actor": { "name": "Test Persona", "account": { "homePage": "http://example.com", "name": "12345" }, "objectType": "Agent" }, "verb": { "id": "http://adlnet.gov/expapi/verbs/registered", "display": { "en": "registered to" } }, "object": { "id": "http://example.com/123", "definition": { "type": "http://example.com/123", "name": { "en": "TEST" } }, "objectType": "Activity" }, "timestamp": "2023-01-05T06:11:35+00:00" } ]
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).