This feature is only available for Elevated or Enterprise accounts
Overview
Our SFTP (Secure File Transfer Protocol) solution offers a comprehensive platform to automatically manage recipients on the Snappy Dashboard.
Users can easily add, update, and delete recipients information on the platform, without the cumbersome process of manually managing their recipients in the Dashboard.
Our SFTP solution is built on top of our robust APIs and provides standard enterprise grade security capabilities.
High level Solution Overview
Our SFTP Integration has few main parts:
Initial Set Up
Server permissions and configuration files
File Upload
Upload a CSV file via SFTP/FTPS into the correct folder location
File Processing
Snappy will automatically process these files and update the recipients in our system
Snappy will upload a report on the outcome of the process (success/failures)
Use the new data set
View the new data set on the recipients page in Snappy Dashboard
Set you campaigns to use this managed set of recipients
Onboarding
Snappy can support using the client’s SFTP server or provide its own Snappy SFTP server. In both cases the onboarding process is fairly easy:
Using the client’s server:
The onboarding process to the SFTP integration using the client’s server will include the following steps:
Clients will provide
Server details:
IP/server name
Username/Password to connect to server
Provide read/write/delete permissions to Snappy user
Optional (pending Client’s security policies): White list the relevant Snappy IPs (prod and dev)
CSV sample file following the file spec below including the data they would like to upload (columns, formats, etc.) .
Snappy team will
Confirm server access
Create a new SFTP setup
Create the folders hierarchy
Create the configuration file on the server (according to the sample file)
Confirm sample file is valid and can be processed
Test
Client can test the integration by automatically adding a new file to the server and checking recipients tab in Snappy dashboard to confirm recipients added
Using the Snappy’s server:
The onboarding process to the SFTP integration using the client’s server will include the following steps:
Clients will provide:
Public key: You can provide Snappy with the Public key in 2 ways:
*Snappy Generated Public Key **recommended *****
Using Snappy’s SFTP key generator within the Snappy Dashboard, which will automatically upload the public key to our server, provide the username and allow immediate access to the server. To use the key generator, follow these steps:
Login to your Snappy account as an owner → select your initials at the top right-hand corner
Go to General settings
Go to the Sharing & Access page
Open the SFTP key access section
Generate key and save the private key for the next step
Client Generated Public Key (ssh-rsa format)
Client can email a public key to Snappy
Snappy will upload the public key to our server
Connect to the Snappy server using the following details:
Server name: sftp.snappygifts.com
Port: 22
Username: The user name shown on Snappy dashboard (or provided by Snappy in case client has sent his external public key)
Private key: copied from the Snappy dashboard (or save by client when creating the external public key)
Test File: Client will upload to the server a CSV sample file of the data they would like to upload (columns, formats, etc.)
Snappy team
Creates configuration file (according to the sample file)
Confirms sample file is valid and can be processed
Client can test the integration by automatically adding a new file to the server
Recipients File
Snappy supports 3 main use case to upload recipients:
Roster change (roster): File should reflect the full company roster - e.g. on each sync, any existing recipients will be updated, new recipients will be created and existing recipients that don’t appear in the file will be deleted.
Adding recipients (add-and-update): File can include a subset of recipients - e.g. on each sync, any existing recipients will be updated and new recipients will be created
Deleting recipients (delete): File can include a subset of recipients - e.g. on each sync, any existing recipients will be deleted
File Format
File should be in a CSV format
File must contain all column headers - column headers doesn’t have to match the fields names below (using the configuration file we will map them to the right column names)
We recommend that the file name will be composed of name_date_uniqueId - e.g. recipients_20240829_1, recipients_20240829_2... We track the file names that we process so no file will be processed twice. using this format will allow better tracking and will support multiple file uploads at the same day (in case of changes/updates/fixes).
File Fields
The table below describes the supported recipient fields, are they required and any validation rules:
Param Name | Description | isOptional | Validations |
first name | Recipient's first name | Required | • Must be 1-50 characters long |
last name | Recipient's last name | Optional | See recipient’s first name validations |
Recipient's email | Optional, but required if sending via email | Valid email | |
mobile phone number | Recipient's phone | Optional, but mandatory if sending via phone | • Must include the country code |
birthday |
| Optional | Date (ISO 8601) |
working since |
| Optional | Date (ISO 8601) |
country |
| Required | use the two-letter code (ISO 3166-1) |
external id | Define the recipient’s external id column. | Optional | String values |
department |
| Optional | String values |
manager first name |
| Optional | See recipient’s first name validations |
manager last name |
| Optional | See recipient’s first name validations |
manager email |
| Optional | Valid email |
accounts | Connect between a specific recipient and a specific account(s) on the Snappy Dashboard. | Required | See more details on the Snappy Accounts section |
custom fields | Add additional information for each recipient | Optional | See more details on the Custom Fields section |
Snappy Accounts
The Snappy accounts column allows you to sync your recipients to a specific account on your Snappy dashboard, multiple accounts or all accounts.
There are 3 ways to use the account columns:
Populate the recipient row with the saved key
all accounts, to indicate it should be connected to all available accounts on the Snappy dashboard.Recommended: Populate the recipient row with distinct values from your system that will be mapped to a specific account in Snappy (see configuration file section). e.g. if a recipient has the value “CA Office” we can map it to the Snappy account named “California employees”. This option provides clients with the flexibility to map their recipients according to companies, cost centers, locations, departments and more. Use comma delimited list to map a recipient to multiple accounts. Using this option ensures the SFTP setup continues to work even if the Snappy account name is changed.
Populate the recipient row with the exact names of your Snappy accounts to indicated which are the accounts he should be associated with. Use comma delimited list to map a recipient to multiple accounts.
Custom Fields
In addition to the standard fields noted above, users can also add custom data that can be used to filter recipients at the camping level. for example, companies can pass the recipient loyalty tier to send different budget gifts to different loyalty levels.
To use custom fields you can simply add additional columns to the template file and add the relevant configurations (see configuration file section).
Custom fields must follow these restrictions:
All custom fields must be of type String
All fields must be defined in the configuration file
Apart from security validations there are no validations on the data in custom fields
Template File
see an example template file here -
Note: This file matches the configuration file appearing below
Detailed Solution
Folder Structure
Once the integration is setup, under a recipients folder, Snappy will create the following folder structure that will define the desired outcome for a specific file:
roster (Roster change)
add-and-update (Adding recipients)
delete (Deleting recipients)
In addition the recipients folder will hold the Snappy.recipients.config.json file which is defining the configuration for recipients uploads (see configuration section)
File processing
Each one of the above parents folders will have the following internal structure:
This structure represents the various stages of the file processing flow:
Uploads
This is the folder that files should be dropped into. It's important to drop files into this folder and not the root folder.
Processed-uploads
This folder will contain the original file for auditing purposes indicating that Snappy has successfully completed the processing of the file and any changes to it will not take effect.
Uploads-errors
Indicates any file that couldn’t be processed by Snappy, due to various reasons (e.g. File columns don’t match the configuration file)
A new text file with the same name will be created indicating the specific error reason
Processed-uploads-success
Includes all rows from the original file that were successfully processed
File name will be {originalFileName}_{processingDate}success{folderName} (e.g. recipients15_20231127_sn_1_20231128_success_gifts.csv)
Each row will have a new column indicating the id of the newly created entity (gift/recipient)
Processed-uploads-failed
Includes all rows from the original file that failed to be processed (see reports)
File name will be {originalFileName}_{processingDate}failed{folderName} (e.g. recipients15_20231127_sn_1_20231128_faileld_add-and-update.csv)
Each row will have a new column “failed process reason” with all the validation messages or error codes that caused the failure
Notifications
Our system can provide automatic notifications to multiple recipients on any upload errors or failures.
We recommend to signup for these notifications, so you can know the status of your automatic uploads and easily monitored and handled any issues. Currently this is done via the configuration file (see below), during the onboarding phase you can pass a list of recipients to be notified.
Configuration File
The root recipients folder will contain a file (Snappy.recipients.config.json) that will define the relevant configurations.
Example File:
Detailed Explanation:
Param Name | Description | isOptional |
sync_files | Defines if the automated Snappy process will process automatically all files that were uploaded |
|
accounts_mapping | allows users to pre-define the mapping between the relevant Snappy account and the distinct accounts column value |
|
recipients_csv_column_header_mapping | The main mapping of the file headers of the recipient | Required when using the add/roster options |
delete_recipients_csv_column_header_mapping | Define the relevant data to delete recipients | Required only when using the delete option |
email_notification_upload_errors | Comma delimited list of emails to get notified when a file had processing errors (upload_errors) | Yes |
email_notification_process_failures | Comma delimited list of emails to get notified when a file has recipients that failed to process (upload-processed-failed) | Yes |
delete_recipients_csv_column_header_mapping:
In order to successfully delete the correct recipients, each row (/configuration) must include one of the following:
Recipient id
ExternalId
Email
First name + birthday
First name + phone number
Snappy Dashboard
Recipients Page
Once the recipients have been successfully uploaded into the Snappy system, they will appear on the recipients page under a new data source named SFTP.
These new recipients:
Can be used across all relevant Snappy flows (e.g. send gift, campaigns).
Cannot be manually updated, since the SFTP sync is an automated process that will happen periodically and the next file will override all changes.
Note: the SFTP integration will not appear under the integrations page
Automated Campaigns
To unlock the full potential of the fact that these new SFTP recipients are automatically updated and managed, you can add them to an existing/new automated campaign:
Change the campaign recipients to the “Dynamically Added” Mode
Choose the new data source (SFTP) as the only data source
Once these changes are done, it means that the campaign’s recipients will be automatically updated on every SFTP sync - meaning you will never miss a gift and will never send one to someone that is no longer eligible for a gift.
Security
Our SFTP solution is built with the highest security considurations:
All communications are done in a secure way (SFTP protocol)
All files are encrypted at rest using SSE-KMS protocol
PGP encryption - We can support PGP encryption for files prior to them being sent to Snappy. In this case, we will provide our own Public key.
Limitations
This new product should support the following volumes:
Each file can support up to 50K recipients