How to Use The Event Set Module

bout the Event Set Module

The Event Set module records student actions within an App lesson. Event Set modules are a type of performance assessment - the assessment analyzes how a student performs within an app without the need for an instructor to be present to manually grade the student.

The Event Set module is set up as a child module to an App lesson and xAPI statements within the App indicate activity for the Event Set. These can be correct, incorrect, or not scored (n/a in the UI). An overall attempt ends when you click complete or complete the lesson via API. The results table does not reflect overall attempts. It only shows "activity" in chronological order per event in the Event Set. However, the score of the latest overall attempt is what shows in the final row.

How to use the Event Module

Refer to this guide after authenticating

Authentication

You cant interact with an event module before setting up your course. Refer to this guide for more info on Course Creator.

Course Manager Tools

1. Lists All Courses

This request lists all courses the authenticated user is apart of, here you will grab the courseId for the next request.

To interact with the sandbox environment replace api.motar.io with sandbox.motar.io

Lists All Courses

GET https://api.motar.io/edu/v1/course/list

Lists all courses.

Query Parameters

NameTypeDescription

limit

number

Page size, defaults to 10.

page

number

Results page to return, defaults to 1.

Headers

NameTypeDescription

Authorization

string

Auth token generated by user login.

{ docs: 
   [ { courseId: 'a1ebfdc5328f33116dbfdc175239f1c5ed7c82f8dd7f7ba153b1b7f9ee8d914b0e3d86f88214ef7ea681d90633b5891e0f4f11aa3489da86d8204809dc0ad1ba15cfb2513747479f456953cc24536ef59e$8778901d1b182ffd2096a4dac481ab91',
       name: 'Test Course',
       description: 'A test course',
       profilePic: '5d691e1677fde4106be829fe',
       coverPhoto: '5d691e1677fde4106be829ff' } ],
  total: 1,
  limit: 10,
  page: 1,
  pages: 1 }

2. Lists Lessons in a Course

Now that we have the courseId value, next you should run the Lists Lessons in a Course request. This request will give us the event module lessonId needed in Step 4.

Lists Lessons in a Course

GET https://api.motar.io/edu/v1/lesson/course

Lists all lessons belonging to a course.

Query Parameters

NameTypeDescription

courseId

string

ID of the course.

limit

number

Page size.

page

number

Results page to return.

Headers

NameTypeDescription

Authorization

string

Auth token generated by user login.

{
  "docs": [
    {
      "lessonId": "ac5f1ba630fe00c29a1c938a22e80a8ba402e1e98b675c7c7d4b66a670c51007566eed9855d125cb270a6b5e963e447688da39561ab4bd3d200c903e3b67fb00afa8dd5a10569c490ab387b75f04c9b217$0992712e1be6dfe76c4b32368531c523",
      "courseId": "ac5f1ba630fe00c29a1c938a22e80a8ba402e1e98b675c787d4b66a670c51007566eed9855d125cb270a6b5e963e447688da39561ab4bd3d200c903e3b67fb00afa8dd5a10569c490ab387b75f04c9b217$0992712e1be6dfe76c4b32368531c523",
      "name": "Test Lesson",
      "description": "A test lesson",
      "profilePic": "5dc48017a104378253bb1b34",
      "coverPhoto": "5dc48017a104378253bb1b35",
      "media": "http://www.google.com",
      "expectedCompletionTime": 120,
      "instructorGraded": false,
      "childLessons": [],
      "public": true,
      "launchParameters": ["extLessonId=sp101"],
      "locked": false
    },
    {
      "lessonId": "ac5f1ba630fe00c29a1c938a22e80a8ba402e1e98b675c7d7d4b66a670c51007566eed9855d125cb270a6b5e963e447688da39561ab4bd3d200c903e3b67fb00afa8dd5a10569c490ab387b75f04c9b217$0992712e1be6dfe76c4b32368531c523",
      "courseId": "ac5f1ba630fe00c29a1c938a22e80a8ba402e1e98b675c787d4b66a670c51007566eed9855d125cb270a6b5e963e447688da39561ab4bd3d200c903e3b67fb00afa8dd5a10569c490ab387b75f04c9b217$0992712e1be6dfe76c4b32368531c523",
      "name": "Another Test Lesson",
      "description": "Another test lesson",
      "profilePic": "5dc48017a104378253bb1b34",
      "coverPhoto": "5dc48017a104378253bb1b35",
      "media": "5dc48017a104378253bb1b5c",
      "expectedCompletionTime": 240,
      "instructorGraded": true,
      "childLessons": [],
      "public": true,,
      "launchParameters": ["extLessonId=sp102"],
      "locked": false
    }
  ],
  "total": 2,
  "limit": 10,
  "page": 1,
  "pages": 1
}

3. Get Classes

Next we need to grab the classId value for your course. This is the last value you need to grab before interacting with student data.

Get Classes

GET https://api.motar.io/edu/v1/class/list

Returns a student class list.

Query Parameters

NameTypeDescription

page

string

Results page to retrieve.

limit

string

Page size. Defaults to 10.

