Processing Queue

The Queue module is used to view and manage a users queued tasks. These will primarily be processing tasks (such as GPX/JSON imports) but may also include other intensive tasks.

All requests must be properly authorised, and only items queued by (or on behalf of) the current user can be viewed.

Job Classes

Each API submodule has its own JobClass, and any queued jobs will be assigned to this class.

  • GPX - Journey, specifically GPX or JSON Import
  • VEH - Vehicle SubModule, usually deletion

 

Job Statuses

Wherever individual Jobs are returned, the relevant Job status will also be returned. There are 6 possible statuses;

  • Awaiting Processing
  • Locked - Currently being processed
  • Completed
  • Failed
  • Cancelled By User
  • Unknown

If the API returns a job status of unknown it's representative of an internal error.

 

Show Queue

To View the current Queue (including some historic items) request

/queue/queue

Example Response


{
"timestamp":1379864224,
"response":{
"jobs":{
"J0":{
"jobID": 1,
"JobClass":"GPX",
"Task":"Import",
"started":"1378825905",
"ended":null,
"status":"Locked"
},
"J1":{
"jobID": 15,
"JobClass":"GPX",
"Task":"Import",
"started":"1379115601",
"ended":null,
"status":"Failed",
"failurereason":"Journey creation failed"
},
"J2":{
"jobID": 43,
"JobClass":"GPX",
"Task":"ImportJSON",
"started":"1379849777",
"ended":"1379849779",
"status":"Completed"
},
"J3":{
"jobID": 116,
"JobClass":"GPX",
"Task":"ImportJSON",
"started":null",
"ended":"1378826723",
"status":"Cancelled By User"
}
},
"errors":null,
"error":0
}

 

Job Status

To retrieve the status of a single Job, place a request to

/queue/jobstatus/{job id}

e.g. to retrieve the third job in the example above, we'd place a request to

/queue/jobstatus/43

Example Response

{
"timestamp":1379871871,
"response":{
"jobID": 43,
"JobClass":"GPX",
"Task":"ImportJSON",
"started":"1379849777",
"ended":"1379849779",
"status":"Completed"
},
"errors":null,
"error":0
}

 

Historic Items

Jobs are not automatically purged from the database on completion, but the queue is pruned periodically by a cron script. Expect completed queue items to persist for no more than 7 days, although the actual retention period may vary from time to time.

Failed items are retained for a slightly longer period.

 

Submodule specific failure reasons

Journey / GPX

There are a number of failure reasons which may be returned by Jobs in the GPX class, most of which should be self-explanatory. If an error arises, the source GPX/JSON file will need to be checked and resubmitted for processing.

Should a warning occur, the main journey record will have been created, so if the intention is to resubmit for processing this record will need to be removed. See the Journey submodule documentation for information on removing Journey records.

Fatal Errors

  • Source file does not exist - A file was queued for import, but doesn't appear to exist on the server
  • Invalid GPX File - A GPX Import job was queued, but the XML could not be parsed.
  • Invalid JSON File - A JSON Import job was queued, but the JSON could not be parsed.
  • Date is suppressed - Will only occur when a JSON file has been submitted for import. Whilst GPXIngest will allow you to suppress dates, the API does not support import of Journeys without date information.
  • Journey creation failed - The journey could not be created in the database. Either there's an issue with the Journey data, or more commonly, that Journey has previously been imported.

Warnings

  • Track x: creation failed - A specific track id could not be created, any child Segments and trackpoints will have been skipped
  • Segment x / y: creation failed - A specific segment could not be created in the database. x signifies the relevant trackID. Any child trackpoints will have been skipped
  • Trackpoint x / y / z: creation failed - A specific trackpoint could not be created in the database. x signifies the relevant trackID, y the segment ID and z the trackpoint ID.