Users import

OpenLMIS enables bulk creation/updating of users and user roles through file imports. 

1. How to import user data?

2. How to import user roles data?

How to import user data?

1. Create a file named user.csv

2. Ensure the file contains the following column headers:

   1. username - username

   2. firstName - user’s first name

   3. lastName - user’s last name

   4. email - user’s email

   5. isEmailVerified - determines whether email is already verified

   6. phoneNumber - user’s phone number

   7. jobTitle - user’s job title

   8. homeFacilityCode - user’s home facility code

   9. timezone - user’s timezone code

   10. isActive - determines whether the user is enabled/disabled. Possible values: true or false

3. Save this file with the name user.csv. It must be in .csv format.

4. Create a .zip file containing the user.csv file. The .zip file name does not matter.

5. Example file might look like this:
   
   

   Open

   

6. Go to the Administration panel and select Data Import

7. Select Users from the drop-down menu.

8. Click Select File and choose your .zip file created in point 4.

9. Click the Import button located at the bottom-right corner of the page.

10. A panel will appear with an import summary. You will see information with import results like how many entries have been saved, how many have not been saved and any error information that occurred during import. 
    
    

1. User password - we do not provide the password in the .csv file to avoid providing sensitive data in an open manner. Passwords for each user are set automatically. The default password is: password - but it is a configurable variable and can be changed in environment variables (USER_IMPORT_DEFAULT_PASSWORD). Default password is set automatically for new and existing users. After the importing process, the user should change the password to his own.

2. Data overwriting for existing users - please be aware that if you do not provide all user’s data in .csv file then existing data will be overwritten by data from file. For example if you already have a user with username diego1 and this user has 111222333 phone number and you provide an empty phone number in the file for this user, then this empty phone number will be saved in the user's contact details.

3. File pre-validation - before the import process input file is validated - there are some pre-checks performed:

   1. It checks if any file entry does not have mandatory fields - username, firstName or lastName

   2. It checks if file does not contain any duplicated username or email

   3. It checks if all emails have correct format

   4. It checks if any of following: username, email, phoneNumber, timezone, jobTitle does not exceed maximum length of characters (255)
      
      If any of the above fails, the user will get an information message about what went wrong. The user must correct the file content and perform the import again.
      
      

How to import user roles data?

1. Create a file named roleAssignment.csv

2. Ensure the file contains the following column headers:

   1. username - username for which roles will be added

   2. roleName - name of role

   3. programCode - code of program

   4. warehouseCode - code of facility

   5. supervisoryNodeCode - code of supervisory node

   6. type - role type. Possible values: supervision, fulfillment, direct

3. Save this file with the name roleAssignment.csv. It must be in .csv format.

4. Create a .zip file containing roleAssignment.csv file. The .zip file name does not matter. You can create .zip file with both files - user.csv and roleAssignment.csv - it will create users first and then their roles.

5. Example file might look like this:

   Open

   

6. Go to the Administration panel and select Data Import

7. Select Users from the drop-down menu.

8. Click Select File and choose your .zip file created in point 4.

9. Click the Import button located at the bottom-right corner of the page.

10. A panel will appear with an import summary. You will see information with import results like how many entries have been saved, how many have not been saved and any error information that occurred during import. 
    
    

1. Data overwriting for existing users - please be aware that all user’s roles are cleared before adding roles from file so all existing user’s role will be replaced by the roles from .csv file.

2. File pre-validation - before the import process input file is validated - there are some pre-checks performed:

   1. It checks if any file entry does not have mandatory fields:

      1. username, roleName - these fields can have any value but can not be empty

      2. type - this field can not be empty and must have only one of possible values: supervision, fulfillment, direct

   2. It checks if any file entry of supervision type does not have programCode field blank (supervision role requires program)

   3. It checks if any file entry of fulfilment type does not have warehouseCode field blank (fulfillment role requires warehouse)

3. Validation during import process - during import process system checks other basic information like:

   1. user with provided username exists

   2. role with provided roleName exists

   3. program with provided programCode exists

   4. facility with provided warehouseCode exists

   5. supervisory node with provided supervisoryNodeCode exists

   6. some roles are not acceptable for given role type

   7. not needed values provided will be ignored - e.g. if we provide programCode for fullfilment role or warehouse for supervision these values will be ignored because are not valid for these roles
      
      If any of the above fails, the user will get an information message about what went wrong. The user must correct the file content and perform the import again.