LMS API / HR Sync FTP Integration Guide

Follow

This article covers the Emtrain LMS API and HR Sync routines. Click on a subject below to learn more.

 

API Concepts

Overview

The Emtrain Learning Management System stores, launches, and tracks a variety of training (eLearning, Workshops, Webinars, etc.) created and taken by individuals in an organization. The Emtrain LMS API provides access to a variety of LMS functions and data.

 

Accessing the API

API calls are made over an https connection by sending either GET or POST requests.

The base URL for the API is:

https://lms.emtrain.com/lms/api/

Each API method has a corresponding .php file which handles calls to that method. Generally, the names of API methods directly correspond to the path and name of the .php file for the method. For example, the learner/sign_in API method URL is:

https://lms.emtrain.com/lms/api/learner_sign_in.php

Note: All url parameters must be url-encoded in accordance with RFC 3986.

 

Authentication

To access API methods which require authentication you will need an API Key and an API Secret. Your company’s API Key and Secret can be obtained by signing into the Emtrain LMS as an administrator and clicking on the Developer Integration link
under the My Account section on the admin dashboard menu. If this link is not available on your admin dashboard menu, please contact customer support to obtain your API key and secret.

API Keys identify the LMS account for which an API call is being made. API Keys are included as a parameter in calls to API methods and as such are (technically) visible to the public. API Keys do not require safe-guarding.

API Secrets are used in the generation of an authenticated call signature parameter (auth_sig) for calls to API methods which require authentication. Likewise, when callbacks are supplied as parameters to an API method the callback http(s) request from Emtrain will contain an authenticated call signature generated using your account’s API Secret. API Secrets should only be known by the Emtrain LMS system and the software your API calls are originating from. API Secrets should be safe-guarded.

To help prevent API call replay attacks, API methods requiring authentication will require an auth_timeparameter. The auth_timeparameter should be set to the number of seconds since January 1, 1970 00:00:00 GMT (Unix epoch). Calls to API methods requiring authentication which are older than 1 hour will be rejected.

 

Generating an authentication signature
To generate an authenticated signature for calls to API methods:

  1. Order all method parameter URL parameter key-value pairs based on the ASCII value of the key (i.e. ascending alphanumeric order).
  2. Create a canonical string by concatenating (in-order) all URL parameter key-value pairs, placing a "=" character between each key and its value, and placing a "&" character between each key-value pair.
  3. Salt your canonical string with your API Secret by appending your API Secret to the end of the string.
  4. Create an authenticated call signature by generating a SHA1 hash (raw output) from your salted canonical string.
  5. Base64 encode your authenticated call signature hash.
  6. URL-encode (RFC 3986) the Base64 encoded signature hash value and add to the URL parameters of your call as the auth_sig parameter.

NOTE:

  • Be sure to include the auth_time parameter when ordering your key-value pairs and generating your canonical string.
  • All strings should be UTF-8 encoded.
  • All url parameters must be url-encoded in accordance with RFC 3986.

 

Authentication signature generation example

Suppose we want to call the learner/sign_in API method - the authentication signature generation procedure is as follows:

Assume we are working with the following data:

api_key = "DE7713CC­8119­E17D­53A7­957837461E92" api_secret "A33CF73E­7A71­11E1­A735­001372551D70" auth_time = "1414528879"
learner_id = "learner@yourcompany.com"

The required URL parameters for the learner/sign_in API method are (in no particular order): learner_id, api_key, auth_time, and (of course) the auth_sig we are generating.

To generate our auth_sig we will first create a canonical string by ordering alpha-numerically (based on key) each URL parameter key-value pair required for our method call. We will place a "="character between each key and its value and we will place a "&"character between each key-value pair. Following this procedure will result in:

canonical_string = "api_key=DE7713CC­8119­E17D­53A7­957837461E92&auth_time=1414528879&learner_id=learner@yourcompany.com"

Next, we will salt our canonical_string by appending our api_secret to the end of the string. Doing so will result in:

salted_canonical_string = "api_key=DE7713CC­8119­E17D­53A7­957837461E92&auth_time=1414528879&learner_id=learner@yourcompany.comA33CF73E­7A71­11E1­A735­001372551D70"

Finally, we will generate a SHA1 hash from our salted_canonical_string and Base64 encode the raw hash output. This Base64 encoded value is our finalized auth_sig:

auth_sig = "ONYY2pbNSEQ3sm6iqJuaMGhKZHI="

...after RFC 3986 url-encoding:

auth_sig = "ONYY2pbNSEQ3sm6iqJuaMGhKZHI%3D"

 

Authentication URL Parameters

The following URL parameters are required for all API methods requiring authentication:

Parameter 

Required 

Description

Example

api_key

required

Your API Key

"DE7713CC­8119­E17D­53A7­957 837461E92"

auth_time

required

The number of seconds since January 1, 1970 00:00:00 GMT (Unix epoch).

"1414528879"

auth_sig

required

A URL encoded (RFC 3986) string consisting of a Base64 encoded SHA-1 hash of all URL parameters, salted with your API Secret.

