Quick Start

Last updated: 19 Jun 18 15:22 CEST

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.

Preparation

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 platform.

  • 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:

  1. Obtain an access token representing your identity, as well as the permissions you hold
  2. Optionally check the token for validity and review its contents
  3. 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:

Basic Command Line Flow
Basic Command Line Flow

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:

  1. Open your browser of choice and navigate to the management service's interactive login page at /login
  2. The system redirects you to the login page and asks you for your user name and password.
  3. 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:
    Obtaining an Access Token using the Interactive Login Page
    Obtaining an Access Token using the Interactive Login Page
  4. 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:

curl -XGET https://xs.adlantics.com/status
{
  "name":"adlantics-xs",
  "version":"[current version]",
  "healthy":true,
  ...
}

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.
curl -XGET -H"Realm: [your realm]" \
           -H"Authorization: Bearer [your access token]"
           https://xs.adlantics.com/status
{
  "name":"adlantics-xs",
  "version":"<current version>",
  "healthy":true,
  ...,
  "passport":{"realm":{"name":"[your realm]"},
              "permissions":[{"name":"read"},{"name":"write"}],
              "subject":"[your subject]>"
}

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.

Executing Operations

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.

{
  "actor":{ "mbox":"hello@adlantics.com" },
  "verb":{ "id":"http://adxx.io/viewed" },
  "object":{ "id":"https://www.adlantics.com" }
}

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 structure of:

  • 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 hello@adlantics.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.

curl -XPOST -H"Realm: [your realm]" \
            -H"Authorization: Bearer [your access token]" \ 
            -d'{
                 "actor":{ "mbox":"hello@adlantics.com" },
                 "verb":{ "id":"http://adxx.io/viewed" },
                 "object":{ "id":"https://www.adlantics.com" }
               }' \
            https://xs.adlantics.com/experience
{
  "statementsIds": [ "510371e2-5850-4a52-a4f8-7e90496675e6" ]
}

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:

curl -XGET -H"Realm: [your realm]" \
           -H"Authorization: Bearer [your access token]" \ 
           https://xs.adlantics.com/experience?id=510371e2-...
{
  "experiences": [
    {
      "actor": { "mbox": "hello@adlantics.com" },
      "object": { "objectType": "Activity", "id": "https://www.adlantics.com" },
      "id": "510371e2-5850-4a52-a4f8-7e90496675e6",
      "stored": "2018-05-14T09:24:18.209Z",
      "verb": { "id": "http://adxx.io/viewed" }
    }
  ]
}

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.