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:

Creation and updates

Loading diagram...

Details

Loading diagram...

Flows | Payroll

For clients with payroll as payment method, every billing cycle the deduction file and deduction file for leavers (in case there were employee removals) will be provided. This is a list of all the employees that paid for a Wellhub subscription with paycheck in a given billing period. This will then be used by the client to discount the subscription amount when running payroll.

Loading diagram...

  • Note: for now, only the .zip is available for MEs (with individual files within it). In the future, there will also be a consolidated file.

Flows | Reporting

The reporting flow is crucial to track the usage of the Wellhub benefit, as it provides a view on the adoption of the solution, as well as the subscriptions data and check-ins of employees and family-members (in case the client has that SKU).

Loading diagram...

  • 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

TEXT
/
└── {CompanyID}/
    ├── employees/
    │   ├── download/
    │   │   └── eligible-list.zip
    │   └── upload/
    │       ├── all/
    │       ├── error-details/
    │       │   ├── {Timestamp}-{Uploaded-Filename}.csv
    │       │   └── ...
    │       ├── leavers/
    │       ├── new/
    │       └── status.csv
    ├── payroll/
    │   ├── YYYYMM_wellhub_payroll_deduction.csv
    │   ├── ...
    │   ├── leavers/
    │   │   ├── YYYYMM_wellhub_partial_payroll_deduction.csv
    │   │   └── ...
    │   └── ...
    └── reports/
        └── 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 (status.csv) - Download the status of uploads.
  • Error details - Get the details for 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

TEXT
/
└── {CompanyID}/
    ├── employees/
    │   ├── download/
    │   │   └── eligible-list.zip
    │   └── upload/
    │       ├── all/
    │       ├── error-details/
    │       │   ├── {Timestamp}-{Uploaded-Filename}.csv
    │       │   └── ...
    │       ├── leavers/
    │       ├── new/
    │       └── status.csv
    └── ...
  • 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 Full 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.

  1. Navigate to the /{CompanyID}/employees/upload/all directory for this company.
BASH
cd /{CompanyID}/employees/upload/all
  1. Upload the all-employees.csv file and replace the existing one with your file containing the full list of employees for a company.
BASH
put all-employees.csv

File Organization

Example file - all-employees.csv
NameEmailNational IDEmployee IDDepartmentPayroll IDCost centerOffice zip codePayroll Enabled
Freyja Obrienfreyja.obrien@coolcompany.com257.573.080-52331234UX13241-114-87304571-926Yes
Ciara Walterciara.walter@coolcompany.com700.594.980-30834372Engineering73751-114-77304571-926No

Upload a Newcomers file

Once connected to the SFTP Server, we can then add new employees.

  1. Navigate to the /{CompanyID}/employees/upload/new directory for this company.
BASH
cd /{CompanyID}/employees/upload/new
  1. Upload the new-employees.csv file. Replace new-employees.csv with your file containing the list of new employees.
BASH
put new-employees.csv

File Organization

Example file - new-employees.csv
NameEmailNational IDEmployee IDDepartmentPayroll IDCost centerOffice zip codePayroll Enabled
Freyja Obrienfreyja.obrien@coolcompany.com257.573.080-52331234UX13241-114-87304571-926Yes
Ciara Walterciara.walter@coolcompany.com700.594.980-30834372Engineering73751-114-77304571-926No

Upload a Leavers file

Once connected to the SFTP Server, we can remove existing employees.

  1. Navigate to the /{CompanyID}/employees/upload/leavers directory for this company.
BASH
cd /{CompanyID}/employees/upload/leavers
  1. Upload the remove-employees.csv file. Replace employees.csv with your file containing the list of employees to be removed.
BASH
put remove-employees.csv

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.
BASH
cd /{CompanyID}/employees/upload
  1. Download the status.csv file.
BASH
get status.csv

File Organization

It contains information about the status of the last 20 uploads (regardless of their source).

filenamebatch_typedate_and_timeprocessing_statussource
Composition between the timestamp and the uploaded file nameUpload type, can be: full_file, newcomers or leavers (exclusive to single entities)Date and time when the upload occurredStatus can be: Validating, Validated, Pending, Processing, Succeeded, Succeeded with errors (exclusive to channel partners), Rejected, Deleted, Approval_RequestedSource of the upload, can be SFTP or W4C

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.

  1. Navigate to the /{CompanyID}/employees/upload/error-details directory for this company.
BASH
cd /{CompanyID}/employees/upload/error-details
ls
  1. List the available error files.
BASH
ls
  1. Download the error details file.
BASH
get {Timestamp}_{Uploaded file name}.csv

File Organization

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

Company Tax IDError SourceLine IDField NameError TypeError Description
N/AThis refers at what level the error occurred: Upload error or Client error - impacted the whole file, Input error - refers to line errorsThe line # will be displayed if applicable to the Error Source + TypeThe impacted field will be displayed if applicable to the Error Source + TypeThis refers to the type of error foundWill 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.

  1. Navigate to the /{CompanyID}/employees/download directory for this company.
BASH
cd /{CompanyID}/employees/download
  1. Download the eligible-list.zip file. Extract the zip file to access the list.
BASH
get 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

TEXT
/
└── {CompanyID}/
    ├── employees/
    ├── payroll/
    │   ├── leavers/
    │   │   ├── YYYYMM_wellhub_partial_payroll_deduction.csv
    │   │   └── ...
    │   ├── YYYYMM_wellhub_payroll_deduction.csv
    │   └── ...
    └── ...
  • 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/YYYYMM_wellhub_payroll_deduction.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/YYYYMM_wellhub_partial_payroll_deduction.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.
BASH
cd /{CompanyID}/payroll
  1. Download a payroll file.
BASH
get YYYYMM_wellhub_payroll_deduction.csv

File Organization

Example file - YYYYMM_wellhub_payroll_deduction.csv
Full nameEmailNational IDEmployee IDAmount dueDepartmentCost centerOffice zip codePayroll ID
Freyja Obrienfreyja.obrien@coolcompany.com257.573.080-52331234R$ 449,90UX132404571-9261324
Ciara Walterciara.walter@coolcompany.com700.594.980-30834372R$ 449,90Engineering737504571-9267375

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.
BASH
cd /{CompanyID}/payroll/leavers
  1. Download a payroll file.
BASH
get YYYYMM_wellhub_partial_payroll_deduction.csv

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

TEXT
/
└── {CompanyID}/
    ├── employees/
    ├── payroll/
    └── reports/
        └── 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.
BASH
cd /{CompanyID}/reports
  1. Download the yearly usage report file.
BASH
get gympass-year-report.zip

File Organization

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

The reports contain 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).