Skip to main content
All CollectionsAdministrator GuideApplications and Automation
SFTP User Sync
SFTP User Sync

Using SSH File Transfer Protocol to sync user information

Updated over a month ago

At this time, User Provisioning is only available to organizations on our Enterprise tier. Please email support at support@joinblink.com for more information.

Blink’s CSV User Sync feature allows for syncing user data from an external system into Blink using Excel or CSV (Comma-Separated Values) files. This documentation provides step-by-step instructions to help you successfully upload and sync your user data.

Summary of the process

In short, the process is as follows:

  1. Blink sets up an SFTP folder for you and securely shares the credentials with you

  2. You upload a sample employee file to the SFTP folder

  3. You send Blink a list of how your fields map to our fields (table below)

  4. Blink configures your mapping, validates the ingestion, and activates the sync

  5. You send an employee file into the active SFTP folder, which performs the relevant updates to your users in Blink

  6. You set up an automated export to send your CSVs into the SFTP folder at a regular interval

How it works

Blink will configure a file server for you and give you access to it via SFTP. You will then be able to upload files (.csv or .xlsx) to this server with user data.

Whenever a file is uploaded to the server, the service will process the file and apply the changes in the file to the users in your Blink instance. To process these changes, we require a mapping table from you that maps the file contents to Blink fields. We use these mappings to update user fields on Blink. The sync will not impact users if their information isn’t in the provided file. This is most noteworthy regarding terminations. Terminations cannot be inferred, so when an employee is terminated, a user record indicating their termination will need to be included in the file sent to Blink.

For example, if an initial sync is done with a file that contains data for 1,000 users and a subsequent sync is performed with a different file with data for only 50 users, the system will not change any information/fields for the other 950 users. It will only update the information for those 50 users in the uploaded file.

It is worth noting that once a user is sync via the CSV User sync, they will be set as “managed by external source” on Blink and their profile fields will be locked from being modified within the Blink admin panel. Changes to their information will only be possible via the CSV User Sync.

One exception to this profile lockdown is users synced with no email or contact information provided from the CSV User Sync. In these cases, these fields can still be modified within Blink, provided they continue to have no contact number of email synced across in the files uploaded.

Mapping and Data

We use a mapping table to inform how to map data from the file provided to Blink User profile attributes. There is a mapping table provided in the What we need from you section at the end of this document.

By mapping each field, we can maintain data consistency and accuracy between your external system and Blink.

  • Cross column mapping

    • It is worth noting that values cannot be mapped across multiple columns. For example, the mapping to Blink’s “Department” field can’t be a combination of multiple fields from your file, and must be pointed to only one column in the provided file.

  • Unmapped columns

    • If there are columns in the provided file that don’t map to anything on Blink, they’ll be ignored.

  • Multiple mappings

    • In situations where your users will be provisioned from multiple sources (e.g. 70% of workforce from Payroll System 1 and 30% of workforce from Payroll System 2), it is possible to have multiple mapping configurations within one Blink organisation. Please let us know if you would like to make use of the functionality.

  • Operations and functions

    • We can perform basic operations on file data, such as IF statements and simple calculations. However, we recommend you handle data processing on your end prior to sending files to Blink, to give you the most control over your settings without involving Blink support. Please let us know if you would like to make use of the functionality.

  • Customer fields

    • In addition to the standard set of user fields that Blink expects, it is possible to sync additional custom fields from your file. Please let us know if you would like to make use of the functionality.

  • Teams and communities

    • It is currently not possible to sync teams using the CSV User Sync.

CSV/Excel data requirements

To ensure the service can properly process and update user data, there are several prerequisites the provided file must adhere to.

Miscellaneous

  • All data must be on the first sheet of the document. Any data on subsequent sheets is not parsed.

  • Files must have UTF-8 encoding.

  • If uploading a CSV, a comma (,) should be used as the separator/delimiter.

  • If you are switching from currently managing your users on Blink to managing them via the CSV User Sync, it is critical that the employee IDs on Blink users match the external IDs provided in your CSV files. Before executing this change, please ensure all users in Blink have their correct employee ID.

Headers

  • The first row of the sheet should contain the headers.

  • Headers should not contain any special or accented characters (e.g., “é”, “ö”, “í”, “ñ”, “ü”, etc.).

  • Headers may not contain parentheses or brackets (e.g. ”(”, “)”, “[”, “]”, “{”, “}”)

  • The Headers should be Pascal Case, e.g., FirstName, Location, DateOfBirth.

Email addresses

  • Email addresses must be sent without any hyperlinks.

  • Email addresses must be unique. Users with conflicting email addresses won’t sync.

  • Emails should be following the standard email format: username@domainname.extension. Malformed emails will cause issue with the registration process as OTPs will not be able to reach users.

Mobile numbers

  • Phone numbers must adhere to the 164 standard. Any users with phone numbers that don’t adhere to E.164 won’t be synced.

    • For example, +447495944376

  • Mobile numbers must be unique. Users with conflicting mobile numbers won’t sync.

Active

We require an “active” value in the sheet that represents a user’s active state on Blink.

  • This must be a true or false

  • Users without an active value set in the provided file won’t be synced.

External ID

We use the External ID value to link users from external systems to Blink users.

  • External ID should be unique per a user and immutable/unchanging.

  • This can be the same value as employee ID.

  • Users without an external ID value set in the provided file won’t be synced.

Username

Username is used for similar purposes to external ID.

  • Username should be unique per a user and immutable/unchanging.

  • Users without a username value set in the provided file won’t be synced.

  • Username can be the same value as external ID.

Manager

  • The “manager” value for a user must be that of the manager’s external ID.

If the data for the following fields is not completely accurate or there are duplicates, it is better not to perform a sync with it until the data is clean as it will cause the sync to fail, create duplicate users or lead to conflicts when creating users.

  • External ID

  • Username

  • Employee ID

  • Email

  • Mobile Phone

What we need from you

  1. A copy of the export format that you will be uploading to the server. This is a requirement to for running a “dry sync” to check the quality of your data before the initial sync. Notably, the data provided must contain the headers that will be used in your upload going forward.

  2. An email address to share sync outcome logs with.

  3. Your field mappings, please complete the below and return:

Blink Fields

Your Mappings

External ID*

Username*

Employee ID

Email

First Name

Second Name

Phone Mobile

Phone Work

Manager

Job Title

Location Name

Department Name

Company

Active*

Start Employment Date

End Employment Date

*required fields

If you have any custom fields you would like to populate from the sync, please complete the table below:

Custom Field Name on Blink

Mapping

FAQs

When should I upload my files?

We recommend preforming uploads outside of your core working hours to limit any potential disruptions

Can I upload multiple files at once?

Uploading multiple files simultaneously to one folder/configuration is not supported.

How often should I upload my file?

It is best to do this daily. If your user data does not change regularly, we recommend performing weekly or monthly ad-hoc uploads.

💡 Ready to get started?

Send the requested information to us at support@joinblink.com and we'd be happy to help!

Did this answer your question?