Headers

NameTypeDescription

Authorization

string

Auth token generated by user login.

{ docs: 
   [ { groupId: '484b2ccaa12326182d1294e033a105994c4efbf8fd13038912fc0afd96b1bd936fb96b5516d6e31cdbcac0e2b40bab5a1ed12c2bd3ac1587a00d44ef81cf19b0f15167d921d5db781763cdc34537ddf50e$98760d68bfcea5269e44347f3760c124',
       name: 'Cool Class for Cool Kids',
       joinCode: '3d09a351a3ca',
       studentId: '7f5d55a96c496150044ce6cab67171af7aa3e2367a79ff3c3ad3b0a51f6dc8c7c8067988e65569d1cbdc7c0e81da6ffa6da5eb831aed038f9973b9b7a74d753e9be04401e3f52b90203a7fecc99fd2a974$2fb47452b1b4d16bab8e98532f7e7cc3',
       course: 
        { courseId: '484b2ccaa12326182d1294e033a105994c4efbf8fd1304dc12fc0afd96b1bd936fb96b5516d6e31cdbcac0e2b40bab5a1ed12c2bd3ac1587a00d44ef81cf19b0f15167d921d5db781763cdc34537ddf50e$98760d68bfcea5269e44347f3760c124',
          name: 'Test Course',
          description: 'A test course',
          profilePic: '5d69318ab26d2810d4b5c9a0',
          coverPhoto: '5d69318cb26d2810d4b5c9a1' } } ],
  total: 1,
  limit: 10,
  page: 1,
  pages: 1 }

4. Read an Event Set

Reporting to an event set requries the eventSetId, this request will give you the next value needed for reporting to an event set.

Read An Event Set

GET https://api.motar.io/edu/v1/event-set

Reads an event set.

Query Parameters

NameTypeDescription

eventSetId

string

The ID of an event set or the ID of an event set lesson.

Headers

NameTypeDescription

Authorization

string

Authentication token generated by user tokens.

[{
  "name": "Talk to the harbinger",
  "description": "You must speak with the harbinger to learn your doom.",
  "eventId": "evt-919a11786f1dae4a"
}, {
  "name": "Cross the bridge",
  "description": "Can you muster the courage to enter the deep dark cave?",
  "eventId": "evt-e84e76424435d361"
}, {
  "name": "Find the treasure",
  "description": "Find the hidden treasure, if you can!",
  "eventId": "evt-d37eb061ccf110be"
}]

5. Start A Lesson

The last value you need to grab before reporting to an event set is the lessonResultId, this is found in the Start A Lesson response.

Without starting the lesson, you will not be able to report scores.

Start A Lesson

POST https://api.motar.io/edu/v1/lesson/progress/start

Indicates a student has started taking a lesson, updating the "start" date in the lesson's progress. If the user has previous started the lesson but not completed it, this method with throw an error. Note that all query parameters in this request can optionally be included in the POST body rather than the query if so desired. Body parameters must be in the body, they cannot be included in the query string.

Query Parameters

NameTypeDescription

classId

string

Lesson progress is tracked on a class-class basis. This parameter is the ID of the student's class for which you would like to update progress.

lessonId

string

ID of lesson.

Headers

NameTypeDescription

string

{ "studentId": "793278a6e6449530a8c46cf98463945965212801cf38051a8e3d8493dc470658291be1b88d884feafe79db39515a85e9bc5c02e9c68e8dff2012bc0e11bdb474098b5b33d04b0fb55aa661abf59573919d$e1e08bd810b80f6993588ff1089a585a",
  "lessonId": "793278a6e6449537a8c46cf98463945965212801cf38074e8e3d8493dc470658291be1b88d884feafe79db39515a85e9bc5c02e9c68e8dff2012bc0e11bdb474098b5b33d04b0fb55aa661abf59573919d$e1e08bd810b80f6993588ff1089a585a",
  "lessonResultId": "793278a6e6449537a8c46cf98463945965212801cf38074e8e3d8493dc470658291be1b88d884feafe79db39515a85e9bc5c02e9c68e8dff2012bc0e11bdb474098b5b33d04b0fb55aa661abf59573919d$e1e08bd810b80f6993588ff1089a585b",
  "pass": false,
  "score": null,
  "answers": null,
  "started": "2019-11-07T16:45:34.273Z",
  "completed": null,
  "progressIntervals": [{"start": "2019-11-07T16:45:34.273Z", "end": null}],
  "idleIntervals": [] }

6. Report to an event set

Event SetxAPI

Referenced from the linked page above:

Event Set modules work differently than other modules. Event Set progress is not reported directly via this API. Instead, event set progress is reported via xAPI statements. This allows a high degree of customization on the part of the implementor.

To report event set progress, you will need to create an xAPI statement referring to an event in an event set, along with a lesson result ID specifying the module attempt. You can also include an optional "correct" flag to tell the MOTAR API whether or not the event activity counts as "correct" for score tracking purposes.

The eventId property can either be found by using the "Read an Event Set" API method above, or in the MOTAR Training dashboard course creator GUI.

