Learner

The Learner endpoints enable you to post learning data to Adaptemy and retrieve the learner profiles

Overview

A typical learner session involves the following sequence of API calls:

Fetch their learner profile to present the learner with personalised information in the app's user interface
Fetch the set of recommendations for the learner given the context
Provide learning content from your Learning Platform
Send learning events to Adaptemy and receive the updated learner profile

The Learn (XAPI) Object

Adaptemy uses the XAPI standard for recording all learning activity. This standard has various flexible implementations, and so the precise interpretation of the standard needs to be agreed between you and Adaptemy.

It is assumed that the Learning Platform (you) maintain the master copy of all learning records, and that Adaptemy receive all or a subset of those records relevant to your project with us.

The XAPI standard also allows for custom extensions, which again should be agreed with Adaptemy during the design phase.

Please refer to your custom documentation for agreed extensions for your implementations.

Property

Description

LRS statement GUID

timestamp

An ISO6801 timestamp indicating the END of the learning event

actor

The user who performed the action, identified by:

account.homepage

URI of the identity provider

account.name

ID of the user within this identity provider

verb.id

The action performed by the user, selected from a preset list of standardised XAPI verbs.

object.id

The URI of the object of the statement, usually a content object.

object.definition

Optional definition of the content object. See content object. If object is not already registered with Adaptemy, definition can be provided, or definition can be made available to be queried at the object.id URI.

result.completion

true/false. See sample payloads for interpretation for each event type.

result.duration

Duration in ISO6801 time of the event.

result.score

Score achieved for this object. Use score.scaled if in range 0 to 1. Else use score.raw and score.max to set the achieved score and the maximum.

result.answer

The answer submitted. Answer interpretation to be configured with Adaptemy if required.

result.extensions

To be configured for your implementation.

context.registration

A GUID of the user's attempt at the root content object. See guidance.

context.platform

The Learning Platform label.

context.contentActivities

The content object environment; parent object, containing learning loop etc...To be configured for your implementation.

context.extensions

The learning environment; class, recommendation, task, assignment etc... To be configured for your implementation.

Sample learn (XAPI) payload

{
  "id": "e474e23c-3755-4631-93a5-074bbf7580d1",
  "timestamp": "2020-12-30T17:12:00+00:00",
  "actor": {
    "account": {
      "homepage": "https://buildup.ie",
      "name": "f28cadb6-a90b-4ae2-9ea3-28f55778484d"
    }
  },
  "verb": {
    "id": "http://adlnet.gov/expapi/verbs/experienced"
  },
  "object": {
    "id": "https://buildup.ie/content/9abdfe6d-e85f-40c0-bbf2-281c0b1cb630"
  },
  "result": {
    "completion": true,
    "duration": "PT3M12S",
  },
  "context": {
    "registration": "bac1656d-1628-420d-bf97-9572506f0508",
    "platform": "buildup",
    "contextActivities": {
      "grouping": [
        { "id": "https://buildup.ie/module?topic=e2bba794-16e0-3f1f-3993-77460b32b66e"} 
      ]
    },
    "extensions": {
      "https://buildup.ie/classgroup": "f59c470f-4edb-45ee-9031-a93789fd6457",
      "https://buildup.ie/role": "student"
    }
  }  
}

{
  "id": "e474e23c-3755-4631-93a5-074bbf7580d1",
  "timestamp": "2020-12-30T17:12:00+00:00",
  "actor": {
    "account": {
      "homepage": "https://buildup.ie",
      "name": "f28cadb6-a90b-4ae2-9ea3-28f55778484d"
    }
  },
  "verb": {
    "id": "http://adlnet.gov/expapi/verbs/completed"
  },
  "object": {
    "id": "https://buildup.ie/content/9abdfe6d-e85f-40c0-bbf2-281c0b1cb630"
  },
  "result": {
    "completion": true,
    "duration": "PT13M12S",
    "success": true,
    "response": "MyAnswer",
    "score": {
      "raw": 7,
      "max": 10
    }
  },
  "context": {
    "registration": "bac1656d-1628-420d-bf97-9572506f0508",
    "platform": "buildup",
    "contextActivities": {
      "grouping": [
        { "id": "https://buildup.ie/module?topic=e2bba794-16e0-3f1f-3993-77460b32b66e"} 
      ]
    },
    "extensions": {
      "https://buildup.ie/classgroup": "f59c470f-4edb-45ee-9031-a93789fd6457",
      "https://buildup.ie/role": "student"
    }
  }  
}

