^

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

Create and get job data via developer API


This guide explains how to create, update and get job 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




Creating and updating Jobs via API

Create and update jobs command are done in the same action.

When using the update_jobs endpoint the third party system is considered the point of truth and Microkeeper is just getting a copy of the list of active jobs.

There are two ways to update jobs in Microkeeper, one is considered real-time and the other is considered batch method which will likely be run on a cron job.


Real-time method

The real-time method is recommended if your development environment can trigger a job being pushed to Microkeeper when it's created or updated in the third party app.

status_set should be set to skip

This means when the job is created, updated or finished in the third party app, it's instantaneously sent to Microkeeper.

Tracking the JID (Job ID) is required with this method.


Batch method

This option is for updating batch list.

The concept of this option is that a full list of active jobs are sent through each time a cron job is ran.

status_set should be set to finish_all

All jobs that are not on the list being sent via API, but are in Microkeeper will be marked as Finished.

This option does not require the JID to bet sent, the Title can be used as a unique way to identify the Job, which is case sensitive.


Duplicate detection

A job with the same title as a job already in Microkeeper will trigger an error, all other jobs will be updated accordingly.


Activating a finished job

All finished jobs are included in the search thus if a finished job is sent through it will become active again.


Deleting a job

For legal reasons a record must be kept for 7 years, therefore jobs can't be deleted, mark the job as Finished instead.


Limitations

It's impossible to update a job's title if the JID is not supplied, therefore if the title is changed in a third party app and the JID is not set, a new job with the new title will be created instead.




Step 1

Set the mk_action variable and mk_data variable.

Variable name
Values and example
mk_action

update_jobs

mk_data
{ "config":{"status_set":"skip"} ,"jobs":[{"JID":"0","JobID":"ABC1","CID":"0","title":"Job 1","startdate":"2018-10-25","enddate":"2018-11-25","job_access":"2","status":"Active"},{"JID":"0","JobID":"ABC2","CID":"0","title":"Job 2","startdate":"2018-10-25","enddate":"2018-11-25","job_access":"2","status":"Active"},{"JID":"0","JobID":"ABC3","CID":"0","title":"Job 3","startdate":"2018-10-25","enddate":"2018-11-25","job_access":"2","status":"Active"},{"JID":"44444","JobID":"ABC4","CID":"0","title":"Job A4","startdate":"2018-10-25","enddate":"2018-11-25","job_access":"2","status":"Active"}] }




Step 2

mk_data variables


Below is a list of variables that can be added to mk_data when adding/updating job data.

Name
Classification
Note
config
Array
Config options
jobs
List
List of all the payments being added to the payrun


'config' variables

Variable name

Description

Required

Excepted formats

Options

status_set

How to treat jobs that at not on the list being sent

TRUE

skip

finish_all

skip - Only update the job being sent through

finish_all - Mark all jobs that are not sent as Finished


Note

Microkeeper recommends using skip while testing to avoid accidentally Finishing all jobs in the database.


'jobs' variables

Variable name

Description

Required

Excepted formats

Example

JID

The unique Job ID as recorded in Microkeeper

TRUE
Must be set to 0 if not known
INT
1234
0
Job ID

The Job ID as recorded by the third-party app
Microkeeper will return this value with relative JID for tracking in the third-party app.

FALSE
Alphanumeric
ABC
CID

Unique Client ID as recorded by Microkeeper
Set to 0 for in-house job.

FALSE
INT
5678
0
title

The title of the Job
Avoid allowing some special characters, eg \ / | " ' &
Brackets are accepted { } [ ] ( )
Other accepted ! @ #

TRUE
Alphanumeric
Job A
startdate
Start date of Job
Default 0000-00-00

FALSE

YYYY-MM-DD
2018-10-20
enddate
End date of jobs
Default 0000-00-00

FALSE

YYYY-MM-DD
2018-10-30
job_access

1 = All employees
All employees can clock onto this job. When adding a new employee they will automatically have access to the job.

2 = Location The employee can only clock jobs that are near their location. This requires a GPS device and locations to be set up correctly. Usually the recommended option for large business.

0 = Individual Individual employees can be selected, allowing access to just those employees. This can be time-consuming for admin and usually overly restrictive. (Deprecated, do not use this option).

INT = Group ID This option is going to replace the Individual option, assigning a group of staff to a Job via the Group ID which will refer to a list of staff. This option is not live yet.


FALSE

INT
1
status

Quoted The Job is quoted for, but not yet won.

Pending The Job is won but is not ready to be clocked yet.

Active The Job is active and ready for staff to clock.

Finished The Job is archived and can no longer be clocked onto.

Case Sensitive.


FALSE

String
Active


If jobs are being sent to Microkeeper via API job management should be taking place in the third party app.

Thus just an Active or Finished status will be required.




Step 3

Response

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

The data field will include four possible lists, these lists will only be present if a record was added to the list.

data variables

FieldDescriptionFormatExample
update
This is a list of JID's that were updated or created.
If a JobID was supplied this is returned.
If no JobID was supplied then the value will be an incremental INT.
If updating a field it's best practice to supply the JID.
If creating a job the JID must be set to 0.

"update":{"JobID":JID}

or

"update":{"INT":JID}
"update":{"ABC":123}
finished
Jobs that are marked as finished are returned in a list.

