^

Insert and get roster data via developer API


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.




Inserting roster data via API

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 nameValues 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

'mk_data' variables


Below is a list of variables that can be added to mk_data when inserting roster data.

NameClassificationNote
configArrayConfig options
shiftsListList of all the payments being added to the payrun


'config' variables


NameRequiredClassificationFormatDescriptionExample
methodTrueFieldString
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_dateTrueFieldYYYY-MM-DD
Start date to be replaced

2018-05-20
end_dateTrueFieldYYYY-MM-DD
Start date to be replaced

2018-05-28
LIDTrueListJSON INT
Locations to be replaced

[1919,1826]


'shifts' variables


NameRequiredDescriptionFormatExample
EIDTrue or eusername
Employee ID as recorded in Microkeeper.
Set to 0 if no employee is assigned.

INT1234
eusernameTrue or EID
Employee username as recorded in Microkeeper.
Set to blank '' if no employee is assigned.

stringjohn_smith
LIDTrue
Location ID as recorded in Microkeeper

INT1826
dateTrue
Date the shift starts on

YYYY-MM-DD2018-05-21
startTrue
Start time


HH:MM:SS
or
HH:MM

09:00
endTrue
End time


HH:MM:SS
or
HH:MM

17:00
breakFalse
Break start time
Note: Break rule must be created in Microkeeper


HH:MM:SS
or
HH:MM

12:00
JIDFalse
Job ID as recorded in Microkeeper

INT1234
hideFalse
Is the shift hidden from the employee

Boolean0
noteFalse
A note attached to the shift

AlphanumericHello 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

Response

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} }





Getting roster data via API

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 nameValues and example
mk_action

get_roster

mk_data
{ "start_date":"2018-01-01", "end_date":"2018-01-05" }




Step 2

'mk_data' variables


Below is a list of variables that can be added to mk_data when retrieving roster data.

NameFormatExampleDescription
start_dateYYYY-MM-DD2018-01-01
Start of range

end_dateYYYY-MM-DD2018-01-05
End of range




Step 3

Response

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] =>
                        )
                )
        )
)