Importing Employees from an Excel or CSV File

Importing employees lets you add a large number of employees and users at once from an Excel or CSV file, instead of adding each employee from the form. It is usually used when starting to work on the system or moving employee data from another system.

This guide explains preparing the file, the accepted values in each column, the import steps, what the system creates afterward, and the error messages and their solutions.

Before You Start

• First add the data the employees will be linked to: branches, Roles, departments, designations, employment types, employee levels, shifts, and leave policies. The import doesn’t create any of them, and a row containing a value that doesn’t exist fails.
• Make sure of your plan balance; each User counts toward the number of users, and each Employee counts toward the number of employees.
• The import is for adding new employees. To edit the data of an existing employee, edit it from its page.

Preparing the Import File

Allowed files: csv, xls, and xlsx. Download the sample file from Download Sample on the import page; the sample file differs according to whether the HR app is enabled, and with it enabled, the job and attendance columns appear.

• Each row in the file = one employee.
• Write the dates in the date format set in your account (the sample file uses day/month/year).
• Write the fixed values exactly as in the following table, such as User, Employee, Yes, and No.
• Don’t use the question mark (?) in any cell; the system considers it a corrupted character and rejects the row.
• Save the CSV file with UTF-8 encoding so Arabic names appear correctly.

Fields and Accepted Values

Basic Data

Column in the sample file	System Field	Required	Accepted values
Employee Code	Code	Yes (map the column)	The employee code. Leave it empty for the employee to take the next number in auto numbering.
Type	Type	Yes	User (a user who can log in to the system) or Employee (an employee). In English only.
First Name / Middle Name / Last name	First Name / Middle Name / Last Name	First Name only	The employee name consists of the three.
Email Address	Email Address	Yes	Not repeated in the file or with an existing employee.
Can Access System	Can Access System	No	Yes or No (or 1 and 0).
Send Credentials to Employee Email	Send Credentials to Employee Email	No	Yes to send the login details to the employee email.
Display Language	Language	Yes	Arabic or English.
Role	Role	No	The role name as in Roles.
Branch	Branch	No	The branch name. If empty, the current branch is used.
Accessible Branches	Accessible Branches	No	Branch names separated by commas. For users only.
Country	Country	Yes	The country name in English, such as Saudi Arabia or Egypt. A country code such as SA is not accepted.
Citizenship Status	Citizenship Status	No	Citizen or Resident.
Mobile Number / Phone Number	Mobile Number / Phone Number	No	Free text.
Official ID Number	Official ID Number	No	Not repeated in the file or with an existing employee.
Present / Permanent Address	Present Address / Permanent Address	No	The city, postal code, and address text.
Notes	Notes	No	Free text.

Job and Attendance Data (with the HR app)

Column in the sample file	System Field	Required	Accepted values
Birth Date	Birth Date	Yes	A date in your account format.
Join Date	Join Date	No	A date in your account format.
Designation	Designation	Depending on the settings	The designation name as in the system.
Department	Department	Depending on the settings	The department name as in the system.
Employment Type	Employment Type	Depending on the settings	The employment type name as in the system.
Employee Level	Employee Level	Depending on the settings	The level name as in the system.
Direct Manager Code	Direct Manager	No	The manager code, not their name. It can be an employee in a previous row of the same file.
Attendance Shift	Attendance Shift	No	The shift name. With the Attendance app.
Leave Policy	Leave Policy	No	The policy name. With the Attendance app.
Attendance Restrictions	Attendance Restriction	No	The restriction name. With the Attendance app.

Import Steps

1. Open Import Employees.
2. In CSV / Excel File, choose the file.
3. For CSV files, choose the Delimiters: usually Comma Separated ( , ), or Semicolon Separated ( ; ), or Tab Delimited. This field doesn’t appear for Excel files.
4. Enable Import First Row only if the first row is data and not column headers.
5. Click Next Step.
6. In Fields Mapping, for each System Field, choose the matching column from Corresponding Field in File. The system automatically matches the columns with the same name; review the matching, especially the Type and Gender fields, because they have the same name in the Arabic interface.
7. Enable Ignore errors while importing to import the correct rows and skip the wrong ones. Without it, the import stops at the first wrong row and no employee is imported.
8. Click Import, and wait for the Results screen.

How Does the System Handle the File Data?

