Skip to main content

Smart Arena SFTP User Import - User Guide

Updated today

Overview

The SFTP User Import integration enables automatic synchronization of users from your external systems (HR systems, ERP, etc.) to SmartArena. This integration eliminates the need for manual user management and ensures your SmartArena user database is always up-to-date with your organization's current employee data.

How It Works

  1. Upload Files: Your system uploads CSV files to a dedicated SFTP folder with the filename format: users_YYYY_MM_DD.csv (e.g., users_2026_02_12.csv)

  2. Automatic Processing: Files are automatically processed daily at 07:30 AM

  3. User Synchronization: The system will:

    • Insert new users found in the CSV

    • Update existing users when data changes

    • Optionally soft-delete users not present in the CSV (if configured)

Prerequisites

SFTP Access Credentials
​

Before you can use this integration, you need to obtain SFTP access credentials from SmartArena support. Contact support to receive:

  • Server address: The SFTP server hostname

  • Username: Your organization's unique SFTP username

  • Password: Secure password for SFTP access

  • Folder path: Your dedicated upload folder path

System Requirements

  • Ability to generate CSV files from your source system

  • SFTP client capability (for manual uploads) or automated SFTP upload process

  • Understanding of your organization's user data structure

Configuration

Step 1: Access the SFTP Integration Settings

  1. Log in to SmartArena as an administrator

  2. Navigate to Organizations → Manage

  3. Go to the Integrations tab

  4. Click on SFTP User Import

Step 2: Configure Comparison Method

Choose how SmartArena identifies users:

  • Compare by Email: Users are matched by their email address

  • Compare by Mapping Code: Users are matched by a unique internal code (employee ID, personnel number, etc.)

Best Practice: Use "Mapping Code" if your organization assigns unique employee IDs. Use "Email" only if email addresses are stable and unique.

Step 3: Configure Delete Missing Users (Optional)

Enable this option if you want SmartArena to automatically soft-delete users who are no longer in your CSV file.

⚠️ Important:

  • Deleted users are soft-deleted (not permanently removed)

  • Soft-deleted users can be restored if needed

  • Only enable this if your CSV represents the complete current user list

Step 4: Upload Sample CSV File

  1. Click the Upload Sample CSV field

  2. Select a sample CSV file from your system

  3. SmartArena will automatically analyze the file and detect columns

  4. The field mapping table will appear

Step 5: Configure Field Mapping

Map your CSV columns to SmartArena fields:

Mandatory Fields
​
Based on your comparison method, these fields are required:

If comparing by Email:

  • Email

  • First Name

  • Last Name

If comparing by Mapping Code:

  • Mapping Code

  • First Name

  • Last Name

Optional Fields
​

You can also map these additional fields:

  • Username: Login username (if different from email)

  • Date of Birth: Format: YYYY-MM-DD or DD.MM.YYYY

  • Sex: M (male) or F (female)

  • Language: Language code (hr, en, de, sl, sr, ru, es)

  • National ID: National identification number

  • Password: User password (will be hashed automatically)

  • Organizational Unit: Internal code of the user's organizational unit (branch)

  • Location: Internal code of the user's location

  • Workplace: Internal code of the user's workplace

Note: Organizational Unit, Location, and Workplace must exist in SmartArena before they can be assigned. If the codes in your CSV don't match existing records, the user will still be inserted but without those invalid organizational assignments.

Step 6: Save Configuration

Click the Save button to store your configuration.

CSV File Format Requirements

File Naming Convention

  • Format: users_YYYY_MM_DD.csv

  • Example: users_2026_02_12.csv

  • Important: The date must match the current date for automatic processing

CSV Structure

  • Delimiter: Semicolon (;)

  • Encoding: UTF-8 (with or without BOM)

  • First Row: Column headers (can be any names - you map them in the configuration)

Example CSV

Field Value Formats

Data Synchronization

The integration synchronizes the following user data:

  1. Basic Information

    • Name

    • Email

    • Username

  2. User Details

    • Date of birth

    • Sex

    • Language preference

  3. Organizational Data

    • Organizational unit (if mapped and exists)

    • Location (if mapped and exists)

    • Workplace (if mapped and exists)

  4. Security

    • Password (if provided - will be hashed)

Synchronization Logic

