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
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
The minimum fields required to add timesheet data are:
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 |
Variable name | Description | Required | Excepted formats | Options |
replace | How Microkeeper will determine how to replace a shift | False | Alphanumeric | overlap (default) For example, the shift from 10:00 to 13:00 replaces shift 10:00 to 12:00 date For example shift 10:00 to 12:00 replaces shift 14:00 to 16:00, even though they don't overlap. date_range none |
| 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.
Variable name | Description | Required | Excepted formats | Example |
EID | Microkeeper Employee ID | TRUE (1) | Numeric | 1234 |
eusername | Employee username | TRUE (1) | Alphanumeric | john_smith |
EmployeeID | 3rd Party Employee ID | TRUE (1) | Alphanumeric | emp001 |
(1) One of the following is required: EID, eusername, EmployeeID | ||||
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 |
| LID | Location ID in Microkeeper | Optional | Numeric | 2233 |
| ROID | Role ID in Microkeeper | Optional | Numeric | 5566 |
JID | Job ID in Microkeeper Jobs > Jobs Mouseover ID OR Third Party ID | Optional | Numeric for Microkeeper OR Third party ID | 4565 OR ABC123 |
| job_title | Job Title | Optional, but required to add a new Job | Alphanumeric | ABC123 |
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 |
| break_duration | Duration in minutes | Optional | Integer | 30 |
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.
If a break duration is sent through this will be used to find a Break Rule in Microkeeper that matches the duration.
Example if 30 minutes is sent through, a 30 minute Selectable Break Rule will be applied.
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 Job ID numbers go to:
Menu > Jobs > Jobs
Mouseover the ID number and a JID will be displayed.
A Third Party Job ID can be sent instead of the Microkeeper JID, this will be used to lookup the Microkeeper JID for recording.
If the Third Party Job ID is not present, a new Microkeeper Job can be created on the fly, the job_title field must be set to do this.
Step 3
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.
| 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
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
The minimum fields required to get timesheet data are:
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
| 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 |
| LID | Location ID integer | 3322 |
| ROID | Role ID integer | 8866 |
| 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 614 = Facial Recognition 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":"","LID":"0","ROID":"0" ,"JID":"0" ,"note":"","break_min":60,"paid_hours":5,"method_on":"613","method_off":"613","approved":"2","who_approved":"joel_davis"}] } }Same Example Readable
{
"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":"",
"LID":"0",
"ROID":"0",
"JID":"0",
"note":"",
"break_min":60,
"paid_hours":5,
"method_on":"613",
"method_off":"613",
"approved":"2",
"who_approved":"joel_davis"
}
]
}
}