# Guide field workers

It is recommended to display information to the field workers to help them perform their work properly. Several information can be retrieved at the task group level :&#x20;

* *Display name* : user-friendly name of the task group.
* *Description* : a short-text description of the task group, to help field workers better understand the type of information that is expected.&#x20;
* *Input examples* : an example image of what is expected, also to guide the field workers.&#x20;

To better understand how these endpoints could be used in practice, please refer to our [mobile application documentation](https://docs.deepomatic.com/platform-documentation/~/revisions/k8bzTvOh5XwOBp4LCTxs/deepomatic-engage/use-deepomatic-lens-on-the-field/complete-work-orders).

Here are described two endpoints to retrieve a specific task group and the complete list of task groups associated to a specific visual application.

{% hint style="info" %}
All endpoints are described with the EU (Europe) server format. If your application runs on the US server, you will need to use the following format: [https://api.{site-id}.customers.us1.deepomatic.com](https://api.000f0174-bdf0-47b3-bb3e.customers.us1.deepomatic.com)/v0.2/.
{% endhint %}

{% hint style="warning" %}
Every Deepomatic application is versioned. We recommend to not integrate any logic based on the tasks and task groups ids as those ids changes when a version is upgraded. You can instead use tasks and task groups names that are agnostic to version changes.&#x20;
{% endhint %}

## Retrieve a task group

<mark style="color:blue;">`GET`</mark> `https://api.{site-id}.customers.deepomatic.com/v0.2/task-groups/{name}`

#### Path Parameters

| Name                                   | Type   | Description                                       |
| -------------------------------------- | ------ | ------------------------------------------------- |
| name<mark style="color:red;">\*</mark> | string | **Slug identifier of the task group to retrieve** |

#### Headers

| Name                                            | Type   | Description                                        |
| ----------------------------------------------- | ------ | -------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | **Deepomatic API Key** associated to your account. |

{% tabs %}
{% tab title="200: OK Everything worked as expected: a response containing the task group information is returned." %}
**Response format**

`input_examples` - array : array containing URL links leading to the input examples (photo) set for a specific task group.&#x20;

`only_for_dashboard` - *boolean* : whether or not a task should be pushed to field workers. If false, the task should be pushed.

`conformity_status` - *boolean* : whether or not a task is included in the conformity score which allows to compute the completion state of a work order.

`outcome_type` - *string* : type of value returned after the analysis (Number, Boolean...).&#x20;

`outcome_validation` - array : array containing the information (color, message, validation status) of how the task should behave depending on different analysis results. The different analysis results scenario are defined in the `schema`.&#x20;

In the example below, if the value detected is superior to 1, then the `color` "#e4264e " and the `sentence` (message) "At least one issue has been detected" should be displayed to the field workers. `is_conformity_validated` returns the validation status of the task, in that case the task is not validated.&#x20;

To retrieve how those different information are configured in our platform, refer to the [tasks documentation ](https://docs.deepomatic.com/platform-documentation/~/revisions/k8bzTvOh5XwOBp4LCTxs/deepomatic-drive/configuring-visual-automation-applications/publishing-visual-automation-apps/manage-application-versions/configure-an-application-version/configure-tasks)and [task groups documentation](https://docs.deepomatic.com/platform-documentation/~/revisions/k8bzTvOh5XwOBp4LCTxs/deepomatic-drive/configuring-visual-automation-applications/publishing-visual-automation-apps/manage-application-versions/configure-an-application-version/configure-task-groups).&#x20;

```json
{
    "id": "6f15b52e-4717-4ec5-a8b2-bd58e7eec5ca",
    "name": "equipment-after-intervention",
    "display_name": "Equipment after intervention",
    "description": "Take a photo in landscape format of the equipment after your intervention",
    "order": 0,
    "input_examples": [
        "https://storage.googleapis.com/dp-resources-prod/questionnaires_images/4ba2632d-d30d-4c2e-97b0-6008780f7b06.jpeg?Expires=1680179687&GoogleAccessId=vesta-pre-prod%40deepomatic-160015.iam.gserviceaccount.com&Signature=Cm2%2BOQ87VwBGqD%2B%2FM%2B6hzYMUh%2FMD0ARuUdeWxO2Kowk%2F02EnEMElrDD4H27DHLwTtJXnikviXwMfDkvBSgMOtzTzHJzeo35%2BurORgucSmSAmPKHcFVh0M7uiQNwSAL78q%2Fd6DiPgGoQvtuMmD0RR6Vrk1OmW5klJlYHQsZbes9aa2FmskC578KU9NNGjRJpdP7D%2B5dcUmaehEKcA6WGUjcaj0fqafIcTNJevq6pwDHU%2B1QdJUlSJrLhfk5j3t3PcJOqZMm36EHHGfYYkdx9Qqmbe4f91%2F9gNXccbXOmjNv6awmCmleUn0B9jszQ8d3QjcwsHfsCF22gMytiFPe66sg%3D%3D",
        "https://storage.googleapis.com/dp-resources-prod/questionnaires_images/cee7f7b2-9589-4d48-b969-60a17744f4f6.jpeg?Expires=1680179687&GoogleAccessId=vesta-pre-prod%40deepomatic-160015.iam.gserviceaccount.com&Signature=Z4l2lfwBVdeAg7uIR3Ywhg5bfdlm92nvGLTLYUUc5B1oN2b4ARvM%2FR3ZeXeJq%2F6tnQ2qQRYa%2Bae829NpMpDuqMT%2Bx1Axqyai%2FKb8T0U%2B1F9DKfPvJ7doVdtlTJXcjOxaLweB5WrK0MQDN4n77Oqa%2B53XhyFFl2xzWgzxkQlFryU2lyoD1rdMfj9hqcly0CACdKjvPD34SmacDiLsWcO9uUMMC8tChijUDil1sq5FF0CSm3lc4OdvqKcEc6ntnCgcAa%2BBANMt13M0k0v6ZEDyiSMYMWtoM2QmftFt4zvAJl%2BtEUJ1OMV9KjjviyA7QWMoRsdvZAhQLOABP%2Fwj31mjwQ%3D%3D"
    ],
    "engage_app_version_id": "fb5516ed-355e-4b2c-9d11-6c39b660045f",
    "tasks": [
       {
            "id": "db081122-b571-48d9-b19b-6f690be1e94e",
            "name": "equipment_after_intervention",
            "sentence": "Is it a photo of the equipment after intervention?",
            "conformity_status": false,
            "outcome_type": "Boolean",
            "outcome_validation": [
                {
                    "color": "#26e4bc",
                    "schema": {
                        "type": "boolean",
                        "const": true
                    },
                    "sentence": "Valid photo",
                    "not_analyzed": false,
                    "is_conformity_validated": true
                },
                {
                    "color": "#e45d26",
                    "schema": {
                        "type": "boolean",
                        "const": false
                    },
                    "sentence": "Invalid photo",
                    "not_analyzed": false,
                    "is_conformity_validated": false
                }
            ],
            "description": "",
            "questionnaire_id": "6f15b52e-4717-4ec5-a8b2-bd58e7eec5ca",
            "questionnaire_name": "equipment-after-intervention"
        },
        {
            "id": "b5293ca9-faa1-4880-8c07-1bb0475da4d6",
            "name": "equipment_after_intervention_degradations",
            "sentence": "Number of degradations",
            "conformity_status": true,
            "outcome_type": "Number",
            "outcome_validation": [
                {
                    "color": "#26e4bc",
                    "schema": {
                        "type": "number",
                        "maximum": 0
                    },
                    "sentence": "No issue detected",
                    "not_analyzed": false,
                    "is_conformity_validated": true
                },
                {
                    "color": "#e4264e",
                    "schema": {
                        "type": "number",
                        "minimum": 1
                    },
                    "sentence": "Degradations have been spotted on the equipment",
                    "not_analyzed": false,
                    "is_conformity_validated": false
                }
            ],
            "description": "",
            "questionnaire_id": "6f15b52e-4717-4ec5-a8b2-bd58e7eec5ca",
            "questionnaire_name": "equipment-after-intervention"
        }
    ]
}
```

{% endtab %}

{% tab title="403: Forbidden The API key doesn't have permissions to perform the request." %}

```javascript
{"detail": "Authentication credentials not provided."}
OR
{"detail": "No user found for such apiKey."}
```

{% endtab %}

{% tab title="404: Not Found The requested resource (task group id) doesn't exist." %}

```javascript
{"detail": "WorkOrder not found!"}
```

{% endtab %}
{% endtabs %}

**Request example**

```
curl 'https://api.{site-id}.customers.deepomatic.com/v0.2/task-groups/{name}' \
    -X GET \
    -H 'Authorization: Token <your_api_key>' \       
    -H 'Content-Type: application/json' 
```

## Retrieve all task groups in a visual application

<mark style="color:blue;">`GET`</mark> `https://api.{site-id}.customers.deepomatic.com/v0.2/task-groups/`

#### Headers

| Name                                            | Type   | Description                                        |
| ----------------------------------------------- | ------ | -------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | **Deepomatic API Key** associated to your account. |

{% tabs %}
{% tab title="200: OK Everything worked as expected: a response containing the list of task groups in your application is returned." %}
**Response format**

`input_examples` - array : array containing URL links leading to the input examples (photo) set for a specific task group.&#x20;

`only_for_dashboard` - *boolean* : whether or not a task should be pushed to field workers. If false, the task should be pushed.

`conformity_status` - *boolean* : whether or not a task is included in the conformity score which allows to compute the completion state of a work order.

`outcome_type` - *string* : type of value returned after the analysis (Number, Boolean...).&#x20;

`outcome_validation` - array : array containing the information (color, message, validation status) of how the task should behave depending on different analysis results. The different analysis results scenario are defined in the `schema`.&#x20;

In the example below, if the value detected is superior to 1, then the `color` "#e4264e " and the `sentence` (message) "At least one issue has been detected" should be displayed to the field workers. `is_conformity_validated` returns the validation status of the task, in that case the task is not validated.&#x20;

To retrieve how those different information are configured in our platform, refer to the [tasks documentation](https://docs.deepomatic.com/platform-documentation/~/revisions/k8bzTvOh5XwOBp4LCTxs/deepomatic-drive/configuring-visual-automation-applications/publishing-visual-automation-apps/manage-application-versions/configure-an-application-version/configure-tasks) and the [task groups documentation](https://docs.deepomatic.com/platform-documentation/~/revisions/k8bzTvOh5XwOBp4LCTxs/deepomatic-drive/configuring-visual-automation-applications/publishing-visual-automation-apps/manage-application-versions/configure-an-application-version/configure-task-groups).&#x20;

<pre class="language-json"><code class="lang-json"><strong>[
</strong>    {
        "id": "6f15b52e-4717-4ec5-a8b2-bd58e7eec5ca",
        "name": "equipment-after-intervention",
        "display_name": "Equipment after intervention",
        "description": "Take a photo in landscape format of the equipment after your intervention",
        "order": 0,
        "input_examples": [
           "https://storage.googleapis.com/dp-resources-prod/questionnaires_images/4ba2632d-d30d-4c2e-97b0-6008780f7b06.jpeg?Expires=1680179687&#x26;GoogleAccessId=vesta-pre-prod%40deepomatic-160015.iam.gserviceaccount.com&#x26;Signature=Cm2%2BOQ87VwBGqD%2B%2FM%2B6hzYMUh%2FMD0ARuUdeWxO2Kowk%2F02EnEMElrDD4H27DHLwTtJXnikviXwMfDkvBSgMOtzTzHJzeo35%2BurORgucSmSAmPKHcFVh0M7uiQNwSAL78q%2Fd6DiPgGoQvtuMmD0RR6Vrk1OmW5klJlYHQsZbes9aa2FmskC578KU9NNGjRJpdP7D%2B5dcUmaehEKcA6WGUjcaj0fqafIcTNJevq6pwDHU%2B1QdJUlSJrLhfk5j3t3PcJOqZMm36EHHGfYYkdx9Qqmbe4f91%2F9gNXccbXOmjNv6awmCmleUn0B9jszQ8d3QjcwsHfsCF22gMytiFPe66sg%3D%3D",
           "https://storage.googleapis.com/dp-resources-prod/questionnaires_images/cee7f7b2-9589-4d48-b969-60a17744f4f6.jpeg?Expires=1680179687&#x26;GoogleAccessId=vesta-pre-prod%40deepomatic-160015.iam.gserviceaccount.com&#x26;Signature=Z4l2lfwBVdeAg7uIR3Ywhg5bfdlm92nvGLTLYUUc5B1oN2b4ARvM%2FR3ZeXeJq%2F6tnQ2qQRYa%2Bae829NpMpDuqMT%2Bx1Axqyai%2FKb8T0U%2B1F9DKfPvJ7doVdtlTJXcjOxaLweB5WrK0MQDN4n77Oqa%2B53XhyFFl2xzWgzxkQlFryU2lyoD1rdMfj9hqcly0CACdKjvPD34SmacDiLsWcO9uUMMC8tChijUDil1sq5FF0CSm3lc4OdvqKcEc6ntnCgcAa%2BBANMt13M0k0v6ZEDyiSMYMWtoM2QmftFt4zvAJl%2BtEUJ1OMV9KjjviyA7QWMoRsdvZAhQLOABP%2Fwj31mjwQ%3D%3D"
        ],
        "engage_app_version_id": "fb5516ed-355e-4b2c-9d11-6c39b660045f",
        "tasks": [
           {
                "id": "db081122-b571-48d9-b19b-6f690be1e94e",
                "name": "equipment_after_intervention",
                "sentence": "Is it a photo of the equipment after intervention?",
                "conformity_status": false,
                "outcome_type": "Boolean",
                "outcome_validation": [
                    {
                        "color": "#26e4bc",
                        "schema": {
                            "type": "boolean",
                            "const": true
                        },
                        "sentence": "Valid photo.",
                        "not_analyzed": false,
                        "is_conformity_validated": true
                    },
                    {
                        "color": "#e45d26",
                        "schema": {
                            "type": "boolean",
                            "const": false
                        },
                        "sentence": "Photo incorrecte.",
                        "not_analyzed": false,
                        "is_conformity_validated": false
                    }
                ],
                "description": "",
                "questionnaire_id": "6f15b52e-4717-4ec5-a8b2-bd58e7eec5ca", 
                "questionnaire_name": "equipment-after-intervention"
            },
            {
                "id": "b5293ca9-faa1-4880-8c07-1bb0475da4d6",
                "name": "equipment_after_intervention_degradations",
                "sentence": "Number of degradations",
                "conformity_status": true,
                "outcome_type": "Number",
                "outcome_validation": [
                    {
                        "color": "#26e4bc",
                        "schema": {
                            "type": "number",
                            "maximum": 0
                        },
                        "sentence": "No issue detected",
                        "not_analyzed": false,
                        "is_conformity_validated": true
                    },
                    {
                        "color": "#e4264e",
                        "schema": {
                            "type": "number",
                            "minimum": 1
                        },
                        "sentence": "Degradations have been spotted on the equipment",
                        "not_analyzed": false,
                        "is_conformity_validated": false
                    }
                ],
                "description": "", 
                "questionnaire_id": "6f15b52e-4717-4ec5-a8b2-bd58e7eec5ca", 
                "questionnaire_name": "equipment-after-intervention"
            }
        ]
    },
    {
        "id": "b184fbda-c6f1-45d6-aba6-bac0745cb987",
        "name": "other-equipment",
        "display_name": "Other equipment",
        "description": "In case of additional equipment, take a photo",
        "order": 1,
        "input_examples": [
           "https://storage.googleapis.com/dp-resources-prod/questionnaires_images/4ba2632d-d30d-4c2e-97b0-6008780f7b06.jpeg?Expires=1680179687&#x26;GoogleAccessId=vesta-pre-prod%40deepomatic-160015.iam.gserviceaccount.com&#x26;Signature=Cm2%2BOQ87VwBGqD%2B%2FM%2B6hzYMUh%2FMD0ARuUdeWxO2Kowk%2F02EnEMElrDD4H27DHLwTtJXnikviXwMfDkvBSgMOtzTzHJzeo35%2BurORgucSmSAmPKHcFVh0M7uiQNwSAL78q%2Fd6DiPgGoQvtuMmD0RR6Vrk1OmW5klJlYHQsZbes9aa2FmskC578KU9NNGjRJpdP7D%2B5dcUmaehEKcA6WGUjcaj0fqafIcTNJevq6pwDHU%2B1QdJUlSJrLhfk5j3t3PcJOqZMm36EHHGfYYkdx9Qqmbe4f91%2F9gNXccbXOmjNv6awmCmleUn0B9jszQ8d3QjcwsHfsCF22gMytiFPe66sg%3D%3D",
           "https://storage.googleapis.com/dp-resources-prod/questionnaires_images/cee7f7b2-9589-4d48-b969-60a17744f4f6.jpeg?Expires=1680179687&#x26;GoogleAccessId=vesta-pre-prod%40deepomatic-160015.iam.gserviceaccount.com&#x26;Signature=Z4l2lfwBVdeAg7uIR3Ywhg5bfdlm92nvGLTLYUUc5B1oN2b4ARvM%2FR3ZeXeJq%2F6tnQ2qQRYa%2Bae829NpMpDuqMT%2Bx1Axqyai%2FKb8T0U%2B1F9DKfPvJ7doVdtlTJXcjOxaLweB5WrK0MQDN4n77Oqa%2B53XhyFFl2xzWgzxkQlFryU2lyoD1rdMfj9hqcly0CACdKjvPD34SmacDiLsWcO9uUMMC8tChijUDil1sq5FF0CSm3lc4OdvqKcEc6ntnCgcAa%2BBANMt13M0k0v6ZEDyiSMYMWtoM2QmftFt4zvAJl%2BtEUJ1OMV9KjjviyA7QWMoRsdvZAhQLOABP%2Fwj31mjwQ%3D%3D"
        ],
        "engage_app_version_id": "fb5516ed-355e-4b2c-9d11-6c39b660045f",
        "tasks": [
            {
                "id": "eba62d14-cf5f-44fc-a317-8c87636c9fbf",
                "name": "other-task",
                "sentence": "Other task",
                "conformity_status": true,
                "outcome_type": "Boolean",
                "outcome_validation": [
                    {
                        "color": "#26e4bc",
                        "schema": {
                            "type": "boolean",
                            "const": true
                        },
                        "sentence": "Valid photo",
                        "not_analyzed": false,
                        "is_conformity_validated": true
                    },
                    {
                        "color": "#e4264e",
                        "schema": {
                            "type": "boolean",
                            "const": false
                        },
                        "sentence": "Invalid photo",
                        "not_analyzed": false,
                        "is_conformity_validated": false
                    }
                ],
                "description": "", 
                "questionnaire_id": "b184fbda-c6f1-45d6-aba6-bac0745cb987", 
                "questionnaire_name": "other-equipment"
            }
        ]
    }
]
</code></pre>

{% endtab %}

{% tab title="403: Forbidden The API key doesn't have permissions to perform the request." %}

```javascript
{"detail": "Authentication credentials not provided."}
OR
{"detail": "No user found for such apiKey."}
```

{% endtab %}
{% endtabs %}

#### Request example

```json
curl 'https://api.{site-id}.customers.deepomatic.com/v0.2/task-groups/' \  
    -X GET \
    -H 'Authorization: Token <your_api_key>' \       
    -H 'Content-Type: application/json' 
```
