User Uploads User Uploads

User Uploads

Mounika Vukkadam Mounika Vukkadam

User Uploads

Create a large amount of user accounts in the LMS.

You need to provide the data in a comma-separated list format. For example:

{ 
"csvdata": [
"username,email,firstname,lastname",
"testAPI.user@example.com,testAPI.user@example.com,Test,User"
]
}

Which is more easily readable as:

username email firstname lastname
testAPI.user@example.com testAPI.user@example.com Test User

 

Required Fields

The first row of the list must be a list of headers for the data set. These headers must include the following:

username,email,firstname,lastname

 

Optional Fields

There are 2 other columns that can be provided, that enable additional functionality.

The suspended field can be used to make existing users suspended, preventing them from logging into the system or appearing in reports. If a row has a suspended value, but the associated user does not yet exist in the system, they will not be created. If this column is included, the user will be suspended if the value is anything other than:

  • ACTIVE
  • FALSE
  • 0

The manager_username field allows for a manager/supervisor to be specified for a user. This will give the manager/supervisor access to a dashboard within the LMS, allowing them to run reports, enrol users, and more. All the features within this dashboard are limited to users that the manager/supervisor supervises.

{
"csvdata": [
"username,email,firstname,lastname,manager_username,suspended",
"testAPI.user@example.com,testAPI.user@example.com,Test,User,testAPI2.user@example.com,FALSE"
]
}

 

Custom Fields

Additional User Fields can be included as additional columns, which can be any name. These are useful if you want to report by additional information, or organise cohorts more efficiently. If a column is included in the file, does not match a Required or Optional Field, and an associated user field does not already exist, a new custom user field of type text will be created.

For example, if you wanted to provide additional 'Location' and 'Date Commenced' user fields, you can do so:

{
"csvdata": [
"username,email,firstname,lastname,Location,Date Commenced",
"testAPI.user@example.com,testAPI.user@example.com,Test,User,Canberra ACT,2019-09-26T07:58:30+00"
]
}

If request is complete:

If request is still processing:

{
"csvdata": [
"username,email,firstname,lastname,Location,Date Commenced",
"testAPI.user@example.com,testAPI.user@example.com,Test,User,Canberra ACT,2019-09-26T07:58:30+00"
],
"automatic": true
}

Automatic Suspension

The LMS can automatically suspend users when the following conditions are met:

  • The user has not been included in a user upload for over 90 days
  • The user has not logged into the LMS for over 90 days

To enable this functionality you can include the "automatic" flag in the API request:

{ 
"csvdata": [
"username,email,firstname,lastname,Location",
"testAPI.user@example.com,testAPI.user@example.com,Test,User,Canberra ACT"
],
"automatic": true
}

 

User Uploads:

Description
Creates or updates a large number of users.
Request Method POST
Request URL {{base_url}}/local/acorn_usermanagement/index.php/api/1/tenancies/{{tenancy_id}}/useruploads
Authorisation Header Bearer {api_key}

 

Request Body:

Parameter Data Type Details
requestid integer optional, if included the endpoint will return the status and results of the request with the specified requestid. If not included a new request will be submitted and its requestid will be returned
csvdata array required unless feedId is provided
emailSend boolean Setting this parameter to true will send any new users a welcome email with login instructions. If this email is not sent, then users will need to be provided their password some other way, or use Single Sign On to access the system.
sendNotifications boolean Setting this parameter to true will send any new users a welcome email with login instructions. If this email is not sent, then users will need to be provided their password some other way, or use Single Sign On to access the system. Along with this, users that have a valid international mobile number within the system will be sent an SMS notifying them of their account creation. This is reliant on the SMS Notification feature being turned on within the tenancy that the user is in.
feedId integer optional

 

Example Response without requestId included:

{ 
"requestid": 161,
"status": "Processing"
}

Example Response with requestId included:

If request is still processing:

{ 
"requestid": 161,
"status": "Processing"
}

If request is complete:


{

"status": "Complete",
"requestid": 161,
"data": {
"users": [
{
"id": 1,
"firstName": "Test",
"lastName": "User",
"email": "test.user@example.com",
"username": "test.user@example.com",
"lastAccess": 0,
"tenancyId": 1,
"suspended": 0,
"resetPassword": false,
"password": "",
"noCohortCalculation": true,
"updates": "",
"newstatus": "New User"
}
],
"totals": "1 records successful, 0 records unsuccessful ",
"message": "",
"success": true,
"failedRows": []
}
}

Example Error Response:

{ 
"status": "Failed",
"requestid": 433,
"data": {
"success": false,
"errors": "File contains unexpected headers, please upload a CSV file with headers starting with username,email,firstname,lastname"
}
}

Add comment

Please sign in to leave a comment.