{
  "id": "e474e23c-3755-4631-93a5-074bbf7580d1",
  "timestamp": "2020-12-30T17:12:00+00:00",
  "actor": {
    "account": {
      "homepage": "https://buildup.ie",
      "name": "f28cadb6-a90b-4ae2-9ea3-28f55778484d"
    }
  },
  "verb": {
    "id": "http://adlnet.gov/expapi/verbs/answered"
  },
  "object": {
    "id": "https://buildup.ie/content/9abdfe6d-e85f-40c0-bbf2-281c0b1cb630"
  },
  "result": {
    "completion": true,
    "duration": "PT3M12S",
    "success": true,
    "response": "MyAnswer",
    "score": {
      "scaled": 1
    }
  },
  "context": {
    "registration": "bac1656d-1628-420d-bf97-9572506f0508",
    "platform": "buildup",
    "contextActivities": {
    "parent": [
        { "id": "https://buildup.ie/content/5abdfe6d-e85f-40c0-bbf2-281c0b1cb630"}
      ],
      "grouping": [
        { "id": "https://buildup.ie/module?topic=e2bba794-16e0-3f1f-3993-77460b32b66e"} 
      ]
    },
    "extensions": {
      "https://buildup.ie/classgroup": "f59c470f-4edb-45ee-9031-a93789fd6457",
      "https://buildup.ie/role": "student"
    }
  }  
}

{
  "id": "e474e23c-3755-4631-93a5-074bbf7580d1",
  "timestamp": "2020-12-30T17:12:00+00:00",
  "actor": {
    "account": {
      "homepage": "https://buildup.ie",
      "name": "f28cadb6-a90b-4ae2-9ea3-28f55778484d"
    }
  },
  "verb": {
    "id": "http://adlnet.gov/expapi/verbs/rated"
  },
  "object": {
    "id": "https://buildup.ie/content/9abdfe6d-e85f-40c0-bbf2-281c0b1cb630"
  },
  "result": {
    "completion": true,
    "duration": "PT13M12S",
    "success": true,
    "response": "8",
    "score": {
      "raw": 8,
      "max": 10
    },
    "extensions": {
      "https://buildup.ie/contentmetadata/rating-dimension": "difficulty"
    }
  },
  "context": {
    "registration": "bac1656d-1628-420d-bf97-9572506f0508",
    "platform": "buildup",
    "contextActivities": {
      "grouping": [
        { "id": "https://buildup.ie/module?topic=e2bba794-16e0-3f1f-3993-77460b32b66e" } 
      ]
	   "other": [
        { "id": "https://buildup.ie/content/1abdfe6d-e85f-40c0-bbf2-281c0b1cb630" }
      ]
    },
    "extensions": {
      "https://buildup.ie/classgroup": "f59c470f-4edb-45ee-9031-a93789fd6457",
      "https://buildup.ie/role": "student"
    }
  }  
}

learn

POST https://api.adaptemy.io/learn

This endpoint enables you to send all learning events to the Adaptemy system for analysis. The correct implementation of this call is essential for model accuracy.

Request Body

Name

Type

Description

learn object

object

An array of Learn objects - see above.

{
  "id": "e474e23c-3755-4631-93a5-074bbf7580d1"
}

{
    "status": "error",
    "message": [
        "Context must be present in [0].context",
        "Registration must be present in [0].context.registration",
        "Platform must be present in [0].context.platform",
        "Cannot read property 'contextActivities' of undefined in [0].verb.id"
    ],
    "code": 0
}

learn_records

GET https://api.adaptemy.io/learn_records