A lessonResultId refers to a specific attempt at a lesson, with a start time, end time, and score. When you start a lesson, the API returns the new lessonResultId which can be used in subsequent API calls for activity during that lesson attempt.

Instructor View - Reported Event Set

This image shows an example reporting to an event-set module. The instructor can access this view by viewing, individual student progress for the event-module.

Create Statement

POST https://api.motar.io/edu/v1/xapi/statement

This endpoint creates an xAPI statement. See below for special keys needed for indexing your metrics.

Headers

NameTypeDescription

Authorization

string

Request Body

NameTypeDescription

timestamp

string

A parseable ISO date (eg. 2020-01-07T21:45:35.649Z)

actor

string

User ID of the actor performing the action.

verb

string

Action that the actor is carying out on the object.

object

string

Target of the action the user is carrying out. This is expected to be a JSON object (stringified or raw)

{
    success: true
}

Example

In this example, we are reporting that a student has made a mistake on the second event. We have also included some additional metadata (specific to our application) about the attempt.

POST https://api.motar.io /edu/v1/xapi/statement
{
    "actor": "3a02cbb9ae4c2e157927d3259159bfa80793ecfebebd74ef89d4db65def37778dc592a8e0bee5b7b39608f5609446cf5f8832576d6a2b992d4919a42acc7e194e81ede86ea2aa670a1436be0678f2fa1ce",
    "verb": "Student fell off the bridge into the dark water below.",
    "object": {
        "lessonResultId": "ac5f1ba630fe00c39a1c938a22e80a8ba402e1e98b67597a7d4b66a670c510075639ebca09d275cd700f615f956512718ad53c561bb1ec697c5896386c31a850aafc865c1352981453e1d0e45a5ccbba13",
        "eventId": "evt-e84e76424435d361",
        "correct": false,
        "error": true,
        "assist": false,
        "timeTaken": "7min",
        "trapTriggered": "trap-82047711"
    }
}

7. Complete the Lesson

After reporting to an event set its important to Complete the Lesson, to ensure data is displayed accurately on the MOTAR Training Dashboard.

Update Student's Lesson Progress

POST https://api.motar.io/edu/v1/lesson/progress

Updates a student's progress for a lesson in a class with a score, answers, and a pass/fail result. Note that all query parameters in this request can optionally be included in the POST body rather than the query if so desired. Body parameters must be in the body, they cannot be included in the query string.

Query Parameters

NameTypeDescription

classId

string

Lesson progress is tracked on a class-by-class basis. This parameter is the ID of the student's class for which you would like to retrieve progress in this lesson for.

lessonId

string

ID of the lesson.

Headers

NameTypeDescription

Authorization

string

Auth token generated by user login.

Request Body

NameTypeDescription

startTime

string

A parseable date to mark the start of the student's session. Suggested format is ISO date, eg. 2020-01-07T21:45:35.649Z.

endTime

string

A parseable date to mark the end of the student's session. Suggested format is ISO date, eg. 2020-01-07T21:45:35.649Z.

complete

boolean

If true, the lesson's "complete" attribute will be set to the current date/time, indicating the student has finished the lesson.

score

number

A numeric score for the lesson. If using Point-based scoring, send in the number correct, eg. Point-based score pass = 40/50, then 'score' is a number 0-50. Not required for Pass/Fail scored lessons.

pass

boolean

A boolean pass/fail flag.

{ "studentId": "793278a6e6449530a8c46cf98463945965212801cf38051a8e3d8493dc470658291be1b88d884feafe79db39515a85e9bc5c02e9c68e8dff2012bc0e11bdb474098b5b33d04b0fb55aa661abf59573919d$e1e08bd810b80f6993588ff1089a585a",
  "lessonId": "793278a6e6449537a8c46cf98463945965212801cf38074e8e3d8493dc470658291be1b88d884feafe79db39515a85e9bc5c02e9c68e8dff2012bc0e11bdb474098b5b33d04b0fb55aa661abf59573919d$e1e08bd810b80f6993588ff1089a585a",
  "lessonResultId": "793278a6e6449537a8c46cf98463945965212801cf38074e8e3d8493dc470658291be1b88d884feafe79db39515a85e9bc5c02e9c68e8dff2012bc0e11bdb474098b5b33d04b0fb55aa661abf59573919d$e1e08bd810b80f6993588ff1089a585b",
  "pass": false,
  "score": 0,
  "answers": [{ "question": "What is Batman's secret identity?", "studentAnswer": "Clark Kent"}],
  "started": "2019-11-06T12:21:54.185Z",
  "completed": "2019-11-06T17:42:32.221Z",
  "progressIntervals": [
    {"start": "2019-11-07T16:45:34.273Z", "end": "2019-11-07T16:45:39.146Z"},
    {"start": "2019-11-07T16:55:42.287Z", "end": "2019-11-06T17:42:32.221Z"}
  ],
  "idleIntervals": [
    {"start": "2019-11-07T17:01:11.107Z", "end": "2019-11-07T17:12:32.091Z"}
  ]  }

Last updated