These instructions describe the steps to configure a SFTP connection to the Calm SFTP server with the purpose of automating eligibility file uploads.

Steps

1. Eligibility File Details: An eligibility file is a list of users who are eligible to redeem the Calm benefit. This file must contain a unique identifier for each user and a set of eligibility fields that the end user will know and can enter into the app to uniquely identify themselves and gain access to Calm.
2. Set SFTP Status Notifications: Assign contact email addresses to receive updates for file successful and failed file transfer.
3. Configure technical contact in Partner Portal: Enter the email address for your technical contact by clicking the "Add new admin" button. A modal will display and "First Name", "Last Name", and "Email" are required. The technical contact will receive instructions to access the Partner Portal and finish the SFTP configuration setup.
4. Generate SSH key: SSH keys are used for secure authentication and must be in OpenSSH format. Generate an SSH key pair (public and private key) using a tool like OpenSSH, PuTTYgen, or ssh-keygen. Share the public key with the SFTP server administrator and keep the private key secure.
5. Share public SSH key with Calm: Provide Calm with your public key in the Calm Partner Portal. We will configure our server to recognize your public key for authentication purposes.
6. Test the connection: Use SFTP client software such as FileZilla, WinSCP, or Cyberduck to test the SFTP connection to the server. Enter the server's hostname or IP address, port number, your username, and select the private key file for authentication. Verify that the connection works properly.
7. Configure automated file syncing: Configure your Human Resource Information System (HRIS), tool, or script to automate these operations. We recommend syncing your file at least monthly.

Common automated file syncing tool instructions

• Workday Instructions
• SAP: Setting Up Outbound SFTP Connections
• Google SFTP Connector

Troubleshooting

• SFTP connection errors: Fix common problems connecting to the Calm SFTP server.
• SFTP upload errors: Fix common problems uploading the file.

• File must be a full file of all eligible members only
• This file must be in a .csv format
• File can be any name. We recommend adding a timestamp
• Frequency and timing of sending the file is at your discretion. Calm recommends sending file at least monthly
• Values that contain commas, for example, Susan, Bob and Bill, must be enclosed in quotes: "Susan, Bob and Bill"

The eligibility file must contain at a minimum:

• Column A: Include the email or unique identifier of every person you want to make Calm available to starting on row 2.
• Cell A1: Include a column header (ie Email Address or Employee ID)

Optional configuration:

Use columns B, C and D to add the employee in column A to a segment to add up to three additional segmented reporting such as department, location, gender

• Each additional column must contain a unique header and these additional columns should not include any identifying information (ie. first name, last name, SSN)
• Segments containing less than 10 signups will not display in reporting, for privacy reasons

Calm can send file transfer status emails to your preferred contacts. Enter the email addresses for these contacts separated by a comma (example: jane.doe@company.com, john.doe@company.com).

Enter the email address for your technical contact by clicking “Add new admin” button. A modal will display and First Name, Last Name, Email are required. The technical contact will receive instructions to access the Partner Portal and finish the SFTP configuration setup.

Please ensure all public SSH keys submitted in Partner Portal are in OpenSSH format. Below are instructions on how to generate an SSH key.

Mac/Linux systems

1. Run the following command in a terminal window to generate an SSH key in OpenSSH format: ssh-keygen -t ed25519 -C 'your_email@example.com' or ssh-keygen -t ed25519
2. Create a passphrase or decline when prompted. The passphrase is optional. If you choose to create a passphrase, you wil be required to enter that passphrase every time you connect with SSH to Calm’s SFTP server.
3. Type open ~/.ssh/ to open the folder where your SSH keys are stored. Inside that folder is a file named id_rsa.pub. This is the public SSH key that you will enter into the Calm Partner Portal

Windows systems

1. Download PuTTY and PuTTYGen to generate your OpenSSH RSA key on Windows
2. Select "EdDSA" as the type of key to generate
3. Enter "Ed25519 (255bits)" for the number of bits
4. Click "Generate" and follow PuTTY's instructions to create the key. Wait for key generation to complete.
5. Click "Save public key" and then "Save private key" to save both as a file on your computer — the private key is what you'll use to authenticate and the public key is what you'll enter into the Calm Partner Portal.
6. Copy the contents of the field "Public key" for pasting into OpenSSH authorized_keys file from PuTTY. Now you're ready to enter your copied public key into the Calm Business Partner Portal.

For more detailed instructions, visit Github's guide on generating a new SSH key

1. Copy the generated public SSH key
2. Log into the Calm Partner Portal
3. Paste the generated public SSH key into the "SSH key" field
4. Click the "Save Configuration" button. Your SFTP Username and SFTP URL will be displayed

1. Locate your SFTP URL and username. Select the private key file for authentication that corresponds to the public SSH key entered in Calm Partner Portal.

   Your SFTP URL is listed on the SFTP integration page at partner.calm.com

