267 lines
8.0 KiB
Markdown
267 lines
8.0 KiB
Markdown
# Running a task
|
|
This page documents how to run a task from the FarmMaps API.
|
|
Once you have uploaded some data and made sure the relevant cropfield is available, you can now instruct the system to start processing the data.
|
|
Processing data is done by running tasks. There are many different types of tasks to acomplish many different things such as:
|
|
|
|
* Identifying the type of file to start automatic processing
|
|
* Converting a CSV file to a Shapefile
|
|
* Filtering data for valid values
|
|
* Creating a taskmap of input data.
|
|
|
|
|
|
## Workflow task.
|
|
There is one special type of task, the `workflow` task.
|
|
When an item (i.e. file-upload, folder, cropfield etc.) is created there are certain processing tasks that can be done by "default".
|
|
As an example, for an uploaded file these tasks are:
|
|
|
|
- Re-assembling the part-chunks back into a single file
|
|
- Identifying the type of file, and how it should be processed.
|
|
|
|
For a cropfield there are slightly different tasks such as:
|
|
|
|
- retrieve AHN mapping data (cut-out from public height maps)
|
|
- retrieve soil compaction data (based on a public map)
|
|
- retrieve shadow mapping data (based on satellite imagery)
|
|
|
|
These steps are all defined in the workflow for each `itemType`.
|
|
So, once an item has been created, we can run the `workflow` task to execute the predefined tasks automatically.
|
|
|
|
### Example: Running the workflow task for a cropfield.
|
|
We run a task by adding the `taskType` to the body of the request, with `vnd.farmmaps.task.workflow` as the type of task.
|
|
The item that the task will be executed on is specified in the url by it's itemcode. Other types of tasks can be run by changing the taskType.
|
|
|
|
**Request**
|
|
```http
|
|
POST /api/v1/items/98a480ad8d7444a8a10ef547cd8594eb/tasks HTTP/1.1
|
|
Authorization: Bearer <access token>
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Cache-Control: no-cache
|
|
Host: farmmaps.awacc.nl
|
|
Accept-Encoding: gzip, deflate, br
|
|
Connection: keep-alive
|
|
Content-Length: 49
|
|
|
|
```
|
|
|
|
**Response**
|
|
```http
|
|
HTTP/1.1 201 Created
|
|
Server: nginx/1.14.0 (Ubuntu)
|
|
Date: Sat, 25 Apr 2020 13:55:28 GMT
|
|
Content-Type: application/json; charset=utf-8
|
|
Transfer-Encoding: chunked
|
|
Connection: keep-alive
|
|
Cache-Control: no-store,no-cache
|
|
Pragma: no-cache
|
|
Content-Encoding: br
|
|
Location: /api/v1/items/98a480ad8d7444a8a10ef547cd8594eb/tasks/52173fb5bf1146efa276ecfe1fda5f60
|
|
Vary: Accept-Encoding
|
|
|
|
```
|
|
|
|
**Troubleshooting**
|
|
|
|
|Status code|Description|
|
|
|---|---|
|
|
|201|Task created|
|
|
|400|Error: Tasktype not found|
|
|
|401|Error: Not authenticated|
|
|
|403|Error: No WRITE permissions in item|
|
|
|404|Error: Item not found|
|
|
|
|
## Polling for task status
|
|
Now that the task was created, we can retrieve its status by performing a **GET** request on the same endpoint as used for starting task.
|
|
Note that the response contains a lot of tasks, and also multiple workflow tasks, indicating that multiple workflows were triggered.
|
|
|
|
**Request**
|
|
```http
|
|
GET /api/v1/items/98a480ad8d7444a8a10ef547cd8594eb/tasks HTTP/1.1
|
|
Accept: application/json
|
|
Authorization: Bearer <access token>
|
|
Cache-Control: no-cache
|
|
Host: farmmaps.awacc.nl
|
|
Accept-Encoding: gzip, deflate, br
|
|
Connection: keep-alive
|
|
```
|
|
|
|
**Response**
|
|
```http
|
|
HTTP/1.1 200 OK
|
|
Server: nginx/1.14.0 (Ubuntu)
|
|
Date: Sat, 25 Apr 2020 14:34:01 GMT
|
|
Content-Type: application/json; charset=utf-8
|
|
Transfer-Encoding: chunked
|
|
Connection: keep-alive
|
|
Cache-Control: no-store,no-cache
|
|
Pragma: no-cache
|
|
Content-Encoding: br
|
|
Vary: Accept-Encoding
|
|
|
|
```
|
|
|
|
**Troubleshooting**
|
|
|
|
|Status code|Description|
|
|
|---|---|
|
|
|401|Error: Not authenticated|
|
|
|403|Error: No READ permissions in parent item|
|
|
|404|Error: Parent item not found|
|
|
|
|
### Polling a single task
|
|
Polling for a siingle task can be done by appending g the `ItemTaskCode` to the task URL:
|
|
|
|
**Request**
|
|
```http
|
|
GET /api/v1/items/98a480ad8d7444a8a10ef547cd8594eb/tasks/a1daf49cf08142c289825def78986027 HTTP/1.1
|
|
Accept: application/json
|
|
Authorization: Bearer <access token>
|
|
Cache-Control: no-cache
|
|
Host: farmmaps.awacc.nl
|
|
Accept-Encoding: gzip, deflate, br
|
|
Connection: keep-alive
|
|
```
|
|
|
|
**Response**
|
|
```http
|
|
HTTP/1.1 200 OK
|
|
Server: nginx/1.14.0 (Ubuntu)
|
|
Date: Sat, 25 Apr 2020 15:02:05 GMT
|
|
Content-Type: application/json; charset=utf-8
|
|
Transfer-Encoding: chunked
|
|
Connection: keep-alive
|
|
Cache-Control: no-store,no-cache
|
|
Pragma: no-cache
|
|
Content-Encoding: br
|
|
Vary: Accept-Encoding
|
|
|
|
```
|
|
**Troubleshooting**
|
|
|
|
| Status code | Description |
|
|
| --- | --- |
|
|
| 401 | Error: Not authenticated |
|
|
| 403 | Error: No READ permissions in parent item |
|
|
| 404 | Error: Parent item not found |
|
|
|
|
## What's next?
|
|
Now that you know how to run a task, you can start running specialized tasks to create or process your own data.
|
|
Head over to the [Task Examples](README.md#task-examples)
|
|
|
|
|
|
|
|
|