Returns the set of learning events that matches the query parameters. Often only used to confirm or debug the LRS synchronisation.

Query Parameters

Name

Type

Description

string

ID of the XAPI statement

actor_name

string

Account name of the User object in the Actor position

limit

string

Limits the number of returned records, starting with most recent.

offset

string

In conjunction with the "limit" parameter, paginates through the records.

timefrom

string

Return only statements with timestamp after this datetime

timeto

string

Return only statement with timestamp before this datetime

verb

string

verb.id of the LRS statement

object

string

object.id of the LRS statement

registration

string

registration of the LRS statement

[
    {
        "payload_guid": "17733611-0596-4fe9-80f2-6ce3ebd4e065",
        "record": {
            "id": "1234-1324-1234-1234-1235",
            "verb": {
                "id": "http://adlnet.gov/expapi/verbs/answered"
            },
            "actor": {
                "account": {
                    "name": "7d48d8f3-ae2d-4ffd-960f-92cdeb33ef42",
                    "homepage": "https://kabas.dk.be"
                }
            },
            "object": {
                "id": "https://kabas.dk.be/content/3035e836-3bd2-41c8-a4e7-a0b709e22770"
            },
            "result": {
                "score": {
                    "scaled": 1
                },
                "success": true,
                "duration": "PT1H30M",
                "response": "MyAnswer",
                "completion": true
            },
            "context": {
                "platform": "kabas",
                "extensions": {
                    "https://kabas.dk.be/classgroup": "1234-5678"
                },
                "registration": "13245681234568",
                "contextActivities": {
                    "parent": [
                        {
                            "id": "https://kabas.dk.be/content/3035e836-3bd2-41c8-a4e7-a0b709e22771"
                        }
                    ],
                    "grouping": [
                        {
                            "id": "https://kabas.dk.be/fluo/module?strand=pedestrian&year=2&type=intake"
                        }
                    ]
                }
            },
            "timestamp": "2020-12-30T17:12:00+00:00"
        },
        "created_on": "2021-02-22T17:55:21.017Z",
        "learning_id": "1234-1324-1234-1234-1235"
    },

The Learner Profile

The Learner Profile is the complete model of the learner. The Learner Profile is updated after each POST learn call; some elements are time-dependent e.g. modelling of memory/forgetting.

The standard Learner Profile object is detailed below. Additional extensions can be configured for your implementation.

Property

Description

global

object of global properties of the learner, not specific to any course or curriculum

global.stats

object of learning statistics across all courses and curriculums

.duration

Total learning time recorded by this learner

.successRate

Raw rate of success across all scored content-objects

.numberContentObjectsAttempted

Count of all content-objects launched / attempted.

.numberContentObjectsCompleted

Count of all content-objects that were completed.

.numberContentObjectsScored

Count of all scored content-objects launched / attempted.

.numberSuccess

Count of all scored content-objects with success=true.

.extensions

Optional extensions object at a global level for this learner.

grouping.Classgroups

Array of Classgroups that this learner is a member of.

preferences

object of preferences expressed by the learner

affective

object of affective properties of this learner, derived from their interactions

courses

array of courses on which this learner has a profile

course.id

course id

contentObjects

An object containing the learner-profile properties for the content-objects in this course.

contentObjects.id

id of the content-object

attempts

number of times this content-object has been attempted by this user

completions

number of times this content-object has been completed

duration

total duration recorded by this user against this content-object

score

average score over all recorded scores on this object

successes

number of successful completions

datetimeBestScore

datetime of best score

datetimeLastAttempt

datetime of last attempt

modules

An object containing all of the learner-profile properties for modules in this course

modules.id

id of the module

progress.duration

total learning time recorded in this module

progress.masteredConcepts

count of concepts mastered in this module

completionStatus

true if this module has been completed

percentageComplete

Completion calculation configurable in module settings

curriculums

array of curriculums on which this learner has a profile

curriculums.id

curriculum id

concepts

An object containing the learner-profile properties for all concepts in this curriculum

guid

concept guid

evidence

basic statistics on this concept

numberDirect

number of direct evidence updates on this concept i.e. assessment questions

numberIndirect

number of indirect evidence updates on this concept i.e. propagation updates or other non-assessment updates

totalScaledScore

total score achieved in direct evidence on this concept

datetimeLastUpdate

datetime last update, direct or indirect

datetimeLastDirect

datetime last direct update

estimates

estimated learner ability metrics on this concept

ability

best estimate of the ability of the learner on this concept, in range 1 to 100

precision

measure of the precision of the ability estimate

masteryStatus

current mastery level, in range 1 to 5

bestStatus

best ever mastery status

probMastery

probability of masteryStatus of 4 or greater

datetimeFirstMastered

datetime masteryStatus of 4 was first achieved

confirmedDirectMastered

number of direct evidences of masteryStatus of 4 or greater

memoryLevel

memory reinforcement level, in range 0 to 5

maxLikelihood

characteristic of the probability distribution vector of ability

iqr

characteristic of the probability distribution vector of ability

Sample learner-profile

{
    "homepage": "https://adaptemy.io",
    "name": "f28cadb6-a90b-4ae2-9ea3-28f55778484c",
    "global": {
        "stats": {
            "duration": "PT1H30M",
            "successRate": 0.75,
            "numberContentObjectsAttempted": 100,
            "numberContentObjectsCompleted": 80,
            "numberContentObjectsScored": 80,
            "numberSuccess": 60
        },
        "extensions": {
            "urbanRural": 2
        },
        "grouping": {
            "classGroups": [
                4567
            ]
        },
        "preferences": {},
        "affective": {}
    },
    "courses": [
        {
            "courseId": "0ad460e4-9377-4da9-820f-45b833935b9a",
            "contentObjects": [
                {
                    "id": "https://buildup.ie/content/c4bc1a50-1f1c-4bed-a6c7-3eeb5779c8ab",
                    "attempts": 34,
                    "completions": 20,
                    "duration": "PT1H30M",
                    "score": 0.7,
                    "successes": 15,
                    "dateTimeBestScore": "2020-12-20T17:12:00+00:00",
                    "dateTimeLastAttempt": "2020-12-20T17:12:00+00:00"
                },
                {
                    "id": "https://buildup.ie/content/697847ef-3b26-4c83-ba1b-c3637f3646bc",
                    "attempts": 14,
                    "completions": 1,
                    "duration": "PT3M",
                    "dateTimeLastAttempt": "2020-12-20T17:12:00+00:00"
                },
                {
                    "id": "https://buildup.ie/content/b8e06af7-4700-4fbd-81e3-357d850d28a9",
                    "attempts": 14,
                    "dateTimeLastAttempt": "2020-12-20T17:12:00+00:00"
                },
                {
                    ...other content-objects
                }
            ],
            "modules": [
                {
                    "id": "https://buildup.ie/ty/module?strand=e2bba794-16e0-3f1f-3993-77460b32b66e",
                    "progress": {
                        "duration": "PT10M",
                        "masteredConceptsCount": 1
                    },
                    "completionStatus": 1,
                    "percentageComplete": 50,
                    "extensions": {
                        "confidence": 2
                    }
                },
                {
                    "id": "https://buildup.ie/ty/module?strand=e2bba794-16e0-3f1f-3993-77460b32b66e",
                    "progress": {
                        "duration": "PT10M",
                        "masteredConceptsCount": 1
                    },
                    "completionStatus": 1,
                    "percentageComplete": 50
                },
                {
                    ...other modules
                }
            ]
        }
    ],
    "curriculums": [
        {
            "curriculumGuid": "2f7633a1-676a-42a3-9770-673392edf854",
            "concepts": [
                {
                    "guid": "0bfdd558-f3dc-c3f8-2167-2a707a2dd9f9",
                    "evidence": {
                        "numberDirect": 0,
                        "numberIndirect": 30,
                        "datetimeLastUpdate": "2021-03-02T12:37:57.556Z"
                    },
                    "estimates": {
                        "iqr": 41,
                        "ability": 53,
                        "precision": 0,
                        "bestStatus": 1,
                        "memoryLevel": 0,
                        "probMastery": 0.2937379304171,
                        "masteryStatus": 1,
                        "maxLikelihood": 55,
                        "confirmedDirectMastered": 4
                    }
                },
                {
                    ...other concepts
                }
            ]
        }
    ]
}

learner-profile

GET https://api.adaptemy.io/learner-profile

Returns the learner profile for the specified user. Can be configured per organisation.

Query Parameters

Name

Type

Description

account

string

account (homepage/name) of the learner

course

string

Course GUID to filter learner profile.

curriculum

string

Curriculum GUID to filter learner profile.

{
    "homepage": "https://adaptemy.io",
    "name": "f28cadb6-a90b-4ae2-9ea3-28f55778484c",
    "global": {
        "stats": {
            "duration": "PT1H30M",
            "successRate": 0.75,
            "numberContentObjectsAttempted": 100,
            "numberContentObjectsCompleted": 80,
            "numberContentObjectsScored": 80,
            "numberSuccess": 60
        },
        "extensions": {
            "urbanRural": 2
        },
        "grouping": {
            "classGroups": [
                4567
            ]
        },
        "preferences": {},
        "affective": {}
    },
    "courses": [
        {
            "courseId": "0ad460e4-9377-4da9-820f-45b833935b9a",
            "contentObjects": [
                {
                    "id": "https://buildup.ie/content/c4bc1a50-1f1c-4bed-a6c7-3eeb5779c8ab",
                    "attempts": 34,
                    "completions": 20,
                    "duration": "PT1H30M",
                    "score": 0.7,
                    "successes": 15,
                    "dateTimeBestScore": "2020-12-20T17:12:00+00:00",
                    "dateTimeLastAttempt": "2020-12-20T17:12:00+00:00"
                },
                {
                    "id": "https://buildup.ie/content/697847ef-3b26-4c83-ba1b-c3637f3646bc",
                    "attempts": 14,
                    "completions": 1,
                    "duration": "PT3M",
                    "dateTimeLastAttempt": "2020-12-20T17:12:00+00:00"
                },
                {
                    "id": "https://buildup.ie/content/b8e06af7-4700-4fbd-81e3-357d850d28a9",
                    "attempts": 14,
                    "dateTimeLastAttempt": "2020-12-20T17:12:00+00:00"
                },
                {
                    ...other content-objects
                }
            ],
            "modules": [
                {
                    "id": "https://buildup.ie/ty/module?strand=e2bba794-16e0-3f1f-3993-77460b32b66e",
                    "progress": {
                        "duration": "PT10M",
                        "masteredConceptsCount": 1
                    },
                    "completionStatus": 1,
                    "percentageComplete": 50,
                    "extensions": {
                        "confidence": 2
                    }
                },
                {
                    "id": "https://buildup.ie/ty/module?strand=e2bba794-16e0-3f1f-3993-77460b32b66e",
                    "progress": {
                        "duration": "PT10M",
                        "masteredConceptsCount": 1
                    },
                    "completionStatus": 1,
                    "percentageComplete": 50
                },
                {
                    ...other modules
                }
            ]
        }
    ],
    "curriculums": [
        {
            "curriculumGuid": "2f7633a1-676a-42a3-9770-673392edf854",
            "concepts": [
                {
                    "guid": "0bfdd558-f3dc-c3f8-2167-2a707a2dd9f9",
                    "evidence": {
                        "numberDirect": 0,
                        "numberIndirect": 30,
                        "datetimeLastUpdate": "2021-03-02T12:37:57.556Z"
                    },
                    "estimates": {
                        "iqr": 41,
                        "ability": 53,
                        "precision": 0,
                        "bestStatus": 1,
                        "memoryLevel": 0,
                        "probMastery": 0.2937379304171,
                        "masteryStatus": 1,
                        "maxLikelihood": 55,
                        "confirmedDirectMastered": 4
                    }
                },
                {
                    ...other concepts
                }
            ]
        }
    ]
}

PreviousImplementation Guidance NextRecommendations

Last updated 4 years ago