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

Name	Type	Description
limit	number	Page size, defaults to 10.
page	number	Results page to return, defaults to 1.

Headers

Name	Type	Description
Authorization	string	Auth token generated by user login.

200 List of courses, along with the page, limit, total results, and numbers of pages.

{ 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

Name	Type	Description
courseId	string	ID of the course.
limit	number	Page size.
page	number	Results page to return.

Headers

Name	Type	Description
Authorization	string	Auth token generated by user login.

200 List of lessons belonging to the specified course.

{
  "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

Name	Type	Description
page	string	Results page to retrieve.
limit	string	Page size. Defaults to 10.

Headers

Name	Type	Description
Authorization	string	Auth token generated by user login.

200 A list of classes, including courses if available. If a class is not associated with a course, the course attribute will be null.

{ 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

Name	Type	Description
eventSetId	string	The ID of an event set or the ID of an event set lesson.

Headers

Name	Type	Description
Authorization	string	Authentication token generated by user tokens.

200 Event set retrieved.

[{
  "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

Name	Type	Description
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

Name	Type	Description
	string

200 Indicates the user has started the lesson, with a "started" attribute indicating when the API recorded the start event.

{ "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 Set

xAPI

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

Name	Type	Description
Authorization	string

Request Body

Name	Type	Description
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)

200 Statement created.

{
    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

Name	Type	Description
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

Name	Type	Description
Authorization	string	Auth token generated by user login.

Request Body

Name	Type	Description
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.

200 Progress updated.

{ "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"}
  ]  }