Follow this guide to add or set up a data feed which will upload new workers from any format spreadsheet file including Excel XLSX, ODF or CSV. This can be used to create new workers and pay items, update existing workers, and provide end dates or any combination.
Add or Update the Data feed #
Go to Company set up > Report definitions and click Update or Add.. This will depend on whether you already have the GB Upload workers from CSV data feed or if you need to add it. If adding, select your company and the GB Upload workers from CSV Template:
If you are uploading from a network SFTP location, then you select that version of the data feed.
Settings #
There are several settings which you can configure to control how workers are uploaded:
Dry-run #
Dry-run is commonly used for testing in that it will allow the full data-feed operation including Validation and Change recording, but will not write any data to the database. When setting up a new feed, we recommend setting dry run as you are likely to run the data feed several times to iron out issues or clean the data.
Tip: You can also use dry run to check for differences between an uploaded file and the workers in the system. This is because the change recording will show you any differences.
Columns #
The column specification is quite simple and uses the column mini-language. Each row has a double-quoted “” left part before the colon : and a right part:
- The left part names are fixed and indicate the fields required by paiyroll®
- The right part after the colon uses your spreadsheet column names in curly brackets as required
Please see below for an example of a spreadsheet worker file and how the columns are specified :
Any columns that exist in your file will be included in curly brackets e.g. {Gender}
You can use multiple columns for one field, for example, name above combines {Worker name} and {Surname} columns from the file.
You do not need to supply every value in the file. The column specification mini-language can provide default values in these cases. Missing values in your file can easily be defaulted with zero or blank right-hand side. end_date is an example of this if your file cannot provide the end date.
Who is the Master? #
Many fields will be uploaded from your data file and in these cases we describe the file as being the master. However, where the data is not provided you can use paiyroll® as the master. If the name field has a trailing equals sign =, this signifies that the existing value in paiyroll® will not be over-written on a subsequent upload.
CSV Dialect #
This is normally the default Excel.
Add from Test Worker Pay Items #
The data feed will automatically add any pay items if a test worker specified when new workers are uploaded from a file. This means you will not need to manually add these to every worker.
Invite #
Is used to automatically send a password-set welcome email to each new worker to explain how to set their password to access the system.
Auto works id #
Will automatically generate sequential works id
Disable employee updates #
Usually, employees will be added by the data-feed and then future updates can be completed by the worker using self-service. In some cases, you may always prefer to upload all workers and disable employee self-service updates.
Schedule #
Select the pay schedule for the data feed e.g. Weekly w1 or Monthly m1. If you need to upload weekly and monthly workers, then you will need 2 data feeds.
Worker key #
There are 2 options for this setting:
- Works ID as the primary key will attempt to change a username and email based on a works ID. This is very useful, for example, when adding workers who may start using only their private email, and then later switch to using a company email. This will be completed automatically using the works ID as the key. Because every username in the system must be unique this option will automatically append a number to the username if an existing user already has that username e.g. uploading john.smith@gmail.com will use john.smith@gmail.com as the username. Email addresses are never changed.
- Username as the primary key means all workers are indexed by their username. You must therefore ensure all usernames are unique and you will need to manage username clashes.
Add #
Click add to save the report definition data feed.
Uploading worker files #
Go to My data Feeds and click the Upload… button for the data feed where you will be prompted for the file location:
The data feed will operate and after a short while you will see a full log of the operation. If you need to review the log, click on the View button. You will also be able to move back and forward and review multiple data-feeds.
Validation #
Full validation is performed on the incoming data, and It is not uncommon to find errors in the columns or bad data in the file. If you see issues then correct the columns and/or clean the source data and repeat the operation. Once you are satisfied that everything is working correctly, disable dry run.
Change recording #
When you upload one or more existing workers, a full change recording is provided so you can see the changes that were made.