Instructions for Single Entity

Introduction

When you want to manage just one company, we call this "Single Entity".

Through Wellhub's SFTP Server, you can perform certain operations for a specific company. The interaction with the SFTP Server is simple - it's a file system where you can navigate between directories, list, upload, and download files.

These are the operations supported on the SFTP Server for a Single Entity:

Single entity - Eligibility Single entity - Payroll Single entity - Reporting

  • Encrypt the content of files you upload and/or download. See Encryption.

The following sections provide more details on each operation.

Overview of the directory structure

File Structure
1/
2└── {CompanyID}/
3    ├── employees/
4    │   ├── download/
5    │   │   └── eligible-list.zip
6    │   └── upload/
7    │       ├── all/
8    │       ├── new/
9    │       └── status.csv
10    ├── payroll/
11    │   ├── leavers/
12    │   │   ├── {Timestamp}_gympass_partial_payroll_deduction_{InvoiceID}.csv
13    │   │   ├── {Timestamp}_gympass_partial_payroll_deduction_{InvoiceID}.sha256sum
14    │   │   └── ...
15    │   ├── {Timestamp}_{YYYY-MM-DD}_{YYYY-MM-DD}_gympass_payroll_deduction_{InvoiceID}.csv
16    │   ├── {Timestamp}_{YYYY-MM-DD}_{YYYY-MM-DD}_gympass_payroll_deduction_{InvoiceID}.sha256sum
17    │   └── ...
18    └── reports/
19        └── gympass-year-report.zip

Employees

Through the SFTP Server, you can manage the employees of a specific company.
Some supported operations are:

  • Full file - Update the entire employee base.
  • Newcomers - Add new employees.
  • Leavers - Remove former employees.
  • Download eligible list - Download the list of registered employees.
  • Upload history - Download the status of uploads.

Get to know more regarding Eligibility and the mandatory fields in the Eligibility section.

Overview of the employees directory structure

Directory Structure
1/
2└── {CompanyID}/
3    ├── employees/
4    │   ├── download/
5    │   │   └── eligible-list.zip
6    │   └── upload/
7    │       ├── all/
8    │       ├── new/
9    │       └── status.csv
10    ├── payroll/
11    └── reports/
  • The initial directory is the root /.
  • /{CompanyID} is the directory representing the company being managed. The directory name is the UUID of the company.
  • /{CompanyID}/employees is the directory where we can manage the employees of this company, for organizational purposes.
  • /{CompanyID}/employees/upload/all is the directory where we can update the employee base by uploading a Fullfile file.
  • /{CompanyID}/employees/upload/new is the directory where we can update the employee base by uploading a Newcomers file.
  • /{CompanyID}/employees/upload/leavers is the directory where we can update the employee base by uploading a Leavers file.
  • /{CompanyID}/employees/upload/status.csv is the file where we can download and view the status of each upload.
  • /{CompanyID}/employees/download/eligible-list.zip is the file where we can download and view the list of employees for this company.

Upload a Newcomers file

Once connected to the SFTP Server, we can then add new employees. For that, you'll need to:

  1. Navigate to the "/{CompanyID}/employees/upload/new" directory for this company.
Terminal
1cd /{CompanyID}/employees/upload/new
  1. The command below uploads the employees.csv file. Replace "employees.csv" with your file containing the list of new employees.
Terminal
1put employees.csv

File Organization

sftp-se-employees-example.png

Upload a Full file

Once connected to the SFTP server, you'll be able to manage all of the employees data. This includes adding, removing, and editing employee records within the file.

Attention!

Since "Fullfile" is a replace operation, it requires extra attention.

The SFTP Server expects the "Full file" to contain all the employees already registered for the company. Any employee that is in the database but not in the file will be removed from the database.
Any employee that exists in the database but cannot be identified in the file by the SFTP Server will be removed from the database. For example, if the SFTP Server knows an employee by the name of "Ciara Walter" through the email "ciara.walter@coolcompany.com," but this email is spelled incorrectly in the file, the SFTP Server will not be able to identify this employee in the database, and they will be removed. Employees found in the file but not in the database will be added.
Employee records present in both the file and the database will be updated with any changes found in the file.

Note: Although it's possible to remove employees by uploading a "Fullfile", it's not possible to remove all employees using this method.

  1. Navigate to the "/{CompanyID}/employees/upload/all" directory for this company.
Terminal
1cd /{CompanyID}/employees/upload/all
  1. The command below uploads the all-employees.csv file and replaces the existing one with your file containing the full list of employees for a company.
Terminal
1put all-employees.csv

File Organization

sftp-se-employees-example.png

Download the status file

Once connected to the SFTP Server, we can download the status of the most recent uploads. This is very useful for checking if a specific upload was successful or if it failed.

  1. Navigate to the "/{CompanyID}/employees/upload" directory for this company.
Terminal
1cd /{CompanyID}/employees/upload
  1. The command below downloads the status.csv file.
Terminal
1get status.csv

File Organization

sftp-se-status-example.png

Download the eligible list file

Once connected to the SFTP Server, we can then download the complete list of employees for the company. With this file you'll both be able to list all the existing employees in a company, as well as use that as a base to add or remove employees for a "Fullfile" operation".

  1. Navigate to the "/{CompanyID}/employees/download" directory for this company.
Terminal
1cd /{CompanyID}/employees/download
  1. The command below downloads the eligible-list.zip file. Extract the zip file to access the list.
Terminal
1get eligible-list.zip

Payroll

