Customer IT / SpaceIQ Onboarding Team
SiQ supports a number of integration options to automate the data import process and enable employee access to SiQ features. One common method used to import employee data is SFTP (Secure File Transfer Protocol). The process allows you to connect to a SiQ-hosted SFTP server and save a file containing relevant information. SiQ will automatically pick up the file and load it into your system.
This article describes a high-level overview of how to set up SIQ to import employee roster information from customers’ HR systems.
Note - SFTP Import (this article) and SFTP Export are two separate integration processes.
- File Format
- Employee Mappings
- Import Schedule
- Integration Process
- Generate Public & Private Key
Your data files need to conform to the following requirements:
- The file name must have a .csv extension. There are no other requirements regarding the file name.
- The file content type should be ASCII CSV. Files containing any other content types will be silently deleted.
- The data table header line must be present in the file, indented by #.
- The file must have at least one entry. Any empty files will be silently deleted.
- The file content must be comma separated with values between double quotation marks (e.g. “first name”).
- The file size should not exceed 25MB maximum. Empty files or files exceeding 25MB size will be silently deleted.
It is good practice to complete at least one import process manually (see Manage Employees) using the SiQ Web App before enabling SFTP import. This will achieve two things:
- Ensure that you have the correct file format and data content.
- Create a mapping in the SiQ web app between your input file structure and SiQ internal data objects.
This mapping will be used by the automated SFTP import process and can be modified later in the integration’s setting.
Reach out to our support team after you have manually imported at least one file, and they will be able to provide you with your mapping definition.
SiQ's SFTP import process is asynchronous. SiQ monitors for any incoming files and will automatically load them into your workspace. New files are typically picked up within 5 minutes of upload and may take up to 30 minutes to process depending on the number of records and number of changes to existing employee records.
To safeguard against malicious attacks, SiQ controls the rate at which files can be uploaded to the system. Multiple subsequent file uploads will not be automatically picked up for processing and will be held to a once-an-hour processing threshold. When multiple files have been uploaded to the SFTP server, only the most recent file will be processed; the other files will be silently deleted.
Step 1. SiQ to set up a dedicated secure SFTP Server
Upon enablement of SFTP import integration, SiQ will set up a dedicated secure SFTP server on the SiQ cloud, allowing you to upload employee files.
As part of the enablement process, you will be assigned your own secured and encrypted folder where files will reside. The file will be deleted automatically once SiQ completes loading it.
Step 2. Active the SFTP Import
From the SiQ Web App, complete the following:
- Click your Profile Name in the top right corner.
- Click Settings. The Settings screen displays.
- From the left menu, click Integrations.
- From the Third Party Integrations area, click the READ MORE link. The Integrations screen displays.
You can either search for SFTP in the Search field or navigate to SFTP tile. To navigate complete the following:
- From the left menu, click Employee Import.
- For SFTP, click the Activate button.
The SFTP dialog displays and it contains an Import (Password) tab and an Import (SSH Public Key) tab.
Depending on the authentication method you want to use, select either:
- Import (Password) tab
- Import (SSH Public Key) tab
SiQ will perform the following actions based on your selection:
- Import (Password) - SiQ will generate a unique username and password for you to use with your SFTP client.
- Import (SSH Public Key) - SiQ will generate a unique username and expect you to supply the SSH Public key you would like to use. You will need to configure your SFTP client with both. Steps to generate Public Key are listed in the section below.
In both cases, SiQ will provide connection details (e.g. hostname, port) that you will use to configure your SFTP client.
Import (Password) Tab
Import (SSH Public Key) Tab
Click the Activate button to complete the process.
Generate Public & Private Key
Run the ssh-keygen command in the terminal and answer the questions when prompted. The defaults are acceptable for most use cases.
ssh-keygen -trsa -f ~/.ssh/spaceiq.access.key
The generated keys should now be located in your local directory:
- private key is in the ~/.ssh/spaceiq.access.key file.
- public key is in the ~/.ssh/spaceiq.access.key.pub file.
Next convert private key to PEM format by using ssh-keygen command:
ssh-keygen -p -m PEM -f ~/.ssh/spaceiq.access.key
Next convert public key to RFC 4716 format and configure SFTP with a public key:
Important Note: Make sure you include the --- BEGIN SSH2 PUBLIC KEY ---- and the ---- END SSH2 PUBLIC KEY ----
ssh-keygen -e -f ~/.ssh/spaceiq.access.key.pub| egrep -v Comment
---- BEGIN SSH2 PUBLIC KEY ----
---- END SSH2 PUBLIC KEY ----