This guide explains how to insert and retrieve roster 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
Also, review the Location API guide and Jobs API guide.
Roster data can be sent from a third party platform to Microkeeper via API.
The third party platform is considered the point of truth if using this endpoint.
Any existing roster data will be permanently deleted before incoming roster data is stored.
Date Range
When roster data is sent the date range must also be sent.
This means if a Mon-Sun date range is supplied, while only Mon-Fri roster data is sent, the Saturday and Sundays data will be deleted.
This allows for a complete clone from the third party platform to Microkeeper.
Locations
Only the Location ID's (LID) supplied are affected.
This means different third party platforms can be responsible for different locations.
Or, some locations can be managed within Microkeeper, while others are managed by a third party platform.
Deleting a roster data
A roster cannot be directly deleted.
However, when new roster data is sent for a supplied date range, it replaces the existing data effectively deleting it within the date range.
Updating roster data
Roster data cannot be updated, new roster data can be sent which replaces existing data.
Working past midnight
Shifts that go past midnight should go back to 00:00.
For example; a 4 hour shift that starts at 11 pm should be sent as:
23:00 to 03:00
Limitations
If the EID or eusername is invalid an error will not be sent, the shift will not have an employee assigned to it.
A shift cannot be longer than 23 hours and 59 minutes long.
The date of the shift is determined based on the start time.
Step 1
Set the mk_action variable and mk_data variable.
| Variable name | Values and example |
| mk_action | add_roster |
| mk_data | { "config":{"method":"replace","start_date":"2018-05-20","end_date":"2018-05-28","LID":[1919,1826]} ,"shifts":
[{"eusername":"joel_davis","LID":1826,"date":"2018-05-21","start":"10:00","end":"15:00","JID":"2206","hide":"0","note":"API1"},
{"eusername":"joel_davis","LID":1826, "date":"2018-05-24","start":"15:00","end":"03:00","JID":"2206","hide":"0","note":"API2","EID":3,"break":"20:00:00"}] } |
Step 2
Below is a list of variables that can be added to mk_data when inserting roster data.
| Name | Classification | Note |
| config | Array | Config options |
| shifts | List | List of all the payments being added to the payrun |
| Name | Required | Classification | Format | Description | Example |
| method | True | Field | String | replace - Deletes all existing roster data between the date range and replaces is with incoming data. Currently, this is the only option. Future releases might include other options. | replace |
| start_date | True | Field | YYYY-MM-DD | Start date to be replaced | 2018-05-20 |
| end_date | True | Field | YYYY-MM-DD | Start date to be replaced | 2018-05-28 |
| LID | True | List | JSON INT | Locations to be replaced | [1919,1826] |
| Name | Required | Description | Format | Example |
| EID | True or eusername | Employee ID as recorded in Microkeeper. Set to 0 if no employee is assigned. | INT | 1234 |
| eusername | True or EID | Employee username as recorded in Microkeeper. Set to blank '' if no employee is assigned. | string | john_smith |
| LID | True | Location ID as recorded in Microkeeper | INT | 1826 |
| date | True | Date the shift starts on | YYYY-MM-DD | 2018-05-21 |
| start | True | Start time | HH:MM:SS or HH:MM | 09:00 |
| end | True | End time | HH:MM:SS or HH:MM | 17:00 |
| break | False | Break start time Note: Break rule must be created in Microkeeper | HH:MM:SS or HH:MM | 12:00 |
| JID | False | Job ID as recorded in Microkeeper | INT | 1234 |
| hide | False | Is the shift hidden from the employee | Boolean | 0 |
| note | False | A note attached to the shift | Alphanumeric | Hello World 123 |
JID
The JID will be set to the JID assigned to the Location when retrieving data from Microkeeper if the JID is not set in the roster.
Step 3
The response will be in JSON and in the format outlined in the Hello World example.
The number of successfully inserted shifts will be returned as the count field.
Successful response example
{ "success":"1", "authenticated":"1", "message":"Shifts successfully inserted", "data": { "count": 2} }
To get roster data via API a date range needs to be supplied.
Up to 31 days of data can be retrieved in a single API call.
Step 1
Set the mk_action variable and mk_data variable.
| Variable name | Values and example |
| mk_action | get_roster |
| mk_data | { "start_date":"2018-01-01", "end_date":"2018-01-05" } |
Step 2
Below is a list of variables that can be added to mk_data when retrieving roster data.
| Name | Format | Example | Description |
| start_date | YYYY-MM-DD | 2018-01-01 | Start of range |
| end_date | YYYY-MM-DD | 2018-01-05 | End of range |
Step 3
The response will be in JSON and in the format outlined in the Hello World example.
Refer to the 'shifts' variables table above for the specs on each field.
The data array includes a roster array with a list of all rostered shift between the dates supplied.
Successful response example
{ "success":"1", "authenticated":"1", "message":"Roster data", "data": { "roster": [{"date":"2018-05-21","LID":"2191","JID":"0","eusername":"alice_tomson","EID":"12","start":"08:00:00","end":"09:00:00","break":"00:00:00","hide":"0","note":""},{"date":"2018-05-21","LID":"2191","JID":"0","eusername":"jemson_mccool","EID":"8565","start":"08:00:00","end":"09:00:00","break":"00:00:00","hide":"0","note":""}] } }
Same example readable
Array
(
[success] => 1
[authenticated] => 1
[message] => Roster data
[data] => Array
(
[roster] => Array
(
[0] => Array
(
[date] => 2018-05-21
[LID] => 2191
[JID] => 0
[eusername] => alice_tomson
[EID] => 12
[start] => 08:00:00
[end] => 09:00:00
[break] => 00:00:00
[hide] => 0
[note] =>
)
[1] => Array
(
[date] => 2018-05-21
[LID] => 2191
[JID] => 0
[eusername] => jemson_mccool
[EID] => 8565
[start] => 08:00:00
[end] => 09:00:00
[break] => 00:00:00
[hide] => 0
[note] =>
)
)
)
)