Documentatie/Running-tasks.md

# 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

{
   "taskType": "vnd.farmmaps.task.workflow"
}
```

**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

{
    "code":"52173fb5bf1146efa276ecfe1fda5f60",
    "taskType":"vnd.farmmaps.task.workflow",
    "attributes":{}
}
```

**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

[
    {
        "taskType":"vnd.farmmaps.task.workflow",
        "code":"52173fb5bf1146efa276ecfe1fda5f60",
        "state":1,
        "started":"2020-04-25T13:55:28.58133",
        "finished":"2020-04-25T13:55:28.750055"
    },
    {   
        "taskType":"vnd.farmmaps.task.vandersat",
        "code":"0586f0f867014d55a90bfe6adf7416d5",
        "state":1,
        "started":"2020-04-25T14:00:36.221527",
        "finished":"2020-04-25T14:02:18.314088"
    },
    {   "taskType":"vnd.farmmaps.task.watbal",
        "code":"f33cfaff01644313b8de73dcfd42bc20",
        "state":3,
        "started":"2020-04-25T14:10:46.201482"
    },
    {   
        "taskType":"vnd.farmmaps.task.workflow",
        "code":"2b76caf17f6d4f5eb497f7ba7609a08c",
        "state":1,
        "started":"2020-04-25T13:55:41.278677",
        "finished":"2020-04-25T13:55:41.442544"
    },
    {   
        "taskType":"vnd.farmmaps.task.crprec",
        "code":"0ddd635c244c47b8a182aa5f8dddb5db",
        "state":1,
        "started":"2020-04-25T13:55:33.609931",
        "finished":"2020-04-25T13:55:34.464812"
    },
    {
        "taskType":"vnd.farmmaps.task.bofek",
        "code":"e95910401dd8493d8483ebde56f8814c",
        "state":1,
        "started":"2020-04-25T13:55:33.135703",
        "finished":"2020-04-25T13:55:34.620735"
    },
    {
        "taskType":"vnd.farmmaps.task.tipstar",
        "code":"172f42ece9004013aaf2b6a56b716e39",
        "state":1,
        "started":"2020-04-25T13:55:33.903717",
        "finished":"2020-04-25T13:55:34.636575"
    },
    {
        "taskType":"vnd.farmmaps.task.soilcompaction",
        "code":"1667fce90d954b1b90d9997e5e642e8d",
        "state":1,
        "started":"2020-04-25T13:55:33.575171",
        "finished":"2020-04-25T13:55:34.767101"
    },
    {
        "taskType":"vnd.farmmaps.task.ahn",
        "code":"23b1e66325134e8cbd778d57865590f2",
        "state":1,
        "started":"2020-04-25T13:55:33.465586",
        "finished":"2020-04-25T13:55:35.170389"
    },
    {
        "taskType":"vnd.farmmaps.task.tipstar",
        "code":"80bcf30893614ad288fe8409cee5f9b1",
        "state":1,
        "started":"2020-04-25T13:55:36.893606",
        "finished":"2020-04-25T13:55:37.331862"
    },
    {
        "taskType":"vnd.farmmaps.task.workflow",
        "code":"c4c7d23b6e534a7e9b5dfb79847ea449",
        "state":1,
        "started":"2020-04-25T13:55:37.237456",
        "finished":"2020-04-25T13:55:37.567148"
    },
    {
        "taskType":"vnd.farmmaps.task.trijntje",
        "code":"e29539ed7a014dfcb739ad3d87298cc2",
        "state":1,
        "started":"2020-04-25T13:55:44.271105",
        "finished":"2020-04-25T13:55:45.64174"
    },
    {
        "taskType":"vnd.farmmaps.task.satellite",
        "code":"b5a549be975e4196972806157ee7f2cd",
        "state":1,
        "started":"2020-04-25T13:55:33.778997",
        "finished":"2020-04-25T13:57:13.811563"
    },
    {
        "taskType":"vnd.farmmaps.task.shadow",
        "code":"a1daf49cf08142c289825def78986027",
        "state":1,
        "started":"2020-04-25T13:55:33.153348",
        "finished":"2020-04-25T13:56:14.590014"
    }
]
```

**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

{   
    "taskType":"vnd.farmmaps.task.shadow",
    "code":"a1daf49cf08142c289825def78986027",
    "state":1,
    "started":"2020-04-25T13:55:33.153348",
    "finished":"2020-04-25T13:56:14.590014"
}
```
**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)