You're receiving this email because you signed up for an account on Veracity Learning. You'll need to verify the account's email address before you can start using the system.

Here's the link to verify [Your username]'s email:
Verify your account

If your email program cannot display links, you can also enter the code manually. Open the address below:
https://lrs.io/ui/users/validateEmail/

And when prompted, enter the code:
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

From here, you can either click the "Verify your account" link or copy the code offered and browse to https://lrs.io/ui/users/validateEmail/. Once your email address is validated, just accept the terms of service, and you'll be logged in.

Creating LRS's

Users can create up to a certain number of separate LRSs depending on their account tier. Each LRS in our system is completely independent. They don't share keys, analytics, or even the same database. This lets you separate different uses of the LRS. One common scenario is to use one LRS as a testing environment, and a different one to host your production data. A few of our customers have their own learning tools and choose to manage a fleet of LRSs for their own clients. However you use them, it's important to understand that there is absolutely no data of any sort shared between your LRSs (or indeed anyone else's). They are separate systems.

We create a sample LRS for users when they first sign up. This does eat into your storage allocation, so feel free to delete the sample LRS if you need to. This sample LRS will be populated with sample data, so you can get a feel for how the system works.

When you log in, you'll see something like this:

This page gives you a quick overview of your existing LRSs. You can see what data is allocated, the traffic and errors rate over time, and the amount of storage used. If you haven't created all your allowed LRSs, then you'll see a button near the top of the page.

If you're allowed to, click this button to begin setting up a new LRS. Once you click the button, you'll be presented with a form to fill out.

This form sets up the new LRS. You can change these options later, but with some drawbacks.

• LRS Name — choose a name for the LRS. This name will become part of the URL for your xAPI endpoint. If you change it in the future, then you might have to update the connection string in any learning record providers. You'll be notified if the name you choose is not available. These names must be globally unique on lrs.io, and unique to your domain if you have a self-hosted version.
• Strict API Mode — This controls how tightly your LRS requires the exact behavior from the xAPI spec. There are a lot of legacy content authoring tools out there that don't properly support the spec. We recommend leaving this unchecked to support the widest possible range of learning record providers.
• Verbose Logs — Whether or not we keep detailed logs of the traffic to the LRS. Leave this on unless you're sure you won't need to troubleshoot any content. We allow you to disable this because the logs can eat into your storage allocation. You can also manually clear the logs and any time to free up space.

Once you click the Create button, you'll see the management page for your new LRS!

xAPI Access Keys

xAPI requires you to use HTTP Basic Authentication when sending data or querying the LRS. Don't use your lrs.io name and password — these credentials will not connect to an LRS. You'll need to allocate "access keys" to create a username/password pair to connect to the LRS. You can create multiple keys — don't feel like you must have just one. A common pattern is to create keys for each different learning record provider that might send data to your LRS. You can also allocate keys for each student or organization… it's up to you how you use them. Still, you must have at least one.

Click the big red button. Since you can't use the LRS without any keys, it's highlighted for you. On the following page, you'll see listed all existing keys (if you have any) and a green button like this:

Click this button to create a key. We'll suggest a username and password for you. You'll see a form like the one below. Again, you can change the setting for the key at any time, but read the bullets below!

• Key Name — A name for the key. This is used to display it in the user interface, but also to set the authority field of the xAPI statements sent with this key. Changing this value can change the name in the authority field, which might not be what you expect! Exercise care when changing this value.
• Read xAPI Permission — This key can be used to read xAPI data. It can issue GET requests to the document endpoints, and query for xAPI statements.
• Write xAPI Permission — This key can write xAPI statements and send PUT and POST requests to the document endpoints. This permission is currently required to use the Aggregation query feature, since it issues a POST request with the query body. We'll fix this in the future.
• Limited Read — When querying the statement endpoint, only return values that were created by this key. Note that this cannot be enforced for the document endpoints, because they don't store authority data. This value is also incompatible with the Advanced Queries option below.
  
• Advanced Queries — Allow this key to be used on the advanced query extensions to the xAPI. Allows access to /statements/search and /aggregate.
• JWT — Allow this key to sign JSON Web Tokens.

Accessing the API with JWT

Using JSON Web Token (JWT)-based access controls greatly simplifies the task of generating short lived credentials. Instead of using a REST API to tell the LRS to create a Basic Auth credential, then revoke it at the end of a session, you can send a payload in the Authentication header that describes what rules are enforced. Why can't the client fake this? Because it's digitally signed with a key that you got from the LRS. Since it's signed, we know the rules (like read, write, or timeout) are what you intended, and because the user sees only the token, not the secret, we know that they can't forge their own. Finally, since a JWT is stateless, we never have to store it in a database, and neither do you. You just generate one on demand, hand it to your client's browser, and forget about it. When it expires, we will reject it — all this without any API call or database logic. It's a fantastic way to authorize clients to your LRS.

When you set up a JWT key, that key cannot be used for regular HTTP Basic Authentication. Never share the password for this key! It can be used to generate access tokens to your server. Should you accidentally lose control of this value, you can disable or delete the key in the LRS, and no tokens signed by it will be valid. The above configuration is the only one that will allow JWT access — you must uncheck all four permissions.

You cannot modify an existing key to sign JWTs. This is a security precaution.

Veracity Learning includes a tool for you to use a key to generate a valid JWT, and to see the expected payload. Not that you do not need to use the Veracity Learning software to generate this token — we offer this functionality for testing purposes. We expect that your LMS or server-side application can generate these tokens. In fact, that's the primary benefit. Your application can issue limited access tokens against the LRS without interacting with it. Click Generate a JWT from the context menu to see the options.

The above form lets you set some options. Most importantly, you can set a time after which the token will expire. You should also allocate some unique ID to the Token ID field. The choice of this value is important but depends on your application's needs. When using the Limited Read permission, xAPI queries are only allowed to fetch information that was generated by the "authority" that issues the query. Because a token can expire, the token itself cannot be used to scope this query. Data posted with a given token ID will use that token ID as the authority, thus allowing you to issue additional JWTs that can read the same, limited pool of data, after one expires. For many use cases, you can leave this blank or enter a random string.

{
    "jti": "Some Unique Value",
    "exp": 1570579200000,
    "sub": "",
    "read": false,
    "write": true,
    "advancedQueries": false,
    "limitedRead": false,
    "aud": "local.veracity.it:3005",
    "iss": "TheTokenIdentifier"
}

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJTb21lIFVuaX
F1ZSBWYWx1ZSIsImV4cCI6MTU3MDU3OTIwMDAwMCwic3ViIjoiIiwicmVhZCI6ZmFsc2UsIndyaXRlIjp
0cnVlLCJhZHZhbmNlZFF1ZXJpZXMiOmZhbHNlLCJsaW1pdGVkUmVhZCI6ZmFsc2UsImF1ZCI6ImxvY2Fs
LnZlcmFjaXR5Lml0OjMwMDUiLCJpc3MiOiJUaGVUb2tlbklkZW50aWZpZXIiLCJpYXQiOjE1Njk5NTI5N
jd9.BAvB4rYGb_wLVV9g0lzgzCI_cjISRa4uhZHqXSuz29U

Viewing xAPI Data

Veracity Learning gives you lots of tools to review your xAPI data. At the most basic level, you can use our Statement Viewer to see your statements. We also have viewers for the document stores, binary attachments, and access logs. We also have a beautiful set of charts you can access from the Analytics page. Most basic data view features are in the left menu, under xAPI Data. You can also find them from the View Data page under All Management Tools.

Viewing xAPI Statements

Statements are the backbone of xAPI. Each one represents an experience, event, or learning activity that a student takes on some content. Our statement viewer lets you explore the statements in the LRS by filtering, sorting, and searching on a variety of fields. The default configuration of the Statement Viewer looks like this.

Most of the toggles here let you show or hide additional columns. Each of these is a field from the xAPI statement data model. When you show these columns, you can sort or filter on them. There are a few toggles that control other aspects of the viewer.

• Format Dates — present the timestamp and stored fields in an easy-to-read format. Disable this to see the raw timestamp.
• Raw IDs — instead of picking a pretty display name out of the statement, display the actor and object IDs directly.
• Property Icons — These icons show you additional information about what sorts of data the statement contains.
• Full Text Search — This controls how the search boxes at the top of the viewer work. When enabled, you can search within the field for words or phrases. When disabled, you search within the raw data for the field, rather than the pretty display values.

Throughout Veracity Learning and the User Manual, you'll see the terms actor and "agent" used interchangeably, and so too the terms object and "activity".

You can clear the search box by clicking the "X" icon on the left. Some columns can be used to sort the results. Click the column header to sort. A border will appear at the top or bottom of the column title to indicate that the results are sorted in ascending or descending order on that field.

This shows us that the results are sorted by stored date, with the newest first. Some search boxes present choices to you, for fields where the xAPI spec defines a vocabulary.

Property Icons

	This statement has a result value
	This statement has a context value
	This statement has extensions
	This statement has a platform value
	This statement has attachments
	This statement has registration
	Search for all statement where this column has this value
	Chart this actor or object in the Analytics tool
	Refresh this page, retrieving new statements that match the current filters
	Refresh this page, retrieving new statements that match the current filters every few seconds
	Export this chart as a CSV file. Note that this includes all pages, not just the current page

Viewing xAPI Document Stores

The xAPI has a few places where learning record providers can store data to be associated with an agent or activity. Veracity Learning offers viewers for the Activity State, Activity Profile, and Agent Profile data stores. Each works basically the same way.

Here, we can see an Activity State. In this case, the posted data is a JSON document. The LRS will attempt to render the data in a meaningful way whenever possible, but it may not be possible to preview all data. The top four fields show the "context" for this document and are required to retrieve this data from the xAPI.

The Attachments viewer will show you the binary data associated with xAPI statements. You can click the Download icon to export the attachment.

The Analytics Page

The LRS includes a large set of visualization tools to help you get actionable insights out of your raw data. You can access this page from the Analytics option in the left menu. This section will describe how the tools work but won't list every possible visualization. Also, read our User Manual article on Custom Dashboards and Charts.

The dashboard system presents a set of widgets, each of which shows a chart, table, or other rendering of some analysis of your data. These widgets are dynamically placed, so your view might not match these screenshots exactly. The system attempts to fit the available widgets into the space available, making them larger or smaller depending on the screen layout and the amount of data they need to display. Also, the content of each dashboard is dynamic. The system will try to hide charts that are meaningless for your data — for instance, a chart of the distribution of scores would be hidden if the data set for the dashboard did not include any xAPI statements that included score information.

The Analytics page also replaces the options on the left menu. Instead, it shows you a list of available dashboards. The dashboards available to you depend on the scope that the analytics package is attached to. Most users will deal only with the LRS Overview dashboard, which shows information about all the data in the LRS. Other dashboards include the Activity Overview, which shows information for a specific object, or the Agent Overview, which restricts the data to only one actor. Additional dashboards are planned in the future.

Click the Back to LRS menu option to return to the LRS Home page. The default dashboard in the LRS scope is LRS Overview dashboard, shown above.

Each dashboard has a set of options that scope what data is displayed. Expand the down arrow below the dashboard title to show the parameters.

All dashboards include a global Time Range filter. Click the button to choose a time range for the dashboard.

Each parameter type will present you with a search box. We strive to minimize the number of URLs and IRIs you must remember, and present intelligent autocomplete text wherever possible. The autocomplete text boxes display the human readable title of activities and agents. You can also paste in the exact activity ID or agent IFI if you know it.

Sometimes, you might find that the dashboard requires that you choose a value. In this case, the choices will be expanded automatically, and you'll see a warning that some value must be selected.

You can hover your mouse over pie slices, bars, and lines to show a tooltip with more information. When the pie slice or bar represents an actor or object, you can click it to open the appropriate dashboard for that actor or object. For instance, below is a section of the Agent Overview dashboard for a certain actor. In their pie chart showing what activities the student has recently used; we can click the pie chart slice to move to the Activity Overview dashboard. The parameters for the Activity Overview dashboard will be set to show the "Forward Button" object, since this is the slice that we clicked.

When a graph shows a legend, you can remove results from the display by clicking in the legend box. The graph will automatically update to best illustrate the remaining data.

Graph results can be expensive to compute. Each value is cached for a predetermined amount of time. To ignore this cache and reload the graph, click the icon in the upper right of each widget.

Exporting Widget Data

Veracity Learning gives you a few tools to export the information from a widget. Many can simply be downloaded as a rendered image in JPG, PNG, or SVG formats. You can also export that raw data that went into the chart as JSON, CSV, or Excel.

Each of these features is accessed by moving the mouse over the More (…) icon on the upper right.

You can also embed a live copy of a widget in a blog, forum, or website. Click the icon in the upper right of the widget. This will open a confirmation dialog.

Clicking the Get Link button will create a unique link to this chart that you can paste into any system that accepts HTML. Heed the warning: this is intended to make the chart data public. Anyone with the link can view the chart.

You can also embed a full dashboard with a similar interface. Click the Link icon in the upper right of a given dashboard. The current parameter values will be recorded. Unless you check the Allow Parameter Modification option, the dashboard parameter will be set and unchangeable. Checking the box will allow the embedded dashboard to change the value, like selecting another actor or changing the time range.