Data	Search method	If not found
Code	An empty code takes the next number in numbering, and a written code is used as is.	—
Branch, Role, department, designation, employment type, level, shift, and leave policy	By name (case-insensitive) or by ID.	The row fails; it is not created automatically.
Country	By the English country name.	Fails the row.
Direct Manager	By the employee code.	Fails the row.
Accessible Branches	By the branch names.	Fails the row.

Results Screen

• The message Thank you, your file has been imported successfully appears, along with with the following errors. and the list of errors, if any.
• Three counters appear: Imported successfully. and Updated successfully. and Records failed to import.
• Always review the counters and errors, because the message appears even if all rows fail.
• Correct the failed rows and import them alone in a new file, so employees are not duplicated.

Impact on the System

Place	What happens
Employees	Each employee is added to Employees with an Active status.
System login	A user with login permission can log in with their email. When you choose Yes in sending the login details, the login details are sent to them by email.
Job data	The job and attendance data is saved with the HR app.
Numbering	The employee code numbering advances.
Plan	Employees and users count toward the plan limits; rows that exceed them are not imported.
Activity Log	Adding each employee is recorded.

The import doesn’t create roles, departments, or branches, nor contracts, salaries, or accounting accounts for employees.

Error Messages and Solutions

Some employee messages appear in English, as shown in the table.

Message that appears	Cause	Solution
Invalid Data, Missing required field or does not exist (field) at row #(number)	A required field is empty.	Complete the value.
Invalid Data, Wrong Relation (value) at row #(number)	A branch, role, department, designation, or country doesn’t exist.	Write the name exactly as in the system, or add it first. The country is in English.
Invalid Employee Mode value “(value)” at row #(number). Accepted values are User or Employee.	The type value is incorrect.	Write User or Employee in English.
Email address “(email)” is duplicated in the import file at row #(number).	The email is repeated in the file.	Give each employee a different email.
Email address “(email)” at row #(number) already exists in the system.	The email is used by an existing employee.	Use another email.
Official ID “(number)” is duplicated in the import file at row #(number).	The ID number is repeated in the file.	Correct the number.
Official ID “(number)” at row #(number) already exists in the system.	The ID number is registered to another employee.	Correct the number.
Direct Manager not found (Code: (code)) at row #(number).	The manager code doesn’t exist.	Write the manager code, and put the manager row before their employees if it is in the same file.
Branch not found: “(branch)” at row #(number).	A branch that doesn’t exist in the accessible branches.	Write the branch names exactly as in the system.
You have exceeded your available slots. Please increase your limit to import this employee.	The number of users or employees in the plan is exceeded.	Upgrade the plan or reduce the number of rows.
Invalid Data, Data must be in the correct date format in ‘(field)’ field at row #(number)	A date in the wrong format.	Write it in the date format set in your account.
Invalid Data, encoding issue or corrupted characters in field (field) at row #(number)	The file is not UTF-8 encoded, or a cell contains the ? mark.	Save the file as CSV UTF-8 and delete the question marks.
Sorry, it is not allowed to import one column file, make sure you have selected a file with the correct format	The delimiter is incorrect.	Choose the suitable delimiter, such as Semicolon.
CSV columns count is not the same through all file rows	Rows with a different number of columns.	Make the columns the same in all rows.
The uploaded file could not be processed. Please ensure it is a valid XLS, XLSX, or CSV file and try again.	An unsupported or corrupted file type.	Save it again as xlsx or csv.
You are not allowed to access this page	You don’t have both the add and edit permissions.	Ask the account manager for the permissions.

FAQs

What is the difference between User and Employee in the Type column?

User is a user who can log in to the system and counts toward the number of users, and Employee is an HR employee and counts toward the number of employees.

Are login details sent to employees?

Yes, if you write Yes in the Send Credentials to Employee Email column.

Can the data of existing employees be updated by import?

No, the import is for adding new employees; edit the existing employee from its page.

Does the import create departments and designations that don’t exist?

No, add them first, then import the employees.

Why did the row fail even though I wrote the country?

Because the country is written by its English name, such as Saudi Arabia, not by its code or in Arabic.

How do I set the direct manager?

Write the manager code in the Direct Manager Code column.

Can salaries be imported?

No, salaries are added from contracts, and they have a separate import.

Why did Arabic names appear as symbols?

Because the file is not UTF-8 encoded; save it as CSV UTF-8 or upload an xlsx file.