Skip to content

Developers

How can we help you?

← Go back

Task

Tasks are each of the steps that need to be completed in order for a job to be processed. A task belongs to a job. It has no child resources.

Here is what its XML/JSON looks like:

<?xml version='1.0' encoding='utf-8' ?>
<task>
  <name>Encoding</name>
  <status>pending</status>
  <requires-duration type='boolean'>true</requires-duration>
  <duration>12:15:00</duration>
  <position type='integer'>1</position>
  <responsible-email>user@bebanjo.net</responsible-email>
  <link rel="self" href="https://sequence.bebanjo.net/api/work_areas/10/jobs/12875/tasks/55999"/>
  <link rel="job" href="https://sequence.bebanjo.net/api/work_areas/10/jobs/12875"/>
</task>

{
  "resource_type": "task",
  "name": "Encoding",
  "status": "pending",
  "requires_duration": true,
  "duration": "12:15:00",
  "position": 1,
  "responsible_email": "user@bebanjo.net",
  "self_link": "https://sequence.bebanjo.net/api/work_areas/10/jobs/12875/tasks/55999",
  "job_link": "https://sequence.bebanjo.net/api/work_areas/10/jobs/12875"
}

Valid attributes

  • name (string, read/write): This is the name of the task. It can be any string. Normally, the name of the tasks for a given job will be derived on the job creation from those defined in a workflow template

  • status (string, read/write): This is the status of a specific task. It can be in one of these two states:

    • pending: This is the initial state of a task, when it has not been completed yet.

    • completed: When a task has been deemed complete

  • requires-duration (boolean, read/write on creation, read only later): This inmutable flag indicates whether a certain task requires a duration. Being true a duration attribute will be present in the task information. Otherwise the duration attribute will be ommited. If not provided on creation, requires-duration will default to false, and the task will not require duration.

  • duration (string, read/write): For tasks that require duration (requires-duration is true), represents the time the task took to complete. Values for this field should be provided in the format hh:mm:ss, otherwise a validation error will be raised. Duration is blank by default, and a task that requires duration will not be able to be completed until this attribute is properly updated.

  • position (integer, read/write): Optional. The position of this task within the list of tasks for this job. The value, if provided, must be an integer value greater than zero. And if not provided, it will be automatically assigned to the next available position starting on 1. Trying to set a value greater than the next available position is not possible.

  • responsible-email (string, read/write): This is the email of the user assigned to the task. It should be a valid email from an user in the company. Trying to assign an invalid email is not possible.

Creating a task

In order to add a task to a specific Job, it is necessary to issue a POST request to the tasks list of a Job. The URL for the request would look something like this:

https://sequence.bebanjo.net/api/work_areas/10/jobs/27188/tasks

The attributes that can be used to create a task are:

  • name (required)

  • status (optional)

  • requires-duration (optional, defaults to false)

  • duration (optional, only valid if require-duration is true)

  • position (optional)

  • responsible-email (optional)

Here is an example using curl:

$ curl --digest -u robot_user:password -H "Content-Type: application/xml" -d @task.xml https://sequence.bebanjo.net/api/work_areas/10/jobs/27188/tasks

$ curl --digest -u robot_user:password -H "Content-Type: application/json" -H "Accept: application/json" -d @task.json https://sequence.bebanjo.net/api/work_areas/10/jobs/27188/tasks

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” or “Content-Type: application/json” (required) and is sending the contents of the file task.xml or task.json as the body of the request.

This is what the body of the POST request should look like:

<task>
  <name>Encoding</name>
</task>

{
  "name": "Encoding"
}

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

<task>
  <name>Encoding</name>
  <status>pending</status>
  <requires-duration type='boolean'>false</requires-duration>
  <position type='integer'>1</position>
  <responsible-email nil="true"/>
  <link rel="self" href="https://sequence.bebanjo.net/api/work_areas/10/jobs/27188/tasks/123941"/>
  <link rel="job" href="https://sequence.bebanjo.net/api/work_areas/10/jobs/27188"/>
</task>

{
  "resource_type": "task",
  "name": "Encoding",
  "status": "pending",
  "requires_duration": false,
  "position": 1,
  "responsible_email": null,
  "self_link": "https://sequence.bebanjo.net/api/work_areas/10/jobs/27188/tasks/123941",
  "job_link": "https://sequence.bebanjo.net/api/work_areas/10/jobs/27188"
}

If duration would be required, the post data would look like:

<task>
  <name>Encoding</name>
  <requires-duration>true</requires-duration>
</task>

{
  "name": "Encoding",
  "requires_duration": true
}

And if successfully created, the body of the response will differ from the above, being in this case:

<task>
  <name>Encoding</name>
  <status>pending</status>
  <requires-duration type='boolean'>true</requires-duration>
  <duration/>
  <position type='integer'>1</position>
  <responsible-email nil="true"/>
  <link rel="self" href="https://sequence.bebanjo.net/api/work_areas/10/jobs/27188/tasks/123941"/>
  <link rel="job" href="https://sequence.bebanjo.net/api/work_areas/10/jobs/27188"/>
</task>

{
  "resource_type": "task",
  "name": "Encoding",
  "status": "pending",
  "requires_duration": true,
  "duration": null,
  "position": 1,
  "responsible_email": null,
  "self_link": "https://sequence.bebanjo.net/api/work_areas/10/jobs/27188/tasks/123941",
  "job_link": "https://sequence.bebanjo.net/api/work_areas/10/jobs/27188"
}

Updating a task

To update a task, it is necessary to issue a PUT request to the URL of a given task. The body of the request should contain the XML/JSON of the task 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 status of the previous task. Note how the URL used now is the one that uniquely identifies the task:

$ curl --digest -u robot_user:password -H "Content-Type: application/xml" -X PUT -d @task_update.xml https://sequence.bebanjo.net/api/work_areas/10/jobs/27188/tasks/123941

$ curl --digest -u robot_user:password -H "Content-Type: application/json" -H "Accept: application/json" -X PUT -d @task_update.json https://sequence.bebanjo.net/api/work_areas/10/jobs/27188/tasks/123941

This is what the body of the request would contain:

<task>
  <status>completed</status>
</task>

{
  "status": "completed"
}

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

<task>
  <name>Encoding</name>
  <status>completed</status>
  <requires-duration type='boolean'>true</requires-duration>
  <duration>12:15:00</duration>
  <position type='integer'>1</position>
  <responsible-email nil="true"/>
  <link rel="self" href="https://sequence.bebanjo.net/api/work_areas/10/jobs/27188/tasks/123941"/>
  <link rel="job" href="https://sequence.bebanjo.net/api/work_areas/10/jobs/27188"/>
</task>

{
  "resource_type": "task",
  "name": "Encoding",
  "status": "completed",
  "requires_duration": true,
  "duration": "12:15:00",
  "position": 1,
  "responsible_email": null,
  "self_link": "https://sequence.bebanjo.net/api/work_areas/10/jobs/27188/tasks/123941",
  "job_link": "https://sequence.bebanjo.net/api/work_areas/10/jobs/27188"
}

Deleting a task

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

$ curl --digest -u robot_user:password -X DELETE https://sequence.bebanjo.net/api/work_areas/10/jobs/27188/tasks/123941

$ curl --digest -u robot_user:password -H "Accept: application/json" -X DELETE https://sequence.bebanjo.net/api/work_areas/10/jobs/27188/tasks/123941

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