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:
Blink sets up an SFTP folder for you and securely shares the credentials with you
You upload a sample employee file to the SFTP folder
You send Blink a list of how your fields map to our fields (table below)
Blink configures your mapping, validates the ingestion, and activates the sync
You send an employee file into the active SFTP folder, which performs the relevant updates to your users in Blink
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.
More information on Pascal Case be found here.
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
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.
An email address to share sync outcome logs with.
Your field mappings, please complete the below and return:
Blink Fields | Your Mappings |
External ID* |
|
Username* |
|
Employee ID |
|
| |
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?
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?
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?
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.
How often is the service run?
How often is the service run?
Every time a new file is added to the SFTP. (We recommend no more than once a day).
Why was an account not created?
Why was an account not created?
This can be due to different reasons. First step is to locate the latest sync report email and review the detailed logs file which includes more information as to what conflict as caused for the account to not be created.
Type of Errors
ORGANISATION_CONFLICT: Duplicate profile data detected. The value provided for this user matches an existing record in Blink. Refer to the Additional Data column to identify the conflicting value and resolve the duplication.
MATCH_CANDIDATE_CONFLICT: Cannot link SCIM user to Blink ID. Example: While the Phone and Employee Number match, the Work Email is different. Please synchronise the email addresses across both systems to complete the link.
GLOBAL_CONFLICT: Duplicate data detected. Certain profile details are already in use by another Blink account. Refer to the Additional Data column for the specific conflict. If the error persists, contact Blink Support for data rectification.
SHARD_CONFLICT: This error is similar to the GLOBAL_CONFLICT error. Please contact the Blink Support team for assistance.
If an account was completely ignored by the sync?
If an account was completely ignored by the sync?
If an account was completely ignored by the sync?
If an account was completely ignored by the sync?
Missing User? If a specific user was bypassed entirely and is missing from the sync report:
Identify the user in the original file uploaded to the SFTP server.
Share those details with the Blink Support team.
We will analyse the system logs to determine why the account was not processed.
Can I make manual bulk uploads?
Can I make manual bulk uploads?
Accounts that are claimed by the sync and are SCIM-managed—where profile fields are greyed out and the profile displays the message “This user is managed by an external source”—cannot be updated via bulk upload.
Any updates to these accounts must be made externally through your HRIS system that feeds the SCIM integration.
Bulk updates will only be performed on accounts that are not SCIM-managed, meaning they have not been claimed by the sync.
💡 Ready to get started? Send the requested information to us at support@joinblink.com and we'd be happy to help! |