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
,HIGHEST
orIMMEDIATE
.
Status Codes: - 404 Not found – Invalid id
Role: _job_write
- priority – Change the job priority. Value should be one of
Warning
Jobs with priority IMMEDIATE
are always started, even if the max concurrent jobs
limit is reached. This could impact system performance. To execute the job with IMMEDIATE
priority the user must be a super user, that is, have role _super_access_user
.
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