User provisioning via CSV

In many cases, users can be provisioned to your learning platform from another system, such as an HR system. This can be used to create and maintain users, job roles, custom profile fields, and entities. To investigate how this could work for your organisation, please talk to your Learning Pool contact. 

Authentication

Learning Pool will provide you with a URL for the SFTP server along with a username and password for transferring the file. If you would prefer to use SSH, let your Learning Pool contact know.

Using a CSV

If you are using a CSV to provision users you'll be provided with a template. Here's a list of the columns that you can / need to fill in:

Column	Description	Required	Type
userId	This is the unique identifier for the user. It is often the HR ID of the employee from the external system.	Yes	User
username	This is the username that the user will use to log in. This must be unique to the user.	Yes	User
firstName	The user's first name.	Yes	User
lastName	The user's last name.	Yes	User
email	The user's email address. This is used for password resets etc so needs to be a working email address.	Yes	User
country	The 3 digit ISO country code.	No	User
timezone	Enter a supported PHP Timezone. This field will default to Europe/London. Click here to read more about valid timezones.	No	User
language	Enter a valid language code here. Click here to read about valid language codes in the LXP.	No	User
expiresAt	Enter a date string in the format:  YYYY-MM-DD HH:MM:SS For example: 2017-10-06 14:51:38 This marks the user as expired / inactive from the date specified. Note: Entering a year after 2037 will not work.	No	User
orgFrameworkId	The ID / Name of the Organisational Framework that the employees Job Assignment is part of. Click here to read more about frameworks.	Yes - If adding a Job Assignment	Framework
orgLevelId_**	To map a user's Role / Job Assignment to the correct level in the Organisational Hierarchy, all Organisation Levels must be provided in the CSV.  Add two columns for each level: orgLevelId_** and orgLevelName_** The asterisks should be replaced with your ID and Name, e.g. orgLevelId_ The last Org hierarchy node pair (ID and Name) in a CSV row must be the Org Hierarchy node to associate with the Users Job Role.	No	Framework / Job Role
orgLevelName_**	See the section on building Organisation and Position Hierarchies further down in this article.	No	Framework / Job Role
positionFrameworkId	The ID / Name of the Positional Framework that the employees Job Assignment is part of.	No	Framework
positionLevelId_**	To correctly map the user's Role / Job Assignment to the correct level in the Positional Hierarchy, all Position Hierarchy Levels must be provided in the CSV down as far as the level the Job Assignment is situated . To add levels to the CSV, add two columns for each level (positionLevelId_** and positionLevelName_**) The last node Org hierarchy node pair (ID and Name) in a CSV row, is taken as the Org Hierarchy node to associate with the Users Job Role.	No	Framework / Job Role
positionLevelName_**	See section below on building Organisation and Position Hierarchies	No	Framework / Job Role
jobAssignmentId	The ID of the user's job assignment. If the job assignment does not currently exist, it will be created. This value is unique to each user.	Only needed when multiple jobs per user required	Job Role / My Team
jobAssignmentName	The name of the user's job assignment.	Yes (If adding a Job Assignment)	Job Role / My Team
startDate	Enter a date string in the format:  YYYY-MM-DD HH:MM:SS For example: 2017-10-06 14:51:38 This is the start date of the user's employment within the current Job Assignment. Note: Entering a year after 2037 will not work.	No	Job Role
endDate	Enter a date string in the format:  YYYY-MM-DD HH:MM:SS For example: 2017-10-06 14:51:38 This is the end date of the users employment within the current Job Assignment. Note: Entering a year after 2037 will not work.	No	Job Role
managerId	The userId of the manager. The manager must previously have been added to the LXP for this to work.	No	Job Role / My Team
managerJobAssignmentId	The id of the manager's job assignment.	Only needed when multiple jobs per user required	Job Role / My Team
customField_xxxxx	All fields that are not part of the core user data can be added as Custom Fields. To add a custom field to the template, simply prefix the column header with ‘customField_’. Note: The custom fields must already have been configured in the LXP (click here to read more about custom fields.)	No	User
deleted	This is used to either restore or delete a user. Do not use it for any other purpose at any other time. Enter a boolean value of 0 (restore) or 1 (delete). This indicates whether or not the user should be marked as deleted in the LXP. Alert: Do not set when creating a user for the first time.	No	User
orgRef	String value. Populates the Org Ref property for the LXP user.	No	User
viewProfile	Boolean value (0 or 1) indicates whether the user's profile is visible to others.	No	User
disableManualLogin	Boolean value (0 or 1) indicates whether the user is allowed to login manually (not via SSO).	No	User
leaderboardOptOut	Boolean value (0 or 1) indicates whether the user should be opted out from the leaderboard functionality on the LXP.	No	User

Building the Organisation and Position Hierarchies

The Organisation Hierarchies and Position Hierarchies exist beneath the Organisation Framework and Position Frameworks.

Organisation Hierarchy

The Organisation Hierarchy will generally start with the organisation's name at the top and it will continue down to the individual stores / offices (or lowest hierarchy level). Below is an example of an Organisation Hierarchy underneath an Organisation Framework named Acme:

In this example, the top level is the Organisation Framework and the bottom tier is actual stores. If we had a user [e-mail] and he worked in the store in Operations in Store-001 in China, these are the columns and values that would be needed in the CSV:

COLUMN TITLE	VALUE
orgLevelId_1	AS1
orgLevelName_1	Asia
orgLevelId_2	AS1-Ops
orgLevelName_2	Operations
orgLevelId_3	CH-Marketing
orgLevelName_3	China
orgLevelId_4	ST-001
orgLevelName_4	Store-001

The ID column values are used to uniquely identify the Organisational Level / Tier.

Note: The Organisation Level Name can, in some cases, be the same as the actual Organisation Level ID. This will only work if the level name is unique within the Organisation Framework.

Position hierarchy

The Position Hierarchy differs from the Organisation Hierarchy in that it is concerned with actual positions within the Organisation. These hierarchies could start from a member of the C-Suite (normally CEO) and continue right down to the most junior positions in the company. The example below begins with a Position Framework named Acme and illustrates the company's Position Hierarchy:

If we were to add a user whose position is Senior Engineer within the development team, we would require these columns:

COLUMN TITLE	VALUE
positionLevelId_1	CEO
positionLevelName_1	CEO
positionLevelId_2	CTO
positionLevelName_2	CTO
positionLevelId_3	Dev-Manager
positionLevelName_3	Development Manager
positionLevelId_4	SSE
positionLevelName_4	Senior Engineer

Note: The Position Level Name can be the same as the actual Position Level ID, so long as it is unique within the Position Framework.

Removing / Clearing values for previously populated data

This provisioning process will only update fields for which values are provided in the CSV. Meaning if a cell is left blank for a user in a field's column in the CSV file, this will not have any effect on that user's field. It will not be modified from it's current state.

If the need arises to clear the value from a user's field. This can be done by explicitly entering null as the value in the cell. This will remove any existing value in the field for the user.

For example, a common scenario takes place when an employee takes a long term absence. Typically, a customer may mark this user as expired temporarily but setting the expiresAt value for the user to the start date of their absence.

However, when the user returns to work, the customer would like to re-enable the user by removing the value for expiresAt for that user. It is important to note that leaving expiresAt cell blank for the user will not have any effect on the value of that field. Rather, the customer must place the text null (lowercase) into the cell - this will be respected and seen as an update to null out the the value.