← 5b. Keyword Indexing

6. Blocked Jobs

If you haven’t already, make sure to read the previous section detailing Jobs.

Blocked Jobs and Workbenches

Jobs move to the blocked status when they require human review. Humans review the job in client applications called workbenches. Generally speaking, a workbench handles a single step in the life cycle of a job. For example, for Data Point Extraction, there are two possible workbenches that can be invoked, namely Zoning and Mapping.

When a job is in the blocked state, an additional field called blocking_step will identify which workbench is required to unblock the job.

Listing Blocked Jobs

The list of blocked jobs, relevant to your workbench, can be retrieved from GET /jobs by passing a couple additional parameters:

  • status — status should be blocked
  • blocking_task — blocking task should be determined by which step the workbench is designed to unblock.

Example

To retrieve the list of jobs blocked on zoning, the Zoning workbench calls this end point: 

GET https://api.innodata.com/v1/jobs?status=blocked&blocking_task=zoning
Authorization: Basic dXNlci1saXZlLTYzMmE1YTYzLWQ2ZDYtNDI0Ni05MWNhLWQ1NDY2MzI2OThkMzo=

Checking Out a Job

Once a blocked job has been selected by the user, the first step is to “check out” the job. The check out process ensures that only the current user is allowed to work on the job, granting them exclusive access for a period of time.

Checking out a job is done through the endpoint POST /jobs/:jobId/checkout. If the checkout is successful, the API will return a 2xx response code. If the checkout is unsuccessful (for example another user has already checked out that job), the API will respond with a 4xx response code. The response for this endpoint will be the same as GET /jobs/:jobId.

When listing blocked jobs, a job that has already been checked out will include the additional field claimed_by which indicates the details of the user that checked out the job. This field will be null if the job has not yet been claimed.

Example

To checkout a job with ID 937a6d0c-d1fe-426a-969f-6d4468712c18:

POST https://api.innodata.com/v1/jobs/937a6d0c-d1fe-426a-969f-6d4468712c18/checkout`
Authorization: Basic dXNlci1saXZlLTYzMmE1YTYzLWQ2ZDYtNDI0Ni05MWNhLWQ1NDY2MzI2OThkMzo=
Body: (empty)

Retrieving Job Contents

In most cases, a blocked job in the workbench must retrieve some populated automated content. This content can be found using the GET /jobs/:jobId/contents endpoint. To filter the list of content by role, the API provides the GET /jobs/:jobId/contents/:role endpoint, providing a paginated list of all content for the given role.

For each piece of job content, a URI will be provided where the client may fetch the actual contents. It is expected that clients use the provided URI to fetch, instead of trying to generate their own. When using the provided URI, clients must still send the appropriate authorization headers.

Many workbenches require multiple pieces of content to populate correctly. It is good practice for workbenches to load content "lazily", only when the user requires it. For example, the Zoning workbench only loads the high resolution images and zones for each page once the user has opened the specific page.

Updating Job Contents

Once a user has finished their work, similar to retrieving content, the workbench can use the PUT verb to upload the user's work and overwrite the content in the API. This call should use Content-type: application/octet-stream and the body should contain the raw content. The uri for the corresponding role should be used. This uri can be the same as the retrieved content but it is good practice to have a separate role for input and output.

Checking In a Job

Once the workbench has uploaded the user’s work successful, the final step to unblocking a job is to “check in”. This is done through the endpoint POST /jobs/:jobId/checkin. The body of the request has the following properties:

  • status — must be one of the following:
    • completed — used to indicate the work has been saved successful and the job can continue.
    • aborted — used to indicate the user wishes to temporarily give up the checkout. The job will be returned to the pool of blocked jobs.
    • failed — used to the indicate the entire job should be failed as there is no way for the work to continue successfully.
  • message — an error message string only used for failed status.

On a "completed" check-in, the job status should return to running and the job will continue through its life cycle.

Example

Below is an example of a completed check-in:

POST https://api.innodata.com/v1/jobs/937a6d0c-d1fe-426a-969f-6d4468712c18/checkin`
Content-type: application/json
Authorization: Basic dXNlci1saXZlLTYzMmE1YTYzLWQ2ZDYtNDI0Ni05MWNhLWQ1NDY2MzI2OThkMzo=
Body:
{
  "status": "completed"
}