Appendix

Engine API Reference

We have discussed the RESTful Engine API throughout this document. A complete API reference is available here.

System Requirements

A successful Engine installation requires an application server, a database management system (DBMS, often referred to simply as a "database"), and a filesystem or equivalent for content.

As a general rule, our implementation team will expect your implementation team to have configuration expertise for your selected deployment environment.

If a specific software requirement is not otherwise listed here, our general policy for any Engine deployment environment is to support any versions of software still officially supported by the vendor. For instance, as of January 12, 2016, we expect to no longer support any version of Internet Explorer no longer officially supported by Microsoft.

Application Server

• For .NET Engine, we required .NET Framework 4.5 or higher be available with IIS.
• For Java Engine, we require Java 7 or higher be available with the Java application container.

For Java, Engine should run in any Java application container, although we develop and test in Tomcat.

DBMS

Engine's installer and data definition language (DDL) allow it to work with any of the following DBMSs:

• SQL Server 2008 or higher
• Oracle 11g2 or higher
• MySQL 5.5 or higher
• PostgreSQL 9.1 or higher

Language Support

The majority of the user-facing strings in Engine are translated. Engine supports the following languages:

• ar-SA - Arabic (Saudi Arabia)
• cy-GB - Welsh
• da-DK - Danish
• de-DE - Deutsch
• en-GB - English (United Kingdom)
• en-US - English (United States)
• es-AR - Spanish (Argentina)
• es-CO - Spanish (Colombia)
• es-MX - Spanish (Mexico)
• es-ES - Spanish (Spain)
• fi-FI - Finnish
• fr-FR - French
• hu-HU - Hungarian
• id-ID - Indonesian
• it-IT - Italian
• ja-JP - Japanese
• ms - Malay (Malaysia)
• nl-NL - Dutch
• no - Norwegian
• pt-BR - Brazilian Portugese
• sv-SE - Swedish
• th - Thai
• tr - Turkish
• ru-RU - Russian
• zh-CN - Chinese (Simplified)
• zh-TW - Chinese (Taiwan)

ASP.NET or JSP pages in Engine with internationalized strings will accept a "cc" parameter on the query string, which will cause Engine to look for strings from the language indicated by the culture code.

If you wanted Engine's strings (not the content's strings; the player's strings) to be translated to French at launch, for instance, your launch URL might look like launch.aspx?cc=fr-FR (with the additional necessary launch parameters).

Engine will fall back to using a browser's language settings if a culture code is not specified.

Logging

.NET

In .NET Scorm Engine, logging is handled exclusively through log4net, an open-source logging library bundled with SCORM Engine. A sensible default configuration for log4net is provided in our web.config templates, but this configuration can be edited or replaced at will. If the configuration is missing, SCORM Engine will still run, but nothing will be logged.

If you are not using our web.config templates and you wish to use log4net, you will need to add a few modifications to your web.config file. First, if you do not have a configSections tag already, you will need to add it as a child of the root configuration element. Then, under the configSections tag, you will need to add:

<section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler,Log4net"/>

In addition, you will need to add a log4net element as a child of the root element. You can copy the example from our templates, or you can consult the log4net documentation.

The default log4net configuration included in our web.config templates will log only those messages with a log level of WARNING or higher. These messages will be written to a rolling log file under C:\\logs\scormengine-log.txt. They will also be written to the ASP.NET trace, with categories corresponding to their log level.

Java

In Java ScormEngine, most logging is handled primarily through SLF4J, an open-source interface to several other logging libraries.

SLF4J can be used in combination with many other logging frameworks. In order to enable a particular framework, you must download the appropriate SLF4J adapter from the SLF4J project website and place it in the classpath for your web application. Engine already ships with logback, an open-source logging library, and its SLF4J adapter so that logging will work "right out of the box."

We also ship with a default logback configuration file, which is deployed when the WAR is deployed. The file, logback.xml, is located in the WEB-INF/classes directory of your deployed application. That said, we do not recommend you edit this configuration, lest your changes get overwritten when you re-deploy Engine after a maintenance release. Instead, we recommend you take advantage of the fact that logback.xml is logback's last choice for a configuration file. If you place a logback.groovy or logback-test.xml file in your web application classpath, logback will load that configuration instead. For more information on logback's configuration file format, see the tutorial on the logback project website.

Automated User Count Reporting

Engine provides the capability to report user count data to Rustici Software periodically for each connection string you use. In order to ensure this process does not interfere with your work we spin it off as a low priority thread only once we detect it's time to send the count, and do not do any retries if there is an error. We added this feature since we've found customers frequently have difficulty finding their user count when it's time to report it. The automated user count report uses the GetUserCount method in your integration.

During your integration process, you will receive the following settings from us (formatted differently as required for your platform's configuration file). You can insert the settings into your configuration file to enable automated user count reporting at your option.

UserCountReportEnabled="true"
UserCountReportCustomerId="OurIDForYourOrganization"
UserCountReportContractPeriodEndDate="12-31-2015"

The information that is sent back to our server (https://cloud.scorm.com/engineUserCount) will be in this format:

{
    "hostName": "yourhost",
    "rangeEnd": "2015-05-28T04:00:00.000+0000",
    "rangeStart": "2014-05-28T04:00:00.000+0000",
    "dbid": "e30ba552-4e4f-409e-943e-04d063bdfa69",
    "customerId": "OurIDForYourOrganization",
    "systemHomePageUrl": "http://example.org/yourSystemHomePageUrl/",
    "usersByTenant": {
        "default": 1234567,
        "other_tenant": 123456
    }
}

xAPI Authorization Callback

Scorm Engine can use a callback URL to validate calls into the xAPI endpoint. In order to configure this you need to use the setting LrsAuthCallbackUrl in you Engine settings file. Also pay note to related settings LrsAuthCallbackMaxCacheSize, LrsAuthCacheSecondsSuccess and LrsAuthCacheSecondsFailure.

Once configured the calling system should hit the xAPI endpoint with a basic auth header consisting of the username/password that it wishes the callback URL to authenticate. The body of the request that is sent to the callback URL will be in this format:

{
    "username": "<username supplied in basic auth header>",
    "password": "<password supplied in basic auth header>"
}

The callback URL implementation must authenticate the credentials and ascertain the xAPI permissions level for the credentials before returning that information in the following format:

{
    "verified": true, 
    "permission": "READONLY", 
    "expireTimeInSeconds": 600, 
    "invalidateEntireCache": false
}

Key:

• verified - required field. Values: true/false. Return true if the username/password authenticated, false if it didn't.
• permission - required field. Values: NONE/USER/ROOT/READONLY/WRITEONLY. The xAPI permissions level granted to the credentials.
• expireTimeInSeconds - optional field. Value: integer. Specifies the number of seconds to cache this authentication. Subsequent, matching, calls to the xAPI endpoint in Scorm Engine will not result in calling the callback URL until the object expires. Will use LrsAuthCacheSecondsSuccess setting if not supplied.
• invalidateEntireCache - optional field. Values: true/false. If this flag is set to true the entire auth callback cache in ScormeEngine will be invalidated when processing this callback.