About This Article
This article defines what an SFTP integration is (Secure File Transfer Protocol), gives detailed instructions on how to set up an SFTP integration, summarizes the usage and the benefits it provides. The article is designed to be used a guide for clients when setting up an SFTP integration.
Click on the links below to read relevant sections in the article:
- About SFTP
- What is an SFTP Integration?
- Benefits of Using an SFTP
- SFTP Integration Setup Overview
- New SFTP Integration - Video
- Step 1: Setting Up the Integration
- Step 2: Testing Initial Setup
- Step 3: Managing Notifications
About SFTP
SFTP is a more secure variant of the classic File Transfer Protocol (FTP). Employee data will be transferred over a Secure Shell (SSH) connection and cannot be viewed by anyone examining the traffic.
An SFTP integration allows our clients' member data to be loaded automatically. It also provides alerts on any errors which occur within data files prior to processing and scheduling.
During the implementation and configuration of the integration, Reward Gateway assigns a unique SFTP to the client. Files uploaded using this SFTP account are processed according to the rules defined by the client, giving them complete control of data transfers.
What Is an SFTP Integration?
An SFTP integration allows you to upload your member data directly into the system for automatic processing.
You'll need to prepare and upload this data, and we recommend discussing this integration with your HRIS (Human Resources Information System) provider. To make this process simple and minimise any risks, we also recommend automating the adding, removing, updating, collecting, and sending of data over the SFTP connection. Once we receive your data, it will be automatically processed and added to our database. This means your offering will be instantly up to date.
Benefits of Using an SFTP
The biggest benefit of using this integration is the automation it delivers. Automating data uploads via SFTP means:
- There is a reduced risk of human error in manipulating data by defining a standard extract format.
- It eliminates the need to download data to a desktop before uploading it to Reward Manager.
- Data can be provided at an increased frequency (e.g. daily) with a lower overall administration cost.
- GPG encryption can be used to further secure data transfers.
Supported MIME Types
A media type (also known as a Multipurpose Internet Mail Extensions or MIME type) indicates the nature and format of a document, file, or assortment of bytes.
For xls:
- application/vnd.ms-excel
- application/msexcel
- application/x-msexcel
- application/x-ms-excel
- application/x-excel
- application/x-dos_ms_excel
- application/xls
- application/x-xls
- application/excel
- application/download
- application/vnd.ms-office
- application/msword
For xlsx:
- application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- application/zip
- application/vnd.ms-excel
- application/msword
- application/x-zip
- application/octet-stream
-
application/vnd.openxmlformats-officedocument.spreadsheetml.sheetapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheet
SFTP Integration Setup Overview
Accessing Reward Manager
To be able to configure an SFTP integration on Reward Gateway, you must have an Administrator account that will enable you to access Reward Manager.
If you don’t have access, please speak with your Client Success Manager or a member of the Client Support team who will assign your permissions.
New SFTP Integration - Video
Watch the following video which demonstrates the setup process step-by-step:
Step 1: Setting Up the Integration
Follow the steps below to set up a new integration:
1. Once logged in to Reward Manager, navigate to Integrations > Explore > select Inbound SFTP:
2. Give the integration a name.
Make it meaningful so other Administrators can understand the purpose of the SFTP setup (e.g. Acme Company Ltd Leavers Integration). This will only be visible in Reward Manager.
3. Set up a Prefix for your file transfer.
This is important as Reward Gateway will determine the correct configuration based on your prefix. Choose something short and easy to remember. Each file transfer MUST contain the filename including the prefix setup here.
4. Select Membership from the drop-down menu.
GPG / PGP Encryption
5. If you would like to send your file encrypted, please select the GPG encryption option.
After ticking the box to confirm GPG encryption, a public key will be displayed. Make sure this is copied and encrypt the files with the public key before using a GPG encrypted file.
We support the following mime types for .pgp files:
- application/octet-stream
- application/pgp
- application/pgp-encrypted
- application/pgp-keys
- application/pgp-signature
6. Please select a workflow you would like to follow.
Reward Gateway supports multiple workflows for processing files:
- Add Members – the data file will only add members to the platform.
- Refresh Members – the file will be considered a snapshot of all employees working for the client's organisation. Any members not included in the file will be removed automatically and any members that currently do not have accounts on Reward Gateway will have accounts created based on the file.
- Remove Members – the file will only remove members from the platform. You will only need the user ID for this file.
7. Welcome Emails, Select Registration Email if you would like to send an email to the new members:
Authentication Type
Now, it's time to decide how to authenticate access to the SFTP box, which will allow the data to be processed.
8. Choose from one of the two supported options: Password or SSH, from the dropdown:
Username and Password Option
If the Username and Password option is chosen, we’ll display the required credentials to enable access to the new dedicated SFTP box.
9. Make sure you select the New Password option and make note of your username and password details somewhere secure. Your password will NOT be shown again.
SSH Key Option
If the SSH Key method is chosen, the required credentials will be displayed to access the dedicated SFTP box.
10. Click the Add SSH Key button.
All SSH Keys must be in RFC-4716 format. When generating the SSH keys make sure you follow the recommended Security Guidelines. Check in real time what ciphers we are currently using from Rebex SSH Check. You can also check the ciphers on our staging SFTP Server.
Reward Gateway supports storing multiple SSH Keys against an individual configuration, allowing clients to set up multiple endpoints on the integration.
Step 2: Testing Initial Setup
Once the initial setup is complete and the authentication details have been copied over, it's time to send a test file.
1. Please install and open your preferred SFTP Client for your operating system, enter the credentials that we have provided to you, and you will log into our SFTP Server.
There you will see two folders, the outbound folder will contain files that Reward Gateway wants to share with you and you can't upload anything there, the inbound folder will contain files that you want to share with Reward Gateway and this is the folder where you have to upload your files.
2. Now log into our SFTP server with your SFTP Client
3. Enter the inbound folder
4. Upload your test file
Your file should be UTF-8 (Unicode Transformation Format – 8-bit) encoded in order to validate on the Reward Gateway servers. For membership data validation please see our guide Integration - Membership Data Validation
Note: Your SFTP Client should upload files without any additional rename of the file's name during the transfer.
The test file allows the mapping data on the file to the fields on Reward Gateway. This is also a way of identifying that the new SFTP box is working as expected.
Please note that the example file won’t be processed on your programme and your file needs at least one row of dummy data in order to be accepted.
Once you’ve connected to the SFTP server successfully, using the credentials given in the previous step and the test file has been uploaded, you will see in Reward Manager that we’ve received the file.
Mapping
5. It’s important to carefully map the columns to match the fields on Reward Gateway. If any issues are encountered with the mapping, please contact Client Support.
Note: Once mapped, every file sent to us must follow the same structure.
Mapping credentials:
- Column Name: Name of the column on the file.
- Example Data: Example data on the file matches this column.
- Matching Field: Field that column maps to on Reward Gateway. We have automatic mapping on most fields, however, it’s advised to manually check if these fields are required. If the column is mapped to ‘-- Ignore --’ this column will be ignored from the upload.
If the column is mapped to ‘-- Ignore --’ this column will be ignored from the upload unless you select it from the dropdown menu.
Review
6. Review all changes carefully in this step:
7. Click on Enable Integration to complete the setup.
Step 3: Managing Notifications
It’s extremely important that clients keep monitoring their SFTP box and the files processing through it.
- To do this, go to your Integration Dashboard
- Select the SFTP Integration of your choice
- Select the Edit Notification Receivers option under Tools
Our advice is to set up multiple members from their organization to receive update notifications. This will allow multiple notifications to be received based on certain events while the files are being processed.
File Upload Frequency
1. Go to your Integration Dashboard
2. Select the SFTP Integration of your choice and select the Edit Reminder Frequency option under Tools.
3. You need to define when we should expect the file to be uploaded. We'll use your input to ensure we notify you in case the file was not uploaded as expected.
4. Once you have added the details, click on Save Frequency.
Provision Master
To turn Provision Master on/off go to your Integration Dashboard
Select the SFTP Integration of your choice and select the Edit Provision Master option under Tools.
See Integrations - Provision Master article to find out more about this feature.
3. Once inside this menu, click the Toggle button to enable or disable the Provision Master for the SFTP integration:
When the toggle is on, you will be able to see which fields are restricted or allowed for manual editing by members of your platform:
Reports
Any members set up to receive notifications will receive one when a file is processed. The notification email will contain information about the actions taken through the file.
For example, a notification would be sent to update on the fact that access was revoked for 25 users after a file was processed.
Reminders
Any members set up to receive notifications will also receive one when there have been no files processed for over a month. This is to ensure that employee data is always up to date.