Integrating with Engine

With Engine, there is a common workflow for delivering content, no matter which supported learning standard is being used.

The primary milestones of a successful Engine implementation are:

  1. import
  2. launch
  3. track
  4. other integration considerations (e.g., custom UI / behaviors)

It's difficult to map Engine integrations to fixed timelines. Our integration and support team tries to work closely and collaboratively with your development team at a pace intended to deliver a materially complete integration according to your project timeline.

That said, our historical internal clocks for the integration team have typically allowed one week per milestone. We will probably be recalibrating those clocks across the Engine 2015.1.x release cycle because the integration process will be considerably different from every previous major release of Engine.

Some customers might prefer to complete these milestones by using the client libraries supplied with Engine.

Import

An e-learning course is kept together in a self-contained unit, called a "package". Although the structure of a package varies between different learning standards, you generally will not have to be aware of these differences when using Engine. Most content is available in the form of ZIP archives (although Engine supports other formats when appropriate, e.g., raw AU files, import-from-URL, etc.).

To import a course, make an HTTP POST to the importJobs resource, taking special note of the course query string parameter. Engine expects your application to generate course identifiers, which get passed to importJobs.

Upon successful import, an import job ID will be returned to you. You can (and should) check the status of your import by checking the importJobs/{importJobId} resource.

Note that in order for users to launch content, the content must be capable of being served by your web server. The WebPathToContentRoot configuration setting should be the path that your web server uses to serve content that resides in your FilePathToContentRoot folder.

There are three ways to import courses into Engine described below.

Importing a ZIP Archive Directly

