All Collections
Integration & Technology
Integrations
Humanity Integration with TimeClock Plus
Humanity Integration with TimeClock Plus

A detailed overview of Humanity’s integration with TimeClock Plus along with instructions for setting up and activating the integration

Yasir Ehsan avatar
Written by Yasir Ehsan
Updated over a week ago

Integration Overview

Integration is bi-directional and supports the following data synchronization:

  • From TimeClock Plus to Humanity: Employee’s personal and Leave data

  • From Humanity to TimeClock Plus: Schedule data synchronization

Synchronization is automatically triggered every 5 minutes.

TimeClock Plus is the source of truth for employee and absence data. Data synced from TimeClock Plus to Humanity shouldn’t be modified by a user in Humanity.

Humanity is the source of truth for schedule data. Data synced from Humanity to TimeClock Plus shouldn’t be changed in TimeClock Plus.

Employee Data Synchronization

- Qualifications Data Sync

- Important Notes

Positions Data Synchronization

- Hourly Rate by Job Code Sync

- Important Notes

Locations Data Synchronization

- Important Notes

Leave Data Synchronization

- Important Notes

Schedule Data Synchronization

- Important Notes

Integration Requirements

- Humanity Application Requirements ve in their Humanity prof

- TimeClock Plus Application Requirements

Integration Setup Instructions

- Integration Activation (Authentication)

Employee Data Synchronization

The integration will synchronize personal data for Employees in the TimeClock Plus account for which the integration is activated. All Employees from TimeClock Plus will be synced to Humanity as users with Employee permissions.

To set proper account permissions per user in Humanity, go to Staff > Click on the Employee name to access their profile > Navigate to Permissions > Select the required permission level from the Account Type drop-down menu.

Depending on the option selected, when configuring how the Employee data will be synced, the following behavior will occur:

  • “Manual Onboarding” will not activate the Employee in Humanity and will require the standard onboarding process for Employees in Humanity,

  • “Send Onboarding E-mail" will not activate the Employee, but will send the onboarding e-mail automatically,

  • “Auto Enable (Needed for SSO)” will create the Employee in Humanity and will also automatically activate them, bypassing the onboarding process.

If “Manual Onboarding” option has been chosen and you would like to send an activation email to a single, newly created Employee in Humanity, you will need to:

  • Change that user’s status to Inactive in their Humanity profile

  • Go to the Not Activated list from the left side panel within the Staff module

  • Choose Send Activation E-mail Now

If you would like to send an activation e-mail to a few, or all, newly created Employees in Humanity, you will need to:

  • Go to the Staff module and select Employees

  • Click on the Bulk Edit button in the upper-right corner

  • Select Send Activation e-mail within the Bulk Edit options

  • Go to Next Step at the bottom of the page

  • Confirm the action by clicking on Confirm

The following Employee data is synced from TimeClock Plus to Humanity:

  • First Name and Last Name

  • Employee ID (EID)

  • Address with State and ZIP

  • Gender

  • Date of Birth

  • Language selection

  • Email

  • Mobile Phone

  • Hire Date

  • Gender

  • Default Pay Rate as Hourly Wage

  • Work Status (Full or Part-time)

  • Employee Type (Hourly or Salaried)

  • Time zone

 

Integration recognizes and synchronizes data from TimeClock Plus to Humanity upon the following actions:

  • Employee account created in TimeClock Plus;

  • Employee information updated in TimeClock Plus – first name, last name, phone, email, status change, etc;

  • Employee deactivated/suspended in TimeClock Plus.

Qualifications Data Sync

The integration supports synchronization of Employee’s Qualifications from TimeClock Plus to Skills in Humanity. This synchronization is optional.

 

The integration will recognize and synchronize data from TimeClock Plus to Humanity upon the following actions:

  • Qualifications added to Employee in TimeClock Plus;

  • Qualifications expired for Employee in TimeClock Plus.

Important Notes

  • For an Employee to be terminated and deactivated in Humanity, the “Suspended” checkbox must be selected in TimeClock Plus.

  • Employees with the Salaried Overtime rule in TimeClock Plus will be synced as Salaried to Humanity. Employee with any other Overtime rule will be synced as Hourly Employee to Humanity.

  • Master list of Qualifications will create Skills in Humanity. A Skill will be activated for an Employee only when a Qualification is assigned to an Employee in TimeClock Plus.

  • If a Qualification expires for an Employee in TimeClock Plus, the synchronization will deactivate it for that Employee in Humanity as well.

Positions Data Synchronization

The integration supports synchronization of Employee’s Job Code from TimeClock Plus to Position in Humanity. This synchronization is optional only if Schedule sync from Humanity to TimeClock Plus will not be used.

Positions manually created in Humanity will not be deleted/overridden by the integration with data from TimeClock Plus.

Integration recognizes and synchronizes data from TimeClock Plus to Humanity upon the following actions:

  • Job Code created and assigned to Employee in TimeClock Plus;

  • Job Code for Employee updated in TimeClock Plus;

  • Job Code unassigned from Employee in TimeClock Plus.

