api/jobs
For general understanding of ROAD data types and especially ROAD jobs, see Jobs Data.
Contents
Use Cases
- Search for jobs
- Get or update a single job (change its data, its description or add triggers)
- Get specific information about a specific job (like its CurrentState)
- Get specific information about a specific job's associated Worker process
- Create a new job
Interface Usage
REST philosophy is a bit different from function-centric thinking. So to fulfill best practices, we use resource-centric interfaces:
| URI | Verb | Parameters (optional) | Success Result | Description |
|---|---|---|---|---|
| jobs | GET | (see below) | OK = 200 | Get data for all existing jobs (completely or specific fields). Examples: Note: If no matching job is found, the result value is not 404 (not found) - instead an empty results list (or count zero) will be returned. |
| jobs/{jobId} | GET | (see below) | OK = 200 | Get an existing job's data (completely or specific fields). Example: Note: If the job is not found, the result value is 404 (not found). |
| jobs | POST | (preJobId) (host) | Created = 201 | Creates a new job object, returning its JobId. BODY may contain a json-formatted job. Note: The job is created on the machine which is processing this POST request. |
| jobs/{jobId} | PUT | (host) | OK = 200 | Updates an existing job object. BODY contains all data fields which will be updated. Launching a job is done by adding a transition with RequestedProcState set to "Start". Note: For now all transitions passed are added to the job's transitions. Removing or changing existing transitions is currently not supported. Note: The job is queried in the local collection only. Archived or remote jobs cannot be updated. Note: If the job is not found, the result value is 404 (not found). |
| jobs | DELETE | (filter) (limit) (force) (host) | Accepted = 202 Count object like { "count": 42 } | Deletes several jobs Note: If no job is not found, the result value is 202, but the count is 0. |
| jobs/{jobId} | DELETE | (force) (host) | OK = 200 Accepted = 202 | Deletes one job Note: If the job is not found, the result value is 404 (not found). |
GET: Supported Parameters for jobs
Optional Query Parameters (for all GET requests)
| Parameter | Description | Example |
|---|---|---|
fields (see below) | Limit the response to specified fields | fields=title,number |
filter | Search filter. See Query Expressions for a detailed description. See below for fields which are supported by this interface. | filter=jobId == "5e20911487759558c854a9d1" OR name == "Test Job" |
sort (see below) | Sort order. Comma-separated list of sort fields. An optional "asc" or "desc" can be added after each field name (separated by space). | sort=name, createdTime desc |
offset skip | Offset in results list (default: 0) offset and skip are synonymic | offset=100 |
| limit | Limit the result list size (default: 100) | limit=100 |
count | Only evaluate the count of matching jobs. Only pass the parameter name count without any value. Filters are considered, but fields, sort, skip and limit are ignored. Returns a count object like { "count": 42 } | count |
| downloadLogIdx | Direct the Service to download a job related Worker log file instead of the job's data. This parameter is supported only for a single job query via jobs/{jobId}. First query the amount of Worker log files for this job. Then they can be downloaded by several requests with increasing index, starting by zero. Be aware every log file may be removed by the standard purging. In such case a 404 (not found) will be returned. | downloadLogIdx=0 |
| noAttachment | When requesting a log file download by the downloadLogIdx parameter, this parameter is used to omit the "attachment" HTTP header (which also defines the file name). When using in a web browser, this leads into opening the file directly in the browser instead of saving to a local file. | downloadLogIdx=2 & noAttachment |
| host | Get jobs' log file from another machine than the one receiving this GET request. This is only relevant in combination with parameter "downloadLogIdx" because log files remain on the host processing them. This relaying to another host if needed is done automatically if the processingHost field of the job directs to another one. So specifying the host parameter is only needed to save a database operation in case the host is already known to the client sending this request. For backgrounds see Distributed ROAD Cluster. | host=road-studio2 |
fields Parameter
The (optional) fields parameter can contain one or several comma-separated column titles. If this parameter is not used, the results' data will be provided completely. All job's field names can be passed in PascalCase or in camelCase.
Fields not existing in general or in a specific job will lead into not providing these fields in the result.
Fields of sub-objects are specified by the dot syntax (see in table).
For a complete list of job fields see Confluence page Jobs Data. Here only some of the most important fields:
| Field Name | Description |
|---|---|
| JobId | Unique id of a job as created by the Service for a POST request |
| Name | Title of a job |
| ProcessingHost | The Service host alias name to process this job (only for closed jobs) As part of a filter specification "localhost" can be passed to specify the addressed Service host. |
| Transitions | List of transitions. This field is a sub-object. If it is specified this way, all its sub-fields will be returned completely. If sub-fields of Transitions are specified, only these will be returned. |
Transitions.Trigger | A job trigger is used to define how or when a job state change request is to be processed by the Worker. |
| Transitions.Trigger.TriggerType | Type of trigger. |
Transitions.Trigger.StartTime | Time (UTC in ISO format YYYY-MM-DD hh::mm::ss.xxx, where seconds and sub-seconds are optional) to trigger Running state. Available for Time triggers only. |
Transitions.Trigger.Duration | Time from start Running state until Finished state. Available for Duration triggers only. |
| CreatedTime | Time of job's creation (time of first transition) |
| UpdatedTime | Time of job's last update (time of last transition) |
CurrentState | Most current state of this job (one of the CurrentProcStates described on Jobs Data page at paragraph "Processing States") |
| IsActive | false, if the job's CurrentState is one of Finished, Cancelled, Error |
| LogInfos | List of log infos (each a string containing the Service host's local file paths of a Worker log file). The amount depends on the Worker's past processing. Use a job/{jobId} request with parameter downloadLogIdx to download a log file, but consider the actual log files may be deleted. This field can only be retrieved by explicitly requesting it, because it is rarely of interest for a client. To get the amont of log infos use the LogInfoCount field. |
| LogInfoCount | Number of log infos which have been created for this job (see field LogInfos) This field can only be retrieved by explicitly requesting it, because it is rarely of interest for a client. |
| JobDescription.PipeSpec | DirectShow pipe description |
WorkerProcessId | Windows process ID if there's currently a worker process responsible for this job. 0 otherwise. |
StatusMessage | Status message of last status reported by the worker process, usually empty except there was an error. |
FriendlyStatusMessage | Short user-friendly variant of StatusMessage. |
sort Parameter
The (optional) sort parameter can contain one or several comma-separated sort criteria. Sort criteria are applied in their order, i.e. the second criteria is applied only where found entries' first field is identical. Each criteria can get an additional sort direction (ascending/asc or descending/desc), where ascending is default.
Example: sort=name, createdTime desc
Supported fields for sorting are all job fields (see Confluence page Jobs Data).
POST: Supported Parameters for jobs
There are optional parameters for a POST jobs request.
| Parameter | Description | Example |
|---|---|---|
preJobId | Transfer notification subscriptions from the passed preliminary or previous job id to the new created one. This is needed to handle a pre-subscription on job notifications as described in Subscriptions, Live Data and Notifications - Overview (paragraph Pre-Subscriptions). Note no subscription will be created if none is existing for the preJobId. | preJobId=c3fe9970-fd01-4250-b0df-873d6deaeea4 |
| host | Create and process the job on another machine than the one receiving this POST request. For backgrounds see Distributed ROAD Cluster. | host=road-studio2 |
PUT: Supported Parameters for jobs
There is one optional parameter for a PUT jobs request.
| Parameter | Description | Example |
|---|---|---|
| host | Update the job on another machine than the one receiving this PUT request. Note an already existing job stores the information about its ProcessingHost and only this host can update it. So the ROAD Service cares for relaying the PUT on jobs to that host. But providing this parameter might be useful to spare a database operation and especially on potential high-frequency POST-PUT scenarios. For backgrounds see Distributed ROAD Cluster. | host=road-studio2 |
DELETE: Supported Parameters for jobs
Deletion is only possible for jobs which are not in active state. Attempting to delete an active job will lead into a 304 (forbidden) response, except by use of the force parameter.
A DELETE request must either be combined with a jobId or with a filter restricting the jobs referred to deletion.
Optional Query Parameters (for all DELETE requests)
| Parameter | Description | Example |
|---|---|---|
| force | Directs the Service to try to cancel all active jobs being referred by the request before deleting them. All referred jobs, which are not active after a timeout period will then be deleted. The response to this request will be a 202 (Accepted). The response will come immediately after the count of relevant jobs was queried from the database. The actual processing is done after that. If used with a filter parameter, the response body the count of jobs being referred, independent from the number of successfully deleted ones (like { "count": 42 }). | force |
| host | Delete jobs on another machine than the one receiving this DELETE request. This is only relevant in combination with parameter "force"because active jobs can only be terminated on the host processing them. For backgrounds see Distributed ROAD Cluster. | host=road-studio2 |
filter | Search filter. See Query Expressions for a detailed description. See below for fields which are supported by this interface. | filter=jobId == "5e20911487759558c854a9d1" OR name == "Test Job" |
| limit | Only in combination with filter: Limit the number of jobs to be referred to (default: 1) | limit=100 |
Restrictions without Database
For database-less installations there's strong restrictions:
- Only local jobs will be found, which are mostly only active ones.
- Parameter fields can only request CurrentState or being omitted, so complete jobs' data will be returned.
- Parameter sort is ignored.
- Finished jobs' data is available as long as it remains in the ROAD Service's memory storage.
- After shutdown of the ROAD Service all jobs' data is being lost.
Job Data as REST Body
Where job data is transferred with a REST request to ROAD Service or response from ROAD Service, it is formatted as a JSON. This JSON's structure corresponds to the data structure as described in Confluence page Jobs Data.
The provided fields may be incomplete:
- A job creation request (HTTP POST) contains the fields to be set initially. All other fields required for running a job may be provided with a later update.
- A job update request (HTTP PUT) will add or update all fields it provides. The only mandatory field for updates is the JobId which identifies an existing job.
- To prepare, activate or run a job (this is adding a trigger with ProcStateRequested Wait, Pause or Start) the job needs to be complete enough to create a DirectShow graph and all the processing worker will need. This is a process limitation - from data integrity standpoint this does not matter.
- Job data being returned by the ROAD Service responding a query (HTTP GET) will contain all fields of jobs, which were requested (fields parameter) and which were found. So the result may contain incomplete jobs data.
Job JSON examples are provided in Confluence page Jobs Data.
DELETE: Restrictions for jobs
A DELETE jobs request can only be provided with the mandatory jobId.
Active jobs cannot be deleted; an attempt to do so will result in a 403 (forbidden). They first need to be finished by sending a PUT with a finish or cancel transition. Only after this job was really terminated, it can be deleted.