^

Guides

Getting Started
  Introduction
  Your Business Settings
  Export From Other Systems
  Add An Employee
  Clocking Hours
  Timesheet Software
  Grouping Employees
  Management Configuration
  Locations

Rostering
  The Roster Process
  Roster Templates
  Roster Calendar
  Calendar View
  SMS Rosters

Timesheets
  The Timesheet Process
  Timesheet vs Roster
  Timesheet from Roster

Payroll
  The Payroll Process
  A Payrun
  Rate Rules
  Shift Rules
  Break Rules
  Deduction Rules
  Extra Rules
  Time In Lieu
  Public Holidays

Leave Request
  The Leave Request Process
  Leave Request Review
  Leave Payroll Process

Reports
  Single Touch Payroll
  Payment Summary
  Xero Integration

Other features
  Messaging

SuperChoice
  Processing Super

SuperChoice (Old process)
  Super Clearing House
  SuperChoice Setup
  Adding Super Fund
  Adding Employees
  Super Payment

Employees
  Employee Console
  Smartphone Login
  Push Notification
  Requesting Leave

Developers
  Partner Logo
  API Hello World
  API Add Employee
  API Timesheet

  Print Guide

Add/Replace and Get timesheet data via developer API


This guide explains how to add, replace, or get timesheet data via API.




Before starting this tutorial make sure you have completed the Hello World tutorial.

To complete the Hello World tutorial click here  Hello World




Adding and replacing timesheet data

The add/replace feature is built into a single action.

After a shift is added to Microkeeper, changes to that shift can be made as expected, however, the third party app is considered the point of truth.

Microkeeper records the method used when clocking on and off. For example fingerprint, NFC, etc.

When timesheet data is added via API the method is set to API.

Duplicate detection

If a shift is added to Microkeeper via API, duplicate detection takes places.

If a shift overlaps another shift, the original shift will be permanently deleted along with any change made to that shift within Microkeeper. 

Only shifts added via API undergo duplicate detection by default, which is recommended.

Example

A shift from 10:00 to 12:00 is added via API.

The shift is then edited in a third party app to 10:00 to 13:00.

If the same data is sent again the new entry will overlap the last entry, the original entry will be permanently deleted and the new record will take its place.




Step 1

Set the mk_action variable and mk_data variable.

Variable name
Values and Example
mk_action

add_timesheet

mk_data

{ "config": {"replace":"overlap", "method":"613"} ,"shifts":[{"EID":"3","date":"2018-05-22", "clockon":"6:15:00", "clockoff":"10:00", "JID":"2206", "note":"I\'m running = late%26quot;!"},{"eusername":"joel_davis","date":"2018-05-21", "clockon":"10:00:00", "clockoff":"16:00:00"}] }




Step 2

List of available fields

The minimum fields required to add timesheet data are:

  • EID or eusername
  • date
  • clock on
  • clock off

Below is a full list of variables that can be added to mk_data when adding timesheet data.

Name
Classification
Note
shifts
List
List of all the shifts being added to Microkeeper
config
Object
Config options when adding shifts


'Config' variables

Variable name

Description

Required

Excepted formats

Options

replace

How Microkeeper will determine how to replace a shift

False

Alphanumeric

overlap (default)
For shifts that overlap, the incoming shift will replace the existing shifts. The analysis is done by date, by employee and by shift.

For example, the shift from 10:00 to 13:00 replaces shift 10:00 to 12:00

date
All shifts from an incoming date replace any existing shifts from that date. 

For example shift 10:00 to 12:00 replaces shift 14:00 to 16:00, even though they don't overlap.

date_range
A range of dates to replace data for. This will delete all current data and replace it with incoming data for the date range set.
replace_start and replace_end must be set.

none
When a shift is not replaced but added, this will result in duplicates if the same data is sent twice.

method
What type of shifts are being replaced
False
Alphanumeric
613 (default)
Only shifts that are created by API are replaced.

all
 Can be used to replace all shifts regardless of the method of clocking. This option is not recommended but might be required if changing between clocking systems.
replace_start
Replace start date
True if replace is set to date_range
Date YYYY-MM-DD
The start date of the date range to be deleted.
replace_end
Replace end date
True if replace is set to date_range
Date YYYY-MM-DD
The end date of the date range to be deleted.


replace set to date_range is the recommended option for a replication model when sending bulk volumes of shifts.

If a shift is deleted from the third party system or the times significantly altered this option offers a full replacement each time.


'Shifts' variables

Variable name

Description

Required

Excepted formats

Example

EID

EmployeeID

TRUE or eusername

Numeric

1234

eusername

Employee username

TRUE or EID

Alphanumeric

john_smith

date

Date of shift

TRUE

Date YYYY-MM-DD

2018-05-18

clockon

Clock on time

TRUE

Time HH:MM:SS, HH:MM

06:15

clockoff

Clock off time

TRUE

Time HH:MM:SS, HH:MM

14:30

JID

Job ID in Microkeeper 

Jobs > Jobs

Mouseover ID

Optional

Numeric

4565

note

Note attached to shift

Optional

Alphanumeric

JSON and URI can cause issues with apostrophe quotes and amps make sure to test.

" = %26quot;

& = %26

' = should be fine might require escaping

I'm running "late &

I'm running %26quot;late %26

BreakID
List of Microkeeper Break ID numbers
Optional
Numeric
714,713


BreakID

