You're looking at an older version of Totara Learn.

Please see Totara 13 help for the latest version.

All pages




Search

The source refers to the data being imported into Totara Learn and should be configured for each enabled element prior to importing any data. A Site Administrator can configure source settings for a specific element.

  1. Go to Site administration > HR Import > Sources.
  2. Select the element name.
  3. Select the source option (either CSV or External database). 
  4. Configure the settings accordingly.
  5. Click Save changes

CSV 

You can configure options related to the incoming source data.

SettingDescriptionNotes
CSV file encoding

This option allows you to select the encoding for the CSV file. The default is 'UTF-8' but this can be changed.  

Source file encoding will be converted to the target database encoding providing the correct encoding for the source has been chosen for this setting.
Delimiter

This field allows you to select the delimiter used in the CSV file. Options include:

  • Comma (,)
  • Semi-colon (;\)
  • Colon (:\)
  • Tab (\t)
  • Pipe (|)
-
Fields to importDecide which fields you would like to import. The fields available in this section varies depending on the element. See Fields to import for more information.
Field mappingsAllows you to enter the column title for each field if these vary from the default. The fields available in this section varies depending on the element.See Field mappings for more information. 

File details in configure CSV source

External database 

Configure the settings for importing from an external database, including entering the external database connection details.

SettingDescriptionNotes
Database type

The database type e.g. MySQL or PostgreSQL.

Options that appear in the Database type dropdown are dependent on what database drivers have been setup in your php.ini file.
Database name

The name of the database you are connecting to.

-
Database hostname The database hostname e.g. 'localhost'-
Database userThe user account that has the appropriate database access privileges.-
Database passwordThe user account password.-
Database portThe port id number of the database-
Database tableThe name of the database table that contains the element data.-
Fields to importDecide which fields you would like to import. The fields available in this section varies depending on the element. See Fields to import for more information.
field mappingsAllows you to enter the column title for each field if these vary from the default. The fields available in this section varies depending on the element.See Field mappings for more information. 

Click the Test database connection button to verify that the details were entered correctly and a connection can be made.

The use of empty strings in your external database will delete the field's value in your site. Null values in your external database will leave the field's current value in your site.

Specific external database source settings.

Select fields for import

Both sources include the Fields to import section. For each element, there are mandatory default fields that need to be included and there are additional optional fields that can be imported. Tick the checkbox next to each field that will be included in the source.

The fields available for each element are:

Organisation

These are the mandatory and optional fields available:

FieldDescriptionNotes
idnumber

A unique identifier that must be specified for each record being imported.

Mandatory field.

fullname

The full name of the organisation item being imported e.g. 'Head Office'.

Mandatory field.

frameworkidnumber

The ID number of the framework the organisation items are being imported to.

Mandatory field.

You need to create your organisation framework and specify an ID number prior to import. If not, HR import will not know where to import the organisation data to and this will result in an error during import.

timemodified


A Unix timestamp that confirms the last time a user's details were changed.


Mandatory field.

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.

deleted

If Source contains all records is set to No, the deleted flag must be provided. In your source, specify the value 1 if a user is to be deleted or the value 0 to create or update the user. 

Mandoatory field.
shortname

The position short name.

Optional field. Must have Display hierarchy shortnames enabled in Advanced features
description

The position description.

Optional field.
parent

The ID number of the position's parent item. This is useful if you want to create sub-items, or children, of a position.

Optional field.
typeThe ID number of any position types you may have created. Note that only one type per item may be specified.Optional field.

Position

There are a number of both mandatory and optional fields that are available, these are:

FieldDescriptionNotes
idnumber

A unique identifier that must be specified for each record being imported.

Mandatory field.

fullname

The full name of the position item being imported e.g. 'CEO'.

Mandatory field.

frameworkidnumber

The ID number of the framework the position items are being imported to.

Mandatory field.

You need to create your position framework and specify an ID number prior to import. If not, HR import will not know where to import the position data to and this will result in an error during import.

timemodified

A Unix timestamp that confirms the last time a user's details were changed.


Mandatory field.

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.

deleted

If Source contains all records is set to No, the deleted flag must be provided. In your source, specify the value 1 if a user is to be deleted or the value 0 to create or update the user. 

Mandatory field.

shortname

The position short name.

Optional field. Must have Display hierarchy shortnames enabled in Advanced features

description

The position description.

Optional field.
parent

The ID number of the position's parent item. This is useful if you want to create sub-items, or children, of a position.

Optional field.
typeThe ID number of any position types you may have created. Note that only one type per item may be specified.Optional field.

User

Below is a lists the mandatory fields for the User source:

FieldDescriptionNotes
idnumber

