forum
login
home HOME

Task

On the KandaSearch indexing pipelines are covered by tasks. To work with the tasks a dedicated API is exposed for the external clients. Using API it is possible:

  • to create a task
  • to execute commands on the task
  • to check the status of the task

All the above API requests should be authenticated. That means that each request should include an authentication token within Authorization header of the request. For more details on how to apply authentication and how to obtain token refer to the KandaSearch REST API Authentication.

Task API exposed using the following base path:

https://api.kandasearch.com/external/v1/projects/{projectId}/instance-sets/{instanceSetId}/tasks

Note the {projectId} and {instanceSetId} entries within a path. They should be replaced with the actual values of ID of the project and ID of the model instance set that task belongs. Those values can be copied from the project and model instance set pages of the KandaSearch website.

Responses for the any of the requests are returned as 200 OK in a form of a result envelope:

{
    "status": ...,
    "result": ...,
    "error": ...
}

In case of a request was handled succefully, the response will contain status of value OK and the result will be resided in a result field:

{
    "status": "OK",
    "result": {
        ...
    }
}

Otherwise, in case of failure, an error envelope will be returned:

{
    "status": "ERROR",
    "error": {
        "message": "command parse failed"
    }
}

Create task

Before executing any command to run on a pipeline, it is necessary to create a task object first. It can be done by executing request using following settings (This can only be executed by the administrator):

{
    "targetId": "..."
}

The value of a targetId represents a unique undentifier of the application that will handle the pipeline execution. This value is provided by the KandaSearch manager.

In a response a task object data will be returned:

{
    "status": "OK",
    "result": {
        "id": "982087df-bc98-43d3-a060-defbe09141a0",
        "projectId": "8d721283-cf1c-4985-a2ae-65c81fe5e164",
        "instanceSetId": "6b3e5dbe-5ed1-4d22-9a6b-af56cbe5a0e7",
        "targetId": "...",
        "date": "2024-05-28T21:55:14.6354669",
        "startDate": null,
        "endDate": null,
        "status": "PENDING",
        "error": null
    }
}

The most significant part of the result is an id value of the task. It is going to be used for all further API requests.

Check task status

To check the current status of the task execute request as follows:

The task object having indicated {taskId} will be returned:

{
    "status": "OK",
    "result": {
        "id": "982087df-bc98-43d3-a060-defbe09141a0",
        "projectId": "8d721283-cf1c-4985-a2ae-65c81fe5e164",
        "instanceSetId": "6b3e5dbe-5ed1-4d22-9a6b-af56cbe5a0e7",
        "targetId": "...",
        "date": "2024-05-28T21:55:14.6354669",
        "startDate": "2024-05-29T13:05:42.172919",
        "endDate": "2024-05-29T18:47:43.560023",
        "status": "COMPLETED",
        "error": null
    }
}

The value of status shows a current status of the task. Task may have following status values:

  • PENDING - task is created and ready to run a pipeline
  • RUNNING - the task pipeline is executing at the moment
  • ABORTED - the task pipeline has been aborted
  • COMPLETED - the task pipeline has been completed
  • FAILED - the task pipeline has been failed

In case of status FAILED a description of the problem should be located in the error field. Fields startDate and endDate indicates the pipeline start and finish dates.

Status values ABORTED, COMPLETED and FAILED are terminal states. After that task will be considered as a completed and will not accept any additional commands.

Execute command

After task is created and ready it is possible to execute commands on the pipeline (This can only be executed by the administrator). It is done with the following request:

{
    "data": {
        ...
    }
}

The data part have a single field data that should contain an action inside. The list of the available actions and their structure are task dependendent. Refer to actions documentation of the desired task for more details.

  1. file (application/octet-stream) containing files related to the action

The file part is optional as not all actions expect the files to be included. Note that it is possible to attach multiple files by adding multiple file parts within the request.