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.

{ "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.

'config' variables

Note

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

'jobs' variables

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

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.

{ "status":"all" }

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

{"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.

Step 3

Response

The response will include the list of jobs.

'data' variables

'jobs' variables [0]

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