Jobs

Job Endpoints and Methods

/api/jobs/

  • GET
    - list (default)
  • POST
    - create

/api/jobs/[job_id]

  • GET
    - show (default)
    - pickup

  • POST
    - update (default)
    - pickup
    - start
    - end
    - update

/api/jobs/[job_id]/tasks

  • GET
    - list

/api/jobs/scheduled

  • GET
    - list

List Jobs

GET /api/jobs?action=list

Returns a JSON encoded array of objects each representing a job.

Required Params:

  • userkey

Optional Params:

Any job property may be passed as a param. The list returned will only included jobs whose value for that property matches the value of the param. For example GET /api/jobs?action=list&beacon_name=default will only return jobs whose "beacon_name" property is "default". Here's a list of valid filter parameters:

  • beacon_name
  • user
  • name
  • cur_task
  • total_tasks
  • add_time
  • q_time
  • pickup_time
  • start_time
  • result
  • duplicate_of

Create Job

POST /api/jobs?action=create

Creates a new job & optionally queues or schedules it.

Required Params:

  • userkey
  • name: Text name for the job.

Optional Params:

  • user_id: The ID of the user the job should belong to, OR:
  • user_guid: The GUID of the user the job should belong to.
    - Note: if user_id is passed, user_guid will be ignored.
    - Note: if neither user_id nor user_guid is passed, the job will be assigned to the user making the request.
  • beacon_name: The name of the beacon box that should run this job.
    - Note: if beacon_name is not passed, the beacon_name will be "default."
  • tasks: A JSON encoded array of objects, each representing a single task for the job.
  • q_time: A unix timestamp representing the time @ which the job should be eligible to run.
  • q: if set to "true" or "1", the job will be queued.
  • schedule: if set to "true" or "1", the job will be scheduled. The following parameters will be ignored if the job is not scheduled.
    - start_date: unix timestamp after which the scheduled job will be eligible to run
    - end_date: unix timestamp until which the scheduled job will be eligible to run
    - min: minute that the scheduled job should run
    - hour: minute that the scheduled job should run
    - dom: day of month that the scheduled job should run
    - dow: day of week that the scheduled job should run
    - month: month that the scheduled job should run

List Scheduled Jobs

GET /api/jobs/scheduled?action=list

Returns a JSON formatted array of objects each of which contains the name, scheduled job ID, and active status of a job that has been scheduled. 

Required Params:

  • userkey

Optional Params: none

Show Job

GET /api/jobs/[job_id]?action=show

Returns a JSON formatted object representing the requested Job.

Required Params:

  • userkey

Optional Params: none

Show Job Tasks

GET /api/jobs/[job_id]/tasks?action=show

Returns a JSON formatted array of objects, each representing a single task that is part of the specified job.

Update Job

POST /api/jobs/[job_id]?action=update

Updates the information for the specified job.

Required Params:

  • userkey

Optional Params: 

  • curtask: an integer representing the task that is currently being processed
  • schedule_active: if this is equal to "false" or "0" and the job is scheduled it will be set to inactive
    - if schedule_active is equal to any non "false" or "0" value and the job is scheduled it will be set to active

Pickup Job

GET|POST /api/jobs/[job_id]?action=pickup

Returns a JSON formatted object representing the requested Job & sets the pickup_time of the job to the current time.

Required Params:

  • userkey

Optional Params: none


Start Job

POST /api/jobs/[job_id]?action=pickup

Sets the start_time of the job to the current time.

Required Params:

  • userkey

Optional Params: none

Finish Job

POST /api/jobs/[job_id]?action=pickup

Sets the end_time of the job to the current time.

Required Params:

  • userkey

Optional Params:

  • result[]: A json object representing the result of a task.
    - To add multiple results to the job, pass the "result[]" parameter multiple time.
    - Results will be added in the order that they are passed.