New Users (INSERT):

  • If a user doesn't exist in SmartArena (based on email or mapping code), they will be created

  • All mapped fields will be populated

  • Active Status:

    • If a password is provided in the CSV, the user will be set as active and can log in immediately

    • If no password is provided, the user will be inactive and will receive a registration email upon first course enrollment or when manually sent by an admin

  • Invalid organizational data (branch/location/workplace that doesn't exist) will be ignored, but the user will still be created

Existing Users (UPDATE):

  • If a user exists and data has changed, their record will be updated

  • Only changed fields are updated

  • Update timestamp is recorded

Missing Users (DELETE):

  • If "Delete Missing Users" is enabled and a user is not in the CSV, they will be soft-deleted

  • Soft-deleted users can be restored through the admin interface

Skipped Users:

  • Users with critical validation errors (e.g., invalid email format, missing required fields) are skipped

  • Users with invalid organizational data (non-existent branch/location/workplace codes) are not skipped - they are inserted/updated but without the invalid organizational assignments

  • Errors are logged in the import history

Upload Methods

Automated Upload (Recommended)
​

Set up an automated process in your source system:

  1. Generate the CSV file daily with current user data

  2. Name it with the current date: users_YYYY_MM_DD.csv

  3. Upload it to your SFTP folder before 07:30 AM

  4. The file will be processed automatically

Example Workflow:

Manual Upload
​

For testing or one-time imports:

  1. Generate your CSV file

  2. Use an SFTP client (FileZilla, WinSCP, etc.)

  3. Connect using your credentials

  4. Upload the file to your designated folder

  5. Click Run Import Now in the Smart Arena interface (superadmin only)

Monitoring and History

Import History
​

The SFTP setup page displays import history with:

  • Date/Time: When the import was processed

  • Filename: Which file was processed

  • Status: Success, Partial (with errors), or Error

  • Statistics:

    • ✅ Inserted: Number of new users created

    • ✏️ Updated: Number of existing users updated

    • 🗑️ Deleted: Number of users soft-deleted

    • ⛔ Skipped: Number of users skipped due to validation errors

    • ⚠️ Errors: Number of error messages

File Storage
​

After processing, files are automatically moved:

  • Successful imports: Moved to processed/ folder with timestamp

  • Failed imports: Moved to errors/ folder with timestamp

  • Retention: Files are kept for 90 days, then automatically deleted

Admin Controls
​

Superadmins have access to:

  • Run Import Now: Manually trigger import of today's file

  • View Today's File: Check if a file exists for the current date

  • Import History: Review all past import operations

Troubleshooting

All Users Showing as "Skipped"
​

Cause: Missing required fields (email, first name, last name, or mapping code) or invalid email format
​

Solution:

  1. Verify all required fields are mapped and present in the CSV

  2. Check email addresses are valid (proper format with @ and domain)

  3. Ensure first name and last name columns are not empty

  4. If using mapping code comparison, verify mapping codes are present

  5. Review the import history error messages for specific validation failures

Note: Invalid organizational unit codes (branch/location/workplace) will not cause users to be skipped - they will be imported without those organizational assignments.

Users Not Updating
​

Cause: Data appears unchanged to Smart Arena
​

Solution:

  1. Verify the comparison field (email or mapping code) matches exactly

  2. Check for whitespace differences in the CSV

  3. Ensure date formats are correct (YYYY-MM-DD)

  4. Review the import history for specific error messages

File Not Processing Automatically
​

Cause: File naming doesn't match the current date
​

Solution:

  1. Verify filename is exactly: users_YYYY_MM_DD.csv where YYYY_MM_DD is today's date

  2. Check the file exists in the upload folder (not a subfolder)

  3. Ensure the file was uploaded before 07:30 AM

  4. Wait for the next scheduled run or use "Run Import Now"

Invalid Email Errors
​

Cause: Email addresses in CSV are not valid

Solution:

  1. Validate email format in your source system

  2. Ensure no spaces or special characters except @ and .

  3. Fix the source data and re-upload

Encoding Issues (Special Characters Garbled)
​

Cause: CSV not saved in UTF-8 encoding

Solution:

  1. Open CSV in a text editor (Notepad++, VS Code)

  2. Save as UTF-8 encoding

  3. Re-upload the file

Debug Logging
​

For deeper troubleshooting, check the Laravel logs:

Location: app/storage/logs/laravel-YYYY-month.log

Search for: SFTP User Import:
​

Example log entries:
​

Getting Help

If you encounter issues not covered here:

  1. Review the import history for specific error messages

  2. Check the Laravel logs for detailed error information

  3. Contact Smart Arena support with:

    • Your organization ID

    • Date/time of the import

    • Screenshot of the import history

    • Sample CSV file (with sensitive data removed)

Related Articles
Bulk user import
Bulk import - organizational units
Bulk import - workplaces
Smart Arena HANFA Integration - User Guide
Smart Arena Beekeeper Integration - User Guide
Did this answer your question?