API for the LLN Robot System

Purpose

The LLN Robot System API can be used by developers to extend the LLN Robot System to further meet your organisation's needs. The LLN Robot System API acts as an interface for external clients to access deployment-specific information from the LLN Robot System.
For example, the LLN Robot System API can be used to access all of the learner information available within your LLN Robot System. Using the LLN Robot System API you can send an HTTP request and receive all of the learner details as a response. This can then be configured for use by external systems such as LMS or accounting software.
These APIs are also used by the LLN-Robot Zapier application and APIs must be enabled for your deployment before using the Zapier integration.

Getting Started

Configure API Access 

To be able to use the API for your deployment, you first need to go to Manage System Settings and switch Enable API to on.  Once enabled, your API Authentication Key will be made visible.  This key is validated on all calls to API endpoints.

This function above is only available to administrators of the system.
Please Note: If you believe that your API Key has been compromised, contact The Learning Resources Group and we can reset it for you.

Authentication

When sending any request to the API we require the api key be passed in a header parameter with key Authorization

Key:                 Authorization

Value:             ROBOT-V1-KEY apikey=” [API Authentication Key]”

Example of header key as shown in a Postman request;

URL Structure

APIs endpoints are access via a standard URL structure;

http://api.lln.training/api/[deployment]/v1/[resource]

where the variables inside [ ] need to be replaced for the correct response.

deployment the deployment name that is assigned to the client to access the LLN Robot
resource the kind of resource information that you want to access from the system, in this case it is 'learners' since we are accessing all the learners information.

Some endpoints may have required / option query string parameters.  These are mentioned under each endpoint.

Data Formats

The response from all APIs is a JSON document. At this time, JSON is the only format that we support, therefore you will need to take it into consideration when displaying the data.

Standard Response Codes

Response Code Definition
200 No Errors. Data should be fetched.
400 Bad Request. There is a mistake in the URL that you entered. Please check and make sure the version and the resource are spelt and placed correctly.
401 Unauthorized - wrong API Key or Deployment name.
404 Not Found. There is no deployment with that name.


API Endpoints

Learners

/api/[deployment]/v1/learners

HTTP Method Use
GET Fetching a list of records.
POST Create / invite a learner

GET Learners

Retrieves the list of learners in your deployment. 

Optional Parameters can be added to this the URL to filter the results;

Name Type Use
since Date a UTC date in JSON format.  Will only retrieve learner records updated since this time.
email string Will only return learner record(s) that have this email address
complete Int If parameter is included, will only return learner which have been completed the quiz.

Examples:

https://api.lln.training/api/testing/v1/learners?since=2019-01-01T00:00:00Z

https://api.lln.training/api/testing/v1/learners?completed=1&email=test@testing.com

Results format

An array of JSON objects will be returned with the following properties;

Property Name Type Use
inviteCode UUID Uniquely identifies the quiz results. 
learnerId string The learnerId from your deployment (if entered).  Please Note: the same learnerId may be on several results if learner has redone the quiz or completed multiple testLevels.
name Object The learners name { first: string, last }
email string The email address of the learner
results Object ACSF Test: The results object contains 5 key-value pairs which display their ACSF scores for each section.
VSL Test: The results object contains 2 key-value pairs which display a 1 if they passed the section or a 0 if they failed.
complete boolean Is true if the learner has completed the quiz.
details Array<Object> The details object includes all custom fields that the administrators of the deployment want learners to fill out.
testLevel String Displays test they were invited for.
updatedAt Date JSON formatted UTC date/time this record was last updated
Example object;

    {
        "email": "danthompson@example.com",
        "inviteCode": "e6d064ee-3e2c-4136-8112-5cda96f86928",
        "completeTime": "2019-07-04T04:51:31.820Z",
        "updatedAt": "2019-09-07T03:22:34.750Z",
        "learnerId": "448-726-085-021",
        "results": {
            "learning": 1,
            "reading": 2,
            "writing": 0,
            "oralcommunication": 2,
            "numeracy": 3
        },
        "details": [],
        "name": {
            "first": "Daniel",
            "last": "Thompson"
        },
        "id": "e6d064ee-3e2c-4136-8112-5cda96f86928",
        "quiz": "ACSF_4",
        "complete": true
    }

POST Learner

This method can be used to create new learners in the LLN robot system.  The learner record will be created and an email will be sent to the leaner inviting them to complete the quiz.

