Overview 

External systems can communicate with Experiential Learning Cloud via integrations. An integration is simply Experiential Learning Cloud and another system exchanging documents. The external system always initiates the exchange. 

An external system initiates the exchange through a command. A command is simply a formatted file deposited at a designated endpoint. Right now, Experiential Learning Cloud only supports SFTP endpoints, but there may be more in the future (such as web services). 

 

SFTP 

Command files should be uploaded to the root directory. It is important that file names be unique. Response files will appear in the responses directory. Response files will have the same file name as the command file. 

Command files will be deleted as soon as they are processed. It is up to the external system to delete response files, but we reserve the right to automatically delete files older than a year. 

Commands are executed on a schedule, so responses should be pulled on a schedule. 

File Names 

File names must begin with the command name (e.g. classCreate), followed by _. Characters following the _ are ignored by the system. The file extension must be .json for JSON formats and .csv for CSV formats. 

Formats 

Both command and response files are formatted as JSON. In some cases, CSV is supported as described below.

CSV 

Some commands support a completely flat CSV file format. A command consists of a single CSV file. The file must have a single header row. The file name must start with the command string followed by an underscore (_). The extension must be ".csv". 

The update flag (below) is always assumed to be true for CSV files. 

Commands 

All commands share the following fields:

Field	Description	Required
command	A command string token (list of allowed commands given below)	X
source	Name of the requesting system or organization	X
email	An email address of someone to contact	X
description	A way for the requester to document this specific command (reason, nature, other circumstances)
updated	This is a boolean that indicates whether duplicate records encountered should be updated. By default, they are not updated.

 

Example:

{
"command": "createClass",
"source": "Acme University",
"email" : "jane_it@acme.edu",
"description" : "Spring 2019 Graduation"
"update" : true
}

Responses 

A response file will appear in the responses directory for each submitted file. The file name will be the same as the submitted file. Response files are in JSON format (regardless of the submitted format). 

All response files contain the following fields:

Field	Description
command	The command string that executed
start	Date/Time when started
completed	Date/Time when completed
errors	An array of errors
records	An array of records created/updated

 

Example:

{
"command": "createClass",
"start": "2019-04-13 17:21:04",
"completed" : "2019-04-13 17:24:38",
"errors" : 
    [
        {
        "error": "INVALID_DATA",
        "element": "code",
        "description": "unable to find code '38298888' for language on line 3829"
        }
    ],
"records":
    [
        {
        "table": "st_staff",
        "inserts" : "3",
        "updates" : "0",
        "deletes" : "0"
        }
    ]
}

 

Data Types 

The following data types are supported:

Data Type	Description
Date	ISO 8601 format with hyphens (YYYY-MM-DD)
Boolean	"true" or "false"
Array	JSON array ( [ ] )
Integer
String
Gender	SNOMED CT has the following values: 1 Male 2 Female 3 Transgender male  4 Transgender female 5 Genderqueer 6 Neither exclusively male nor female 7 Other 8 Declined to answer Note: the codes have been simplified from their SNOMED CT counterparts.
Sexual Orientation	SNOMED CT has the following values: 1. Straight or heterosexual 2. Lesbian, gay, or homosexual 3. Bisexual 4. Other 5. Don't know 6. Declined to answer Note: the codes have been simplified from their SNOMED CT counterparts.