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 Engine, logging is handled exclusively through log4net, an open-source logging library bundled with 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, 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 Engine, 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
    }
}

User Count API

If you do not have automated user count reporting enabled, then you may be asked to provide a user count yourself. As of Engine version 2017.1.27, Engine includes a REST API for calculating user counts.

This API can be accessed via the browser. Simply navigate to http://mylms.com/ScormEngineInterface/api/v1/default/about/userCount?since=2017-01-01&before=2018-01-01, where "mylms.com/ScormEngineInterface" is the "root" of your Engine installation, and the since and before parameters are provided by your account manager. When prompted for credentials, provide the username and password of an account with system-level permissions (i.e., an account defined by ApiBasicSystemAccounts). Tenant-level authorization cannot access the user count API, as it includes the list of tenants, which is considered sensitive information. Copy the returned JSON and send it to the account manager who requested the user count.

Personally Identifiable Information (PII) and Privacy

Linking to a Privacy Policy

In some use cases of Engine, learners may be linked directly to a launched course that will be recording PII or data associated with PII. In those cases it may be necessary to provide access to a Privacy Policy. Engine provides a setting, PrivacyPolicyUrl, for activating a link in the content player to an external URL that should display a Privacy Policy statement. The URL can be absolute or relative, and may need to point to a dynamic resource that is capable of handling Accept-Language headers to support multiple translations.

Removing PII from the Database

While the registration is the central piece of information in Engine's data model, at the core of a registration is a learner's identifier. Most (if not all) data associated with that learner identifier could be classified as PII and subject to needing to be deleted. Engine provides an API to request deletion of PII data based on learner identifiers and/or xAPI Agent identifiers.

Due to the nature of the data and the extent to which it may be referenced within the Engine schema, this API is job based. To delete information for a set of learners, a POST request should be made to the /{tenant}/pii/deletionJob resource including a list of learner identifiers and/or xAPI Agent objects. The response of a successful request will return a job identifier that can be used when requesting job status via a GET request to the /{tenant}/pii/deletionJob/{jobId} resource. When all PII data has been removed, the job will report its status as COMPLETE.

Actions performed:

• Removal of all registrations associated with any learner identifiers provided, including pass/fail, completion, score, runtime information, launch history, etc.
• Removal of xAPI statements including any of the Agents provided or the Agent associated with a learner identifier anywhere in the statement
  • For voiding statements (where verb.id is http://adlnet.gov/expapi/verbs/voided) a new voiding statement will be issued in its place
  • Recalculation of statement targeting chains for statements previously involved with statement references

GDPR Note: This process is intended to be sufficient for removing data per the GDPR requirements from Engine's provided schema. We suggest using additional third party data audit tools to ensure GDPR compliance.

Log Redaction

Given the learner's central role in data handled by Engine it is natural to need to log information from requests that may include learner data. While usable, at the same time this presents a problem when needing to protect PII, therefore Engine includes settings to enable redaction of PII from its logs.

Settings controlling the redaction of information from logs include:

• RedactLogs
• RedactedItems
• RedactedTables
• UnRedactedColumns

Use the RedactLogs setting to enable redaction. The other three settings have reasonable defaults that should be reviewed, but should match the majority of customers' installations. Contact support if you think they are not sufficient for your system or if you have additional questions on their use.

xAPI Authorization Callback

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 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 Engine will be invalidated when processing this callback.