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. Prepare Eligibility File: 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 that the end user 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.

Instructions for common automated file syncing tools

• 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.

Each Calm Business and Calm Health program has its own Partner Portal and issues a unique SFTP username for eligibility file uploads. The SFTP hostname is the same (sftp.ws.calm.com), but each program’s file must be sent to the correct username and portal. When setting up Calm Health, we recommend generating a new SSH key for that SFTP connection.

During a transition period from Calm Business to Calm Health, it is customary for a customer to send both a Calm Business and Calm Health Eligibility File in parallel. These are two separate SFTP eligibility files, capturing Eligibility for each program. Calm Business files follow a simpler format, typically including a unique identifier and/or email, alongside Segment data, while Calm Health files must follow our Default Eligibility File Format.

When ready to stop syncing for Calm Business, customers can disable automation or clear out the SSH key on the Calm Business side; Calm does not need to take any action. Note that Calm Health SFTP files often include PHI/HITRUST data, so Calm employees must follow HITRUST protocols for troubleshooting (never email files, use the Portal, and screenshare if needed).

Calm Health eligibility files are formatted differently from Calm Business eligibility files. Follow the instructions for your Calm product.

Calm Health

The Calm Health product has its own Eligibility File Setup Guide. For details on formatting a Calm Health eligibility file, please reference 'Setting up the Eligibility File' on page 3.

Calm Business

Calm Business eligibility files:

• must include all eligible members. Eligible members that are not included in the file will lose access to the Calm product.
• must be in CSV file format (file ends in .csv)
• can be named anything you want, but Calm recommends unique names for each file
• can be sent at the frequency and timing of your choice. Calm recommends sending a file at least monthly.
• must quote values that contain commas or apostrophes. For example, the value Vice President, Southwest Region, must be enclosed in quotes:"Vice President, Southwest Region". The same goes for the name O'Donnell, which must also be enclosed in quotes: "O'Donnell".

At a minimum, the eligibility file must include a column with a unique identifier for each user. This unique identifier can be an email address, employee ID, or any other unique value that the end user can enter into the app to uniquely identify themselves and gain access to Calm. Each row should have only one identifier.

Enable segmented reporting

Segmented reporting summarizes data across categories of people such as gender, job title, and location. Segments containing less than 10 signups will not display in reporting for privacy reasons.

Segmented reporting can be enabled by adding up to three additional columns in the eligibility file, for a maximum total of four columns. Eligibility files with segmented reporting must include a header row that labels the columns of data. The first column must contain the unique identifiers. The second, third, and fourth columns are for the segments (categories) that describe each user.

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 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.

The following configuration settings are required to connect to the Calm SFTP server and upload eligibility files:

• SFTP Server/Host: sftp.ws.calm.com
• SFTP Port: 22
• SFTP Username: Provided in Partner Portal after SSH key upload
• Directory: /inbound/eligibility
• Authentication: OpenSSH key (no password)
• PGP encryption: We do not support PGP encryption of 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

The command line can also be used to connect to the Calm SFTP server and upload files:

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 (Calm Business) and not_csv (Calm Health) : The uploaded file must end in .csv and be a valid CSV file.

• misplaced_file (Calm Business) or Unable to create or access resource (Calm Health): The file was uploaded to the incorrect directory. Please double check that you are uploading the file to the /inbound/eligibility/ directory.

• [column name]: [column name] should be in X format (Calm Health): The specified column name is not in the expected format. The message should state what format is expected.

• invalid_length (Calm Health): There are an unexpected number of columns in a given row.

• ef_upload_failure (Calm Business) and parser_err (Calm Health): 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 (Calm Business only): 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, Vice President, Southwest Region, must be enclosed in quotes: "Vice President, Southwest Region". Commas determine where one value ends and the next one begins.
  • Values with apostrophes and quotes: Values that contain apostrophes or quotes, for example, O'Donnell, must be enclosed in quotes: "O'Donnell". Apostrophes and quotes 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