(see: Generating an authentication signature...)

"ONYY2pbNSEQ3sm6iqJuaMGhKZHI %3D"

 

API Methods

Method: learner/sign_in Overview

The learner/sign_in method automatically signs a learner into their learner portal. Using this method a developer can add dynamically generated links within their company’s intranet portal which when clicked will take the currently signed-in intranet user directly into their Emtrain Learner Portal.

URL: https://lms.emtrain.com/lms/api/learner_sign_in.php

Supported Request Types: GET

Authentication Parameters: Required

Method Parameters:

Parameter

Type

Required

Description

Example

learner_id

URL

Required

The unique id (often the employee id) of the learner to be signed into their learner portal. This id corresponds to your LMS account’s custom learner data field which has been designated as the unique learner id field. (See LMS Admin Dashboard > Professional Tools > Custom Learner Data)

"674567"

Return Value: None

Example Call:

https://lms.emtrain.com/lms/api/learner_sign_in.php?learner_id=learner@yourcompany.com&api_key=D E7713CC­8119­E17D­53A7­957837461E92&auth_time=1414528879&auth_sig=ONYY2pbNSEQ3sm6iqJuaMGhKZHI%3D

 

Method: learner/update Overview

The learner/update method provides a way to create new learners and update existing learners for your account. Customers desiring a tight integration between their HR systems and the Emtrain LMS can use this API method as a “real-time” alternative to the nightly-executed HR Learner Sync FTP routines.

URL: https://lms.emtrain.com/lms/api/learner/update.php

Supported Request Types: POST

Authentication Parameters: Required

Method Parameters:

Parameter

Type

Required

Description

Example

Learner Data Array

JSON POST

Required

A non-associative array containing all learner data fields present in the HR Sync FTP import template CSV file. The format of HR Sync import files vary based on the custom learner data fields which have been configured for your account. A link to download a sample template file for your account is available on the Developer Integration screen (See LMS Admin Dashboard > My Account > Developer Integration)

NOTE: The fields in the learner data JSON array must be in the same order as they appear in the HR Sync FTP template CSV file.

['1','2014­01­06 00:00:00','2014­05­01 00:00:00','2014­06­01 00:00:00','2014­07­01 00:00:00','2014­08­01 00:00:00','Social Engineering','54','learner@you rcopmpany.com','Keyser','2014­ 01­01 00:00:00','1','Soze','learner@ yourcopmpany.com','supervisor@ yourcopmpany.com','321password !','3','2012­05­01 00:00:00','northern california','emp','2012­05­01 00:00:00']

Return Value: JSON Object

Example Call:

<script src="//ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js"></script> <script type="text/javascript">

var learner_data = ['1','2014­01­06 00:00:00','2014­05­01 00:00:00','2014­06­01 00:00:00','2014­07­01 00:00:00', '2014­08­01 00:00:00','Social Engineering','54','learner@yourcopmpany.com','Keyser',
'2014­01­01 00:00:00','1','Soze','learner@yourcopmpany.com','supervisor@yourcopmpany.com', '321password!','3','2012­05­01 00:00:00','northern california','emp','2012­05­01 00:00:00'];

$.ajax({
type: "POST",

url:"https://lms.emtrain.com/lms/api/learner/update.php?api_key=DE7713CC­7A71­11E1­A735­001372551D70&auth_ti me=1414520008&auth_sig=XVzRGI0GxjgdYXbL6ZOK3WRhLMA%3D",
data: JSON.stringify(learner_data),

dataType: "json" })

.done(function( response ) { alert( response );

}); </script>

 

HR Sync FTP Concepts Overview

The Emtrain Learning Management System stores, launches, and tracks a variety of training (eLearning, Workshops, Webinars, etc.) created and taken by individuals in an organization. The Emtrain HR Sync FTP provides a means of automatically syncing data contained within Emtrain with your company’s HR systems.

 

Connecting to the HR Sync FTP host

The FTP host supports the following transfer methods:

Explicit FTPS:

  • Host: hr-sync-ftp.emtrain.com
  • Control Port: 21
  • Data Port: Will negotiate a port in the 50000 - 55000 range for data transfer.

Implicit FTPS:

  • Host: hr-sync-ftp.emtrain.com
  • Port: 990

SFTP:

  • Host: hr-sync-ftp.emtrain.com
  • Port: 2222 (Do not use the default SFTP port, use the 2222 port)
  • Login method: Interactive

Unsecured FTP (Not recommended)

  • Host: hr-sync-ftp.emtrain.com
  • Port: 21

Unsecured FTP is supported, but it is not recommended that this method be used. We suggest highly that you use one of the secure methods to transfer your employee data to Emtrain's LMS.

 

Logging into the FTP Server

Use your accounts API Key as the Username and the API Secret as the password.

Your company’s API Key and Secret can be obtained by signing into Emtrain as an administrator and clicking on the Developer Integration link under the My Account section on the admin dashboard menu. If this link is not available on your admin dashboard menu, please contact customer support to obtain your API key and secret.

