adlantics is an integrated system for advanced learning analytics. Its main objective is to unearth
actionable patterns from large sets of learning records so that training organizations can more effectively manage their
training. At its core, adlantics provides fast, reliable, and secure mechanisms for:
storing learning records,
retrieving learning records and aggregates thereof,
computing trends, patterns, and other "intelligent, non-obvious" summaries of learning records, and
managing large collections of learning records.
adlantics is capable of doing so for even the largest and most dynamic learning environments where millions of learning
records are generated every hour.
At the end of this quick start tutorial you will be able to access the adlantics platform from the command line to store
and retrieve simple learning records and analytical information. Please refer to the overview section
for a higher-level introduction.
To follow the quick start tutorial you will need:
Credentials that identify you as a legitimate user of the system. The process of establishing you as a legitimate
user is also referred to as authentication below. For the purposes of this guide, we will work with simple user name
and password credentials. However, adlantics equally supports more sophisticated authentication methods, such as two-factor
authentication or federated authentication through your Facebook, Google, or corporate network accounts. See the
authentication section for further details.
To follow the command line access examples you will additionally need:
A Realm that identifies the private database on the adlantics platform you will operate on. adlantics as a hosted
service is built from the ground up to ensure that your data is kept strictly confidential and separate from other users'
data. A realm is a short text identifier that uniquely identifies your separate, private database on the adlantics
A command-line HTTPS client. We use the popular cURL client below, which can be freely downloaded
here for most operating systems. However, any other client capable of basic
GET and POST operations with headers will work just as well.
For information on your realm and credentials, please contact us. The command line example
requires basic familiarity with your operating system's command line as well as the HTTP protocol. If you have any
questions about this tutorial, please contact us.
Access from the Command Line
Access to the adlantics platform through the command line proceeds in three main steps:
Obtain an access token representing your identity, as well as the permissions you hold
Optionally check the token for validity and review its contents
Call the service and operation you wish to perform, e.g., store or retrieve a learning record
You can repeat step 3 with the same token as often as required, as long as the token is valid. When using adlantics from
within one of your production applications, the first two steps are part of a one-time setup and the bulk of your calls
to adlantics operations will consist of calls to actual operations (i.e., step 3).
The following figure provides an overview of the three steps above:
Note, that for this tutorial we have selected the adlantics Experience Store (xs) as the service we will call for
reasons of simplicity. In practice you will interact with multiple services, each dedicated to a particular aspect of
the learning analytics challenge. However, all adlantics services operate on the same principles outlined below.
Please see refer to the overview section for more details.
Let us now consider each of the three steps in turn.
Obtaining an Access Token
With your credentials and realm information ready, the first step is to obtain an access token from the system.
An access token is a long string of characters that encodes who you are and what you are entitled to do with the system.
adlantics uses the JSON Web Tokens (JWT) standard for its access tokens with further information on
this topic to be found under authentication. Think of an access token as a passport that the system
issues based on your credentials, that is valid for a certain period of time, and that is presented, as a surrogate for
your credentials, on every subsequent call to the system.
Service and Operations Notation
Each service and operation in the adlantics system
is uniquely identified by a URL. We will often abbreviate such URLs to only contain the operation-specific suffix, so
that the /login operation of the management service is actually reached under the full URL
https://mg.adlantics.com/login. Please prepend https://mg.adlantics.com (management service) or
https://xs.adlantics.com (experience store) to the operations in this tutorial when not explicitly mentioned. Refer to
the service parameters page for more details.
There are several ways to obtain an access token from the system depending on the caller's needs. Here, we will
use the simplest way and manually enter our credentials on a web page in exchange for an access token:
Open your browser of choice and navigate to the management service's interactive login page at /login
The system redirects you to the login page and asks you for your user name and password.
After entering your credentials correctly, the system returns to the interactive login page where you now see a long
character string representing your access token, along with its expiration time, as in the following screenshot:
Copy the access token to the clipboard as we will need it in the subsequent steps.
While access tokens look cryptic at first, they are actually easily legible using the right tools, and are only
superficially encoded to make them easier to share between sender and receiver. We will see one way of interpreting
access tokens in the next step. The authentication section describes other tools.
Validating the Access Token
Equipped with your access token, you can now access various adlantics services and operations. One simple but helpful
operation that every adlantics service provides is /status which returns diagnostic information about the service and the
caller. This is one of the few operations that can be called without prior authentication, so let us first access it in
an anonymous fashion by executing the following command:
The output on your system may vary but will contain basically the same information. Without knowing who you are, the
system is willing to reveal its own identity (adlantics-xs refers to the Experience Store service, and the current version
will change frequently as the system evolves), as well as the fact that it diagnoses itself as healthy. If you see this
or a similar output you have successfully connected to adlantics platform!
Let us now identify ourselves to the system and observe the difference in result. To this end, we will issue the same
request but now include two so-called headers, one identifying the realm we wish to operate on, and one containing
the access token we obtained in the previous step. To have cURL send these headers we use its -H option twice and give a
key-value pair on each occasion:
For the realm, we send a Realm header with the realm identifier obtained above.
For the access token, we send an Authorization header with your access token preceded by the word Bearer.
As you can see from the output above, the basic response looks the same as when we asked anonymously. However, the system
now additionally includes information regarding what it inferred about you based on your access token. This information
is contained in the passport attribute:
realm - indicates the realm you operate on. For most users, this value will always refer to their organization's
unique realm. However, there are also cases in which one organization operates across multiple realms, in which case this
information becomes critically important.
permissions indicate at a lower level, what you are allowed to do in the given realm. Some users might be
restricted to read-only access on a given realm, or might only be allowed to retrieve data from certain parts of
their organization. Permissions are a complex topic discussed more in depth in each service's documentation.
subject refers to the caller's unique user id within the system. While this is rarely of interest under normal
circumstances, adlantics supports certain complex identity management setups (e.g., federated logins, single sign-on, etc.)
where this information becomes important.
Now that you have successfully connected and authenticated to the adlantics platform you are ready to use its actual operations.
For the purpose of this tutorial, we will send a learning record for storage in the Experience Store and then perform a
simple query to retrieve the same learning record back from storage. While the storage and retrieval of individual records
may not be the most sophisticated use case, it allows us to demonstrate certain principles that will resurface in even the
most sophisticated operations, from real-time streaming of gigabytes of learning records to advanced machine learning.
The most important ingredient in this task is the learning record we wish to store. Learning records in the adlantics
system are expressed using the conventions of the so-called Experience API or xAPI.
Understanding the xAPI along with the vocabularies that have been developed to fill the standard with life is an
important topic in its own right. The adlantics platform is open to any kind of xAPI vocabulary but it also comes with a
proposed vocabulary based on experiences we have made in customer projects within certain domains. Please refer to the
vocabulary section for further details.
In this tutorial, we will limit ourselves to the simple learning record, or statement in xAPI parlance, given above.
Syntactical conventions aside, this statement is easy enough to interpret, and it follows the xAPI standard's general
Actor (the person or system acting)
Verb (the action performed)
Object (the target of the performed action)
Using the statement above, we assert that an individual identified by her email address email@example.com viewed
a certain object, namely the web page stored at https://www.adlantics.com. By sending this data to the adlantics
platform we are not only storing this statement securely and reliably without having to worry about backups or data
security. Much more importantly, we are making an assertion about the particular learner that the system can
use to make intelligent inferences such as:
How active is the given individual? Are there areas that the learner is particularly active in?
How can instructors, management, or an automated system increase the learner's engagement?
What are the factors leading to the individual's (lack of) success, especially when compared to other learners?
How should the curriculum be redesigned to systematically improve learner outcomes?
Sending the statement above to adlantics proceeds in much the same way as retrieving status information with the exception
that we are now directing our request to the /experience resource of the Experience Store, and we are using a POST
operation instead of the GET operation used above, consistent with our objective of sending data. We also include the
-d option in our curl call to specify the data we wish to submit.
Modifying Production Data
Issuing the following commands will result in changes to your realm. Please ensure that you are operating on a test realm
so as to not pollute your production data.
The response to our request contains a list of individual responses, one for each submitted statement, in the order of
submission. As we submitted only one statement, the response only contains a single id that the system assigned to
the statement when it was stored. This id uniquely and permanently identifies the statement we submitted, and it will be
different for between invocations, even if the same statement is submitted multiple times.
To retrieve our previously stored statement, we simply issue the following GET request to the /experience resource,
where you will have to substitute the id you obtained for your case:
Several things are worth noting about this response:
The statement is wrapped in an experiences array even if it is the only statement. This is so that responses that
do contain multiple statements can use the same response format.
The statement now contains several pieces of data that were not submitted originally. The id we encountered
before has been permanently assigned to the statement. xs has also spelled out the object type (which, in the xAPI specification,
is Activity by default) and it has added a stored timestamp containing the time when the statement was stored in the
LRS. While storing the statement, and invisible in the output above, xs also performed data quality checks on the
statement, including checks for compliance with the basic xAPI standard as well as additional user-defined standards
imposed on the realm. The adlantics Experience Store comes with a powerful, configurable validation engine that allows
its users to single out faulty statements for further diagnosis before they are admitted into the permanent record.
This attention to data quality stems partly from the fact that statements, once committed to the LRS, are permanent.
The xAPI standard supports a process called voiding, but even a voided record will stay on file. It is only
considered void for the purpose of analyses, etc.
Conclusion and Further Reading
By successfully submitting and retrieving you first statement, you have completed this quick start tutorial. While the
sample use case may not have been very difficult, it introduced important topics such as authentication, authorization,
and service status, and it allowed you to check your end-to-end connectivity with the adlantics Experience Store.
The Experience Store is the basic source of truth about learners and, as such, it supports many more intricate operations
than the one we saw in this tutorial. As a next step, consider learning more about important Experience Store concepts,
such as performing complex queries or xs' extensive support for hierarchical and structured data. Users with a thorough
background in learning analytics may also proceed to the adlantics Analytics Engine documentation for
information on more "learning analytics" type inferences that adlantics calculates from stored experiential data.