Homebase Integration

Homebase Integration



Step 1 - Essential Fields in BO and Homebase

  1. There are fields to be filled out in Back Office User Management and Homebase Settings.

  1. During self-boarding on the Homebase portal, initiate the process by clicking the link to request API access. Once the request is submitted, Homebase will generate the required API credentials. After the credentials are created, navigate to Homebase Settings → API Access (the last option in the menu) to retrieve them. Finally, copy the generated API credentials and paste them into the Back Office (BO) to complete the setup.
  2. Make sure all Users under BO User Management (User Management > Users) have a First Name, Last Name, Email Id, and User Roles.
  3. Break timings must be the same in all of Back Office, POS and Homebase. Mismatch in Break definitions between BO, POS and Homebase will result in sync failures.
  4. To create a break in Homebase, see the below steps (and included screenshots):
    1. Select Settings.

    2. Then select Breaks & Compliance.

    3. On the Breaks & Compliance page, click Add New Break.

Step 2 - Subscribe and Configure in Back Office

Navigation: Log into Back Office. On the left-side pane, select Home then 
Integration Hub

  1. On the Integration Hub page, select Browse and Subscribe Integrations.


  2. Under the Payroll section: for Homebase select ADD.


  3. The Disclaimer page appears. After selecting the Terms and Conditions box at the bottom left, click Confirm at the upper right. After that, you are redirected to the Configure and Manage Integrations page.


  4. On the Current Integrations page (Integration Hub > Configure and Manage Integrations): navigate to the row with Homebase, then under the right-side Actions column select the settings (gear) icon.


  5. The Homebase page shows two tabs: Settings and Action.


  6. Under the Settings tab:

    1. Enter the homebase API Key (provided by Homebase), which may be common for all Stores on your Account.
    2. Enter the Location UUID (provided by Homebase), which is unique for the Store. 
    3. Enter the Notification Email ID which will receive the Time Clock Events sync failures.

  7. Under the Action tab:


    1. You will find the option to synchronize Users with Homebase by clicking the Sync Users button. This must be performed for the first time right after the configuration and every time a new user is added via User Management
      in Back Office.
      1. If the sync completes successfully, the info message 'User synced successfully' will appear at the top right side of the page.
      2. If failure occurs while performing user sync, the info message 'Sync user failed' will appear at the top right side of the page.
         
    2. Similarly in the Action tab, you will find the option to synchronize Shifts with Homebase by clicking the Sync Shifts button. It should only be clicked when there is a change in Shift configuration in Homebase in the middle of the day. It is not required to click if Shift detail is not changed from the previous day.
      1. Click Sync Shifts to fetch the latest scheduled Shift details from Homebase to ensure that accurate Roles are captured in Homebase Time Clock Events sync.
      2. If any updates are made to the shift in the middle of a day, make sure to click Sync Shifts to avoid sending incorrect roles in time entry.
        1. If the sync completes successfully, the message 'Shifts synced successfully' will appear at the top-right of the page.
        2. If failure occurs while performing Sync Shifts, the message 'Sync Shifts failed' will appear at the top-right of the page.
      3. If you click Cancel, you are redirected to the Current Integrations page.


Notes

  1. If a user is in Back Office and not in Homebase, clicking sync users will create the user in Homebase.
  2. If a user is present in Homebase but not in Back Office, that user needs to be manually created in Back Office User Management.
  3. If a user exists in both Back Office and Homebase, the system will map the users.
  4. When you update a user's information in Back Office, such as their First Name, Last Name, Email Address, or Role, click Sync Users to update the user in Homebase.
  5. Upon completion of user synchronization, the data sync for Clock In & Out, as well as Break In & Out, are automatically transmitted to Homebase.
  6. If a Role-based Shift hasn’t been created in Homebase and the user clocks in POS, Homebase will record it under the default Role.
  7. To ensure clock events are correctly recorded in Homebase for a specific Role, shifts must be defined in Homebase with that Role assigned. When a user clocks in from the POS, the integration attempts to match the clock-in event with a Shift in Homebase that has the same Role.
  8. If the Role in current Homebase shift and the POS clocked-in Role doesn’t match, the default Role will be captured in Homebase. Refer to the example below to understand how Role-based Clock In works with Homebase.
  9. All timecard activities on the Homebase side (including early/late clock-ins, clock-outs, and unscheduled shifts for the same business day) sync accurately with POS time events. Manager-edited entries (clock-in, break in, break-out, clock-out) will reflect in BO/POS without discrepancies by clicking Sync Shifts in Back Office Integration Hub Settings tab, appear in Payroll reports, and continue syncing correctly after editing to keep data integrity.
  10. Editing a timecard for the previous day must be performed either in Back Office or on the Homebase platform. The sync option supports same-day processing only
  11. All actions performed within the Integration Hub for Homebase are automatically recorded and reflected in the Back Office audit log reports

Back Office - Role
Homebase User - Role
Homebase Shifts
Scenarios
POS Role Used in Clock In
Roles Recorded in Homebase
User A (Admin)
User A - Admin
Not defined
Clock in with no Shift defined
Admin
Admin (default Role)
User B (Bartender)
User B - Bartender
Bartender - 1pm to 5pm
Clock in with correct Role
Bartender
Bartender
User C (Cashier, Driver)
User C - Cashier
Cashier - 1pm to 5pm
Clock in with incorrect Role
Driver
Cashier (default Role)



Limitations

  1. Homebase’s API currently supports only one Role per Employee at the time of creation. During sync, only the user’s primary (first) Role will be sent to Homebase. If the user needs to have additional Roles in Homebase, they must be manually added in the Homebase system after the sync is complete.
  2. If there is any failure in the clock and break events data sync, an email will be triggered to the email ID configured in the settings tab
  3. The default email from (no-reply@infoposfood.com) or you can change the default Email Address through the Admin SMPT settings as shown in the below image.
      

  4. The email contains information about the failed events, along with the user's Email ID and Store ID, as well as the sample email contents mentioned below:
    1. Error 401 ('The Authorization header supplied is invalid') typically indicates that integration is incorrectly configured in the back office. You may need to check your API key, location UUID.
    2. Error 422 ('Please add break clock-in time to save timecard") suggests that a required field (Clock events) is missing when attempting to save a timecard. You may need to verify that all necessary time clock entries, including break start and end times, are correctly recorded.
  5. After receiving the email, you need to manually add the Clock events in Home Base for the failed event (example below):


  6. Without updating the failed time events in Homebase, the next Clock events for the User will not be updated in Homebase.
  7. If a User has not taken a break configured in BO due to busy business hours and even the Manager creates a break in POS then the User takes this break (This break created in POS will not be synced with Homebase because, this break is an ad-hoc break created in POS and the same is not created in Homebase).
  8. Any manual updates like Force Punch In & Out in Back Office and adding timecards in POS will not be updated with Homebase due to API limitation.
  9. All changes must be made on the Homebase platform and synchronized with the Back Office Integration Hub using Sync Shifts. The updated data will be reflected in POS and Back Office reports.
  10. If the POS is offline and an employee performs a time event, the time events will not sync with Homebase once the POS comes back online.