Explained: Automated Bulk User Import – Civica Learning

Introduction

Civica Learning enables you to perform automated user imports, which you can use to schedule user imports on a regular cycle. This guide explains what you need to do to use the automated user import feature.

Import File

First, you need a file that contains the user information you would like to add to your Civica Learning. Ideally this file is in a compatible format with the CSV file used within your Civica Learning administration portal.

Note: You can download a template CSV file to specify the users to be imported. To do this, in the Administration Portal, on the the Users | Import users page, click download the template file. You can also test your import file manually using the Import users option. Further information on manually bulk importing users is available here.

FTP

After you are happy that you have a correctly formatted file, you need to upload the file to an FTP server.

Civica Learning provides an FTP server, secured using either SFTP or FTPS, which you can use to upload your file:

ftp-<region>.portal-agylia.com

Region can be either eu or us, for example, ftp-eu.portal-agylia.com.

Note: Only the EU site is available at this time.

You should get in contact with Civica Learning support so we can create you an FTP user for your lms. The user name for your FTP account will be the first part of your Civica Learning Administration Portal hostname, for example, if your hostname is example.admin-agylia.com your user name will be example. The password for your FTP account is your API Key. You can find your API Key from your Admin portal (Settings | Advanced | API Key).

Example

The following example shows how to connect to the EU Civica FTP site, with the user name example and the password 9c52047e63db436bf0b990e6910d71aedf32656ef23, by using the lftp command line tool:

$ lftp ftp-eu.portal-agylia.com
lftp ftp-eu.portal-agylia.com:~> login example 9c52047e63db436bf0b990e6910d71aedf32656ef23
lftp example@ftp-eu.portal-agylia.com:~> ls
drwxr-xr-x    2 0        0            4096 Aug 22 16:51 log
drwxr-xr-x    2 1000     1000         4096 Aug 22 15:39 reports
drwxr-xr-x    2 0        0            4096 Aug 23 08:49 tmp
drwxr-xr-x    2 1000     1000         4096 Aug 22 17:07 uploads
lftp example@ftp-eu.portal-agylia.com:/>

Uploading files

You must upload your user import CSV file into the /uploads folder. The file must be called user-import.csv. You should overwrite this file each time you want to perform a user upload.

The job that processes the upload runs once a day at midnight UTC by default. However, please let us know if you would like to change this scheduling. The import job only processes uploads that have not been processed before, so don't worry about leaving the file on the FTP server.

Note: The import job creates a SHA1 hash of the upload file and places the hash in your /tmp folder; this is how the import job knows if it has processed that version of the user-import.csv file before. Therefore, if you want retry an import, simply remove all the SHA1 hash files in the folder.

The import job writes to the /log/user-import.log as it processes your import file, so you can look at this file to see if everything worked as expected with the upload.

Note: The log file does not contain detailed information about the processing of the user records within the file. This information is sent by email after Civica Learning has processed all the users.

The import process runs in the context of a nominated administrator account. We recommend creating a global admin user for this specific purpose, for example, a user called FTP User. The email address associated with this user will receive the email notifications from Civica Learning, including a status report, on completion of the bulk processing. The status report contains a record by record indication of success for each user update. The import job needs to know the identity (but not the password) for your selected administrator account. Please let us know which account you’d like to use and we will update the import job for you.

Summary

In summary, to successfully set-up user imports you need to:

Let us know you'd like use the user import feature (so we can provision you an FTP User)
Let us know which global administrator account to act as (so you can receive email updates)
Copy a user-import.csv file to the /uploads folder (so we process your users)

If you need any help or have any questions please contact Civica Learning support, we're happy to help.

Related

Explained: Batch user CSV files