Through the SFTP Server, you can download the payroll information for the employees in a specific company. Some supported operations are:

  • Deduction file - Download existing payroll files for a specified date range.
  • Deduction file for leavers - Download any existing payroll files for employees who have been removed.

Note: Only employees with payroll enabled will appear in the payroll files.

Get to know more regarding Payroll on the Payroll section.

Overview of the payroll file structure

File Structure
1/
2└── {CompanyID}/
3    ├── employees/
4    ├── payroll/
5    │   ├── leavers/
6    │   │   ├── {Timestamp}_gympass_partial_payroll_deduction_{InvoiceID}.csv
7    │   │   ├── {Timestamp}_gympass_partial_payroll_deduction_{InvoiceID}.sha256sum
8    │   │   └── ...
9    │   ├── {Timestamp}_{YYYY-MM-DD}_{YYYY-MM-DD}_gympass_payroll_deduction_{InvoiceID}.csv
10    │   ├── {Timestamp}_{YYYY-MM-DD}_{YYYY-MM-DD}_gympass_payroll_deduction_{InvoiceID}.sha256sum
11    │   └── ...
12    └── reports/
  • The initial directory is the root /.
  • /{CompanyID} is the directory representing the company being managed. The directory name is Wellhub's UUID for the company.
  • /{CompanyID}/payroll is the directory where the payroll files are available for download.
  • /{CompanyID}/payroll/{Timestamp}_{YYYY-MM-DD}_{YYYY-MM-DD}_gympass_payroll_deduction_{InvoiceID}.csv is a payroll file. The name consists of a timestamp (for sorting purposes), the start and end dates of the period, and the UUID of the invoice.
  • /{CompanyID}/payroll/leavers/{Timestamp}_gympass_partial_payroll_deduction_{InvoiceID}.csv is a payroll file for removed employees. The name consists of a timestamp and an invoice's UUID.

Download payroll files

Once connected to the SFTP Server, we can download the available payroll files for this company.

  1. Navigate to the "/{CompanyID}/payroll/" directory for this company.
Terminal
1cd /{CompanyID}/payroll
  1. The command below downloads a payroll file.
Terminal
1get {Timestamp}_{YYYY-MM-DD}_{YYYY-MM-DD}_gympass_payroll_deduction_{InvoiceID}.csv

File Organization

sftp-se-payroll-example.png

Download payroll files of removed employees

Once connected to the SFTP Server, we can download the payroll files for employees who have been removed from this company.

  1. Navigate to the "/{CompanyID}/payroll/leavers/" directory for this company.
Terminal
1cd /{CompanyID}/payroll/leavers
  1. The command below downloads a payroll file.
Terminal
1get {Timestamp}_gympass_partial_payroll_deduction_{InvoiceID}.csv

Verify Integrity via checksum

Payroll files offer an optional integrity check after download. This verification ensures the file remains unaltered during transfer, guaranteeing data accuracy. Each payroll file has its own SHA-256 hash stored in a file with the same name and with a .sha256sum extension.

To validate the integrity, download both files: the payroll file and its respective hash (present in the file with the same name and .sha256sum extension).
The process is the same for both "payroll" and "payroll/leavers."

  1. Once in the "/{CompanyID}/payroll/" directory, download the files.
Terminal
1get {Timestamp}_{YYYY-MM-DD}_{YYYY-MM-DD}_gympass_payroll_deduction_{InvoiceID}.csv
2get {Timestamp}_{YYYY-MM-DD}_{YYYY-MM-DD}_gympass_payroll_deduction_{InvoiceID}.sha256sum
  1. Generate the hash of the payroll file using the sha256sum CLI tool.
Terminal
1sha256sum {Timestamp}_{YYYY-MM-DD}_{YYYY-MM-DD}_gympass_payroll_deduction_{InvoiceID}.csv
  1. You can now compare the generated hash with the hash found inside the {Timestamp}_{YYYY-MM-DD}_{YYYY-MM-DD}_gympass_payroll_deduction_{InvoiceID}.sha256sum file. They should be the same.

Reports

Through the SFTP Server, you can download usage data for the employees of a specific company. This is important to track employee engagement with the Wellhub services.

Overview of the reports file structure

File Structure
1/
2└── {CompanyID}/
3    ├── employees/
4    ├── payroll/
5    └── reports/
6        └── wellhub-year-report.zip
  • The initial directory is the root /.
  • /{CompanyID} is the directory representing the company being managed. The directory name is the UUID of the company.
  • /{CompanyID}/reports/wellhub-year-report.zip is the report file for the usage of employees for this company.

Download report file

Once connected to the SFTP Server, you can then download any available reports for this company.

  1. Navigate to the "/{CompanyID}/reports/" directory for this company.
Terminal
1cd /{CompanyID}/reports
  1. The command below downloads the yearly usage report file.
Terminal
1get gympass-year-report.zip

File Organization

File name: start date + end date + report name + wellhub Example: 20231209-20241209_subscription-history-wellhub.csv

This report contains information from the last 12 months on:

  • Engagement rates: A daily snapshot of the total number of eligibles, members, subscribers, and family-members (if applicable).
  • Check-ins: A full list of the check-ins in Wellhub partners, for both physical and virtual activities. Includes family-member data (if applicable).
  • Subscribers snapshot: A full list of the subscribers and their subscription details, including the plan selected and its price. Includes family-member data (if applicable).
  • Subscription history: A full list of transaction events related to an employee’s subscription, such as: first subscription, upgrade, downgrade, pause, cancellation, and new subscription. Includes family-member data (if applicable).