SFTP user provisioning

Overview

SFTP User Sync is an automated user provisioning feature that keeps employee information in Appraisd synchronized with your HR system. Instead of manually updating employee profiles, manager relationships, and organizational changes, you can automate an upload a CSV file to our SFTP server with employee data, and Appraisd will automatically update user accounts.

Who Should Use This Feature

You should not use this feature if you're HRIS is supported by one of our native HRIS syncs. Instead follow this guide on setting up a native HRIS sync.

SFTP User Sync is ideal for organizations that:

• Use an HR Information System (HRIS) that can export employee data to CSV format
• Have an internal IT team with the required skills to automate the publishing of the CSV to the SFTP server

Key Benefits

• Time Savings: Automate updates so that no manual input is needed
• Data Accuracy: Single source of truth from your HRIS
• Automatic Onboarding: New employees are created in Appraisd automatically
• Manager Sync: Manager relationships stay current with org changes
• Audit Trail: Every sync is logged with detailed results

How It Works - The Big Picture

The SFTP user sync process follows these steps:

1. Export from HR System: Your HRIS (or IT team) periodically exports employee data to a CSV file
2. Upload File: Your IT team automatically uploads the CSV file to a secure SFTP server that Appraisd monitors
3. Validate Data: Appraisd checks the file for required fields, duplicates, and formatting issues
4. Process Updates: Valid user records are created or updated in Appraisd
5. Send Notifications: Administrators receive an email summary of the sync results

When Syncs Happen

This is up to you, but we recommend scheduled daily syncs.

Some organisations only update their HRIS data once a week, so you can also sync weekly if preferred.

CSV File Requirements

Required Columns

Your CSV file must include these five columns with exact header names:

Important: Column names are case-sensitive. Email will work, but email or EMAIL will not.

Optional Columns

You can include these optional columns to sync additional information:

Manager Relationships Explained

Manager relationships are how Appraisd knows who reports to whom. You have two ways to reference managers:

Option 1: Manager Email (Recommended)

Use LineManagerEmail with the manager's email address. Appraisd will find the matching user account.

Example:

UniqueId,Email,FirstName,LastName,Active,LineManagerEmail
E12345,jane.smith@company.com,Jane,Smith,true,john.doe@company.com

Best For: When email addresses are stable and unique in your organization.

Option 2: Manager Employee ID

Use LineManagerEmployeeIdString with the manager's employee ID. Appraisd will match this to the EmployeeIdString field of the manager's user account.

Example:

UniqueId,Email,FirstName,LastName,Active,EmployeeIdString,LineManagerEmployeeIdString
E12345,jane.smith@company.com,Jane,Smith,true,EMP-12345,EMP-67890
E67890,john.doe@company.com,John,Doe,true,EMP-67890,

Best For: When you want to reference managers by a stable ID independent of email changes.

What Happens with Blank Manager Fields

If you leave both LineManagerEmail and LineManagerEmployeeIdString blank for a user:

• The user will be marked as "Not Appraised" (no direct manager)
• This is common for executives and board members

The same logic applies to SecondManager and SSO (sign-off) manager fields.

Preparing Your CSV File

CSV Format Requirements

Your file should follow these guidelines:

• File format: Standard CSV (Comma-Separated Values)
• First row: Column headers with exact names from the tables above
• Column order: Any order is fine, as long as headers match
• Text encoding: UTF-8 recommended (but most encodings work)
• File naming: Any name ending in .csv

Example CSV Structure

Here's what a complete CSV file looks like:

UniqueId,Email,FirstName,LastName,Active,EmployeeIdString,Position,LineManagerEmail,Language
E12345,jane.smith@company.com,Jane,Smith,true,EMP-12345,Senior Engineer,john.doe@company.com,en-gb
E67890,john.doe@company.com,John,Doe,true,EMP-67890,Engineering Manager,sarah.jones@company.com,en-gb
E54321,sarah.jones@company.com,Sarah,Jones,true,EMP-54321,VP Engineering,,en-us
E99999,bob.wilson@company.com,Bob,Wilson,false,EMP-99999,Consultant,john.doe@company.com,en-gb

Notes:

