How to Import Staff Schedules in Booxi

To improve efficiency and make the process of configuring schedules in Booxi easier, the "Import Staff Schedule" feature provides the ability to import schedules from an external source.

Table of Contents

Format

Importing Schedules

Validation

Warning Messages

Error Messages

---

Requirements & Permissions

Access to this feature is limited to users with the Admin, Manager and Supervisor roles. The feature is available in the Back Office and Head Office.

Workflow

Importing staff schedules is performed by following the below steps.

1. From a workforce management tool or a spreadsheet, staff schedules are exported in .CSV format. The resulting file must be formatted per Booxi’s import template. 
2. From the Head or Back Office, schedules are imported using the appropriate dialog.
3. Content is validated and a report is generated. If errors are found during the validation process, they must be fixed and the procedure must be repeated until there is no error left. 
4. Records are imported and published. A notification is displayed once records have been published successfully.

---

Format

Schedules must be exported in .CSV format and must include columns as listed below. If schedules are exported from an external source in a format different than the template provided by Booxi, column names must match the below table. Consult the template rules for examples of how the file and records must be formatted. Contact your Booxi representative to be provided with the import template file.

Columns

Template Rules

• There is no maximum number of records allowed in the import file. However, the process cannot exceed 10 minutes to complete in the Head Office.
• Order in which columns appear in the file is not of importance. During the validation process, Booxi will default to the same order as found in the template.
• The encoding of the file must be Unicode (UTF-8)
  • *Note: if you are using MS Excel, you may set the proper encoding by clicking "Save as" (Name your file, then select CSV file type); in the window, select "Tools", then "Web Options", making sure to select Unicode (UTF-8))
• The column names must be an exact match to the provided template.
• Each DOW (Day of the week) must have at least one Start-End pair. There is no maximum number of pairs. Each pair must follow the proper format as shown below.
  • Additional Start and End columns must respect the naming convention.
  • Additional columns must use the next number in sequence after Start or End. 
  • Additional Start and End columns must be paired (Start4 with End4, etc.).
• Example
  Here’s an example for a day (Monday) with three time pairs.
  

  Mon Start1	Mon End1	Mon Start2	Mon End2	Mon Start3	Mon End2
  09:00	12:00	13:00	17:00	18:00	21:00

  Here's an example where there is no availability on a Wednesday.
  

  Mon Start1	Mon End1	Tue Start1	Tue End1	Wed Start1	Wed End1
  09:00	18:00	09:00	18:00

Importing Schedules

From the Head Office interface, follow the below steps to import staff schedules.

1. Navigate to the Personnel tab
2. Click the drop-down menu (⋮)
3. Select Import Staff Schedules.
   
4. From the Import Dialog, select an appropriate .CSV file. The validation process will start automatically.
   
5. Once the validation process is complete:
   1. Download the report to validate that the schedules to be imported are correct and browse the list of errors if any.
   2. If all records are valid, click on Import to proceed.
   3. If there are warnings, validate if they are acceptable or not. Fix them or opt to proceed by checking the appropriate box. 
   4. If there are errors, fix any issues and repeat the process until the validation is successful.

---

Validation

Validation automatically starts upon selecting a file to import. The validation tool will analyze the CSV file to verify data accuracy, integrity and formatting. It will scan the file and search for common errors, ensure that formatting is respected and mandatory fields are present. 

Once the validation process is complete, the dialog box will display a report with the following information:

• Number of “Valid” entries
• Number of “Warning” entries
• Number of “Rejected” entries

Click on the download link to get a copy of the report generated during the validation process. See the section below for a list of all error messages and how to fix each individual error.

---

Warning Messages

During the validation process, entries can be marked with a warning when a schedule meets one of the following criteria. 

Conflicting schedule with #***

This warning message will be displayed if the start and end dates are NOT a perfect match with an existing schedule, where #**** represents the existing schedule ID that is in conflict with schedules contained in the file. 

Matching schedule with #***

This warning message will be displayed if the start and end dates are a perfect match with an existing schedule, where #**** represents the existing schedule ID that is in overlap with schedules contained in the file. 

---

Error Messages

File format, Cells and Data Validation

Validation against all columns and cells.

“Schedule start is invalid” or “Schedule end is invalid”

Reason for error: date is not formatted as YYYY-MM-DD (ISO 8061).

“Invalid time in DOW Start# / DOW End#”

Reason for error: time is not formatted properly.

Time must be expressed in 24h format.
Time must be expressed as HH:MM .
Seconds and milliseconds must be ignored.
All times must be expressed in the merchant time zone.

“Header error“

Reason for error: one or several column names are not matching the template.

