^ Login

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.

Update/inserts can be made by either JID or JobID.

Tracking the JID is required if the JobID is not set.

If the JID is sent the comparison will be made by the JID and the JobID will just be recorded.

If the JID is not send the comparison will be made by the JobID.

Multiple records can still be sent in one hit with this method.


Batch method

This option is for updating batch lists.

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


If tracking by JID:
TRUE
Must be set to 0 if not known

If tracking by JobID:
Do not send the JID

INT
1234
0
JobID

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.


If tracking by JID:
FALSE
Record keeping only

If tracking by JobID:
TRUE
This will always be known

Alphanumeric
ABC123
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" }

or

{"status":"JID","JID":["8557","8556"]}

or 

{"status":"JobID","JobID":["ABC5","ABC3"]}




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.

JID - This option will return the jobs that match the list in JID list example in step 1

JobID - This option will return the jobs that match the list in JobID list example in step 1

JIDList of JIDsIf status is set to JID
["8557","8556"]

JobIDList of JobIDsIf status is set to JobID
["ABC5","ABC3"]




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
JobID
The third-party Job ID as recorded by the third-party app
Should be unique to all other JobIDs

ABC123
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
)
)
)
)