Setting Up Automated HR Import in Totara

Totara’s HR Import automates user provisioning from CSV files via SFTP, supporting delta or complete imports of users, organizations, positions, and job assignments. This guide covers setup, custom profile field mapping, and transitioning from manual testing to fully automated imports.

Assumptions

This guide assumes:

• The customer has an external system from which they want to import data into Totara.
• They can provide CSV files through SFTP in an automated way (we do not cover any other data sources for HR Import in this guide yet).

If the integration architecture calls for direct API calls rather than file transfer — or if you’re integrating with a Moodle installation alongside Totara — see Moodle Web Services and REST API Integration: A Practical Guide.

Terminology

• Element: determines which type of data can be imported — Job assignment, Organisation, Position, and User.
• Source: for each element, you can configure a data source. For example, the User element can be fed from a CSV file or an external database.
• SFTP: Secure File Transfer Protocol, used to copy files from one host (e.g., a web server) to another over the internet.
• Public–private key pair: to provide secure, passwordless access to the SFTP server, ask the customer for their public SSH key and add it to the .ssh/authorized_keys file on the web server. Their private key handles encryption on their end.

Provide Sample CSV Files and Documentation

Most customers ask for an example of the CSV files. Use spreadsheets to list the column headers and provide a row of sample data. Also add a clearly delineated row of documentation (explaining the data types, uniqueness requirements, and so on).

If the site is using any custom profile fields, you must adapt the sample CSV files and documentation accordingly. Here is an example: Kiwa – HR Import Samples Plus Instructions.

The file names for automated HR Import should be:

• Users: user.csv
• Job assignments: jobassignment.csv
• Organisations: org.csv
• Positions: pos.csv

Ask for a Public SSH Key for SFTP

In this scenario, the customer will set up an automated process to upload their CSV files to the Totara web server via SFTP. To make this easy and safe, ask them to send over their public SSH key and add it to the .ssh/authorized_keys file (or ask the system administrator to do this).

Since we don’t know anything about the customer’s system (and don’t want to), we’re not going to explain how to set up an automated upload process or how to generate a public–private key pair.

Configure HR Import

In this section, we’re going to configure HR Import for the customer’s data. One important note: don’t automate the import yet. Test manually first (see Test the Customer’s CSV Files), then switch to automation (see Automate the HR Import).

Delta vs. Complete Import

It is worth understanding what happens when you set “Source contains all records” to “Yes”. This is not spelled out explicitly in the documentation, but combining the various descriptions, the behavior is as follows:

• Users who are present in Totara but missing from the source file will be removed.
• What removed means depends on your “Allowed HR Import actions” > “Delete” setting: keep, suspend, or full delete. A full delete removes all user data, including associated records (grades, appraisals, etc.).
• The recommended setting is suspend rather than full delete.
• If you are only importing a delta, include a deleted column in your source file (0 for retained users, 1 for users to be removed).

The following is documented: for the source user, there is a timemodified field. The documentation states:

If you want records to be updated every time an import is performed and not take the Unix timestamp value into account, you can specify a zero (0) value for this field. This will effectively force HR Import to import the data every time and ignore changes in Unix timestamp values.

Check the Customer's SFTP Upload of the CSV Files

The goal here is twofold:

• Make sure that the CSV files were transferred to the correct directory on the web server (a directory that must also be readable by Totara).
• Check the format of the CSV files.

Format of the CSV Files

Check the uploaded CSV files against the documentation and samples you provided earlier. Keep a sharp lookout for custom profile fields. These must have a column header in the following format: customfield_[shortname] (replace [shortname] with the actual short name, without brackets).

Test the Customer's CSV Files

If the CSV files are present on the web server and their formatting is correct (see the previous section), test the actual import. Use a test version of Totara to do this.

Automate the HR Import

Scheduling uses the totara_coretasktool_totara_sync_task scheduled task. HR Import expects the following folder structure on the server:

path-to-totara/csv/ready/
path-to-totara/csv/store/

In the HR Import settings, set the files directory to the root of this structure (i.e., path-to-totara, without the csv/ready suffix). Totara appends csv/ready automatically.

Place CSV files in the ready folder before each scheduled run. After the import completes, Totara moves them to the store folder and appends a Unix timestamp to each filename. The store folder is created automatically on the first run; if Totara lacks permission to create it, create it manually beforehand.

Agree with the customer on a retention policy for files in the store folder.