Important Note

  • Positions manually created in Humanity will not be deleted/overridden by the integration with data from TimeClock Plus.

Hourly Rate by Job Code Sync

If Employee Job Codes are synced as Positions, the integration will support the synchronization of Hourly Rates by Job Code as Hourly Wages in Humanity.

Integration recognizes and synchronizes the data from TimeClock Plus to Humanity upon the following actions:

  • Hourly Rate added to Employee’s Job Code in TimeClock Plus;

  • Hourly Rate for Employee’s Job Code updated in TimeClock Plus;

  • Hourly Rate removed from Employee’s Job Code in TimeClock Plus.

Important Notes

  • Master list of Job Codes in TimeClock Plus will not sync and/or not create a list of Positions in Humanity. Only Job Codes assigned to an Employee that has a Default Location in TimeClock Plus will be synced as (Employee’s) Positions.

Locations Data Synchronization

Integration supports the synchronization of TimeClock Plus Locations or to Humanity Locations. Employee’s assigned Location in TimeClock Plus will become their assigned Location in Humanity. This sync is optional.

 

Locations manually created in Humanity will not be deleted/overridden by integration with data from TimeClock Plus.

 

If an Employee doesn't have an assigned Location in TimeClock Plus, then that Employee’s jobs will be synced to Humanity but won't have an assigned Location. Instead, the Employee’s jobs will belong to a Default Location in Humanity.

 

Integration recognizes and synchronizes data from TimeClock Plus to Humanity upon the following actions:

  • A new Location created and assigned to Employee in TimeClock Plus;

  • An existing Location assigned to Employee is updated in TimeClock Plus;

  • An existing Location assigned to Employee is either deleted or unassigned from Employee in TimeClock Plus.

Important Notes

  • Master list of Locations in TimeClock Plus will be synced to Humanity and create Locations, but Employees won’t be assigned.

  • An Employee will belong to a Location in Humanity only when a Location is assigned to an Employee in TimeClock Plus.

  • If an Employee was assigned a Location in TimeClock Plus, it is highly recommended to enable Locations sync so Employee Job Code can sync to a Position in a corresponding Location in Humanity. Otherwise, those Positions will be created in Default Location in Humanity.

Leave Data Synchronization

Integration supports synchronization of Employee’s Leave data from TimeClock Plus to Humanity.

The Leave data synced from TimeClock Plus to Humanity includes:

  • Leave Code Name

  • Approved Leave Request Start Time and Date

  • Approved Leave Request End Time and Date

The integration recognizes and syncs data upon the following actions:

  • Approved Leave request created in TimeClock Plus.

Important Notes

  • Master list of Leave Codes in TimeClock Plus will be synced to Humanity and create Leave Types. Only Leave Codes assigned to an Employee in TimeClock Plus will be synced as enabled Leave Types for that Employee in Humanity.

  • If there is no “Last Sync Date,” that is, during the first sync between TimeClock Plus and Humanity, the integration will sync all approved absence requests. With every next sync, only approved requests which have been created after the initial sync will be synced to Humanity.

  • Approved Leave requests that have been synced will be visible in Humanity’s Dashboard On Leave widget, Leave module (Upcoming Absence), ShiftPlanning module (Schedule Overview, Leave Schedule, Staff Availability), Staff module (within employee profile in the Leave section), and Reports module (Vacations, Vacation Summary reports).

  • Leave request types in TimeClock Plus may be in hourly units only, but all approved Leave requests will be synced to Humanity as full-day requests only.

  • If an Employee takes an hourly absence request (for example, three hours on Thursday), that employee will be shown in Leave Schedule as being unavailable for the whole day. The Manager will be able to see how many hours the Employee is actually unavailable by pulling up the Vacation Summary Report (in Humanity’s Reports module). The information will be available in the Comments column.

  • For an accurate entitled Leave days/hours amount, please refer to TimeClock Plus as the primary source of truth for Leave data. This information will not be synced to Humanity. In Humanity, Entitled Leave Days for each synced Leave type will be set to 365/366 days by default.

Schedule Data Synchronization

Integration supports synchronization of Employee’s Schedule data from Humanity to TimeClock Plus Basic Scheduler as Scheduled Segments, with Unpaid Breaks duration.

This sync is optional.

Published Humanity Shift, for an Employee, will be synced to TimeClock Plus Basic Scheduler as one whole Scheduled Segment. If there are Unpaid Breaks, the Shift will be split into multiple Scheduled Segments with empty space in between, representing the duration of Unpaid Breaks.

The Schedule data synced from Humanity to TimeClock Plus includes:

  • Shifts Start Time

  • Shift End Time

  • Shift Start Date

  • Shift End Date

  • Shift Unpaid Break(s) duration

  • Shift Employee (employee for whom the shift was created)

  • Shift Position

Integration recognizes and syncs data from Humanity to TimeClock Plus upon the following actions:

  • A Shift for an employee is created and published in Humanity;

  • A Shift for an employee is updated/edited and published in Humanity;

  • A published Shift for an Employee is deleted / Employee is removed from a Schedule in Humanity.