The details of the new learner must be passed as a JSON object in the request body having the following properties.

* denotes that a field is required

Property Name Type Use
nameFirst * String Learners first name
nameLast * String Learners surname
Email * String Email address of the learner
testLevel * String The test level to create for them.  Value in this field must be one of;
  • acsf3
  • acsf4
  • vfh
  • acsf3shortcourse
learnerId String Identifier from your system (optional)
noInvite Boolean If noInvite property is true, the email invite to the learner will not be sent and would then need to be done manually by an administrator in the LLN-Robot application. (optional)
{LearnerFormField} Various See information below (optional, unless required)

Learner Form Fields

Where custom learner form fields have been added in LLN-Robot, these can be sent via the API using the Field Label as a property on the learner JSON object that is submitted.
In the case where a Learner Form field has been marked as REQUIRED (red * in the screenshot below) those fields MUST be included in the JSON object.

Example of JSON object for the above configuration where List and Course Name are required.  Note that the property name must match exactly the label in LLN-Robot, including spaces.

{

"learnerId": "MTUR001",
"nameFirst": "Turneye",
"nameLast": "McTurnbull",
"testLevel": "acsf3",
"email": "marcus@turncode.productions",
"List": "Sample List Item",
"Course Name": "Learning Course 1"

}

Where the custom field is a Dropdown Menu type, the value sent to the API must match a valid entry in the list.


COURSES

/api/[deployment]/v1/COURSES

The courses endpoint can be used to retrieve the list of courses defined in your deployment.  The results from this API could then be used in calling the Learner Report endpoint.

GET Courses

Retrieves the list of courses set up your deployment. 

Result format

An array of JSON objects will be returned with the following properties;

Property Name Type Use
title String Title of the course
level Number Qualification level
profile Object The ACSF result profile for this course and level
Units Array<string> Array of the units for the course
Id String Internal LLN-Robot id for the course
Example object;

    {
        "title": "Business Administration",
        "level": 4,
        "profile": {
            "numeracy": 3,
            "oralcommunication": 3,
            "writing": 4,
            "reading": 4,
            "learning": 4
        },
        "units": [
            "BSBWRT401",
            "BSBSUS401",
            "BSBRSK401",
            "BSBADM301"
        ],
        "id": "57cf74e12e3d91ef586e1b75"
    }

LEARNER SUMMARY REPORT

/api/[deployment]/v1/learnersummary

This endpoint can be used to generate the learner results summary report for a specific learner.  The report is generated and a URL link to the report is returned.

GET

The learnerId parameter is required on this request.  

Name Type Use
learnerId UUID The unique identifier of the record
IMPORTANT NOTE: this is the inviteCode field returned from the GET Learners endpoint

Examples:

https://api.lln.training/api/testing/v1/learnersummary?learnerId=9875687a-8417-49c6-8da3-5d3c8479a71a

Result format

The response is an array but will only include a single entry.  The object returned simply has one property “file” which is the URL of the document that can be downloaded from AWS.

Example object;

    {
        "file": "https://s3-ap-southeast-2.amazonaws.com/static.lln.training/zapier/testing/9875687a-8417-49c6-8da3-5d3c8479a71a_summary"
    }

LEARNER REPORT

/api/[deployment]/v1/learnerreport

This endpoint can be used to generate the LLN report for the learner results and any supplements required based on a corresponding course.

GET

The learnerId and courseName parameters are both required on this request. 

Name Type Use
learnerId UUID The unique identifier of the record
IMPORTANT NOTE: this is the inviteCode field returned from the GET Learners endpoint
courseName String Course Name – must match a course name that exists in your deployment, eg. as returned from the Courses endpoint.

Examples:

https://api.lln.training/api/testing/v1/learnerreport?learnerId=9875687a-8417-49c6-8da3-5d3c8479a71a&courseName=Warehousing Operations

Result format

The response is an array but will only include a JSON object which includes a link to the report document and supplements (if applicable).

Example object;

   {
        "file": "https://s3-ap-southeast-2.amazonaws.com/static.lln.training/zapier/testing/9875687a-8417-49c6-8da3-5d3c8479a71a_Warehousing Operations",
        "supplementLink": "https://api.lln.training/testing/supplement/d243a0db-4875-46dd-bfee-a5df214f3975"
    }

Still need help? Contact Us Contact Us