"finished":{"INT":JID}
"finished":{"ABC":123}
not_found
If a JID was not found it will be returned.
This will be considered an error, requiring the user's action to fix.

"not_found":{"INT":JID}
"not_found":{"ABC":123}
duplicate
If a JID is not supplied the job Title will be used.
If a duplicate job title is detected the record will not be created.
This will be considered an error, requiring the user's action to fix.

"duplicate":{"INT":JID}
"duplicate":{"ABC":123}


Successful response example

{ "success":"1", "authenticated":"1", "message":"Jobs updated", "data":{"update":{"ABC1":2591,"ABC2":2592,"ABC3":2593},"finished":[2588,2589,2590]},{"not_found":{"ABC1":"44444"},{"duplicate":{"ABC1":"44444"} }


Same example readable

Array
(
    [success] => 1
    [authenticated] => 1
    [message] => Jobs updated
    [data] => Array
        (
            [update] => Array
                (
                    [ABC1] => 2591
                    [ABC2] => 2592
                    [ABC3] => 2593
                )
            [finished] => Array
                (
                    [0] => 2588
                    [1] => 2589
                    [2] => 2590
                )
            [not_found] => Array
                (
                    [ABC4] => 44444
                )

            [duplicate] => Array
                (
                    [ABC4] => 44444
                )
        )
)

In the example in Step 1, 3 new jobs were sent and 1 job was being updated. There were already 3 jobs in Microkeeper which were no longer active, thus they were changed to finished.

The 3 jobs were assigned a new JID which was returned, the JobID of the third party app was sent thus it was also returned.

A JID that was not found in Microkeeper was included, thus an error was returned.

A duplicate response was added for demonstration purposes.

If the same command was run again, the finished list would not be present because they are already marked as Finished in Microkeeper.





Retrieving job data

Microkeeper job data can be exported from Microkeeper via API.

If this API endpoint is being called then it assumed Microkeeper is the point of truth.

This means job management would take place in Microkeeper and the third party app would be considered a copy of the job list in Microkeeper.




Step 1

Set the mk_action variable and mk_data variable.

Variable name
Values and Example
mk_action

get_jobs

mk_data

{ "status":"all" }




Step 2

List of available fields

Below is a list of variables that can be used to get job data.


Variable name

Description

Required

Excepted formats

status

The status field

TRUE

all - This option will return all jobs that are not set to Finished.

finished - This option will return all jobs that are set to Finished.




Step 3

Response

The response will include the list of jobs.


'data' variables

Field name
Explanation
jobs
List of jobs


'jobs' variables [0]


Field name
Explanation
Example
JID

Job ID as recorded in Microkeeper.
Unique to all other Jobs.

1234
CID

Client ID as recorded in Microkeeper.
Multiple Jobs might be recorded to the same client.
Required if Microkeeper is being used for invoicing hours worked.
Set to 0 for no client, know as an In-house job in Microkeeper.

0
title

The title of the Job

Job A
startdate

Start date of job
Format YYYY-MM-DD
0000-00-00 if not set

2018-10-20
enddate

End date of job
Format YYYY-MM-DD
0000-00-00 if not set

2018-10-30
job_access

1 = All employees
All employees can clock onto this job. When adding a new employee they will automatically have access to the job.

2 = Location The employee can only clock jobs that are near their location. Requires a GPS device and locations to be set up correctly, usually recommend option.

0 = Individual Individual employees can be selected, allowing access to just those employees, can be time-consuming for admin and usually overly restrictive. (Deprecated, do not use this option).

INT = Group ID This option is going to replace the Individual option, assigning a group of staff to a Job via the Group ID which will refer to a list of staff. This option is not live yet.

2
status

Quoted The Job is quoted but not yet won.

Pending The Job is won, but is not ready to be clocked yet.

Active The Job is active and ready for staff to clock.

Finished The Job is archived and can no longer be clocked onto.

Active



Successful response example

{ "success":"1", "authenticated":"1", "message":"Job data", "data": { "jobs": [{"JID":"2588","CID":"0","title":"Job 1","startdate":"2018-10-25","enddate":"2018-11-25","job_access":"0","status":"Active"},{"JID":"2589","CID":"0","title":"Job 2","startdate":"2018-10-25","enddate":"2018-11-25","job_access":"0","status":"Active"},{"JID":"2590","CID":"0","title":"Job 3","startdate":"2018-10-25","enddate":"2018-11-25","job_access":"0","status":"Active"}] } }


Same example readable 

Array
(
    [success] => 1
    [authenticated] => 1
    [message] => Job data
    [data] => Array
        (
            [jobs] => Array
                (
                    [0] => Array
                        (
                            [JID] => 2588
                            [CID] => 0
                            [title] => Job 1
                            [startdate] => 2018-10-25
                            [enddate] => 2018-11-25
                            [job_access] => 0
                            [status] => Active
                        )
                    [1] => Array
                        (
                            [JID] => 2589
                            [CID] => 0
                            [title] => Job 2
                            [startdate] => 2018-10-25
                            [enddate] => 2018-11-25
                            [job_access] => 0
                            [status] => Active
                        )
                    [2] => Array
                        (
                            [JID] => 2590
                            [CID] => 0
                            [title] => Job 3
                            [startdate] => 2018-10-25
                            [enddate] => 2018-11-25
                            [job_access] => 0
                            [status] => Active
                        )
                )
        )
)