File Connector

Introduction

TRAX LRS provides a convenient feature to import and export statements from/to a file. The import and export processes may be very long tasks so this feature is accessible only from the console.

Configuration

Import settings

The default settings of the import feature can be changed in the .env file, including:

  • The location of the file to import, which must be accessible from your application with reading permissions
  • Pseudonymization option, if the statements to import have not been pseudonymized yet
  • The number of statements imported at the same time
  • The authority that will be assigned to the imported statements
IMPORTER_FILE_PATH="C:\wamp64\www\elastic\xapi_statements.json"
IMPORTER_PSEUDONIMIZE=true
IMPORTER_BATCH_SIZE=100
IMPORTER_AUTHORITY_NAME=import
IMPORTER_AUTHORITY_HOMEPAGE=http://traxlrs.com

Export settings

The default settings of the export feature can be changed in the .env file, including:

  • The location of the file to export, which must be accessible from your application with read and write permissions
  • The number of statements exported at the same time
EXPORTER_FILE_PATH="C:\wamp64\www\elastic\xapi_statements.json"
EXPORTER_BATCH_SIZE=100

File Format

The file connector supports 3 formats when importing data. When exporting data, the basic format is used.

Basic format

A text file with 1 statement per line. The \n character must be used for line returns.

{"actor":{"mbox":"mailto:agent1@traxlrs.com"},"verb":{"id":"http://adlnet.gov/expapi/verbs/completed"},"object":{"id":"https://traxlrs.com/course01"}}
{"actor":{"mbox":"mailto:agent2@traxlrs.com"},"verb":{"id":"http://adlnet.gov/expapi/verbs/completed"},"object":{"id":"https://traxlrs.com/course02"}}

Elasticsearch friendly

A text file with 1 statement per line, embedded in the _source property of a JSON object (there may be other properties). The \n character must be used for line returns.

{"_source":{"actor":{"mbox":"mailto:agent1@traxlrs.com"},"verb":{"id":"http://adlnet.gov/expapi/verbs/completed"},"object":{"id":"https://traxlrs.com/course01"}}}
{"_source":{"actor":{"mbox":"mailto:agent2@traxlrs.com"},"verb":{"id":"http://adlnet.gov/expapi/verbs/completed"},"object":{"id":"https://traxlrs.com/course02"}}}

JSON friendly

One of the previous option, with [ and ] at the begining and end of the file, and a , at the end of each line, in order to make this file JSON compliant.

[
{"actor":{"mbox":"mailto:agent1@traxlrs.com"},"verb":{"id":"http://adlnet.gov/expapi/verbs/completed"},"object":{"id":"https://traxlrs.com/course01"}},
{"actor":{"mbox":"mailto:agent2@traxlrs.com"},"verb":{"id":"http://adlnet.gov/expapi/verbs/completed"},"object":{"id":"https://traxlrs.com/course02"}},
]

Commands

Before using these commands, you must create a store in your LRS.

Import statements

You can create an import job for each store.

php artisan statements:file-import

The following parameters are optional. When not provided in the command line, some of them will be asked.

Option Example of value Description
--file /path/to/file Path of the file to import
--batch 50 The batch size
--owner 1 Internal ID of the LRS store
--entity 1 Internal ID of an LRS entity
--pseudo Pseudonymize statements
--noprompt Don't ask options (take defaults)
--restart Restart from the 1st statement

Display the last import status

php artisan statements:file-import-status

When not provided in the command line, the following option will be asked.

Option Example of value Description
--owner 1 Internal ID of the LRS store

Export statements

You can create an export job for each store.

php artisan statements:file-export

The following parameters are optional. When not provided in the command line, some of them will be asked.

Option Example of value Description
--file /path/to/file Path of the file to export
--batch 50 The batch size
--owner 1 Internal ID of the LRS store
--entity 1 Internal ID of an LRS entity, or -1 (all entities), or omitted (no entity)
--noprompt Don't ask options (take defaults)
--restart Restart from the 1st statement

Display the last export status

php artisan statements:file-export-status

When not provided in the command line, the following option will be asked.

Option Example of value Description
--owner 1 Internal ID of the LRS store

Resuming

When an import or export fails or is interrupted, you can resume it where it stopped. Relaunch the command and it will ask you if you want to resume or restart.

When the --noprompt option is used, it always tries to resume, except when the --restart option is used together.

Important information

Statements ID

2 statements can't have the same ID in an LRS store. So if you try to import the same dataset twice, an error will be thrown. Therefore, you should always remove the imported data before trying to restart the import.

Validation

We assume that you are importing statements from another xAPI conformant LRS, so the import command will not validate the statements again.

However, you can use the php artisan statements:validate afterwards. See statements validation.

Logs

If you enabled the logging system, be aware that importing statements does not generate any log.

Attachments

The import command accepts only JSON data. So you can not import statements with raw attachments because it requires a multipart format. However, you can import statements with attachments referenced by the fileUrl property.

The export command exports only JSON data. Statements with raw attachments will be exported without the attachments.