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    │       ├── error-details/
9    │       │   ├── {Timestamp}-{Uploaded-Filename}.csv
10    │       │   └── ...
11    │       ├── leavers/
12    │       ├── new/
13    │       └── status.csv
14    ├── payroll/
15    │   ├── {Timestamp}_{YYYY-MM-DD}_{YYYY-MM-DD}__gympass_payroll_deduction_{InvoiceID}.csv
16    │   ├── ...
17    │   ├── leavers/
18    │   │   ├──{YYYY-MM-DD}_{YYYY-MM-DD}_gympass_partial_payroll_deduction_{InvoiceID}.csv
19    │   │   └── ...
20    │   └── ...
21    └── reports/
22        └── 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.
Error details - Get the details for the errors found during an upload and what's required to address them.

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    │       ├── error-details/
9    │       │   ├── {Timestamp}-{Uploaded-Filename}.csv
10    │       │   └── ...
11    │       ├── leavers/
12    │       ├── new/
13    │       └── status.csv
14  └── ...

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/upload/error-details is the directory where we can download the errors of a rejected upload.
/{CompanyID}/employees/upload/{Timestamp}-{Uploaded-Filename}.csv is the error report of a specific 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 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.

Navigate to the "/{CompanyID}/employees/upload/all" directory for this company.

Terminal
1cd /{CompanyID}/employees/upload/all

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

Upload a Newcomers file

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

Navigate to the "/{CompanyID}/employees/upload/new" directory for this company.

Terminal
1cd /{CompanyID}/employees/upload/new

The command below uploads the new-employees.csv file. Replace "new-employees.csv" with your file containing the list of new employees.

Terminal
1put new-employees.csv

File Organization

Upload a Leavers file

Once connected to the SFTP Server, we can remove existing employees. For that, you'll need to:

Navigate to the "/{CompanyID}/employees/upload/leavers" directory for this company.

Terminal
1cd /{CompanyID}/employees/upload/leavers

The command below uploads the remove-employees.csv file. Replace "employees.csv" with your file containing the list of employees to be removed.

Terminal
1put remove-employees.csv

File Organization

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.

Navigate to the "/{CompanyID}/employees/upload" directory for this company.

Terminal
1cd /{CompanyID}/employees/upload

The command below downloads the status.csv file.

Terminal
1get status.csv

File Organization

Download the error details

Once connected to the SFTP Server, you can download the files with error details of a rejected upload. For example, you uploaded a Fullfile, checked the status.csv, and saw that this upload failed. You can check the reason for the failure using the error details.

Navigate to the "/{CompanyID}/employees/upload/error-details" directory for this company.

Terminal
1cd /{CompanyID}/employees/upload/error-details
2ls

The command below downloads the error details file.

Terminal
1get {Timestamp}_{Uploaded file name}.csv

File Organization

It contains information about the type of error and where the error is.

Company Tax ID	Error Source	Line ID	Field Name	Error Type	Error Description
N/A	This refers at what level the error occurred: Upload error or Client error - impacted the whole file, Input error - refers to line errors	The line # will be displayed if applicable to the Error Source + Type	The impacted field will be displayed if applicable to the Error Source + Type	This refers to the type of error found	Will explain in detail what needs to be addressed

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

Navigate to the "/{CompanyID}/employees/download" directory for this company.

Terminal
1cd /{CompanyID}/employees/download

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    │   │   ├── ...
8    │   │   └── ...
9    │   ├── {Timestamp}_{YYYY-MM-DD}_{YYYY-MM-DD}__gympass_payroll_deduction_{InvoiceID}.csv
10    │   └── ...
11    └── ...

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.

Navigate to the "/{CompanyID}/payroll/" directory for this company.

Terminal
1cd /{CompanyID}/payroll

The command below downloads a payroll file.

Terminal
1get {Timestamp}_{YYYY-MM-DD}_{YYYY-MM-DD}_gympass_payroll_deduction_{InvoiceID}.csv

File Organization

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.

Navigate to the "/{CompanyID}/payroll/leavers/" directory for this company.

Terminal
1cd /{CompanyID}/payroll/leavers

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

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

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

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.

Navigate to the "/{CompanyID}/reports/" directory for this company.

Terminal
1cd /{CompanyID}/reports

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