LRS Management
Veracity Learning LRS gives you many tools to manage your LRS and the data in it. These include backup and restore features, import and export features, as well as tools to update, migrate and modify the data in the LRS.
LRS Management Basics
Now that you have an LRS, you'll probably want to learn more about what tools you can use to manage it. While several features are available from the left side menu, you can find all of them from the "All Management Tools" link.
Taking The LRS Offline
If for any reason you need to temporality take the LRS offline, so it can no longer receive statements, you can click "Deactivate LRS". This can take a few seconds to become active. Once it does, all clients connecting to the xAPI endpoint will receive an error message indicating that the LRS is offline. xAPI read and write operations will not modify the state of the database.
Generating And Deleting Sample Statements
Veracity Learning LRS offers you the opportunity to populate your LRS with some sample data so you can test the tools. If you've subsequently posted real data to an LRS, you might want to filter out and delete the sample data.
To generate sample data, the LRS must have a minimal amount of data present already. This is to prevent you from confusing sample data from production data. If you have only a few statements, a link will appear beneath the LRS stats box on the LRS home page.
Once you click this button, a background process will generate some data. After a few seconds the page will refresh, and you'll see new xAPI statements are in the LRS.
To clear this data, you can find the link under "All Management Tools" that says "Clear Sample Data". This will scrub the sample data from the LRS.
Clearing Logs
If you have verbose logging enabled, you might find that a significant amount of your storage allocation is used up by verbose records of every HTTP transaction. You can clear logs by clicking the "Clear Logs" link from "All Management Tools"
Clearing XAPI Data
Be careful using the options below. Unless you've created a backup, there is no way to undo these options. You can permanently remove the xAPI binary attachments, documents in the document API endpoints, or the statements themselves by clicking "Clear attachments", "Clear Statements", or "Clear Documents". Again, this cannot be undone!
System Messages
You may occasionally see a message on the LRS home page. These messages are warnings, events, or other pieces of information you might need to know. These messages are generated by the system when some running task completes, when some error condition occurs, or when a configuration change requires you to take some action. You can generally dismiss these messages by clicking the white "X" on the right, but if they represent a state where you need to take some action, they will simply reappear.
Deleting The LRS
You might find that you're completely finished with a test environment, or that you need to remove an old LRS to make room for a new one. Deleting the LRS removes the database completely, scrubbing out every record related to it. This includes a huge amount of internal data that you don't interact with. Because of this internal data, we do recommend that you use this option to destroy an LRS, rather than clearing all the data and using it for a new purpose. We don't impose any limits on how often you can do this, so it's a good option to use when you need to change the fundamental settings and don't want to keep the data. For instance, if you're testing your environment and are ready to move to production don't rename "testLRS" to "productionLRS" and clear the data. Just delete one and create the other.
Changing LRS Settings
The initial settings you choose when creating the LRS can be modified at any time. This includes strict mode, verbose logging mode, and the LRS name. Choose the options "LRS Settings" from "All Management Tools". Be careful when changing the name! This will update the URL that your Learning Record Providers should send data to.
Import and Export
It's your data - you should be able to do what you like with it. Veracity Learning LRS gives you several tools to import data, export data, and move data between LRSs. You'll find the import and export tools under "All Management Tools" then "Import / Export"
Exporting A Backup
Any time you have valuable data, it's a good idea to keep backups. If you're in our SaaS version at LRS.io, we manage nightly backups of all databases, as well as host a fault tolerant, geographically distributed, replicated database cluster. Nevertheless, you might sleep better at night knowing that you have your own copy of your valuable data. You can create a full binary backup of the database associated with each of your LRSs. This backup file includes logs, all xAPI data, cached analytics, custom dashboards, learner, class and course files, access keys... everything there is about the LRS. Note that it does not contain LRS setting like the LRS name, strict mode flag, or owner (you).
Once you click the "Yes" button on the confirmation dialog, you'll immediately begin downloading a .bson file. Don't cancel this download! We don't currently have any technology to post this file elsewhere on your behalf - if you want to upload to a cloud storage provider, you'll have to finish downloading it first. The backup file is encrypted. If you have an on-premises Enterprise install, the backup is encrypted with the server secret you provided at install. This file can be uploaded to any install of Veracity Learning LRS that has the same secret. For help decrypting a backup from LRS.io, please contact us.
You can continue posting data to your LRS while the backup downloads. Data added between the start of the backup and the completion will be added to the end of the backup file. There is a small chance that your LRS is receiving data faster than you're downloading the backup. In this case, the backup will never complete. For this reason, we recommend you disable the LRS while downloading the backup.
Restoring A Backup
You can upload a backup file to any copy of Veracity Learning LRS that shares the same secret encryption key. For users of LRS.io, this means you can only restore data to LRS.io. This is by design. Please contact us for help exporting LRS.io LRSs to an on-premises install.
Restoring a backup destroys the existing LRS. Data is not appended - the LRS to which you upload the backup is completely replaced. The only settings that are maintained are the LRS URL, ownership data, and some internal data we use to manage that LRS and your account.
You can use the backup and restore features to duplicate an LRS for testing by download a backup, then restoring to a new blank LRS.
Exporting XAPI Statements As JSON
You might find that you occasionally need to load your xAPI data into some other tool. To retrieve all your xAPI statements in a format that is easy to import into many other tools, choose the "Export Statements" feature. This will immediately start streaming a JSON array of xAPI statements, and your browser will prompt you to choose a location to download them to. Note that this is all data. If you need to export a subset of xAPI statements, try configuring the Statement Viewer with the search query you need, then using the "Download as CSV" button. In the future we'll add an option to use the filters in the statement viewer to configure a JSON export as well.
If your LRS is under heavy load, this export might miss data that was posted after you started the download.
Pulling Data from Other LRSs
Veracity Learning LRS provides a simple tool to help you import all the xAPI statements from another LRS. Choose "Harvest Statements" from the "Import / Export" page. You'll see a form like this one.
Enter the full xAPI endpoint from another LRS, and provide the username and password that can access the data. You can also choose a date - we'll only pull data that was posted after this date.
The process will run in the background - you'll see a notification on the LRS home page when the process completes. You can use your LRS normally while the process runs.
Sending Data To Other LRSs
Veracity Learning LRS can also send data to other LRSs. We call this feature "Statement Forwarding", and you can find it on the left side menu, and also from the "All Management Tools" page. This is not a one time event - once you've set up an "upstream LRS", all new data will be forwarded automatically. For performance reasons, you might notice up to a 500 millisecond delay between Veracity Learning LRS receiving the data and sending it on. There is no limit to the number of upstream LRSs you can configure.
To register a new upstream LRS, click this button.
You'll see a form that looks like this:
The values here are pretty self-explanatory. We need a name and description. These are just for you to keep track of what is what. We also need the full xAPI URL, the username and the password on the remote system to use to post data. Since we retain these in our database, they are encrypted when not in use. Fill out the form and click OK. The Statement Forwarding page will now display a card for the upstream.
The upstream has a few options that you can access from the upper right menu.
- disable - data will not be posted to this upstream, but we'll keep the record so you can enable it again in the future.
- delete - permanently remove this upstream record.
- edit - change the name, description, endpoint or credentials.
- resync - send all historical data to this upstream. Use this if you've added the upstream after accepting data. We'll send everything - even statements that the upstream probably already knows about, The upstream is responsible for rejecting statements that are duplicated.
Sharing Access
Veracity Learning LRS allows you to share access to your LRS with other users. You can allow several permission levels, allowing another user to fully administer, edit, or just view the LRS data. Under-the-hood, every operation on the LRS is assigned a permission value, but these values are grouped into these three categories for convenience. Future versions of the software will allow more granular control of each operation.
Before you can assign a permission level to another user, that user must have an account on the server, and the account must be marked as "public". Accounts that do not opt in to the "public" feature won't appear in the account search box. If you have an on-premises Enterprise install and use the user account features, then the user will need an account on your domain.
You can access the permission management tools from "All Management Tools" then "Change Permissions"
On an LRS that has no specific settings yet assigned, you'll see just your account name, and a note that this account is the owner. You can't remove the ownership permission, nor edit it.
You must add users to the permission dialog before you can assign a permission level. To find a user to add, click the "Add User" button. This will pop up a dialog where you can search for an account on the system.
Users must opt in to being listed in this dialog. Mark your account as "public" in your account page in order to be visible in the "Find Users" list.
You can search for a user by entering a search term in the search box. Click the "Search" link to execute the search.
To add a user to the permissions list, click on their name. This will add a new dialog to the permissions editor. You can also cancel the operation by clicking the "cancel" link on the bottom right. The user will appear in the permission list with the default permission level - none.
In the dropdown menu, you are offered a list of permission levels. These are:
- None - The user has no permissions on the LRS. This is effectively the same as not including the user in the list.
- View - The user can view the xAPI data and analytics, but cannot edit any settings nor see most setting values.
- Edit - The user can view the xAPI data and analytics, and change basics settings like access keys.
- Admin - The user has full control. They can view data, edit all settings, change permissions, and even delete the LRS.
You can remove a user from the list, and remove all permissions, by clicking the "x" button next to their entry.
If you've made any changes to the permissions for the LRS, a save button will appear. You must click save to write the edited values. Navigating away from the page without saving will reset the permissions to there original values.
If you have permissions on any LRSs (other than the ones you own) you'll see a new section when you log in. This section is called "LRSs shared with you" and lists the LRSs on which have some permission.
This dialog lets you see the LRS name, endpoint, and the LRS owner and your permission level. Note that the permission level displays the fine grained permission values rather than the more convenient display name like "Admin" or "View".
If you attempt to access a feature that is not allowed for your permission level, you'll get a permission denied message.
You might also note that some features or links are missing altogether. We've attempted to hide UI elements that you can't access with your permission level, but this work is not complete, so there are still some links that will just lead to the permission denied page.
Database Upgrades and the Analytics Index
This section is for advanced users, and is generally only relevant for on-premises installs. For users of LRS.io, or any dedicated systems managed by Veracity, we handle all the for you.
The features discussed here are found under "All Management Tools" then "Database Management". Each of the tools below will launch a background process that will run as soon as possible. You'll see messages in the message area for the LRS or on your home page when these jobs start and complete. You should disable the LRS until these jobs are finished, so that new data does not interfere with the process.
Rebuild Statements
This process reads each statement out of the database and reinserts it. Run this process when the internal representation for an xAPI statement has changed. This process creates a backup of the entire collection of statements, then streams each through the internal storage logic. Should there be some problem, the old collection can be renamed to
statements to restore the data. Canonical representations will be dropped and recomputed. Because this creates a new Mongo collection to store the re-built statements, it will also have the effect of rebuilding the MongoDB indexes.Rebuild Mongo Indexes
The MongoDB database requires some configuration to make the LRS performance optimal. Veracity Learning LRS configures the database for you - you should not have to manage the MongoDB indexes. If for some reason you've modified the DB index configuration, you can run this process to restore them. The LRS will detect if the indexes are not aligned with the configuration expected and warn you on the LRS homepage. You might see this warning after an upgrade to the software as well. In this case, it's probably better to run "Rebuild Statements".
Rebuild Analytics Cache
LRS.io and any install of the Enterprise version can optionally use ElasticSearch for various analytics operations. ElasticSearch needs a record of each statement. Its possible to receive some statements with the server not configured to use ElasticSearch, then add ElasticSearch later. If this happens in this order, the ElasticSearch server will not have records for all the statements in the system, causing odd errors in the analytics. The LRS will warn you with a message on the home page if ElasticSearch has fewer statements than MongoDB. In this case, you can use this option to resync all statements from MongoDB to ElasticSearch. Note that the operation of posting statements to ElasticSearch is batched by the LRS - it can take a few seconds after receiving a statement for it to be forwarded on. In this case, you might see a temporary warning. This warning will clear after a few seconds. In the rare case that the LRS is under constant load, this message may never disappear. Nevertheless, the system is working as designed. In this scenario, the analytics may lag behind the actual stored data by a few seconds.
Related Articles
The LRS API
Veracity Learning has many tools, features, and functions that users can exercise. While many of these features are available through the user interface, you may wish to automate some of the functionality of your LRS. You can accomplish this via the ...The System API
The on-premises install of the Enterprise version of Veracity Learning includes a system level API for creating users and LRSs. This API works exactly as the LRS level does, with the same conventions for GET, PUT, POST and DELETE. You'll find the API ...LMS Integration
The Veracity Learning offers seamless integration with your LMS to allow instructors and students to access the services of the LRS without leaving their LMS environment. This is accomplished via LTI (Learning Tools Interoperability), a standard from ...Versions of Veracity Learning
Veracity Learning LRS comes in a few versions. The main version, and the one you're most likely looking at right now, is LRS.io. LRS.io This is our cloud hosted SaaS service, where anyone can create an LRS. You can use the free version, which is ...Elasticsearch Integration
Overview The LRS can accelerate its dashboard and statement viewer by leveraging Elasticsearch in addition to MongoDB. When configured with the optional Elasticsearch connection, the LRS will synchronize xAPI statements in real time between these two ...