^

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
  Jobs and Cost Centres

HR
  The Leave Request Process
  Leave Request Review
  Leave Payroll Process
  Skills Matrix

Reports
  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 Employee
  API Timesheet
  API Payroll
  API Jobs
  API Roster

  Print Guide

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