A unique identifier that must be specified for each record being imported. It will not be possible to sync data for users who have been added manually and have not been assigned an idnumber. By assigning these manually added users with a idnumber it will then make it possible to sync their data by including them in the CSV sync file. In 2.5 and later versions you will also need to tick the HR import checkbox within a user's profile to allow them to be updated in the sync/import process.

Mandatory field.


This checkbox will only become visible in a users profile once you've enabled/clicked the eye-icon for the User import option in HR import > Elements> Manage Elements.

timemodified

A Unix timestamp that confirms the last time a user's details were changed.


Mandatory field.

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.

username

The username of the user being imported.

Mandatory field.
deleted

If Source contains all records is set to No, the deleted flag must be provided. In your source, specify the value 1 if a user is to be deleted or the value 0 to create or update the user. 

Mandatory field.
firstname

The first name of the user being imported.

Mandatory field.
lastname

The last name of the user being imported.

Mandatory field.
email

The email address of the user being imported.

Mandatory field.

There are a number of additional user profile fields that can be imported. Any custom user profile fields created will also be available.

When users are created using the CSV sync/import process and the password column is not included, a random password will be generated and will be sent to users in a welcome email. The user will then be required to change this password the first time they login. 

If you have set up a different authentication system such as LDAP this will be different and you'll need to include the "auth" column in the csv.

The following fields are important to be mindful of for mapping users to their appropriate organisation, position and manager.

  • Organisation: Specify the idnumber of the organisation item you wish to map the user to.
  • Position: Specify the idnumber of the position item you wish to map the user to.
  • Manager: Specify the idnumber of the manager user you wish to map the user to.

When making a user a manager of another user, the manager user is automatically granted the Staff Manager role permissions and will have the capability to manage their team members.

Job assignment

In the job assignment source if you don't update the CSV to give it a different timemodified (e.g. you leave it at the current entry) and then a user updates the job assignment manually (e.g. they change the job name by editing the job assignment itself) then that won't get overwritten on any following HR import run, until you change that number.

This differs from the other sources where if you were importing a user and decided to keep the timemodified as it was as well as not making any manual changes to the user, HR import won't try to update it. However, if you do update the user manually, it will be overwritten by HR import the next time that runs.

FieldDescriptionNotes
idnumberThis is the job assignment's id number.

Mandatory field.

In previous versions this was the jobassignmentidnumber field in the user source.

useridnumberThis is the id number for the user.Mandatory field.
timemodified

A Unix timestamp that confirms the last time a user's details were changed.

Mandatory field.

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.

deleted

This is required if Source contains all records is set to No.

Mandatory field.
fullname

The fullname of the job assignment.

This was jobassignmentfullname in the user source in previous versions.

startdate

The date the job assignment starts. This was jobassignmentstartdate in the user source in previous versions.
enddate

The date the job assignment ends.

This was jobassignmentenddate in the user source in previous versions.

orgidnumber

The organisation id number.-

posidnumber

This position id number.-
manageridnumber

The id number for the user that will be assigned as manager.

-
managerjobassignmentidnumber

The id number for the specific job assignment involved in the manager relationship.

This field is mandatory if manageridnumber is set to on and updateidnumbers is off (i.e. you're using more than just the first jobs).
appraiseridnumber

The id number for the user that will be assigned as appraiser.

-

Circular management job assignment loops

This occurs when a manager reports to themselves, this can occur when users are imported that have a manager assigned to them that they are the manager of further down the management hierarchy. For example:  User A has User B as their manager, User B has User C as their manager, User C has User A as their manager.  It is also possible with multiple job assignments to have a loop as follows. If you have two users A and B each with two job assignments 1 and 2, then you are allowed to have A1 > B1 > A2 > B2, but you couldn't then add > A1 at the end. This can lead to unexpected behaviour for management approvals and management reporting so needs to be prevented.

If a circular management is found when importing a manager with HR Import then none of the users forming the circular reference will have their manager assigned, with a notice explaining why.

To import the users identified as having a circular reference the records of the import file will need to be adjusted so the circular reference no longer exists. In the example above User C will need to have their manager changed from User A.

Field mappings 

The Field mappings section allows you to enter the column title for each field if you want to match the names of the columns that are being imported to the HR Import field names.

More often than not, the field names in the source data might not match the field names required by HR Import to import data. Field mapping is useful if another system is exporting the source data files or being connected to directly, so that HR Import knows what to look for in terms of fields and column names.


On this page

Related pages

The Totara Academy has a whole course dedicated to Creating users in Totara Learn.  Here you can learn more on how to add users, see best practice, and give it a go yourself.

Provide feedback about this page using the link in the bottom right of this page. 

Still have questions? Why not post them in the forums of the Totara Community?