In this case, you can POST your ZIP archive directly to /importJobs with a Content-Type of multipart/*.

Upon successful import, the course will be unzipped and expanded, and placed in the folder specified by your FilePathToContentRoot configuration setting.

Importing a ZIP Archive by URL

Rather than POST a file, you can POST JSON (as Content-Type application/json) to /importJobs with a url property pointing to a ZIP archive corresponding to a course.

Upon successful import, the course will be downloaded to your FilePathToContentRoot location, unzipped, and extracted.

Importing via Manifest

If a webPathToCourse property is supplied with url as JSON to /importJobs, then Engine will assume you are importing via manifest.

Thus, the associated url property should point to a SCORM or Tin Can manifest or one of the possible AICC files.

webPathToCourse is the URL to the root of the course that will be accessed by the learner. For this type of import, the content will not be downloaded; instead the manifest referenced by the url will be used to import the course definition only, so this needs to be a path at which the content is already available. The content will be launched from that location rather than copied locally, so this approach should not be used for SCORM packages that are hosted on a different domain from Engine.

Launch

A "registration" refers to the experience of a particular learner taking a particular course. In order for your learners to take one of your courses, you will need to create a registration. Registrations are created by making an HTTP POST to the registrations resource.

Once a registration is created, you can then obtain a launch link via the launchLink resource. You can provide the returned launch link to your application to deliver to the end user. Following the launch link will actually launch the course and begin tracking.

A registration may involve several launches before the user actually finishes the course. Your application can use the same launch link for multiple such launches. Other API functions are available for resetting the registration so that the user can retake the course, and Engine can also be configured to restart the registration if a new version of the course is available.

Sometimes, you may want to provide the ability to "preview" a course without actually creating a registration or actually tracking a score. To do this, you can use the launch link generated by the preview resource.

Engine supports the ability to create signed, expirable launch links using JWT.

If signed launch links are enabled, links generated by the API will be signed, and only signed launch links will be accepted by the player (so launch links must be generated via the API).

In order to enable signed launch links in Engine, use the following configuration settings:

In order to cause a launch link to expire, pass expiry as a parameter to either the /preview or /launchLink resources, where the value is the number of seconds till expiration (and 0 represents no expiration).

A signed launch link would look like this:

http://example.org/ScormEngineInterface/defaultui/launch.jsp?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25maWd1cmF0aW9uIjoiIiwicmVnaXN0cmF0aW9uIjoiZ29sZnNpbmdsZXNjb3JlZyIsImV4cCI6MTQ1NjE0ODU0NH0.uYkLek3F7jH_EgK6IQ1cOdFY5H22dJSXFN6N9Q0AKrE

Track

Technically, Engine does all the tracking for you. But Engine doesn't have any idea what you intend to do with the data it's capturing about its supported learning standards. This is why the API lets you do a few different things for reporting purposes.

When you create a registration, you have the opportunity to pass in a postback URL. This is an endpoint in your application that you would configure to receive data about the state of a registration in one of a few different formats while a registration is in progress.

After a registration is complete, you can at any time request the progress or detail resource for a given registration. These resources are intended for use to populate your reporting tables a single time, not as ad hoc reporting mechanisms.

Our expectation is that you will use the API to do the entirety of your reporting against Engine. We recommend considering Engine a black box with the API constituting its interface.

Here is a typical post-back that might be received by your application as a user takes a course:

{
  "activityReport":{
    "id":"golf_sample_default_org",
    "title":"Golf Explained - Run-time Advanced Calls",
    "attempts":1,
    "activityCompletion":"COMPLETED",
    "activitySuccess":"PASSED",
    "score":1.0,
    "scoreIsKnown":true,
    "completionAmount":0.0,
    "completionAmountIsKnown":false,
    "suspended":false,
    "children":[
      {
        "id":"item_1",
        "title":"Golf Explained",
        "attempts":1,
        "activityCompletion":"COMPLETED",
        "activitySuccess":"PASSED",
        "score":1.0,
        "scoreIsKnown":true,
        "timeTracked":"0000:00:32.20",
        "completionAmount":0.0,
        "completionAmountIsKnown":false,
        "suspended":false,
        "children":[
        ]
      }
    ]
  },
  "summary":{
    "id":"test-golf-02",
    "instance":0,
    "updated":"2015-10-22T17:00:57.157Z",
    "registrationCompletion":"COMPLETED",
    "registrationSuccess":"PASSED",
    "score":{
      "scaled":100.0
    },
    "totalSecondsTracked":32.0,
    "course":{
      "id":"scorm-2004-golf",
      "version":0,
      "title":"Golf Explained - Run-time Advanced Calls",
      "courseLearningStandard":"SCORM_2004_3RD_EDITION",
      "updated":"2015-10-22T11:00:08.550Z"
    },
    "learner":{
      "id":"ConsoleLearner",
      "firstName":"Console",
      "lastName":"Learner"
    }
  },
  "globalObjectives":[
  ]
}

Client Libraries

In your Engine distribution, you will see an ApiClient folder. In it, you will find a library that allows native .NET or Java access to the Engine API, as well as dependencies.

The .NET version is called RusticiSoftware.Engine.Client.dll. To get a sense of what is available in the .NET API client, load the Object Browser in Visual Studio for a solution that includes the API client library.

The Java version is SCORMEngineClient_java-1.0.jar. Java Engine releases have API client documentation in the Documentation folder.

Java Example: Creating a Registration

In order to create a registration using the Java API client library, you could do something like this:

// creates a learner for use with the registration
LearnerSchema learner = new LearnerSchema();
learner.setId(user.getUserId());
learner.setFirstName(user.getPerson().getFirstName());
learner.setLastName(user.getPerson().getLastName());

// creates the registration
RegistrationSchema registration = new RegistrationSchema();
registration.setCourseId(courseId);
registration.setLearner(learner);
registration.setRegistrationId(String.valueOf(System.currentTimeMillis()));

// adds the Basic Auth credentials to request
ClientRequestFilter authFilter =  new BasicAuthFilter("username", "password");

// sets up the REST client with the correct base URI and auth details
Registrations regClient = new Registrations("http://localhost/ScormEngineInterface/api/v1/", authFilter);

// actually makes the call to the API
regClient.postRegistrations(registration);