This document is provided to help merchants have a better understanding of what appointment automated reports are, how they can be configured and what data is available with each report type.
What You Will Find in this Document
- Transfer and hosting configurations
- Report configuration and options
- List of all reports and metrics
- Data exported for each report type
Requirements
Transfer Configuration
The below table lists the information required to configure where automated reports will be transferred and how they will be stored. Take note that Booxi doesn’t provide hosting service.
| Protocol | Select one of the supported protocols: FTP, FTPS, SFTP or GCS. For GCS, no further details are required for the transfer configuration. Please contact your Booxi representative for the GCS guide. |
| Storage URL |
Hostname or IP of FTP site where reports will be sent.
|
| Storage Port | FTP port on which to connect. |
| Storage Directory | Folder on the destination FTP site in which to store reports. |
| Host Key Fingerprint | If you opt for SFTP, please provide a host key fingerprint. |
| Storage Login User | User to log into the storage URL. |
| Storage Login Password | Password to log into the storage URL. |
Report Configuration
The content of the reports will be configured per the information below.
|
Merchant ID or Merchant ID Template |
Merchant ID or template or any merchant within group for which the report will be generated. For group reports, it must be used in combination with "includeMerchantGroupLocations". |
| Options | Select one of the preconfigured reports. For custom reports, a list of fields to be exported must be provided in a JSON format. |
| Options JSON | For custom reports only. Fields to be exported in JSON format. |
| Schedule | Time at which reports must be generated. Time must be provided in 24H format, in merchant local time. All reports are generated daily. |
Report Types
Preconfigured Reports
Booxi provides a list of reports to choose from, each report comes with a predetermined list of fields. Take note that the preconfigured report will only export data marked as default. However, it is possible for a merchant to create a custom report by selecting any combination of fields. Please consult with your Booxi representative to make a selection.
| Appointment | Export all daily appointments of a merchant location. The report includes date, duration, service, staff, client and revenue associated with each appointment. |
| Time Slot | Export all calendar time slots associated with a merchant. The report includes dates, duration, status, associated staff and store information. |
| Metric Merchant Occupancy | Export data on the number of bookings, scheduled, booked and serviced hours for a merchant. |
| Metric Merchant Appointment | Export data on the number of bookings and their status. Additional fields are available. |
| Metric Service Occupancy | Export occupancy for each service offered by a merchant. It includes the number of bookings, booked and serviced hours as well as revenue service. |
| Metric Staff Occupancy | Export the occupancy of each staff associated with a merchant. It includes the number of scheduled, booked and serviced hours, time slots and #bookings. |
| Metric Resource Occupancy | Export the occupancy of each resource associated with a merchant. It includes the number of scheduled, booked and serviced hours. |
Customizations
Field Selection
Reports can be customized by selecting any combination of fields and so for each report type. If you wish to customize the content of any report, please consult with your Booxi representative.
Field Names
Reports are generated in CSV format with each field as an individual column. If you wish to rename any or all columns appearing in a report, please consult your Booxi representative.
Field Order
When providing a custom list of fields, the order in which the fields are listed will dictate the order in which they will appear in the report. If you wish to change the order in which fields will appear in a report, please consult with your Booxi representative.
Appointment
Generate a report of all daily appointments for a merchant location. The report includes date, duration, service, staff, client and revenue associated with each appointment.
Filters
The following filters are provided to further customize the report’s content. Once set, all appointment reports will be generated with the selected filters.
| Filter | Description | Default Value |
| excludeCancelled | Exclude cancelled appointments when exporting. | FALSE |
| includeMerchantGroupLocations | Include all merchants in the target merchant group. | TRUE |
| splitPriceAndCurrency | Strip currency symbols from all prices and display them in a distinct column. | FALSE |
| splitServiceNameAndCategory | Appointment’s total duration excluding free spacing. | FALSE |
| useDateFormatYMD | Display dates as “yyyy-mm-dd” instead of “dd mmm yyyy”. | TRUE |
| useTimeFormat24h | Display time in 24H format instead of 12H. | TRUE |
| dateFilter | Set which date field to select appointments by, start date or last modified date. | START |
| quoteMode | Specify which quote mode to use, all, minimal, all none null, non numeric. Leave blank if none. | ALL |
| encodingFormat | Specify which file encoding format to use, UTF-8 or UTF-16-LE. | UTF-16-LE |
The below table lists all available fields for an “Appointment” type report. For multi-service appointments, service fields will be repeated up to 5 times, once for each service assigned to the appointment.
| Field | Description | Default |
| id | Appointment's ID. | ☑ |
| start_date | Appointment’s start date. | ☑ |
| start_time | Appointment’s start time. | ☑ |
| duration | Appointment’s total duration excluding free spacing. | ☑ |
| status | Appointment’s status at the time the report is generated. | ☑ |
| created_on_date | Appointment’s creation date. | ☐ |
| created_on_time | Appointment’s creation time. | ☐ |
| booked_by | Shows if an appointment was booked by a client or a member of staff. | ☑ |
| last_modified_by | Shows if an appointment was last modified by a client or a member of staff. | ☐ |
| last_modified_on_date | Date an appointment was last modified on. | ☐ |
| last_modified_on_time | Time an appointment was last modified on. | ☐ |
| location | Appointment’s location. | ☐ |
| location_details | Details about the appointment’s location. | ☐ |
| reminder | Should a reminder be sent to the client? | ☐ |
| client_request | Client request for an appointment. | ☐ |
| quick_note | Quick note associated with an appointment. | ☐ |
| invoice_subtotal | Invoice’s subtotal. | ☐ |
| invoice_tax_1 | Amount for first tax. | ☐ |
| invoice_tax_2 | Amount for second tax. | ☐ |
| invoice_total | Invoice’s total price. | ☑ |
| invoice_fee | Transaction fee. | ☐ |
| invoice_paid | Has the invoice been paid or not? | ☐ |
| invoice_balance | Balance left to be paid. | ☐ |
| currency | Currency ISO code. | ☐ |
| staff_id | ID of the staff assigned to the appointment. | ☑ |
| staff_name | Full name of the assigned staff. | ☑ |
| customer_id | External customer ID used with a custom client module. | ☐ |
| cegid_customer_id | External customer ID used CEGID module (only if applicable). | ☑ |
| membership_id | Client’s membership ID if any. | ☐ |
| client_id | Client’s unique ID. | ☑ |
| client_name | Client’s full name. | ☑ |
| client_first_name | Client’s first name. | ☐ |
| client_last_name | Client’s last name. | ☐ |
| client_email | Client’s email address. | ☑ |
| client_phone | Client’s phone number (formatted per locale). | ☑ |
| client_phone_int | Client’s phone (unformatted/RAW). | ☐ |
| client_mobile | Client’s mobile phone (formatted per locale). | ☑ |
| client_mobile_int | Client’s mobile phone (unformatted/RAW). | ☐ |
| client_dob | Client’s date of birth. | ☐ |
| client_gender | Client’s gender. | ☐ |
| client_language | Client’s preferred language. | ☐ |
| client_postal_code | Client’s postal or ZIP code. | ☐ |
| home_address | Client’s home address. | ☐ |
| home_street | Street of a client’s home address. | ☐ |
| home_city | City of a client’s home address. | ☐ |
| home_state | State of a client’s home address. | ☐ |
| home_country | Country of a client’s home address. | ☐ |
| home_postal_code | Postal or ZIP code of a client’s home address. | ☐ |
| service_id | [repeatable for multi-service appointment] Service ID associated with the appointment. |
☑ |
| category_name | [repeatable for multi-service appointment] Service’s category name. |
☐ |
| service_name | [repeatable for multi-service appointment] Service’s name. |
☑ |
| service_duration | [repeatable for multi-service appointment] Service’s duration in minutes. |
☑ |
| service_spacing | [repeatable for multi-service appointment] Service’s spacing in minutes if any. |
☐ |
| service_question | [repeatable for multi-service appointment] Service’s pre-booking question (single question). If a survey is assigned to the question, this field will be set to "survey" but questions will not be exported. |
☐ |
| service_answer | [repeatable for multi-service appointment] Service’s pre-booking answer (single question). If a survey is assigned to the service, this field will contain an array of answers. |
☐ |
| resource_id | Resource ID associated with the appointment. | ☑ |
| resource_name | Resource’s name. | ☑ |
| store_id | Store ID where the appointment is held. | ☐ |
| store_number | Store’s number. | ☑ |
| store_name | Store’s name. | ☐ |
| store_city | City in which the store is located. | ☐ |
| store_state | Store’s state, province or territory. | ☐ |
| store_postal_code | Store’s postal or ZIP code. | ☐ |
| store_country | Store’s country. | ☐ |
| cegid_staff_id | CEGID staff ID (if applicable). | ☐ |
| cegid_product_id | CEGID product ID (if applicable). | ☑ |
| client.metadata.{SUB_FIELD} | Client metadata sub-field, where {SUB_FIELD} is any custom metadata. | ☐ |
| sevice.metadata.{SUB_FIELD} | Service metadata sub-field, where {SUB_FIELD} is any custom metadata. | ☐ |
| staff.metadata.{SUB_FIELD} | Staff metadata sub-field, where {SUB_FIELD} is any custom metadata. | ☐ |
| store.metadata.{SUB_FIELD} | Store metadata sub-field, where {SUB_FIELD} is any custom metadata. | ☐ |
Time Slot
Identify peak and downtimes by generating a report of all calendar time slots associated with a merchant. The report includes dates, duration, status, associated staff and store information.
Filters
The following filters are provided to further customize the report’s content. Once set, all timeslot reports will be generated in accordance with the selected filters.
| Filter | Description | Default Value |
| includeMerchantGroupLocations | Include all merchants in the target merchant group. | FALSE |
| useDateFormatYMD | Display dates as “yyyy-mm-dd” instead of “dd mmm yyyy”. | FALSE |
| useTimeFormat24h | Display time in 24H format instead of 12H. | FALSE |
| detailOptions | Determine what level of details to export with, available, busy, imported or all. | ALL |
| quoteMode | Specify which quote mode to use, all, minimal, all none null, non numeric. Leave blank if none. | ALL |
| encodingFormat | Specify which file encoding format to use, UTF-8 or UTF-16-LE. | UTF-16-LE |
Fields
The below table lists all available fields for a “Time Slots” type report.
| Field | Description | Default |
| start_date | Date on which the time slot starts. | ☑ |
| start_time | Time on which the time slot starts. | ☑ |
| duration | Time slot’s duration in minutes. | ☑ |
| status | Time slot’s status, available, busy, etc… | ☑ |
| label | The custom label assigned to the time slot. | ☑ |
| description | Time slot’s description. | ☑ |
| staff_id | ID of the staff assigned to the time slot. | ☑ |
| staff_name | Name of the staff assigned to the time slot. | ☑ |
| cegid_staff_id | External staff ID used for the CEGID module. | ☐ |
| staff_metadata.{SUB_FIELD} | Staff metadata sub-field, where {SUB_FIELD} is any staff metadata sub-field. | ☐ |
| store_id | Store’s ID. | ☑ |
| store_group_id | Store’s merchant group ID. | ☑ |
| store_tag | Location filter tags assigned to the store. | ☑ |
| store_number | Store’s number. | ☑ |
| store_name | Store’s name. | ☑ |
| store_city | Store’s city. | ☑ |
| store_state | Store’s state, province or territory. | ☑ |
| store_country | Store’s country. | ☑ |
Metric Reports
Metric reports provide a concise and comprehensive set of metrics to analyze how your business is performing from resource occupancy, popularity of services to trends. Several report types are offered to focus on specific data. See below for a list of all metric reports.
| Merchant Occupancy | Generate a comprehensive summary of all merchants within a group. Examine the performance of each location by comparing the number of bookings, booked, scheduled and serviced hours as well as busy time slots. |
| Merchant Appointment | Generate a detailed report of appointments booked at each merchant location. The report includes the number of appointments, their status, the number of booked, scheduled and serviced hours as well as the revenue generated. |
| Service Occupancy | Analyze how each service provided is performing by examining the number of bookings, booked and serviced hours as well as the revenue generated. Use these metrics to implement changes to your service offering, refocus resources on services generating more revenue, etc… |
| Staff Occupancy | Analyze how staff are performing, from the number of bookings they were involved with to the number of scheduled, booked and serviced hours. Modify work schedule based on peak hours. |
| Resource Occupancy | Survey how resources are performing, the number of bookings the resource was used for along with booked and serviced time. |
Metric Filters
The following filters are provided to further customize the report’s content. Take note that all metric report types will be generated with the selected filters.
| Filter | Description | Default Value |
| includeMerchantGroupLocations | Include all merchants in the target merchant group. | TRUE |
| splitPriceAndCurrencry | Strip currency symbols from all prices and display them in a distinct column. | FALSE |
| useDateFormatYMD | Display dates as “yyyy-mm-dd” instead of “dd mmm yyyy”. | FALSE |
| useTimeFormat24h | Display time in 24H format instead of 12H. | FALSE |
| quoteMode | Specify which quote mode to use, all, minimal, all none null, non numeric. Leave blank if none. | ALL |
| encodingFormat | Specify which file encoding format to use, UTF-8 or UTF-16-LE. | UTF-16-LE |
Merchant Occupancy
Fields
The below table lists all available fields for a “Merchant Occupancy” type report.
| Field | Description | Default |
| date | The date on which the data was compiled. | ☑ |
| store_id | Booxi Merchant ID. | ☑ |
| store_group_id | Booxi Merchant Group ID. | ☐ |
| sore_tag | Location tags associated with a store. | ☐ |
| store_number | Store count of the merchant group. | ☐ |
| store_name | Store’s name. | ☐ |
| store_city | Store’s city. | ☐ |
| store_state | Store’s state, province or territory. | ☐ |
| store_country | Store’s country. | ☐ |
| open_minutes | Total scheduled time in minutes for all staff on the same date. | ☐ |
| open_hours | Total scheduled time in hours for all staff on the same day. | ☑ |
| booked_minutes | Total time booked in minutes. | ☐ |
| booked_hours | Total time booked in hours. | ☑ |
| serviced_minutes | Total time serviced in minutes. | ☐ |
| serviced_hours | Total time serviced in hours. | ☑ |
| busy_timeslot_minutes | Total of all busy time slots in minutes. | ☐ |
| busy_timeslot_hours | Total busy time slots in hours. | ☑ |
| nb_bookings_total | Number of bookings. | ☑ |
Merchant Appointment
Fields
The below table lists all available fields for a “Merchant Appointment” type report.
| Field | Description | Default |
| date | Date of the appointment. | ☑ |
| store_id | Booxi merchant ID. | ☑ |
| store_group_id | Booxi Merchant Group ID. | ☐ |
| store_tag | Location filter tags associated with a store. | ☐ |
| store_number | Store count in the merchant group. | ☐ |
| store_name | Store’s name. | ☐ |
| store_city | Store’s city. | ☐ |
| store_state | Store’s state, province or territory. | ☐ |
| store_country | Store’s country. | ☐ |
| nb_bookings_confirmed | Number of bookings with the status “approved” (“pending client” and “requested” are excluded). | ☑ |
| nb_bookings_requested | Number of bookings with the status “requested. | ☑ |
| nb_bookings_rescheduled | Number of bookings with the status “rescheduled”. | ☑ |
| nb_bookings_pending_client | Number of bookings with the status “pending client”. | ☐ |
| nb_bookings_client_arrived | Number of bookings with the status “ongoing”. | ☐ |
| nb_bookings_completed | Number of bookings with the status “completed”. | ☐ |
| nb_bookings_staff_canceled | Number of bookings with the status “canceled by staff”. | ☑ |
| nb_bookings_client_canceled | Number of bookings with the status “canceled by client”. | ☐ |
| nb_bookings_no_show | Number of bookings with the status “no show”. | ☑ |
| nb_bookings_total | Total number of bookings (all status). | ☑ |
| nb_bookings_online | Number of bookings made online (client origin). | ☑ |
| nb_bookings_offline | Number of bookings made offline (staff origin). | ☑ |
| booked_minutes | Total minutes booked in a day. | ☐ |
| booked_hours | Total hours booked in a day. | ☐ |
| serviced_minutes | Total minutes serviced in a day. | ☐ |
| serviced_hours | Total hours serviced in a day. | ☐ |
| booked_revenue_subtotal | Subtotal revenue booked in a day (excluding taxes). | ☐ |
| booked_revenue_total | Total revenue booked in a day (including taxes). | ☐ |
| serviced_revenue_subtotal | Subtotal revenue serviced in a day (excluding taxes). | ☐ |
| serviced_revenue_total | Total revenue serviced in a day (including taxes). | ☐ |
Service Occupancy
Fields
The below table lists all available fields for a “Service Occupancy” type report.
| Field | Description | Default |
| date | Date on which the appointment started. | ☑ |
| store_id | Booxi merchant ID. | ☑ |
| store_group_id | Booxi Merchant Group ID. | ☐ |
| store_tag | Location filter tags associated with a store. | ☐ |
| store_number | Store count in the merchant group. | ☐ |
| store_name | Store’s name. | ☐ |
| store_city | Store’s city. | ☐ |
| store_state | Store’s state, province or territory. | ☐ |
| store_country | Store’s country. | ☐ |
| service_id | Booxi Service ID. | ☑ |
| service_name | Service’s name. | ☑ |
| service_tags | Tags assigned to a service. | ☐ |
| cegid_product_id | CEGID product ID (if applicable). | ☐ |
| nb_bookings_online | Number of bookings made online (client origin). | ☑ |
| nb_bookings_offline | Number of bookings made offline (staff origin). | ☑ |
| booked_minutes | Total minutes booked in a day for a service. | ☐ |
| booked_hours | Total hours booked in a day for a service. | ☑ |
| serviced_minutes | Total minutes serviced in a day for service. | ☐ |
| serviced_hours | Total hours serviced in a day for service. | ☑ |
| booked_revenue_subtotal | Subtotal revenue booked in a day (excluding taxes) for a service. | ☑ |
| booked_revenue_total | Total revenue booked in a day (including taxes) for a service. | ☑ |
| serviced_revenue_subtotal | Subtotal revenue serviced in a day (excluding taxes) for a service. | ☑ |
| serviced_revenue_total | Total revenue serviced in a day (including taxes) for a service. | ☑ |
| nb_bookings_total | Number of bookings made with a service. | ☑ |
| service_metadata.salesforce_service_id | Salesforce service ID from metadata (if applicable). | ☐ |
Staff Occupancy
Fields
The below table lists all available fields for a “Staff Occupancy” type report.
| Field | Description | Default |
| date | Date on which the appointment started. | ☑ |
| store_id | Booxi merchant ID. | ☑ |
| store_group_id | Booxi Merchant Group ID. | ☐ |
| store_tag | Location filter tags associated with a store. | ☐ |
| store_number | Store count in the merchant group. | ☐ |
| store_name | Store’s name. | ☐ |
| store_city | Store’s city. | ☐ |
| store_state | Store’s state, province or territory. | ☐ |
| store_country | Store’s country. | ☐ |
| staff_id | Booxi Staff ID. | ☑ |
| staff_name | Staff’s name. | ☑ |
| cegid_staff_id | CEGID Staff ID (if applicable). | ☐ |
| open_minutes | Open hours in minutes. | ☐ |
| open_hours | Open hours in hours. | ☑ |
| scheduled_minutes | Total scheduled time in minutes for a staff member. | ☐ |
| scheduled_hours | Total scheduled time in hours for a staff member. | ☑ |
| booked_minutes | Total booked time in minutes for a staff member. | ☐ |
| booked_hours | Total booked time in hours for a staff member. | ☑ |
| serviced_minutes | Total serviced time in minutes for a staff member. | ☐ |
| serviced_hours | Total serviced time in hours for a staff member. | ☑ |
| busy_timeslot_minutes | Total of all busy time slots in minutes for a staff member. | ☐ |
| busy_timeslot_hours | Total of all busy time slots in hours for a staff member. | ☑ |
| nb_bookings_total | Number of bookings for a staff member. | ☑ |
| nb_assigned_services | Number of appointment-type services assigned to the staff. | ☐ |
| staff_metadata.salesforce_staff_id | Salesforce Staff ID from metadata (if applicable). | ☐ |
Resource Occupancy
Fields
The below table lists all available fields for a “Resource Occupancy” type report.
| Field | Description | Default |
| date | Date on which the appointment started. | ☑ |
| store_id | Booxi merchant ID. | ☑ |
| store_group_id | Booxi Merchant Group ID. | ☐ |
| store_tag | Location filter tags associated with a store. | ☐ |
| stoer_number | Store count in the merchant group. | ☐ |
| store_name | Store’s name. | ☐ |
| store_city | Store’s city. | ☐ |
| store_state | Store’s state, province or territory. | ☐ |
| store_country | Store’s country. | ☐ |
| resource_id | Booxi Resource ID. | ☑ |
| resource_name | Resource’s name. | ☑ |
| open_minutes | Open hours in minutes. | ☐ |
| open_hours | Open hours in hours. | ☑ |
| scheduled_minutes | Total scheduled time in minutes for a resource. | ☐ |
| scheduled_hours | Total scheduled time in hours for a resource. | ☑ |
| booked_minutes | Total booked time in minutes for a resource. | ☐ |
| booked_hours | Total booked time in hours for a resource. | ☑ |
| serviced_minutes | Total serviced time in minutes for a resource. | ☐ |
| serviced_hours | Total serviced time in hours for a staff resource. | ☑ |
| nb_bookings_total | Number of appointments that were booked with the resource. | ☑ |
Protocol Options
Here is a list of protocols supported with the automated FTP report. When it comes to selecting a transfer method between FTP, FTPS or SFTP we highly recommend avoiding the basic FTP protocol and choosing a more secure option. As an alternative, reports can be uploaded to Google Cloud Storage by specifying GCS as a protocol.
Booxi is using dedicated outbound IPs for all reports except GCS. They should be whitelisted by customers.
FTP
FTP exchanges data using two separate channels known as the command channel and data channel. With FTP, both channels are unencrypted, leaving any data sent over these channels vulnerable to being intercepted and read. It should only be used in limited cases or on networks you trust.
FTPS
Like FTP, FTPS uses two connections: a command channel and a data channel. It authenticates your connection using a user ID and password, a certificate, or both. When connecting to a trading partner's FTPS server, your FTPS client will validate if the server's certificate is trusted.
SFTP
SSH File Transfer Protocol is a separate protocol packaged with SSH that works in a similar way but over a secure connection. The advantage is the ability to leverage a secure connection to transfer files and traverse the filesystem on both the local and remote system. SFTP is preferable to FTP because of its underlying security features and ability to piggy-back on an SSH connection. Furthermore, SFTP needs only a single port number for all SFTP communications, making it easy to secure.
Public Key Fingerprint
SFTP supports server fingerprint as an optional security feature. Our implementation requires the key to be in MD5 format.
Your server’s fingerprint can be obtained with the following console command:
| ssh-keygen -lf /path/to/public_key/pubkey_in_openssh_format.pub |
A remote server’s fingerprint can be obtained like so:
| ssh-keyscan -t rsa ftp.host.com > key.pub ssh-keygen -l -f key.pub -E md5 |
Google Cloud Storage (GCS)
Google Cloud Storage is the object storage service offered by Google Cloud. In Cloud Storage, different objects are grouped in unique “namespaces” called buckets. A bucket can hold multiple objects yet, a single object will belong to only one bucket.
Client Configuration
The client must configure its destination storage bucket, using a Service Account. A destination folder must be created as files can’t be saved on the root. Contact your Account Manager or CS to request an account.
We recommend configuring the storage bucket with the following settings.
- Region: Can either be Multi-Region or Region specific
- Storage Class: Standard
- Public Access: NOT Public
- Access Control: Uniform
- Protection: Activate one or more of the following protection options: Object Versioning Retention Policy or Default Event-Based Hold Option.
- Life Cycle rules: Weekly data deletion
- Requesters Pay: OFF
- Permissions: storage.buckets.get and storage.objects.create
The permissions above are included into the below roles:
- Storage Legacy Bucket Reader
- Needed to read the metadata and the permissions on the bucket.
- Storage Object Creator
- Needed to write the file blob.
Storage Directory
The client can specify in what “destination folder” reports will be exported. Folders and sub-folders must be formatted as : 'level1/level2/'. Leading '/' is unnecessary unless a root '/' folder is needed.
Furthermore, the storage directory must follow the below naming guidelines as provided by Google:
- Object names can contain any sequence of valid Unicode characters, of length 1-1024 bytes when UTF-8 encoded.
- Object names cannot contain Carriage Return or Line Feed characters.
- Object names cannot start with .well-known/acme-challenge/.
- Objects cannot be named . or ...
For further information about the naming guidelines, please consult this article.