Every Emtrain customer is automatically placed into a secure private directory upon connection to the HR Sync FTP host. 

 

HR Sync Routines: Learner (Employee) Sync

Overview

The Learner Sync routine provides a means of routinely importing new learners and updating existing learners in the Emtrain LMS.

 

LMS Setup

By default the HR Learner Sync routine assumes that a Learner’s sign-in username serves as a unique primary key for the purposes of updating existing records. If the learner sign-in usernames you have configured in the Emtrain LMS are not stored in your HR system you can define a custom learner data field representing a unique key for the learner (e.g. Employee Id). To define this field sign into Emtrain as an administrator and click on “Custom Learner Data” under “Professional Tools” on the admin dashboard menu. On the “Custom Learner Data” screen add a new field representing the unique key for your learners. Be sure to designate this field as the unique key by selecting the “Unique Key” radio button for this field.

Date Format

Dates must be formatted as YYYY-MM-DD. If date fields are formatted differently, the values will not be written to the field.

Learner Import File Format

The column format of the CSV file expected by the HR Learner Sync routine will vary based on the custom learner fields your Emtrain administrator has defined. To get started, you must first download an HR Learner Sync CSV import file template generated specifically for your account. You can generate your template by signing into the Emtrain LMS as an administrator and clicking the “Developer Integration” link under “My Account” on the admin dashboard menu. On the “Developer Integration” screen you will see a link to download the “Learner Sync File Format Template” under the HR Sync FTP header.

NOTE: Be sure to include the headers from the template in your CSV files. The order of the columns must be exactly as they appear in the HR Learner Sync template CSV.

When configuring your HR system to generate HR Learner Sync import files, the following file name (naming convention) is recommended:

emtrain_hr_learner_sync_YYYY_MM_DD.csv
(e.g. emtrain_hr_learner_sync_2015_01_01.csv)

 

Maintaining LMS-Specific Learner Data With [NOCHANGE]

The HR Learner Sync CSV template file for your LMS account will contain every learner-attribute field in the Emtrain LMS database. If you have configured custom learner data fields in the Emtrain LMS which are not available in your HR System, you can disable HR Learner Sync updates on a field-by-field learner-by-learner basis by setting a learner’s value for any field to [NOCHANGE]. To prevent the updating of a particular field for every learner, simply set the value of the field for every learner to [NOCHANGE].

 

Processing Your First HR Learner Sync FTP Upload

To begin using the HR Learner Sync FTP, simply upload one or more properly formatted CSV file exports from your HR system to the HR Sync FTP host. The HR Learner Sync routine runs at 11:00 PM, 12:00 AM, 1:00 AM, 2:00 AM and 3:00 AM Pacific Standard Time every night. Everytime the HR Learner Sync routine runs all unprocessed csv import files in your directory will be processed.

After the HR Learner Sync routine completes, the processed CSV import file(s) you uploaded will be moved into the “imported” directory under your account’s HR Sync FTP directory and re-named to indicate the date and the order in which the file was imported (e.g. 1_1_2012_1.csv, 1_1_2012_2.csv).

 

Troubleshooting

If you encounter issues with the processing of HR Learner Sync files, a log of the most recent HR Learner Sync processing operations and errors for your account is viewable through the Emtrain LMS on the Developer Integration screen. To view your HR Learner Sync log, simply log into the Emtrain LMS as an administrator and click the “Developer Integration” link under “My Account” on the admin dashboard menu. For frequently asked questions, please refer to this help center article: http://support.emtrain.com/hc/en-us/articles/202986914

 

Change Log

Version 1

  • Initial Launch of the Emtrain LMS API / HR Sync FTP

Version 1.1

  • Added new learner/update.php API method for the update / creation of learners.
  • Changed API base url to https://lms.emtrain.com/lms/api/. The previous API base url (https://lms2.emtrain.com/lms/api/) is deprecated and will cease functioning 6/1/2015.
  • Changed URL path for the learner/sign_in.php API method to https://lms.emtrain.com/lms/api/learner_sign_in.php. The previous url (https://lms.emtrain.com/lms/api/learner/sign_in.php) is deprecated.
  • ­ Added support for the processing of multiple import files to the HR Sync FTP nightly routine.
  • Added support for [NOCHANGE] field values in HR Learner Sync FTP import files. Any fields in an HR Learner Sync import file row containing [NOCHANGE] will not be updated for the corresponding Learner.
  • ­Updated documentation of HR Sync FTP routine execution times.
  • Added most recent routine execution log entries to the Developer Integration screen (LMS Admin Dashboard > Developer Integration) to facilitate debugging of HR Sync FTP integration issues.
  • Updated auth_sig creation documentation to correct usage of lower-case api keys and secrets in code examples. Uppercase versions of api keys and secrets, as they are presented on the Emtrain LMS Developer Integration screen, should always be used when generating authentication signatures.

Version 1.2

  • Added support for Implicit FTPS and SFTP to the FTP host.

 

Comments