Keypay/Employment Hero Integration

The KeyPay base connection is configured through the KeyPay API
In Salesforce we hold the credentials that are required to connect to KeyPay through the KeyPay API in a Custom Setting which can be access via the Setup Menu.
Salesforce sandboxes are connected to the Key Pay Staging Environment for testing.
There are a set of Apex Classes developed to establish the base connection and to manage the different data services that are supported between the two systems.

See below 3 data services and requirements:

1. Employee Sync

When a Contact Record in Salesforce meets the requirement of having the Start Date field with a value, on Save of the Contact Record a trigger will attempt to sync the record to KeyPay.
Once a sync is triggered the following fields will map from the Employee record in Keypay > Salesforce Contact staff record
WHEN Start_Date__c is created/updated with a value in Salesforce
- THEN create the Contact Record in KeyPay.
WHEN any of the below values are updated on the Salesforce side.
- THEN update the corresponding value in KeyPay.
WHEN End_Date__c is entered on a Contact Record.
- THEN update the termination_date on the corresponding record in KeyPay.

Field in Keypay	Field on Staff Contact record Salesforce

Field in Keypay	Field on Staff Contact record Salesforce
`Employment Type`
`Tax File Number`
`EH Sync Status`
`EH Last Sync Status`
`EH Sync Details`

2. Timesheet Sync

Time Sheet Records are created in Salesforce based on a configured scheduled process which runs at an agreed time. This configuration can be access via the Time Sheet Settings option in the Setup Menu.

Generated Time Sheets have Time Sheet Entry Records associated to them when workers complete a Service Appointment. Time Sheet Entry Records are usually auto generated based on the employee checking in and checking out of their appointment.

At an agreed time a scheduled process runs in Salesforce to sync the Time Sheets with their related Time Sheet Entries to KeyPay. When the sync is complete, the Time Sheet Entry Records will be available in KeyPay for approval.

We can also enable users to sync a Timesheet or Timesheet Entry

TECHNICAL SPECIFICATION

From a Time Sheet and Time Sheet Entry record in Salesforce we will trigger the creation of Time Sheet and Time Sheet Entry records in Employment Hero through the KeyPay API.

A summary of the Time Sheet data services can be found here - https://api.keypay.com.au/australia/reference/timesheets

We will use the following methods:

Method	HTTP Request	Description

Method	HTTP Request	Description
Bulk Insert Timesheets	`POST /api/v2/business/{businessId}/timesheet/bulk`	When a `Time Sheet` is created in Salesforce, we will trigger the creation of the `Time Sheet` in KeyPay. `Time Sheets` get created in Salesforce via a scheduled service (see Time Sheet Settings in the Setup Menu) where `Time Sheets` for all 400-500 workers will be created. We can run a Bulk Insert `Time Sheets` scheduled service after the `Time Sheet` creation service is run in Salesforce and trigger individual `Time Sheet` creation for any records that are created outside this service.
Create timesheet line	`POST /api/v2/business/{businessId}/timesheet`	When a `TimeSheetEntry` is updated or created with `Status = 'Approved'`, then trigger the `Time Sheet Line` to be created in KeyPay.
Delete timesheet line	`DELETE /api/v2/business/{businessId}/timesheet/{timesheetLineId}`	If a `TimeSheetEntry` is deleted in Salesforce, then delete the `Time Sheet Line` in KeyPay.
Update timesheet line	`PUT /api/v2/business/{businessId}/timesheet/{timesheetLineId}`	If a `TimeSheetEntry` is updated in Salesforce, then update the `Time Sheet Line` in KeyPay.
Update/Replace timesheets	`PUT /api/v2/business/{businessId}/timesheet/bulk`	If a `TimeSheet` is updated in Salesforce, then update the `Time Sheet` in KeyPay.

TIME SHEET MAPPING

https://api.keypay.com.au/australia/reference/timesheets/au-timesheet--post?v=latest

Method	HTTP Request	Description

Method	HTTP Request	Description
Bulk Insert Timesheets	`POST /api/v2/business/{businessId}/timesheet/bulk`	When a `Time Sheet` is created in Salesforce, we will trigger the creation of the `Time Sheet` in KeyPay. `Time Sheets` get created in Salesforce via a scheduled service (see Time Sheet Settings in the Setup Menu) where `Time Sheets` for all 400-500 workers will be created. We can run a Bulk Insert `Time Sheets` scheduled service after the `Time Sheet` creation service is run in Salesforce and trigger individual `Time Sheet` creation for any records that are created outside this service.
Create timesheet line	`POST /api/v2/business/{businessId}/timesheet`	When a `TimeSheetEntry` is updated or created with `Status = 'Approved'`, then trigger the `Time Sheet Line` to be created in KeyPay.
Delete timesheet line	`DELETE /api/v2/business/{businessId}/timesheet/{timesheetLineId}`	If a `TimeSheetEntry` is deleted in Salesforce, then delete the `Time Sheet Line` in KeyPay.
Update timesheet line	`PUT /api/v2/business/{businessId}/timesheet/{timesheetLineId}`	If a `TimeSheetEntry` is updated in Salesforce, then update the `Time Sheet Line` in KeyPay.
Update/Replace timesheets	`PUT /api/v2/business/{businessId}/timesheet/bulk`	If a `TimeSheet` is updated in Salesforce, then update the `Time Sheet` in KeyPay.

TIME SHEET ENTRY MAPPING

KeyPay	Salesforce	Notes

KeyPay	Salesforce	Notes
classification		DO NOT MAP
classificationId		DO NOT MAP
comments	TimeSheet.Description
employeeId	TimeSheet.ServiceResourceId.Contact__c.Employment_Hero_ID__c
endTime	TimeSheetEntry.EndTime
externalId	TimeSheetEntry.Id
fullyQualifiedLocationName		DO NOT MAP
hiddenComments		DO NOT MAP
id
leaveCategoryId		DO NOT MAP
locationId		DO NOT MAP
locationIdDeleted		DO NOT MAP
payCategoryId		DO NOT MAP
rate		DO NOT MAP
shiftConditionIds		DO NOT MAP
shiftConditions		DO NOT MAP
source		`"Salesforce"`
startTime	TimeSheetEntry.StartTime
status	TimeSheetEntry.Status
units	TimeSheetEntry.EndTime - TimeSheetEntry.StartTime	Create new formula field
workType	Service_Appointment__r.WorkOrder.WorkType
workTypeId	Service_Appointment__r.WorkOrder.WorkType.Employment_Hero_Code__c

3. Leave Requests

Leave Requests are retrieved from Employment Hero and added into Salesforce as Resource Absence records.

SCHEDULED SERVICE

Salesforce will run a process each night at a specified time to retrieve Leave Request records from KeyPay and create them as Resource Absence records in Salesforce.

Absence Records are created in Salesforce with the following mapping:

KeyPay Leave Field	Salesforce Absence Field

KeyPay Leave Field	Salesforce Absence Field

Concept Care