Instructions for Multi Entities

Introduction

When you want to manage multiple companies in one go (aggregated), we call this "Multi Entity".

Through Wellhub's SFTP Server, you can perform certain operations for a specific company, or for all your managed companies at the same time.

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 Multi Entities:

Multi entity - Eligibility Multi entity - Payroll

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

  • To manage multiple companies within the multi-entity structure, you must select the ‘All companies’ view when generating the SFTP keys. See Getting Started All companies view.png

The following sections provide more details on each operation.

Overview of the file structure

File Structure
1/
2├── multientity/
3│   ├── employees/
4│   │   └── upload/
5│   │       ├── all/
6│   │       ├── error-details/
7│   │       │   ├── {Timestamp}-{Uploaded-Filename}.csv
8│   │       │   └── ...
9│   │       └── status.csv
10│   └── payroll/
11│       ├── leavers/
12│       │   ├── {company name}_gympass_partial_payroll_deduction_{InvoiceID}.csv
13│       │   ├── {company name}_gympass_partial_payroll_deduction_{InvoiceID}.sha256sum
14│       │   └── ...
15│       ├── {company name}_{YYYY-MM-DD}_{YYYY-MM-DD}_gympass_payroll_deduction_{InvoiceID}.csv
16│       ├── {company name}_{YYYY-MM-DD}_{YYYY-MM-DD}_gympass_payroll_deduction_{InvoiceID}.sha256sum
17│       └── ...
18└── ...

Employees

Through the SFTP Server, you can manage the employees of multiple companies at the same time. It's simple: include on the file all the tax ids you want to send updates for, and we will update the base accordingly. Note: If a given tax id isn't included on the upload, its eligible base will remain unchanged.

Some supported operations are:

  • Full file - Update the entire employee base.
  • Upload history - Download the status of uploads.
  • Error details - Get the details for the errors found during an upload and what's required to address them.

Overview of the employees' directory structure

Directory Structure
1/
2├── multientity/
3│   ├── employees/
4│   │   └── upload/
5│   │       ├── all/
6│   │       ├── error-details/
7│   │       │   ├── {Timestamp}-{Uploaded-Filename}.csv
8│   │       │   └── ...
9│   │       └── status.csv
10│   └── payroll/
11└── ...
  • The initial directory is the root /.
  • /multientity is the directory representing all companies being managed.
  • /multientity/employees/upload/all is the directory where you can update the employee base by uploading a Fullfile file.
  • /multientity/employees/upload/error-details is the directory with the rejected upload error report.
  • /multientity/employees/upload/error-details/{Timestamp}-{Uploaded-Filename}.csv is the error report of a specific upload.
  • /multientity/employees/upload/status.csv is the file where you can download and view the status of each upload.

Upload a Fullfile file

Once connected to the SFTP Server, we can replace the employees base of all companies in the same time. In other words, we can add, remove, and edit employees in the same file.

Attention!

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

The SFTP Server expects the Fullfile to contain all the employees already created for the companies (if there is a company/tax id that doesn't have changes, you don't need to include it on the file).
For the companies/tax ids in the file, a given employee who was part of the database and isn't now part of the file, will be removed. The employees that are new entries, will be added accordingly. For employees found in both the file and the database, will be edited if any of their fields were changed.

Note: Even though it is possible to remove employees by uploading a Fullfile, it's not possible to remove all employees (as there's a safety threshold; if this is surpassed we will throw the 'Database wipe' error and reject the upload).

  1. Navigate to the "/multientity/employees/upload/all".
Terminal
1cd /multientity/employees/upload/all
  1. The command below uploads the all-employees.csv file. Replace "all-employees.csv" with your file containing the list of employees.
Terminal
1put all-employees.csv

File Organization

sftp-me-employees-example.png

Download the status file

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

  1. Navigate to the "/multientity/employees/upload" directory.
Terminal
1cd /multientity/employees/upload
  1. The command below downloads the status.csv file.
Terminal
1get status.csv

File Organization

sftp-me-status-example.png

Download the error details files

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. Through the error details, you can check the reason for the failure.

  1. Navigate to the "/multientity/employees/upload/error-details" directory. And display the list of error details.
Terminal
1cd /multientity/employees/upload/error-details
2ls
  1. The command below downloads the 1736255395-all-employees-02.csv file.
Terminal
1get 1736255395-all-employees-02.csv

File Organization

This file is a little more self-explanatory. It contains information about the type of error and where the error is.

Payroll

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

  • Deduction file - Download existing payroll files for the latest billing cycle.
  • Deduction file for leavers - Download any existing payroll files for employees who have been removed (during the latest billing cycle).

Note: Only employees with payroll enabled (field: "Payroll Enabled: Yes") will appear in the payroll files. There will be a file per company inside the .zip. The latest deduction file replaces the previous, therefore these won't be listed.

Overview of the payroll file structure