2. On the command line from the machine with the private key counterpart to the public SSH key you provided Calm, you can use:

   sftp -oHostKeyAlgorithms=+ssh-rsa sftp_username@sftp.ws.calm.com.

There are a variety of Human Resource Information Systems (HRIS), software tools, and scripts that can be used to connect to the Calm SFTP server and upload eligibility files.

Consult the documentation of the respective tools for detailed instructions and troubleshooting assistance. Here are instructions for a few common tools:

• Workday Instructions
• SAP: Setting Up Outbound SFTP Connections
• Google SFTP Connector

• Command Line:

  sftp -oHostKeyAlgorithms=+ssh-rsa your-sftp-username@sftp.ws.calm.com <<< $'put /path/to/local/file/csv /inbound/eligibility/any-filename.csv

  Note that you must upload your file to the /inbound/eligibility/ folder.

  Attempts to upload the file to other directories, upload folders to that directory, or upload files that are not of type CSV will cause errors.

  Avoid:

  • /inbound/eligibility/any-filename.txt: incorrect file format
  • /inbound/eligibility/some-other-folder/any-filename.csv: nested folders
  • /any-filename.csv: incorrect remote directory
  • /inbound/elgibility/any-filename-YYYY-MM-DD.csv: misspelled directory

  Do:

  • /inbound/eligibility/any-filename-YYYY-MM-DD.csv

Calm sends alert emails to the technical contact configured in the Calm Partner Portal whenever a file upload fails.

Common user errors

• incorrect_file_type: The uploaded file must end in .csv and be a valid csv file.
• misplaced_file: The file was uploaded to the incorrect directory. Please double check that you are uploading the file to the /inbound/eligibility/ directory.

• ef_upload_failure: There is a problem with the format of the file you are trying to upload. We only accept CSV (comma-separated values) files. Please double check that you are uploading a valid CSV file. Some common problems include:

  • Too many columns: We allow a maximum of one column for the employee identifier and three segmentation columns for a total of four columns.
  • Inconsistent column length: Every row must have the same number of columns. This error is sometimes caused by values with commas, addressed in the following item.
  • Values with commas: Values that contain commas, for example, Susan, Bob and Bill, must be enclosed in quotes: "Susan, Bob and Bill". Commas determine where one value ends and the next one begins.

Internal errors

The following errors suggest a internal error on Calm’s end. Please contact your Customer Success Manager and they will escalate this to our engineering team:

• copy_sftp_object_failure
• delete_sftp_object_failure
• incorrect_partner_state_folder
• invalid_sftp_message_event
• missing_sftp_object_in_bucket
• no_records_on_message
• partner_not_eligibility_file_integration_type
• partner_not_found_in_db

SFTP connection errors indicate problems establishing the SFTP connection. These errors are surfaced in the tool you are using to make the connection and do not result in emails to your technical contact.

Connection Error: Unable to negotiate error

Specify the host key algorithm as ssh-rsa. Implementation will vary. On the command line it is -oHostKeyAlgorithms=+ssh-rsa

Connection Error: Any request for a password.

Double-check your SFTP username to make sure it is correct. Make sure that you have uploaded the correct SFTP public key to the Calm Partner Portal and that you are attempting the connection from the machine that has the private key counterpart to the public key you shared.

Firewall error

The Calm SFTP server needs to be able to get past your firewall to successfully make a connection. If you're not able to connect to the server, your firewall is likely blocking the connection and you may see the following error message: Something went wrong. Please try again.

Please allowlist the domain for the Calm SFTP server: sftp.ws.calm.com. Then run the following command on the command line to see if your organization's firewall is still blocking connections:

If you're able to connect successfully, you're all set! Your firewall settings are optimal for a connection.

OpenSSH key error

Ensure you're using the correct OpenSSH key type, in the correct format. Keys must be RSA public keys in the OpenSSH format.

If you attempt to submit the wrong SSH key type, you may see the following error message when attempting to establish a connection:SSH key must adhere to OpenSSH format. Here is a valid OpenSSH key:

Make sure you provide the Calm server with the public SSH key that corresponds to your private key to connect to the Calm SFTP server.

Multiple SSH key error

A single public key must be entered that matches your organization's single private key. If multiple public keys are sent, or you have more than one private key for your public key, you may experience the following issues:

• FileZilla is unable to connect on a Mac because multiple multiple keys are present. To prevent FileZilla from using other keys, start the program in the Terminal App using the following command:
  SSH_AUTH_SOCK="" open /Applications/FileZilla.app
• Socket connection closed. Use this command to test whether you can successfully connect:
  sftp -v -o "IdentitiesOnly yes" -F/dev/null -i <PRIVATE_KEY_FILE> <SFTP-username> @sftp.ws.calm.com