Overview

Our FTP (File Transfer Protocol) solution offers a comprehensive platform for both managing recipients in your Snappy Dashboard or directly sending gifts to a list of recipients.

Key Features:

Gift Sends: This versatile system streamlines the process of sending gifts while ensuring a seamless and efficient experience for both senders and recipients. This is mainly aimed at companies that don’t want to manage recipients and would like to directly send gifts to eligible recipients.
Recipient Management: Users can easily add, update, and delete recipients information on the platform, without the cumbersome process of manually managing their recipients in the Dashboard. This is mainly aimed at companies that cannot use our HRIS integrations for one of the following reasons:
- They are not uploading employees data
- Their HR system is currently not supported by Snappy
- They have custom data build in their HR that isn’t supported by the HR’s APIs

Our SFTP solution is built on top of our robust APIs and provides standard enterprise grade security capabilities.

High level Solution Overview

This integration has few main parts:

Initial set up including server permissions and configuration files
Customers will upload a CSV file via SFTP/FTPS into the correct folder location, according to the desired outcome - send gifts, roster change, update recipients list or delete recipients
Snappy will automatically process these files and using our API capabilities will update the recipients in our system
Reporting: Snappy will upload a report on the outcome of the process (status, IDs, etc.)

Detailed Solution:
1. Server Details and Authentication

Clients will provide the following:

IP/server name
Username/Password to connect to server
Provide read and write permissions to Snappy user
Optional: White list the relevant Snappy IPs (prod and dev)

Folder Structure

Under the defined root folder, Snappy will create the following folder structure that will define the desired outcome of a specific file:

Gifts
- File should reflect all eligible recipients that will be sent a gift
- Snappy.config.json - defining the configuration for gift sends (see configuration section)
Recipients
- Roster change (roster): File should reflect the full company roster - e.g. 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. any existing recipients will be updated and new recipients will be created
- Deleting recipients (delete): File can include a subset of recipients - e.g. any existing recipients will be deleted
- Snappy.recipients.config.json - defining the configuration for recipients uploads (see configuration section)

File processing

Each one of the above parents folders will have the following internal structure, indicating 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.
- The file name will be composed of name_date_uniqueId. This will allow tracking and supporting multiple file uploads and will ensure we will not process the same file twice.
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
- indicating 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
unclaimed-gifts-reports
- this is an optional step only relevant for the gifts flow. This folder will contain a list of all gifts that haven’t been claimed to date.
  - 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 this specific row to fail processing (e.g. invalid first name, missing account, etc.)

Configuration File

Each one of the main folders will contain a specific configuration file that will define the relevant configurations:

Snappy.config.json (Gifts)

Param Name	Description	Example	isOptional
Sync_files	Defines if the automated Snappy process will process the files that were uploaded or not
Recipient_csv_column_header_mapping	The main mapping of the file headers to the gift recipient	See separated table
Campaign_tier_map	Defines the mapping between the gift tier name (see below) and an actual Snappy campaign id	"campaign_tier_map": { "25_GIFT": "123abc", "50_GIFT": "456def", "100_GIFT": "789ghi" }
Email_notification_list_on_error	Separated comma array of emails to get notified when a file has failed to process (upload_errors or upload-processed-failed)	"email_notification_list_on_error": ["test@org.com", "test2@org.com"]	Yes
Generate_unclaimed_report	Define if we should automatically add all unclaimed gift to date		Yes

Recipient_csv_column_header_mapping:

Param Name	Description	Example	isOptional
First_name	Recipient's first name
Last_name	Recipient's last name		Yes
Email	Recipient's email		Yes, but mandatory if sending via email
Mobile_phone_number	Recipient's phone		Yes, but mandatory if sending via phone
Gift_tier	The gift tier that the recipient should receive (associated with a specific campaign via the Campaign_tier_map param)	"25_GIFT”
External_fields	Define the recipient’s external id column. Note that you can combine multiple columns into a single id	"external_fields": [ { "column_header_name": "Transaction Id" }, { "column_header_name": "Account number" } ]	Yes

Snappy.recipients.config.json (Recipients)

