Getting started with the Node.js client for the SCORM Cloud API

Updated on March 5, 2018

If you’re using Rustici Software’s SCORM Cloud service to deliver and manage e-learning content, the SCORM Cloud API provides an interface to build custom integrations and reporting tools. To get you started, I’ve put together some examples using the Node.js client library.

Installation

To get started, first install the module using the npm install command:

$ npm install scormcloud-api-wrapper
+ scormcloud-api-wrapper@1.0.7
added 62 packages in 7.109s

Usage

If you have not already, sign up for a SCORM Cloud account. You are required to provide API credentials in the form of an Application ID (App ID) and a secret key. You can access this information from the Apps / API page:

Click the Details link to view the secret key for an existing application. The App ID is also listed at the top of this page.
Click the Add Application button to create a new application for testing purposes.

You’ll need to import the module and construct an instance of the API client with your Application ID and secret key. You can do this from the Node REPL by running the node command without a filename.

// Import the module.
var SCORMCloud = require('scormcloud-api-wrapper');

// Create an instance with your API credentials.
var api = new SCORMCloud('appid', 'secretKey');

Use the authPing method to verify that your credentials are valid and that the web service is reachable. Note that asynchronous functions use error-first callbacks. The first argument is reserved for an error object, and the second for response data.

// Verify credentials are valid and service is reachable.
api.authPing(function (error, result) {
  if (error) throw error; console.log(result);
});

If true was printed to your console, you’re ready to continue to the next section.

Importing a course

Use the importCourse method to add a course to your library in SCORM Cloud. You’ll need to provide a unique identifier and file path for the course, and a callback function. If the course identifier refers to an existing course, a new version of the course will be created.

// Import a course to your library.
api.importCourse(
  'personal_protective_equipment',
  'personal_protective_equipment_v1.0.zip',
  function (error, result) {
    if (error) throw error; console.log(result);
  }
);

The import results will be printed to your console. If your import was successful, you should see output similar to the following:

{
  "status": "finished",
  "message": "Finished",
  "importresult": [
    {
      "successful": "true",
      "title": "Personal Protective Equipment Knowledge Assessment",
      "message": "Import Successful"
    }
  ]
}

Creating registrations

One way that you can connect learners to your content in SCORM Cloud is through registrations – you provide the learner and course information to create a unique registration that can be launched from your system. When an integrating system “assigns” a course to a learner, if will often create a registration in SCORM Cloud.

Use the createRegistration method to create a new registration. You’ll need to provide the unique identifier for the course, a unique identifier for the registration, learner information, and a callback function.

In the examples below, I’m using the uuid module to generate unique identifiers for registrations. Use the npm install uuid command to install the module before continuing.

// Import the uuid module.
var uuid = require('uuid');

// Generate a UUID for the registration.
let regid = uuid();

// Create a new registration.
api.createRegistration(
  'personal_protective_equipment',
  regid,
  'Jane',
  'Doe',
  'jane.doe@example.com',
  {
    email: 'jane.doe@example.com'
  },
  function (error, result) {
    if (error) throw error; console.log(result);
  }
);

If true was printed to your console, the registration was created successfully.

Launching a registration

Registrations are launched using an API url that will respond with a 302 Redirect that provides the learner access to the registration and course content.

Use the getLaunchUrl method to generate a launch url for a registration. This API url is valid for approximately 15 minutes – you should generate this immediately before launching a registration for a learner.

let launchUrl = api.getLaunchUrl(regid, 'blank');

Creating invitations

Another way that you can connect learners to your content in SCORM Cloud is through invitations. Invitations can be used to create a public link to your course, or a private link that is emailed directly to each learner. Use the createInvitation method to create either type of invitation.

Public invitations require that learners enter a name and email address in order to create the registration and launch the training. To create a public invitation:

api.createInvitation(
  'personal_protective_equipment',
  true, // Public invitation
  function (error, result) {
    if (error) throw error; console.log(result);
  }
);

The web service responds with a unique identifier for the invitation. Use the getInvitationInfo method to retrieve details about an invitation.

api.getInvitationInfo(
  '8d45bd8c-aa05-4ab4-9069-0033a196fe3f',
  function (error, result) {
    if (error) throw error; console.log(result);
  }
);

Details about the invitation should be printed to your console if you’re following along in the Node REPL.

{
  "id": "8d45bd8c-aa05-4ab4-9069-0033a196fe3f",
  "body": "Dear [USER],<p>You have been invited to take &#39;Personal Protective Equipment Knowledge Assessment&#39;. To start your training click on the Play button or copy the training URL into your browser.</p><a href="[URL]" rel="nofollow">Play course</a><br /><br />URL: [URL]<br/>When you click the link above to launch the course, you\'ll see a screen first confirming your email address to make sure you get proper credit for taking the course. The default is the address this email was sent to, but you can use another if you already have a SCORM Cloud account or want the training tied to a different email address.<br/><br/>If you run into a problem launching the course, either contact the person who sent you this invitation by replying to this email, or drop us an email at support@scorm.com. We\'ll be happy to help you out.<br/><br/>",
  "courseId": "personal_protective_equipment",
  "subject": "Personal Protective Equipment Knowledge Assessment",
  "url": "http://cloud.scorm.com/sc//InvitationConfirmEmail?publicInvitationId=3f5fbc69-4075-4f9f-9dea-992165079bf4",
  "allowLaunch": true,
  "allowNewRegistrations": true,
  "public": true,
  "created": true,
  "createdDate": "2017-11-26T15:00:01.000+0000",
  "userInvitations": []
}

Retrieving registration results

The getRegistrationListResults method allows you to retrieve a list of registration results limited to a specific course or learner. Registration results include the completion status, success status, total time spent, and the overall score.

api.getRegistrationListResults(
  {
    "courseid": "personal_protective_equipment"
  },
  function (error, result) {
    if (error) throw error; console.log(result);
  }
);

The registration results will be printed to your console. You should expect to see output similar to the following:

[
  {
    "id": "e34e9eb0-2682-4680-954d-e6bf7777e1ea",
    "courseId": "personal_protective_equipment",
    "courseTitle": "Personal Protective Equipment Knowledge Assessment",
    "lastCourseVersionLaunched": "0",
    "learnerId": "jane.doe@example.com",
    "learnerFirstName": "Jane",
    "learnerLastName": "Doe",
    "email": "jane.doe@example.com",
    "createDate": "2017-11-26T18:48:53.000+0000",
    "firstAccessDate": "2017-11-26T19:12:37.000+0000",
    "lastAccessDate": "2017-11-26T19:14:09.000+0000",
    "completedDate": "2017-11-26T19:14:09.000+0000",
    "registrationreport": {
      "format": "course",
      "regid": "e34e9eb0-2682-4680-954d-e6bf7777e1ea",
      "instanceid": "0",
      "complete": "complete",
      "success": "passed",
      "totaltime": "180",
      "score": "80"
    }
  }
]

If you found this article helpful, visit the GitHub project page and star the project. Use the Issues to request new features or report bugs. Stay tuned for additional examples!