Setup and Installation

Engine has three required components: a database to store Engine application data, a filesystem to store courses, and an application server to serve these courses. Detailed instruction on configuring these components follows. (Note: instructions about the filesystem are included in the section about configuration settings.)

Configuration in Engine

Configuration settings in Engine have four primary scopes--system, tenant, course, and registration.

System-level settings can be configured via a settings file in Engine. Your Engine delivery includes a template for this file.

For each of tenant, course, and registration, Engine supplies a /configuration resource in the API, as per the API documentation.

To make use of /configuration, you will need to supply a setting ID. We do not include a complete list of these setting IDs (or possible values) in this documentation, but you can check with your integration developer or send a note to support@scorm.com if you want to know a setting ID or whether a particular Engine behavior is configurable.

API Configuration Examples

One of the most common default Engine behaviors that is overridden is SCO launch type.

Here are examples of requests that could be used to set this at each of tenant, course, and registration in the default tenant with a course ID of "RusticiGolf" and registration ID "RusticiGolf-JoeLearner":

In each case, the body of the PUT request would look something like this:

{"value":"FRAMESET"}

Required Configuration Settings

In order for Engine to run, you must fill out a small number of configuration settings. First, there are a few URL-based settings that you will need to fill out with the web path you configure on your server. We recommend searching the configuration template for instances of "/ScormEngineInterface" and replacing it with the web path, starting with ScormEngineUrl.

Apart from the URL settings, there are a few others that will need to be provided manually:

FilePathToContentRoot and WebPathToContentRoot are good examples of settings that might be set on a per-tenant basis. There is more information about how to do that in our Tenancy documentation.

Finally, there are two necessary settings if you want to use xAPI:

Replacement

Some settings are likely to have finer grained requirements but might not be set via the API, such as RedirectOnExitUrl. This presents a possible use case for a special ${RegistrationId} replacement token available in Engine. So, for example, if you set RedirectOnExitUrl, which would look like this in SCORMEngineSettings.config:

<add key="RedirectOnExitUrl" value="http://example.org/lms?registrationId=${RegistrationId}" />

then your app would have the registration ID available to it when Engine redirected on exit.

It is also possible to do replacement based on ${TenantName}. Any setting that can be configured at the tenant level in the API (i.e., any tenant-, registration-, or package-scoped setting) can accept the ${TenantName} syntax in the configuration file.

Authentication

Authentication is handled via HTTP Basic Auth (username and password). For each request, the supplied credentials will be checked against the set of accounts specified by your ApiBasicAccounts configuration setting.

In order to keep your credentials secure we strongly recommend using TLS (https) when accessing the API, and using long random strings for both the username and password components (these should not be real user accounts, no one should ever have to type these credentials!)

N.B. This API is designed to allow your application to integrate with Engine and does not provide the fine grained security control you'd want for an API available to users. Any API account can perform any operation. The ability to set up multiple accounts is only relevant for the purpose of having different sets of credentials that can be revoked separately.

Optional Configuration Settings

There are a number of scenarios where additional settings could prove useful for the operation of Engine.

Postback

Engine allows the integrating application to supply a custom URL to process registration results. If these settings are configured, Engine will post results back to the application server as provided.

Database Setup

Requirements

Engine generally supports a given platform as long as the vendor offers public support for that platform. As of October 2015, Engine supports the following DBMSes:

Database Connectors

For legal reasons, we are not generally allowed to redistribute the database connectors for most platforms. On .NET, we are able to include the connectors for SQL Server, Oracle, and PostgreSQL. If you are running Java or .NET with MySQL, you will need to download the database connector for your platform and include it in the Engine application's bin folder/classpath.

Preliminary Considerations

As discussed in the Tenancy Overview, you will need to decide whether you will separate Engine's system and tenant tables. To summarize, you will need to separate the tenant and system tables if you ever plan on sharding Engine's tenant tables or otherwise separating different tenants into different databases. You will also need to decide whether you are keeping Engine's tables in the same database as your application's other tables, or if you are using a separate database. Before you use the installation tool, you will need to create any new databases, users, or tablespaces required for your setup.

Installation Tool

First, you will need to use your command line to navigate to the proper directory. .NET customers should navigate to the ScormEngineInterface/bin folder of the Engine distribution. Java customers should navigate to the Installer folder of the Engine distribution.

Second, you will need to copy any database connectors required by your installation. For .NET customers, this applies only to MySQL users; copy the MySQL connector into your current directory. For Java customers, copy your JDBC connector into the lib folder of your directory.

Third, you will need to actually run the command. The command consists of four parts:

baseCommand persistenceEngine connectionString schemaPrefix

Customers who wish to specify different system and tenant databases will need to use an XML configuration file. An EngineInstall.xml.template file will be given with your installation; fill it out and save a copy (without the .template extension) in the folder where you are running the tool. Then run the tool using basecommand EngineInstall.xml -install

Server Setup

Every customer application environment into which Engine is deployed is a snowflake. We don't pretend to be server configuration experts for every possible scenario, as our primary goal is to ensure that Engine can run comfortably according to your administrative preferences and expertise.

That said, we can typically ensure that Engine can be stood up in a given supported environment. The basics are covered below.

.NET/IIS

Engine for .NET runs as a web application. It requires .NET Framework 4.5. Engine ships by default as a binary distribution with an assembly intended to be the basis of a .NET web application.

You can drop the entire ScormEngineInterface folder onto your application server, point an IIS application to it, and try hitting an ASP.NET page (like console; see below).

You might want to map a content folder for use with Engine, depending on how you intend to store and serve content.

Java

Engine for Java needs a Java application container to run. It requires Java 7. Cloud, our hosted training delivery system, runs on Tomcat. Most of our development team uses Tomcat for testing, too. So we'll cover the basics of setting up Engine for Tomcat in this manual.

We generally support Engine's use with other Java application containers, but configuring Engine for use with all Java application containers is outside the scope of this document.

We ship Engine as a WAR file. This can be dropped in Tomcat's webapps directory.

As mentioned earlier, your SCORMEngineSettings.properties file should be somewhere in the web application classpath.

We also ship Engine with a context.xml template that you can use as a reference for configuring JDBC.

We specifically recommend that you do not use your Java application container to serve content through Engine. Instead, prefer a traditional web server. There are a variety of ways to map your web server so that the web paths referenced by Engine are served by a web server rather than the app server serving Engine.