Validate that each column name is an exact match with the template (values are case-sensitive).
Any extra characters such as an extra space can trigger this error. (*Note: An invisible or whitespace character can trigger this error; to fix this, ensure your file is in Unicode (UTF-8)).

Validate that all separators used are commas (",").

“Missing mandatory data”

Reason for error: mandatory data is missing and the file cannot be processed. 

Validate the following data is included:
Each entry has a valid merchant ID or a Store Number and a Merchant Group ID. 
If store numbers are used, a merchant group ID is mandatory.

Each entry has at least one of the following staff identification:
   Staff ID
   External Staff ID and External Module ID.
   Staff’s first and last name
   Staff’s email address

Each entry has a start date.
Each entry has an end date.

"Number of fields in row mismatch the number of header fields"

Validate that the number of fields in each row matches the number of columns.

---

Merchant ID and Store ID Validation

Validation against columns named “Merchant ID” and “Store ID”

“Merchant not found”

Reason for error: the import file contains an invalid merchant ID.

Validate that the Merchant ID exists. It must be an exact match with its Booxi equivalent.
Validate that the Merchant ID is linked to the user/staff initiating the import.

“Merchant/Store not found”

Reason for error: the import file contains invalid merchant or store IDs.

If a Store ID is used, a Merchant Group ID must be provided. 
The Store ID and Merchant Group ID must be valid and matched.
If a Store Number, a Merchant Group ID and a Merchant ID are provided, 
they must all be valid and matched.

Validate that the Merchant ID or Merchant Group ID and Store ID exists. 
They must be an exact match with Booxi.

Validate the user/staff initiating the import is linked to the Merchant ID, 
Store ID and Merchant Group ID found in the import file.

---

Staff Validation

Validation against columns named “Staff ID”, “First Name”, “Family Name”, “Staff Email”, “External Staff ID” and  “External Module ID”.

“Need at least one: Staff ID or (First Name AND Last Name) or Staff Email or (External Module AND External Staff ID)”

Reason for error: staff identification is missing or incomplete or staff can’t be found.

Any provided identifier must exist in Booxi.

Each entry must include at least one of the following identifiers:
   Staff ID
   External Staff ID and External Module ID.
   Staff’s first and last name
   Staff’s email address

When using First and Family Names as identifiers, they are both required. 
They must be an exact match with their corresponding record in Booxi (accents, hyphens, etc.).
When using External Staff ID as an identifier, the External Module ID becomes mandatory 
and vice versa. An exact match is required.
If more than one identifier is provided, they must all be valid and matched.

“Invalid staff”

Reason for error: no corresponding staff record found in Booxi.

Validate that the staff is associated with the merchant or store provided.
Validate that the staff has a calendar.
Validate that the email is in the expected format (recipient@domain.ext)

---

Start and End Date Validation

Validation against columns named “Start Date” and “End Date” for each schedule.

“Invalid schedule range”

Reason for error: the start or end dates are not valid.

Validate that the schedule’s end date is in the future or on the same day as the 
import is performed. End date cannot be in the past.

Validate that the schedule’s start date is earlier than the end date. 
The start date can be in the past as long as the end date is in the future or
on the same day as the import is performed.

---

DOW Validation

Validation against columns named DOW Start# and End#.

“Incomplete daily times in range DOW Start# / DOW End#”

Note: DOW Start and DOW End will specify the faulty range (ex: Start2 / End2,etc.)

Reason for error: DOW start and end times must come in pairs.

Validate that each DOW Start# is matched with a DOW End#.
Validate that each DOW End# is matched with a DOW Start#.
All DOW entries must come in pairs.

Example of an invalid DOW (missing Fri End2)

"Overlapping work hours"

Reason for error: hours specified in DOW start and end are not sequential.


Validate that each start and end pair are sequential.

Example of a non-sequential DOW (overlapping pairs)

“Work hours ‘HH:MM - HH:MM’ in range ‘DOW Start# / DOW End#’ are empty”

Reason for error: Overlapping pairs or end time is earlier than start time.

Validate that each start time is earlier than is matched end time.

Example of a conflicting/overlapping DOW

Validation Report

Upon completing the validation, a report will be generated and made available to download. The report will include a summary of all entries processed each with an assigned status “valid”, “warning”, along with any applicable error message. Errors can be corrected directly in the report and reuploaded for validation.

Consult your Booxi representative for a sample.

Importing Validated Data

Once an error-free validation has been completed on the file, it can be imported and published  by clicking on the “Import” button found in the import dialog.

If warnings are found during the validation, they can be fixed directly in the reports as errors would. It is however possible to import schedules with warnings if the checkbox “Accept warnings and proceed” is checked.

Upon completion, the schedules will become active and visible to all members of staff.