Param Name	Description	Example	isOptional
Sync_files	Defines if the automated Snappy process will process the files that were uploaded or not	true
recipients_csv_column_header_mapping	The main mapping of the file headers to the gift recipient	See separated table	Yes, but mandatory if using the add/roster options
delete_recipients_csv_column_header_mapping	Define the relevant data to delete recipients, Including the fields: id First_name Last_name Email Mobile_phone_number External_id birthday	"delete_recipients_csv_column_header_mapping": { "first_name": "First Name", "last_name": "Last Name", "email": "Email", "mobile_phone_number": "Phone", "external_id": "Employee ID", "birthday": "Birthday" }	Yes, but mandatory if using the delete option
Email_notification_list_on_error	Comma delimited list of emails to get notified when a file has failed to process (upload_errors or upload-processed-failed)	"email_notification_list_on_error": ["test@org.com", "test2@org.com"]	Yes
custom_fields	Define the recipient’s custom fields. Must be of type String (see more info on the custom fields)	"custom_fields": [ { "column_header_name": "Transaction Id" }, { "column_header_name": "Account number" } ]	Yes

recipients_csv_column_header_mapping:

Param Name	Description	Example	isOptional
First_name	Recipient's first name
Last_name	Recipient's last name		Yes
Email	Recipient's email		Yes, but mandatory if sending via email
Mobile_phone_number	Recipient's phone		Yes, but mandatory if sending via phone
birthday			Yes
working_since			Yes
country
external_id	Define the recipient’s external id column.
department
accounts	Comma delimited list of relevant snappy accounts to which this recipient should be associated with
manager_first_name
manager_last_name
manager_email

delete_recipients_csv_column_header_mapping:

Param Name	Description	Example	isOptional
id	The id of the recipient provided when it was created
First_name	Recipient's first name
Last_name	Recipient's last name
Email	Recipient's email
Mobile_phone_number	Recipient's phone
birthday
external_id	Define the recipient’s external id column.

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

Fields Value and Validations

File should reflect only the relevant recipients for to update

Each file will contain the following fields:

Field	description	format	Validations	isOptional
First Name		String	Must be 1-50 characters long Supports alphabetical chars Supports diacritics support .’()- and spaces in any amount and location in name Not supporting numbers and special chars - e.g. /\!@#$%^&*><?}{][\|_
Last Name		String	See recipient’s first name validations	Yes
email		email	Valid email	Yes* Mandatory to use the email sending method Or If using the email&SMS sending method
Mobile Phone			Must include the country code + Sign is optional	Yes* Mandatory to use the phone sending method Or If using the email&SMS sending method
Birthday		Date	(MM/DD/YYYY)	Yes* Mandatory to use the birthday campaign
Working Since		Date	(MM/DD/YYYY) Can be up to 3 years in the future	Yes* Mandatory to use the anniversary/new hire campaigns
Country		Country code	use the two-letter code (ISO 3166-1)
ExternalId	An external id used by the customer to track their recipients	String	-	Yes
Department		String		Yes
Accounts	All accounts that the recipient will appear in	Comma delimited list of accounts	Must be an existing account in Snappy Must be an account the uploading user has access to
Manager First name		String	See recipient’s first name validations	Yes
Manager Last Name		String	See recipient’s first name validations	Yes
Manager email		email	Valid email	Yes

Custom Fields

In addition to the standard fields noted above, users can also add new custom data that can be used to filter recipients in the camping level.

Custom fields must follow these restrictions:

All custom fields must be of type String
All fields must be of defined in the configuration file
Apart from security validations there are no validations on the data in custom fields

Snappy Dashboard
1. Gifts

All successful gifts will be shown under the gift activity tab on the Snappy dashboard and will be marked as gifts sent via FTP.

Recipients

Once the recipients have been successfully uploaded into the Snappy system, they will appear under a new data source named FTP. These new recipients:

can be used across all relevant Snappy flows (e.g. send gift, campaigns).
Since the FTP sync is an automated process that will happen periodically, these recipients cannot be manually updated (as the next file will override all changes).