Persona Imports
Represents a CSV import (typically from a HR system) containing persona identifiers and their attributes.
It is accessible through the following HTTP interfaces:
Connection HTTP Interface via http://www.example.org/api/connection/personasImport.
REST HTTP Interface via http://www.example.org/api/v2/personasImport.
To import a CSV via the API, you need to make the three requests below in order.
Create the persona import model via the REST HTTP Interface (http://www.example.org/api/v2/personasImport).
Upload the CSV via the Upload HTTP interface.
Process the persona import model via the Process HTTP interface.
Alternatively, you can create/update personas via the Persona Upsert HTTP Interface.
SCHEMA
Name | Description |
---|---|
_id | The id of this persona import model. |
organisation | The id of the organisation this persona import belongs to. |
owner | The id of the user that created the persona import. |
title | The title of this persona import. |
csvHeaders | An array of the header names from the CSV. |
structure | The structure of the CSV. |
importedAt | The date and time that the persona import was imported. |
csvHandle | The location of the CSV file in the storage provider. |
csvErrorHandle | The location of the CSV file with its errors in the storage provider. |
totalCount | Total number of data rows in the CSV. |
processedCount | Total number of processed data rows in the CSV. |
importErrors | An array of the errors in the CSV. |
result | The result of the import in terms of personas created and merged. |
EXAMPLE
{
"_id" : "59c1219936229d4ce9634601",
"organisation" : "59c1219936229d4ce9634602",
"owner": "59c1219936229d4ce9634603",
"title": "Example Persona Import",
"csvHeaders": ["Full Name", "Moodle User ID", "Moodle Home Page", "Age"],
"structure": {
"Full Name": {
"columnName": "Full Name",
"columnType": "COLUMN_NAME",
"relatedColumn": "",
"primary": null
},
"Moodle User ID": {
"columnName": "Moodle User ID",
"columnType": "COLUMN_ACCOUNT_VALUE",
"relatedColumn": "Moodle Home Page",
"primary": null
},
"Moodle Home Page": {
"columnName": "Moodle Home Page",
"columnType": "COLUMN_ACCOUNT_KEY",
"relatedColumn": "Moodle User ID",
"primary": 1
},
"Age": {
"columnName": "Age",
"columnType": "COLUMN_ATTRIBUTE_DATA",
"relatedColumn": "",
"primary": null
}
}
}
STRUCTURE
Defines the structure of the CSV and how it should be parsed. The structure property is stored as an object where the keys are the CSV column names and the values are objects that define the column structure (value object schema defined below).
SCHEMA
Name | Description |
---|---|
columnName | The name of the column in the CSV (CSV header). |
The type of the column or how it should be parsed. | |
relatedColumn | For account names this is the account home page column, for account home pages this is the account name column. |
primary | Defines the order in which identifiers should be used. |
COLUMN TYPES
Column Type | Description |
---|---|
COLUMN_NAME | Persona name. |
COLUMN_ACCOUNT_KEY | Persona identifier account home page. |
COLUMN_ACCOUNT_VALUE | Persona identifier account name. |
COLUMN_ATTRIBUTE_DATA | Persona attribute value. |
COLUMN_MBOX | Persona identifier mbox. |
COLUMN_MBOXSHA1SUM | Persona identifier mbox_sha1sum. |
COLUMN_OPENID | Persona identifier openid. |
UPLOAD HTTP INTERFACE
This interface uploads the CSV for the persona import model. Requests to this interface should look something like the request below.
POST http://www.example.org/api/uploadpersonas
Authorization: YOUR_BASIC_AUTH
Content-Type: multipart/form-data; boundary=YOUR_FORM_BOUNDARY
Content-Length: YOUR_CONTENT_LENGTH
--YOUR_FORM_BOUNDARY
Content-Disposition form-data; name="id"
Content-Length: YOUR_PERSONA_IMPORT_MODEL_ID_LENGTH
YOUR_PERSONA_IMPORT_MODEL_ID
--YOUR_FORM_BOUNDARY
Content-Disposition form-data; name="file"; filename="import.csv"
Content-Length: YOUR_CSV_CONTENT_LENGTH
Content-Type: text/csv
YOUR_CSV_CONTENT
--YOUR_FORM_BOUNDARY--
The interface will respond with a 200 response code when the CSV is successfully uploaded.
PROCESS HTTP INTERFACE
This interface starts the processing of the persona import. Requests to this interface should look something like the request below.
POST http://www.example.org/api/importpersonas
Authorization: YOUR_BASIC_AUTH
Content-Type: application/json; charset=utf-8
{
"id": "YOUR_PERSONA_IMPORT_MODEL_ID"
}
The interface will respond with a 200 response code, processing of the persona import will start shortly after the response is received.
PERSONA UPSERT HTTP INTERFACE
This interface provides API access to the function we use to process individual CSV rows in Persona Imports. Requests to this interface should look something like the request below.
The interface will respond with a response similar to the one below after it has created/updated a matching persona.
RETRIEVING CREATED/UPDATED PERSONA
To retrieve the persona that was created/updated in the previous upsert request, you can make the following request to the Connection HTTP Interface for Persona Indentifiers.
This will provide a response similar to the one below.
Learning Locker and the Squirrel logo are trademark of Learning Pool 2020 | Learning Locker is licensed under GPL 3.0.