Jobs¶
Managing jobs¶
Create job¶
See Creating jobs.
Get list of jobs¶
-
GET
/job
¶ Return jobs matching the criteria given.
Query Parameters: - jobmetadata –
Optional, multiple query parameters can be specified. If no query parameters are specified, all jobs are returned.
- key
=
value - Filter out only the jobs that has job metadata according to the filter criteria.
Note that
=
is part of the query parameter, and has to be encoded (%3d
). - key
- metadata –
true
- Include job metadata with all jobs.false
(default) - Do not include job metadata with all jobs.
- idonly –
true
- Only return a list of idsfalse
(default) - Return job information such as job status
- starttime-from – Optional ISO8601 timestamp. Return only jobs started after and at the given timestamp.
- starttime-to – Optional ISO8601 timestamp. Return only jobs started before and at the given timestamp.
- finishtime-from –
Optional ISO8601 timestamp. Return only jobs finished after and at the given timestamp.
New in version 4.10.
- finishtime-to –
Optional ISO8601 timestamp. Return only jobs finished before and at the given timestamp.
New in version 4.10.
- step –
true
- Include step information in the job listing.false
(default) - Do not include step information in the job listing.
Matrix Parameters: - type – Optional comma-separated list of job types. Default is
all
, return all jobs. - state – Optional comma-separated list of job states. Default is
all
, return all jobs. - first – Optional integer. Return jobs from that number in the list of sorted jobs. Default is
1
, the first jobs. - number – Optional integer. Return at most that number of jobs. Default returns the first 100 jobs.
- sort –
Optional list of form
field (asc|desc)[, ...]
. Sort by specific fields.jobId
type
state
user
startTime
priority
New in version 4.0.1.
- user –
true
(default) - Include only jobs created by current userfalse
- Include all jobs
Produces: - application/xml, application/json – JobListDocument
- text/plain – CRLF-delimited list of job ids.
Role: _job_read
- jobmetadata –
Get job information¶
-
GET
/job/
(job-id)¶ Return information about specified job.
When returning in format
text/plain
, only a string representation of the state is returned.Query Parameters: - metadata –
true
- Include job metadata with all jobs.false
(default) - Do not include job metadata with all jobs.
Status Codes: - 404 Not found – Invalid id
Produces: - application/xml, application/json – JobDocument
- text/plain – State of job
Role: _job_read
- metadata –
Modify job parameter¶
-
PUT
/job/
(job-id)¶ Updates the job by setting job priority
Query Parameters: - priority – Change the job priority. Value should be one of
LOWEST
,LOW
,MEDIUM
,HIGH
orHIGHEST
.
Status Codes: - 404 Not found – Invalid id
Role: _job_write
- priority – Change the job priority. Value should be one of
Abort job¶
-
DELETE
/job/
(job-id)¶ Does not delete the job, but aborts it.
To delete one or more jobs, use
DELETE /job
.The job is marked for abortion, but the call may return before all tasks have been killed. Hence, the status return by this call is likely to be ABORT_PENDING rather than ABORTED. Caller should poll the status of the job or use job notifications to find out when job has been fully aborted.
Query Parameters: - reason – Optional string, reason for cancellation.
- cleanup –
true
(default) - Run cleanup steps before aborting.false
- Skip the cleanup steps, unless the job is already running. For READY jobs this means that the job will immediately be marked as ABORTED.
New in version 4.2.4.
Status Codes: - 404 Not found – Invalid id
Role: _job_write
Create duplicate job¶
-
POST
/job/
(job-id)/re-run
¶ Retrieves an existing job, duplicates it and starts the duplicated version.
Changed in version 4.2.5: The job priority now defaults to the priority of the existing job. Previously the priority was always MEDIUM.
Query Parameters: - priority –
The priority of the new job. If no priority is specified then the priority of the existing job will be used.
New in version 4.2.5.
Status Codes: - 404 Not found – Invalid id
Produces: - application/xml, application/json – JobDocument
Role: _job_write
- priority –
Start a job with custom type¶
-
POST
/job
¶ Starts a new job, of the type specified in the
type
parameter.New in version 4.6.
Query Parameters: - type – The job type name. Mandatory parameter.
- notification – The placeholder job notification to use for this job. (Optional)
- notificationData – Any additional data to include for notifications on this job. (Optional)
- priority – The priority to assign to the job. Default is
MEDIUM
. - jobmetadata – Additional information for the job task.
Status Codes: - 400 – Invalid job type name
Produces: - application/xml, application/json – JobDocument
Role: _job_write
Job problem conditions¶
Jobs can enter the state WAITING if a recoverable problem has occurred. Depending on the problem the system might resolve itself or require manual assistance, e.g. out of storage space.
Get a list of all active job problems¶
-
GET
/job/problem
¶ Returns a list of unresolved problems, together with what jobs are waiting for them to be resolved.
Produces: - application/xml, application/json – JobProblemListDocument.
Role: _job_read
Get a list of all job problems that affects a specific job¶
-
GET
/job/
(job-id)/problem
¶ Retrieves a list of problems that affects the specified job.
Status Codes: - 404 Not found – Invalid id
Produces: - application/xml, application/json – JobProblemListDocument
Role: _job_read
Job states¶
Job states¶
The following states are defined for a job:
- READY
- Job can be run, in queue.
- STARTED
- One or several job steps are running.
- VIDINET_JOB
- One or several job steps are running on Vidinet.
- FINISHED
- The job has finished with success.
- FINISHED_WARNING
- The job has finished, but a non-critical step failed.
- FAILED_TOTAL
- The job has finished, but a critical Job step has failed.
- WAITING
- The job is waiting for a condition.
- ABORT_PENDING
- A request to abort the job has been made.
- ABORTED
- The job is aborted, and all job steps have finished.
Step states¶
The following states are defined for a job step (task):
- NONE
- Job step has just been initialized. Normally this should not be returned.
- READY
- Job step about to start.
- STARTED
- Job step started, running in a transaction. (Short tasks.)
- STARTED_ASYNCHRONOUS
- Job step started, running outside of an transaction. (Longer tasks, or tasks that cannot execute in an EJB.)
- STARTED_PARALLEL
- Job step has started, and signals that other parallel tasks can start.
- STARTED_PARALLEL_ASYNCHRONOUS
- Job step has started, and signals that other parallel tasks can start.
- STARTED_SUBTASKS
Job step has started, and will be performed in multiple subtasks.
New in version 4.0.
- FINISHED
- Job step has finished successfully.
- FAILED_RETRY
- Job step has failed, but will be retried.
- FAILED_FATAL
- Job step has failed, and will not be retried.
- WAITING
- Job step is waiting for a condition, see Get a list of all job problems that affects a specific job for cause.
- DISAPPEARED
- The job worker was missing (possible cause is a restart of the application server). The job step will be re-run.
Job types¶
The following job types exists. They can also be retrieved
using GET /jobtype
.
- NONE
- Not used.
- IMPORT
- Not used.
- PLACEHOLDER_IMPORT
- Regular import (using URI or file id to existing or new item).
- RAW_IMPORT
- Import where essence is in request body.
- AUTO_IMPORT
- Import using auto import rules.
- SHAPE_IMPORT
- Import using URI or file id to a shape.
- SIDECAR_IMPORT
Import a sidecar file to an existing item.
New in version 4.0.1.
- ESSENCE_VERSION
- Import a new essence version.
- TRANSCODE
- Transcode of item.
- TRANSCODE_RANGE
- Transcode of part of item.
- CONFORM
- Conform an item sequence.
- TIMELINE
- Conform a timeline.
- THUMBNAIL
- Create thumbnails or posters of item.
- ANALYZE.
- Do analysis of item.
- SHAPE_UPDATE
- Update shape information of item.
- RAW_TRANSCODE.
- Send transcode job directly to transcoder.
- EXPORT
- Export item to remote location.
- COPY_FILE
- Copy file (and keep track of new copy).
- MOVE_FILE
- Move file.
- DELETE_FILE
- Delete file.
- LIST_ITEMS
- Generate item report.
Get list of job types¶
-
GET
/jobtype
¶ Get list of job types
Produces: - application/xml, application/json – URIListDocument
- text/plain – list of job types
Job metadata¶
Additional job metadata can be specified using the jobmetadata
parameter, when a job is created. Note that the equals sign is part
of the value of the query parameter, so it has to be URL encoded (%3d).
Hint
Prefer to always prefix any custom job metadata by the name of your
application, for example, myApp_customSetting
, to avoid
conflict with any existing or future job metadata used by Vidispine.
Reserved keys¶
-
smpteTimeCode
¶ The first frame to be included in transcoded output.
Type: String (SMPTE timecode)
-
lastSmpteTimeCode
¶ The last frame to be included in transcoded output.
Type: String (SMPTE timecode)
-
checksumMode
¶ Can be set to
transfer
to have the checksum computed during the transfer step of the import job.Note: This will not work if the files are transferred by the transcoder. Since: 4.2.8
-
cerifyPriority
¶ The priority to assign jobs created in Cerify. Either
LOW
,MEDIUM
orHIGH
.Default: LOW
Since: 4.2.8