We use cookies (just for analytics) on this website. If you continue we will assume you are happy with it. ok

BeBanjo

Back to index

Job

A job represents a work order in the system, and it is essentially a set of tasks that need to be accomplished before a specific due date. This is how it looks like:

<?xml version='1.0' encoding='utf-8' ?>
<job>
  <name>Ironman 2</name>
  <due-date type='date'>2010-05-05T00:00:00+02:00</due-date>
  <licensor-name>Warner</licensor-name>
  <status>pending</status>
  <tasks-status>pending</tasks-status>
  <assets-status>not_received</assets-status>
  <link href="https://sequence.example.com/api/work_areas/52/jobs/12875" rel="self"></link>
  <link href="https://sequence.example.com/api/work_areas/52" rel="work_area"></link>
  <link href="https://sequence.example.com/api/work_areas/52/jobs/12875/assets" rel="assets"></link>
  <link href="https://sequence.example.com/api/work_areas/52/jobs/12875/tasks" rel="tasks"></link>
  <link href="https://sequence.example.com/api/work_areas/52/jobs/12875/notes" rel="notes"></link>
  <link href="https://sequence.example.com/api/work_areas/52/jobs/12875/problems" rel="problems"></link>
</job>

Valid attributes

  • id (integer, read): The Sequence internal identifier of the job. It mustn’t be supplied in the creation of the job, because Sequence will set this attribute.

  • name (string, read/write): The job name. Normally a movie or an episode

  • due-date (datetime, read/write, ISO-8601: This is the date by which the job should be completed.

  • ends-at (string, optional for job creation): This is the end date for a given job. Normally corresponds with the end date of a Video On Demand availability/license window.

  • template (string, required for job creation): This identifies the name of the workflow template that needs to be used when creating the job. The tasks and assets defined on that template would be the ones that would get associated to the new job. A template with that name must exist in the account of the job creation will fail.

  • licensor-name (string, read/write, required for job creation): This is the name of the Licensor or Production Company associated to this job. It is used to request Materials and for filtering purposes.

  • tag-list (string, optional for job creation): This is a comma separated list of tags that can be used to describe the job. They can be then used in Sequence for filtering.

  • status (string, read only): This is a summary of the possible statuses of a job, which is derived from the statuses of its tasks and assets. The status cannot be changed directly in the job, it will change according to the status of its tasks and assets. The possible values are the following:

    • late: A job will be late if at least one asset or task is pending and the due date is in the past.

    • pending: A job will be pending if at least one asset or task is pending and the due date is in the future.

    • done: A job will be done when all tasks and assets have been completed.

    • live: A job will be live when all tasks and assets have been completed and the current date is inside the scheduling window.

    • passed: A job will be passed when all tasks and assets have been completed and the current date is outside the scheduling window (it has passed).

  • assets-status (string, read only): This is a summary of the statuses of the Assets of a given job. As it is derived from the status of its Assets, it cannot be updated directly. The possible values are the following:

    • not_received: When none of the Assets of the job have been completed.

    • partly_received: When at least one Asset has been marked as received and there is at least one asset still to be received for that given job.

    • received: When all Assets of the job have been marked as received.

  • tasks-status (string, read only) This is a summary of the statuses of the tasks of a given job, and it is derived from the status of its tasks. It will only change as the status of its tasks change, so it cannot be changed directly. The possible values are the following:

    • pending: When none of the tasks of the job have been completed.

    • in_progress: When at least one task has been completed and there is at least one task still pending for that given job.

    • completed: When all tasks of the job have been completed.

Resources of a job

If you’re using BeBanjo’s Movida or Metadata, your jobs in Sequence will link to the following resources there:

  • The corresponding scheduling in Movida. See the scheduling page.
  • The corresponding title in Movida. See the title page.
  • The corresponding representation in BeBanjo’s Metadata product.

Please note that there can be a small delay before the job resource is updated with its corresponding title link after the job is created via the send to Sequence process in Movida; the title link is also available in the linked scheduling resource.

Getting a list of jobs

In order to get the jobs of a work area, it is necessary to GET the jobs from the link jobs in the work area. Here is an example with cURL:

$ curl --digest -u robot_user https://sequence.example.com/api/work_areas/10/jobs

And would yield something like:

<jobs type="array">
  <job>
    <name>Mulholland Drive</name>
    <due-date type='date'>2010-12-31</due-date>
    <ends-at>2011-01-31</ends-at>
    <template>Ingest</template>
    <licensor-name>Miramax</licensor-name>
    <tag-list>Drama, Surreal</tag-list>
  </job>
  <job>
    <name>Lord of The Rings</name>
    <due-date type='date'>2010-10-31</due-date>
    <ends-at>2011-01-31</ends-at>
    <template>Ingest</template>
    <licensor-name>Miramax</licensor-name>
    <tag-list>Action</tag-list>
  </job>
</jobs>

Valid attributes

  • pagination: Note that by default the Job resource is not paginated. If you want to enable pagination you need to provide the pagination parameter with a value of “true”, for example https://sequence.example.com/api/work_areas/10/jobs?pagination=true.
  • per_page: Number of elements returned in each page; only effective with enabled pagination. The maximum value allowed is 200 and the default is 50, for example https://sequence.example.com/api/work_areas/10/jobs?pagination=true&per_page=20.
  • page: Number of the page you want to be returned; only effective with enabled pagination. For example https://sequence.example.com/api/work_areas/10/jobs?pagination=true&per_page=20&page=10.
  • filter: You can filter the list of jobs by passing in a filter. Valid values for the filter attribute are:
    • ready: Jobs returned will have all assets marked as received and all tasks completed
    • pending: Jobs returned will have either assets not received, or some tasks pending.
    • completed: Jobs returned will have all of their tasks completed, independently of their assets status
    • not_completed: Jobs returned will have at least some task pending, independently of their assets status
    • received: Jobs returned will have all assets received, independently of task status.
    • not_received: Jobs returned will have at least some asset pending, independently of task status.
    • problematic: Jobs returned will have active problems.
    • not_problematic: Jobs returned will not have active problems.

If you needed to filter the jobs by any of the filters above you, you need to provide the filter parameter:

$ curl --digest -u robot_user https://sequence.example.com/api/work_areas/10/jobs?filter=problematic

Creating a job

In order to create a job, it is necessary to POST a job XML to the jobs URL of a given work area. Let’s say we want to create a job in a work area with id 10, we would post to a URL like the following:

https://sequence.example.com/api/work_areas/10/jobs

The attributes to create a job are the following (see above for descriptions):

  • name (required)
  • due-date (required)
  • licensor-name (required)
  • template (required)
  • tag-list (optional)
  • ends-at (optional): If not specified, the job will by default have and end date of 2 months after its due date.

Here is an example with cURL:

$ curl --digest -u robot_user -X POST -H "Content-Type: application/xml" -d @job.xml https://sequence.example.com/api/work_areas/10/jobs

This line would issue a POST request to the URL specified at the end using digest authentication. It is also setting the HTTP header Content-Type: application/xml (required) and is sending the contents of the file job.xml as the body of the request. This is what the body of the POST request should look like:

<job>
  <name>Mulholland Drive</name>
  <due-date type='date'>2010-12-31</due-date>
  <ends-at>2011-01-31</ends-at>
  <template>Ingest</template>
  <licensor-name>Miramax</licensor-name>
  <tag-list>Drama, Surreal</tag-list>
</job>

If successfully created, the response will be the complete XML of the new job with an HTTP status code of 200:

<job>
  <name>Mulholland Drive</name>
  <due-date type='date'>2010-12-31T00:00:00+00:00</due-date>
  <licensor-name>Miramax</licensor-name>
  <status>pending</status>
  <tasks-status>pending</tasks-status>
  <assets-status>not_received</assets-status>
  <link href="https://sequence.example.com/api/work_areas/10/jobs/27187" rel="self"></link>
  <link href="https://sequence.example.com/api/work_areas/10" rel="work_area"></link>
  <link href="https://sequence.example.com/api/work_areas/10/jobs/27187/assets" rel="assets"></link>
  <link href="https://sequence.example.com/api/work_areas/10/jobs/27187/tasks" rel="tasks"></link>
  <link href="https://sequence.example.com/api/work_areas/10/jobs/27187/notes" rel="notes"></link>
  <link href="https://sequence.example.com/api/work_areas/10/jobs/27187/problems" rel="problems"></link>
  <link href="https://sequence.example.com/api/work_areas/10/jobs/27187/hooks" rel="hooks"></link>
</job>

Updating a job

To update a job, it is necessary to issue a PUT request to the URL of a given job. The body of the request should contain the XML of the job with the changed attributes. Note that not all attributes must be included: it would be enough to include the attributes that we wish to update.

The following example updates the name and due-date of the previous job. Note how the URL used now is the one that uniquely identifies the job:

$ curl --digest -u robot_user -H "Content-Type: application/xml" -X PUT -d @job_update.xml https://sequence.example.com/api/work_areas/10/jobs/27187

This is what the body of the request would contain:

<job>
  <name>Mulholland Dr.</name>
  <due-date type='date'>2011-01-01</due-date>
</job>

If the request is successful, it should return the updated job XML and a status code of 200:

<job>
  <name>Mulholland Dr.</name>
  <due-date type='date'>2011-01-01T00:00:00+00:00</due-date>
  <licensor-name>Miramax</licensor-name>
  <status>pending</status>
  <tasks-status>pending</tasks-status>
  <assets-status>not_received</assets-status>
  <link href="https://sequence.example.com/api/work_areas/10/jobs/27187" rel="self"></link>
  <link href="https://sequence.example.com/api/work_areas/10" rel="work_area"></link>
  <link href="https://sequence.example.com/api/work_areas/10/jobs/27187/assets" rel="assets"></link>
  <link href="https://sequence.example.com/api/work_areas/10/jobs/27187/tasks" rel="tasks"></link>
  <link href="https://sequence.example.com/api/work_areas/10/jobs/27187/notes" rel="notes"></link>
  <link href="https://sequence.example.com/api/work_areas/10/jobs/27187/problems" rel="problems"></link>
  <link href="https://sequence.example.com/api/work_areas/10/jobs/27187/hooks" rel="hooks"></link>
</job>

Deleting a job

In order to DELETE a job, it is only necessary to issue a DELETE request to the job URL, like so:

$ curl --digest -u robot_user -H "Content-Type: application/xml" -X DELETE https://sequence.example.com/api/work_areas/10/jobs/27187

The response should be a 204 (no content) HTTP Status code, with no body.

Deleted jobs

Even after deleting a job you are still able to retrieve its associated data. Here it’s an example with cURL:

$ curl --digest -u robot_user https://sequence.example.com/api/work_areas/10/jobs/27187?deleted

Note how have added the flag deleted to the job URL. This is part of the contract and therefore it’s important. Take in mind you will be receiving a 404 HTTP Status code instead of the XML representation of to the job if you omit that flag while trying to get an already deleted job.

Unlike a normal job, the following is like a deleted job looks like:

<job>
  <name>Mulholland Drive</name>
  <due-date type='date'>2010-12-31T00:00:00+00:00</due-date>
  <licensor-name>Miramax</licensor-name>
  <status>pending</status>
  <tasks-status>pending</tasks-status>
  <assets-status>not_received</assets-status>
  <link href="https://sequence.example.com/api/work_areas/10/jobs/27187?deleted" rel="self"></link>
  <link href="https://sequence.example.com/api/work_areas/10" rel="work_area"></link>
  <link href="https://sequence.example.com/api/work_areas/10/jobs/27187/assets?deleted" rel="assets"></link>
  <link href="https://sequence.example.com/api/work_areas/10/jobs/27187/tasks?deleted" rel="tasks"></link>
  <link href="https://sequence.example.com/api/work_areas/10/jobs/27187/notes?deleted" rel="notes"></link>
  <link href="https://sequence.example.com/api/work_areas/10/jobs/27187/problems?deleted" rel="problems"></link>
  <link href="https://sequence.example.com/api/work_areas/10/jobs/27187/hooks?deleted" rel="hooks"></link>
</job>

See we’ve added the deleted flag already for you to the job self link and also to the links to the different kind of resources associated with the job. Of course, you are free to follow these links when needed in order to retrieve these resources from the API.

Finally, it’s also possible to retrieve the list of deleted jobs from a given work area, again, by using the deleted flag like the following cURL example. Take into account the pagination mechanism and all the filters in the Getting a list of jobs section above will continue gloriously working with deleted jobs.

$ curl --digest -u robot_user https://sequence.example.com/api/work_areas/10/jobs?deleted

Beware these are the two only operations allowed targeting deleted jobs. Consequently if you try to update (or to delete) an already deleted job, while using the deleted flag, the response you’ll obtain will be a 405 (Method Not Allowed) HTTP Status code. Also making a POST of a job XML to the jobs URL of work area adding the deleted flag will eventually be responded with the aforementioned 405 HTTP Status.

Last updated July 07th, 2017.