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).

  • 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 ids
    • false (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 user
    • false - Include all jobs
Produces:
  • application/xml, application/jsonJobListDocument
  • text/plain – CRLF-delimited list of job ids.
Role:

_job_read

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/jsonJobDocument
  • text/plain – State of job
Role:

_job_read

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 or HIGHEST.
Status Codes:
  • 404 Not found – Invalid id
Role:

_job_write

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:
Role:

_job_write

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:
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:
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:
Role:

_job_read

Delete one or several jobs

DELETE /job

Deletes a job and every related database entry.

Query Parameters:
 
  • id – Comma-separated list of job ids. Must not be empty.
Status Codes:
  • 400 Invalid input – The job is still running
  • 404 Not found – Invalid id
Role:

_job_write

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/jsonURIListDocument
  • 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 or HIGH.

Default:LOW
Since:4.2.8