Using Custom Data in Student Lesson Progress

This article explains how to add custom data to a student’s course progress and surface that data in a Skilljar HTML lesson. This could be used, for example, to expose a unique-per-user “Launch URL” for an off-site learning activity.

In this example, suppose we have a unique “launch_url” per student that we want to surface in a Skilljar lesson. In this example - we will listen for a webhook event when a user enrolls in a given course. Assuming we have a unique “launch_url” for that user in another service, we will call back to the Skilljar API to set the “launch_url” on a lesson in the Skilljar course. When the student views that lesson - Javascript on the page will turn the launch_url into a clickable link where the student will be redirected to your external service. 

Setup: Enable Javascript in HTML Lessons

Our Customer Success team can configure the HTML editor to allow Javascript to be saved in your HTML lessons. This is a one-time configuration update to your account to enable the editor to not filter JavaScript in your HTML. Contact our Customer Success team or Skilljar Support.

Setup: Collect the Lesson ID and PublishedCourse ID

First, you’ll need to know the ID of the published course and the lesson in that published course for which you want to attach custom data.

1. Published Course ID: Once you’ve published your course - the published course ID is available on the Skilljar Dashboard. If you go to https://dashboard.skilljar.com/ -> “Domains & Publishing”, scroll down past “Your published courses” and select the “Edit” icon next to the course. The URL of the “edit” page will look something like this: https://dashboard.skilljar.com/publishing/publish/abcde12345/edit note the bold text - “abcde12345” is your PublishedCourse ID.
2. Lesson ID: In “Course Management” on the Skilljar Dashboard, select the course to edit, then choose the lesson. Note the 2nd ID in the URL: https://dashboard.skilljar.com/course/abc123def456/qwert87654 in this example “qwert87654” is the lesson ID.

Listen for new course enrollments

There are many ways to be notified of when a user enrolls in a Skilljar course. Skilljar’s Salesforce connector will create a “skilljar__Enrollment__c” custom object (see our Salesforce help article), or, you can listen for a webhook event from Skilljar with a “COURSE_ENROLLMENT” event type (see our Webhooks help article).

Assuming you have an endpoint that can listen for a webhook notification, then you’d want to parse the COURSE_ENROLLMENT webhook JSON, and if the “course.published_course_id” matches the PublishedCourse ID you collected above. The webhook event will also have a “user.id” field which contains the ID of the user.

Generate your custom data

Out of the scope of this article - you’ll generate a custom “launch_url” for your user.

Call the Skilljar API to attach the custom data

Skilljar’s API takes a combination of the PublishedCourse ID, Lesson ID, and User ID - to update a lesson’s progress for a user:

https://api.skilljar.com/docs/#!/users/User_Lesson_update

With this API, you can pass JSON that contains whatever arbitrary data you want to connect to the user in the “custom_data” field of the “lesson_progress” object. We recommend that you pass an escaped JSON string - as it’s easier than using javascript in your lesson to parse the data field, and you can always extend your data later without breaking your lesson.

For example, if your launch URL was:  http://example.com/launch/12345 - then setting the following JSON for your custom data would allow you to easily parse it later:

{
  "launch_url": "http://example.com/launch/12345"
}

Since the “custom_data” field is a string - to encode the JSON into the string field - we’ll have to escape the quotations, etc. so the actual JSON that you would pass to the Skilljar API would be:

HTTP PUT 

https://api.skilljar.com/v1/users/{user_id}/published-courses/abcde12345/lessons/qwert87654

{
  "lesson_progress": {   
     "custom_data": "{\"launch_url\": \"http://example.com/launch/12345\"}"
  } 
}

This API call will update the lesson progress for the given “user_id” - and update only the custom_data field for that user.

Surface the custom_data in the student’s lesson

Skilljar surfaces the “custom_data” field of the user’s lesson progress as a javascript variable on the lesson page itself. Back on the Skilljar dashboard, edit the HTML of the lesson you’ve created, add some javascript to look for this field, parse the JSON, and surface your “launch_url” as a clickable link:

<div class="example-lesson">
 <p>This lesson contains a custom launch URL. It will show the URL to access your content once it is provisioned.</p>
</div>

<div class="example-lesson example-lesson-prepare" style="display: none;">
 <p>Your custom URL is being prepared...</p>
</div>

<div class="example-lesson example-lesson-url" style="display: none;">
 <p>Your custom URL is ready! Click the button to open it in a new window.</p>
 <p><a class="button example-launch-button" href="#" target="_blank">Launch <em class="fa fa-external-link">&nbsp;</em></a></p>
</div>

<div class="example-lesson example-lesson-error" style="display: none;">
  <p>ERROR: You should not see this.</p>
</div>

<script>
 function parseCustomDataUpdateLesson() {
   if ((typeof(skilljarLessonProgress) == 'undefined') ||
     (typeof(skilljarLessonProgress.customData) == 'undefined')) {
     // Variable does not exist
     return;
   } else if (!skilljarLessonProgress.customData) {
     // No data, show the "prepare" section
     $('div.example-lesson').hide();
     $('div.example-lesson-prepare').show();
     return;
   }
 
   // Parse the JSON in the customData...
   data = JSON.parse(skilljarLessonProgress.customData);
 
   if (typeof(data.launch_url) !== 'undefined' && data.launch_url !='') {
      // Custom data contains a launch URL, update the button and show the "launch" section
      $('a.example-launch-button').attr('href', data.launch_url);
      $('div.example-lesson').hide();
      $('div.example-lesson-url').show();
   }
 }
 
try {
   parseCustomDataUpdateLesson();
 } catch (e) {
   // Error, show error panel
   $('div.example-lesson').hide();
   $('div.example-lesson-error').show();
 }
</script>
 

The above HTML contains a few different divs, mostly hidden by default, and then some javascript to parse the “skilljarLessonProgress.customData” field. Depending on the contents of the field, it populates (and shows) a “Launch” button, or gives a status message to the user.

Conclusion

As you can see, the custom data can be extremely flexible - allowing you a wide range of custom integrations into Skilljar. Rather than encoding a single “launch_url” - you could encode any sort of data you want, and then write javascript in the lesson to parse and utilize that data.