Important Notes

  • The integration will sync only published shifts. Unpublished shifts will not appear in TimeClock Plus.

  • The integration will sync published shifts that have been created, updated, or deleted 48 hours prior to the current sync date and time.

  • All synced shifts will have a Start Time and End Time in the Employee’s assigned time zone synchronized from TimeClock Plus to Humanity, which is the same as the time zone in the Humanity master account.

Integration Requirements

To activate Humanity’s integration with TimeClock Plus and enable data synchronization, a certain set of requirements related to Humanity and TimeClock Plus must be fulfilled.

Humanity Application Requirements

The integration user must have an active Humanity account with administrator access.

The "Prepare account for TCP integration” checkbox must be selected. Please contact your Humanity representative for details.

The preconditions for Absence sync activation are:

  • The Leave settings (Settings > Leave and Availability) must be set to the values shown in the following screenshot:

  • The Deduct weekends from leave requests option under Advanced settings for the Leave module (Settings > Leave and availability) has to be set in a way that none of the days are selected. See the screenshot below:

TimeClock Plus Application Requirements

The following configuration is required in TimeClock Plus:

  • An administrative or integration user must be created;

  • Username and Password details of that user are required to connect Cronicle and TimeClock Plus.

Integration Setup Instructions

Integration Activation (Authentication)

Prerequisites for activating the integration in TimeClock Plus are: 

  • Humanity App ID and App Secret;

  • Humanity User and Password, in order to get the token for the connection.

Integration activation steps, in TimeClock Plus:

1. Once all required data is gathered, open TimeClock Plus Automation Module named “Humanity Integration”.

2. In the “General” part of the screen enter: 

a. Humanity App ID, 

b. Humanity App Secret. 

3. In the “Token” part of the screen enter:

a.  Humanity User, 

b.  Humanity Password (for that user), 

c.  Select “Retrieve new token” checkbox to retrieve the initial token,

d. Save the configuration, click away from module configuration, and then come back to it to see the token generated.

Please do not enter any values manually in fields in the “Last Sync Times” part. These will be automatically populated every 5 minutes with times of successful syncs. 

These steps are required to make a connection and authentication (“handshake”) between TimeClock Plus and Humanity. The actual configuration of the data which will be synced between the two apps is done in the Cronicle tool. 

Integration configuration steps, in Cronicle:

1.   For Plugin, select "Humanity Integrator".

2.  Company ID is the TCP Company number (should always be 1).

3.  Company Namespace will be the customer's Namespace.

4.  User and Password are from the TCP Manager account that the system will use to connect to the Database.

5.  "Sync Employees" determines if Employees will be synced to Humanity. This must be enabled in order to leverage sync of any following data.

6.   "Employee Activation Options" will determine how the Employee activation process will perform. There are 3 options:

a. "Manual Onboarding" will not activate the Employee in Humanity and will require the standard onboarding process for Employees in Humanity,

b.   "Send Onboarding E-mail" will not activate the Employee, but will send the onboarding e-mail automatically,

c.    "Auto Enable (Needed for SSO)" will create the Employee in Humanity and will also automatically activate them, bypassing the onboarding process.

7.   "Location Sync Options" will determine if Locations will be synced and if the TimeClock Plus value used will be Location of Department. There are 3 options:

a.  "Do Not Sync" will not sync Location data to Humanity;

b.  "TCP Locations to HUM Locations" will create Locations in Humanity based on the Locations in TCP;

c.  "TCP Departments to HUM Locations" will create Locations in Humanity based on Employee Departments in TimeClock Plus.

8.  "Sync Employee Job codes" will be the option that determines if Positions will be created in Humanity. If selected, Positions will be created and attached to Employee's Default Location. This option is required if Schedule needs to be synced from Humanity to TimeClock Plus.

9.   "Sync Master Qualifications list" will determine if Qualifications will be used to create Skills in Humanity. If this is not enabled, Skills will not be created.

10.   "Sync Employee Qualifications" will determine if assigning the Skill to the Employee will be done by the adapter. If enabled, the Qualifications assigned to Employees in TimeClock Plus will be used to assign Skills to Employees in Humanity.

11.   "Sync Leave codes" will determine if Leave Job Codes in TimeClock Plus will create Leave Types in Humanity for time off schedule.

12.   "Sync Employee Leave Codes" will determine if Leave Codes assigned to Employees in TimeClock Plus will be used to assign Leave Types to Employees in Humanity.

13.   "Sync Schedules from Humanity to TCP" determines if schedules will be synced to TimeClock Plus from Humanity.

14.   "Sync Leave requests to HUM" determines if approved time-off requests in TimeClock Plus will be sent to Humanity as time off schedule items.

15.   TCP API URL must contain customer’s TimeClock Plus URL in the following format:

https://CUSTOMERNAMESPACE.tcpondemand.com/v1.

16.   Humanity API URL must contain the following URL:
https://humanity.com/api/v2/partners/tcp.

If you have any further queries, please don't hesitate to reach out to us at support@humanity.com.

Did this answer your question?