Overview
The User Importer lets you create and update employee records in Rotageek in bulk from a file, usually sent from your HR or payroll system. It is mainly configured on the User Import Settings and User Import Field Mappings pages in the Admin Console.
Use the User Importer when you want an upstream system (HR/payroll) to remain the source of truth for people data (names, employee IDs, positions, locations, contracted hours, contact details and, optionally, leave allowances and pay rates).
Before setting up or changing a user import, decide:
Who is the source of truth for user data – HR/payroll vs manual maintenance in Rotageek.
Which field will be the unique identifier, usually a stable employee ID (CompanyID) rather than an email address.
How new starters, changes and leavers should behave – for example, whether leavers are end‑dated automatically when they drop out of the file.
How often files will be sent (daily, weekly, etc.)
Accessing User Import settings
Sign in to your Rotageek environment as an Admin.
Open the Admin Console.
Go to User Import Settings to configure how files are read and processed.
Go to User Import Field Mappings to control how file columns map to Rotageek fields.
File format and common fields
The User Importer typically reads a CSV file delivered via SFTP. The exact specification for your organisation is agreed during implementation, but commonly used fields include:
FirstName (required) – employee first name
Surname (required) – employee last name
CompanyID (required) – primary unique employee ID from HR
LocationID or Location (required) – store/site identifier (ID is preferred where available)
Position (required) – job title/position used for permissions and scheduling
ContractedHours – contractual weekly hours
Email_Primary – main email address for login, welcome and reset emails
EmployeeStartDate / EmployeeEndDate – employment dates (EU format, e.g.
31/01/25)HourlyRate – hourly pay rate for costing
AnnualLeaveAllowance and AnnualLeaveAllowanceEffectiveDate – entitlement and the date it takes effect
MaximumHoursPerWeek / MinimumDaysWorkedPerWeek / MaximumDaysWorkedPerWeek – optional working-time limits
ContractType / ContractTypeEffectiveDate – employment type and its effective date
PhoneMobile – mobile number
Tips:
Not every field needs to be used. Only include columns you intend to maintain in Rotageek via the import.
All support user import fields are found on Admin Console -> User Import Field Mappings
In Admin Console → User Import Settings, you control how the importer behaves. Key options include:
Below is a complete list of the User Import Settings as they appear on the page, with short descriptions:
Front Door Configuration Id – Internal identifier that links the import to your Rotageek/SSO front door configuration. Most customers do not need to change this.
Maximum hours per week – Upper limit on planned weekly hours, used for warnings and reporting where configured.
Working hours in a day – Default number of working hours in a standard day, used by some calculations and checks.
Minimum hours per day – Lower limit for daily hours; used in warnings where a day would otherwise be too short.
Maximum hours per day – Upper limit for daily hours; helps flag days that are longer than allowed.
Leave Request – Controls the default unit for leave requests (for example, days vs hours) for users created via the importer.
Contracted Hours – Default number of contracted hours applied when new users are created if the contracted hours are not included in the file.
Supervisor Positions – List of positions that should automatically be treated as Supervisor roles when they appear in the import file (where UserPermissionTypeId is not used).
Keyholder Positions – Positions that should be treated as keyholders for specific access/permissions where your configuration uses this concept.
Location Names to ignore – A list of location names in the file that should be skipped by the importer (for example, training or test sites).
Default Location – Fallback location assigned to new users if no valid location is provided in the file.
Default Position – Fallback position assigned to new users if no valid position is provided in the file.
Prefix for new Usernames – Optional text added at the start of system‑generated usernames created by the importer.
File inbound directory – SFTP folder where Rotageek looks for new user import files.
File archive directory – Folder where successfully processed files are moved so the inbound directory stays clear.
ShiftOffboardAction – What happens to future shifts and leave when a user is end‑dated by the import (for example, delete or move to gaps).
Scheduled hour in UTC – Time (in UTC) when the automatic import job runs to collect and process new files.
Send welcome emails – When enabled, new users with valid email addresses automatically receive welcome emails when they are created.
Location name is ExternalId – Tells Rotageek to treat the mapped location column as the external ID rather than the Rotageek location name.
Manually assigned supervisor – Protects manually assigned supervisor relationships so they are not overwritten by the import where supported.
End date user when not in file – When switched on, users who drop out of the file are automatically end‑dated (with Admins typically excluded).
Import by cluster – Allows one HR location to be mapped to multiple Rotageek locations using cluster names defined in your configuration.
Mapping file columns to Rotageek fields
In Admin Console → User Import Field Mappings:
Confirm that each column header in your file appears in the mappings list.
Map each header to the relevant Rotageek field (e.g.
AnnualLeaveAllowance,HourlyRate,CompanyID).Avoid mapping the same file column to multiple conflicting Rotageek fields.
If the header in the file does not match what is configured in Field Mappings, that data will not load (for example, a file column named Company ID will not populate CompanyID unless the mapping is updated).
Tip: If you change a column header in your HR report, update the User Import Field Mappings at the same time.
Running a user import
Prepare and upload the file
Generate the HR/people file in the agreed format and folder, e.g.
/Customers/CUSTOMERNAME/UserImport/.Ensure the file is not password‑protected and the encoding is standard (e.g. UTF‑8).
Use a consistent file naming pattern as agreed during implementation.
Once ready, place the file into the configured File inbound directory.
Run a manual import
From Admin Console → User Import Settings:
Check that File inbound directory and field mappings are correct.
Use Run manual import to process the file immediately.
Wait for the import to complete and check the status message.
Your implementation or support contact can help you locate processed and error files on the SFTP server if a run fails repeatedly.
3. Scheduled imports
In most live configurations, imports run on a schedule (e.g. nightly).
Your HR/integration team continues to send files to the same folder and naming pattern.
Rotageek processes each file at the configured time and updates users automatically.
What happens during an import
During each run, Rotageek:
Reads the input file from the configured inbound directory.
Matches records to existing users using the unique identifier
CompanyIDCreates new users if no existing match is found, using required fields such as
name, CompanyID, position and location.Updates existing users where a match is found, changing the mapped fields only.
Optionally end‑dates users who are missing from the file if End date user when not in file is enabled (excluding admins).
Applies your chosen ShiftOffboardAction to future shifts and leave for end‑dated users, without changing already signed‑off timesheets.
If welcome emails are enabled, newly created users with valid email addresses will receive login details automatically.
Best Practice
Exact matches for Location and Position Location and position values in the file must match what exists in Rotageek. Mis‑spelled names, extra spaces or missing locations/positions will cause users to fail to load.
Follow the expected date format All date fields (e.g. start/end dates, effective dates) should follow the EU format (DD/MM/YY or DD/MM/YYYY as configured).
Keep files and schedules predictable Use unique, timestamped filenames and a regular cadence (for example, daily or weekly) for file delivery to reduce confusion and make troubleshooting easier.
Treat “End date user when not in file” with care Only enable this behaviour once you are confident the file always contains all active users, and set a reasonable change tolerance to guard against partial files.
Don’t manually override HR‑managed users If your organisation uses the User Importer or API as the source of truth, manual changes on the People page may be overwritten by the next import. Make corrections in the source system first, then allow them to flow through the next file.
Check error files when something fails For users that don’t appear or don’t update as expected, check the processed and error files for that import run. Common issues include missing CompanyID, invalid location/position, or mismatched headers.
Frequently Asked Questions
Why did a user fail to load?
A user will fail to load if:
Required fields (such as CompanyID, Location / LocationID, or Position) are missing, or
The location or position does not exactly match what exists in Rotageek, or
The file failed validation (for example, incorrect date format or invalid mapping).
Check the user’s row in the processed file and any associated error file, then correct the data at source and resend a new file.
Does the User Importer automatically pro‑rate leave for new starters?
No. If you import a leave allowance, Rotageek uses the exact value provided. Any pro‑ration (e.g. based on start date or part‑time hours) must be calculated in your HR or payroll system before the allowance is sent in the file.
How do I re‑run a file after fixing an issue?
If your environment allows manual imports:
Move the processed file back into the main user_import (or equivalent) folder.
Rename it to remove any “processed” suffix in the filename.
Go to Admin Console → User Import Settings and run a manual import.
Confirm that the file processes successfully and that changes appear on the People page.
If it still fails, capture the error details and contact Rotageek Support.
Where can I see or change which fields are imported?
Go to Admin Console → User Import Field Mappings. This page shows each Rotageek user field and the corresponding file column header (if any). You can update mappings to align with changes in your HR file headings.
If you are unsure about any of the settings above or are planning a major change to your HR or payroll integration, please contact your Rotageek Customer Success Manager or the Rotageek Support team before making changes in production.