When a Break Rule is created in Microkeeper it is assigned a unique ID number. Those numbers can be sent via API when adding timesheet data.

To get your BreakID numbers go to:

Settings > Payroll Rules > Break Rules

Mouseover the ID number and a BreakID will be displayed.


Job ID (JID)

When Jobs are added to Microkeeper they are assigned a unique ID number. A JID can be send via API when adding timesheet data.

To get your Job ID numbers go to:

Jobs > Jobs

Mouseover the ID number and a JID will be displayed.




Step 3

Response

The response will be in JSON and in the format outlined in the Hello World example.

When timesheet data is successfully added to Microkeeper a successful message will be returned.

The message could be displayed to the user as a confirmation.

The variables added and replaced are returned.

added could be used for validation. For example; sent 15 shifts, 15 shifts added, thus validation passed.

replaced is an indicator. For example, if 8 shifts were added then 10 shifts were added the next time, replaced would be set to 8, thus making sense to the user.


Successful example

{ "success":"1", "authenticated":"1", "message":"15 shifts added replacing 13 shifts", "data": {"added":15,"replaced":13} }


Notes and limitations

If a shift is deleted from the third party system, then it will not be automatically deleted in Microkeeper, thus if the data has already been pushed through, it might have to be manually deleted in Microkeeper if replace is not set to date_range.

All incoming shifts will automatically be approved, but "who_approved" the shift will not be recorded.


API timesheet performance


Event
X = 100
X = 1,000
X = 10,000
Adding X shifts
0.5
1.2
3.2
Replacing X shifts
0.6
1.4
4.8
Get X shifts  (including graphics render)
0.5
2.3
11.5

Delete 10,000 shifts 2.7 seconds

Time in seconds





Retrieving timesheet data

Microkeeper timesheet data can be exported from Microkeeper via API

All timesheet data will be included via the data range supplied.

Up to 31 days of data can be exported in a single request.




Step 1

Set the mk_action variable and mk_data variable.

Variable name
Values and Example
mk_action

get_timesheet

mk_data

{ "start_date":"2018-05-21", "end_date":"2018-05-21", "EID":"3,4,5" }




Step 2

List of available fields

The minimum fields required to get timesheet data are:

  • start_date
  • end_date

Below is a full list of variables that can be used to filter the results.

A list of staff can be returned by including the eusername of EID.


Variable name

Description

Required

Excepted formats

Example

start_date

Start of the date range

TRUE

Date YYYY-MM-DD

2018-05-18

end_date

End of the date range

TRUE

Date YYYY-MM-DD

2018-05-23

eusername

Employee username

Optional

Alphanumeric separated by commas

john_smith1,john_smith2

EID

Employee ID

Optional

Numeric separated by commas

1234,1235,1236




Step 3

Response

Field name
Explanation
Example
TSID
The Timesheet ID as recorded by Microkeeper - Unique for every record
11235321
eusername
Employee username
john_smith
EID
Employee ID
1234
date
Date YYYY-MM-DD
2018-05-18
clockon
Clock on time HH:MM:SS
09:00:00
clockoff
Clock off time HH:MM:SS
If a shift goes past midnight it will start back to 00:00
17:00:00
original_on
original_off

The original clock on and off time before manager might have made changes
09:00:00
mod_on
mod_off

eusername of who changed the clock on or clock off time
john_smith
JID
Job ID integer
2231
note
A note left by manager or employee - Alphanumeric special characters
Hello World
break_min
Break duration in minutes. Break rules are calculated and if applicable are summed up and totaled
60
paid_hours
Hours that will go through to payroll clock off-clock on-breaks
7.6
method_on
method_off

605 = GPS
606 = Fingerprint
607 = Manually entered by manager/employee
608 = Generated from roster
609 = Quick clock
610 = Employee console used
611 = NFC used
612 = Phone used
613 = Entered via API
Blank = not clocked off
String, usually numeric
613
lon_on
lon_off

If GPS, the clock on and off Longitude
144.52562
lat_on
lat_off

If GPS, the clock on and off Latitude
-38.21302
acc_on
acc_off

If GPS, the accuracy of GPS in meters when clocking on and off
63
approved
0 = Not approved
1 = Approved
2 = Declined
There are two methods of approving shifts in Microkeeper.
This is used for tick approval only
1
who_approved
Username of who approved
john_smith


Notes and limitations

All shifts will be included regardless of their approval status.

Deleted shifts will not be included in the export even though they are still present.

Break analysis is only on an individual shift.

For example; shift 10:00 to 12:00 and shift 12:00 to 15:00. In Microkeeper payroll this is treated as a 5 hours shift for break analysis but in API export this is treated as two separate shifts thus some break rules won't apply.

If clockoff is set to 00:00:00 the employee clocked off at midnight.

If clockoff and original_off are set to 'blank' the employee has not clocked off, break_min and paid_hours will be set to 0.


Successful example

The example below includes a single record from a search from a single date for a single employee.

{ "success":"1", "authenticated":"1", "message":"Timesheet data", "data": { "timesheet": [{"TSID":"1631504","eusername":"joel_davis","EID":"3","date":"2018-05-21","clockon":"10:00:00","clockoff":"16:00:00","original_on":"10:00:00","original_off":"16:00:00","mod_on":"","mod_off":"","JID":"0","note":"","break_min":60,"paid_hours":5,"method_on":"613","method_off":"613","approved":"2","who_approved":"joel_davis"}] } }