• Jane reports to John (via LineManagerEmail)
• John reports to Sarah
• Sarah has no manager (blank field means she's at the top of the hierarchy)
• Bob is inactive (Active=false)

Setting Up File Upload

Once your CSV file is ready, it needs to be uploaded to a location where Appraisd can access it.

Your IT Team's Role

Your IT team will need to set up the file upload process. This typically involves:

1. Get Connection Details: Contact your CSM or Appraisd support (support@appraisd.com) to receive secure upload credentials
2. Configure Upload: Set up automated upload from your HRIS or file server
3. Test Connection: Upload a test file to verify the connection works
4. Schedule Regular Uploads: Configure weekly uploads if using scheduled sync

What Appraisd Provides

Appraisd will provide your IT team with:

• A sandbox account to test the integration
• Secure connection credentials for file upload
• Technical documentation for setup
• Support during initial configuration

Your Role as HRBP

As the HR Business Partner, you will:

• Coordinate between your IT team and Appraisd support
• Validate that the CSV export includes the correct data
• Test the sync with a small group of users first
• Monitor sync results and address any data quality issues

What Gets Updated vs. What Doesn't

Always Updated:

• Name (first name, last name)
• Email address
• Active status
• Position/job title
• Manager relationships
• Custom fields included in the CSV

Never Updated (Preserved):

• User's password
• Manually set permissions and admin groups
• Historical performance data
• Completed reviews and feedback
• User preferences (unless Language is in CSV)

Notification Emails

After each sync completes, administrators listed in the configuration receive an email with:

• Subject Line: "User Provisioning Sync Completed" or "User Provisioning Sync Failed"
• Summary: Number of users created, updated, and any errors
• Link: Direct link to view detailed logs

(If configured) New users who are created will also receive:

• Welcome email to Appraisd
• Login link to set up their account
• Your custom instructions for getting started

Common Validation Errors

When a sync encounters problems, you'll see error codes in the run logs. Here's what they mean and how to fix them:

Required Field Errors

Fix: Check your HRIS export to ensure these fields are populated for all active employees.

Duplicate Entry Errors

Fix: Review your CSV file for duplicate entries. This often happens when an employee is listed in multiple departments or has multiple roles.

Format Errors

Fix: Standardize date formats in your export. ISO format (YYYY-MM-DD) is most reliable.

Manager Reference Errors

Fix: Ensure that managers appear in the CSV file before (or in the same file as) the employees who report to them. Check for typos in email addresses or employee IDs.

Organisation Errors

Fix: Contact Appraisd support for cross-organization issues. For same-firm duplicates, check your user list and resolve the conflict.

Field Length Errors

Fix: Shorten the values in your CSV export or ask Appraisd support about field length limits.

Scheduling and Running Syncs

Daily Automated Sync (Recommended)

For most organizations, a daily scheduled sync is the best approach:

How to Set Up:

Speak with your Customer Success Manager who can schedule this for you. 

Manual On-Demand Sync

For some situations, you may want to run a manual sync:

When to Use Manual Sync:

• Initial setup and testing
• Urgent updates that can't wait for daily sync
• After fixing data quality issues

How to Run a Manual Sync:

1. Prepare your CSV file with updated data
2. Upload the file to the designated location
3. In Appraisd, go to Configuration → User Provisioning
4. Click Run Sync Now
5. Monitor the notification email for results

Best Practices

Data Quality Tips

Keep Your HRIS Clean:

• Ensure employee records are complete before exporting
• Regularly audit for duplicate emails or employee IDs
• Update manager relationships promptly when org changes occur

Consistent Formatting:

• Use the same date format across all date fields
• Keep email addresses lowercase for consistency
• Use consistent language codes

Test Before Production:

• Validate manager relationships in the sandbox environment
• Check for edge cases (employees with no manager, matrix reporting)

Frequently Asked Questions

General Questions

Q: What happens if the same email address already exists in Appraisd?

A: If the email matches an existing user in your organization, that user's information will be updated with the new data from the CSV. If the email exists in a different organization, you'll receive an error (emailinanotherfirm) and should contact Appraisd support.

Q: How do we deactivate users who have left the company?

A: Set their Active field to false in your CSV file. They will remain in Appraisd for historical reporting purposes but they won't be able to log in.

Q: Can we test the sync without affecting real users?

A: Yes, use should use the sandbox provided. If you don't have one, contact Appraisd support about setting it up for you. Please note it can take up to 3 working days to create sandbox accounts.

Q: What if our HRIS doesn't export to CSV?

A: Most modern HRIS systems can export to CSV or Excel (which can be saved as CSV). If yours cannot, you may need:

• A middleware tool to convert your HRIS export format
• Custom scripting by your IT team
• An API-based integration (contact Appraisd for options)

Q: How long does a sync take?

A: Sync time depends on the number of users:

• 100 users: ~2-5 minutes
• 500 users: ~5-10 minutes
• 1,000+ users: ~10-20 minutes

Manager Relationships

Q: What happens if a manager isn't in the CSV file yet?

A: You'll receive an error (defaultappraiserdoesnotexist). The employee will be created/updated, but their manager relationship won't be set. Fix this by ensuring managers are included in the CSV or run a second sync after the manager is created.

Q: Can an employee have multiple managers?

A: Yes, Appraisd supports:

• Direct Manager (LineManager fields)
• Matrix Manager (SecondManager fields)
• Sign-off Manager (SSO fields)

Include the appropriate columns in your CSV to set up these relationships.

Data and Security

Q: Is the file transfer secure?

A: Yes, files are uploaded using secure protocols and stored in encrypted cloud storage. Only authorized Appraisd systems can access the files.

Q: What happens to the CSV file after it's processed?

A: The file is processed and then archived for audit purposes. It's stored securely and is not accessible outside of Appraisd's systems.

Q: Can we see what changed in each sync?

A: Yes, detailed logs are available in Appraisd under Configuration → User Provisioning → Run Logs. These show which users were created, updated, and any errors that occurred.

Advanced Use Cases

Q: Can we sync users from multiple HR systems?

A: If you have multiple systems, create a single consolidated CSV file. I that's not possible, contact Appraisd support before for information on how to manage this use case.

Q: Do custom fields need to be set up in Appraisd first?

A: Yes, Custom1 through Custom6 fields should be configured in your Appraisd settings with appropriate labels before including them in your CSV.

Q: Can we control which users receive admin permissions through the CSV?

A: No, admin permissions and admin groups are managed separately in Appraisd and are not overwritten by the sync. This is a security measure to prevent accidental privilege escalation.

Information to Provide When Seeking Help from Appraisd

When contacting our support team include:

• Your organisation name in Appraisd
• Date and time of the sync
• Number of users in the CSV file
• Error messages (exact text or screenshots)
• Sample CSV rows (with sensitive data removed)
• What you've already tried to fix the issue
• Expected behaviour vs. what actually happened