File Structure
1/
2├── multientity/
3│   ├── employees/
4│   └── payroll/
5│       ├── leavers/
6│       │   ├── {company name}_gympass_partial_payroll_deduction_{InvoiceID}.csv
7│       │   ├── {company name}_gympass_partial_payroll_deduction_{InvoiceID}.sha256sum
8│       │   └── ...
9│       ├── {company name}_{YYYY-MM-DD}_{YYYY-MM-DD}_gympass_partial_payroll_deduction_{InvoiceID}.csv
10│       ├── {company name}_{YYYY-MM-DD}_{YYYY-MM-DD}_gympass_partial_payroll_deduction_{InvoiceID}.sha256sum
11│       └── ...
12└── ...
  • The initial directory is the root /.
  • /multientity is the directory representing all companies being managed.
  • /multientity/payroll is the directory where you can download the payroll files.
  • /multientity/payroll/{company name}_{YYYY-MM-DD}_{YYYY-MM-DD}_gympass_payroll_deduction_{InvoiceID}.csv is a payroll file. The name consists of the company name, the start and end dates of the period, and the UUID of the invoice.
  • /multientity/payroll/leavers/{company name}_{YYYY-MM-DD}_{YYYY-MM-DD}_gympass_partial_payroll_deduction_{InvoiceID}.csv is a payroll file for removed employees. The name is similar to the general payroll file, but with "partial".

Download payroll files

Once connected to the SFTP Server, you can download the available payroll files.

  1. Navigate to the "/multientity/payroll" directory.
Terminal
1cd /multientity/payroll
  1. The command below downloads a payroll file.
Terminal
1get {company name}_{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, you can download payroll files of employees who have been removed.

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

Verify Integrity via checksum

A particularity of the payroll files is the option to verify the integrity of the file after downloading. This is important to ensure that nothing was altered or lost during the transfer.
Each payroll file has its own SHA-256 hash stored in a file with the same name and 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 "payroll/" directory, download the files.
Terminal
1get {company name}_{YYYY-MM-DD}_{YYYY-MM-DD}_gympass_payroll_deduction_{InvoiceID}.csv
2get {company name}_{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. Now compare the generated hash with the hash found inside the {company name}_{YYYY-MM-DD}_{YYYY-MM-DD}_gympass_payroll_deduction_{InvoiceID}.sha256sum file. They should be the same.

Flexible Benefits

Flexible Benefits allow multi entities to upload credits for their clients, allowing a company's employees to allocate the credits to those that best suit their individual needs. For an employee to be eligible for credits, they need to be created in the eligibility flow.

Contrary to the eligibility flow, partial uploads are accepted. This means that, by default, the correct lines will be created; and the ones with errors will be rejected. Every time a full or partial rejection happens, the multi entity admins will be notified via email.

Overview of the employees file structure

Directory Structure
1/
2├── multientity/
3│   └── flexben/
4│       └── upload/
5│           ├── add-or-update/
6│           ├── removal/
7│       └── download/
8│           ├── upload_history.csv/
9│           ├── errors/
10│           │   ├── {Timestamp}-{Uploaded-Filename}.csv
11│           │   └── ...
12│           └── beneficiaries-list.csv
  • The initial directory is the root /.
  • /multientity is the directory representing all companies under the multi entity's structure.
  • /multientity/flexben/upload/add-or-update is the directory to use if you need to create new credits and/or update existing ones.
  • /multientity/flexben/upload/removal should be used to delete credits.
  • /multientity/flexben/download/upload_history.csv is the file containing the status of the latest uploads.
  • /multientity/flexben/download/errors/ is the directory containing the failed upload error report.
  • /multientity/flexben/download/errors/{Timestamp}-{Uploaded-Filename}.csv is the error report referring to a specific upload.
  • /multientity/flexben/download/beneficiaries-list.csv/ will download the snapshot of credited employees.

Manage the credits

There are two types of uploads available:

  • Add or update - a file that will create new credits or edit existing ones
  • Removal - a file that will delete existing credits

Upload an Add/Update credits file

  1. Navigate to the "/multientity/flexben/upload/add-or-update/".
Terminal
1cd /multientity/flexben/upload/add-or-update/
  1. The command below uploads the .csv file, creating the new credit entries and updating the existing ones. 
Terminal
1put credit-employees.csv

File Organization

Credits file.png

Upload a Credits removal file

  1. Navigate to the "/multientity/flexben/upload/removal/".
Terminal
1cd /multientity/flexben/upload/removal/
  1. The command below uploads the .csv file, deleting the credits.
Terminal
1put credits-removal.csv

File Organization

Removals file.png

Download the status file

You can download the status of the most recent uploads. This is very useful for checking if a specific upload was successful or failed. This file will contain the last 40 uploads (regardless of the method - W4C or SFTP), sorted by date.

  1. Navigate to the "/multientity/flexben/download/upload_history.csv" directory.
Terminal
1cd /multientity/flexben/download/upload_history.csv
  1. The command below downloads the upload_history.csv file.
Terminal
1get upload_history.csv

File Organization

Upload history credits.png

Download the error details

You can download the error details of a failed upload. For example, you uploaded a credits file, checked the upload_history.csv and saw that this upload was rejected. Through the error details, you can check the reason for the failure.

  1. Navigate to the "/multientity/flexben/download/errors/" directory. And display the list of error details.
Terminal
1cd /multientity/flexben/download/errors/
2ls
  1. The command below downloads the credit-employees.csv file.
Terminal
1get 1736255395-credit-employees.csv

File Organization

Credits error details.png

Download the beneficiaries list

You can download a snapshot of the credited employees from a given multi entity.

  1. Navigate to the "/multientity/flexben/download/beneficiaries-list.csv" directory. 
Terminal
1cd /multientity/flexben/download/beneficiaries-list.csv
2ls
  1. The command below downloads the beneficiaries-list.csv file.
Terminal
1get beneficiaries-list.csv

File Organization

Beneficiaries list.png