# Processi asincroni (job)

La piattaforma consente la possibilità da parte di sistemi esterni di creare/modificare/visualizzare ed eliminare oggetti **Job**

Ad esempio nel nostro ambiente di demo è possibile consultare le API dedicate a questo scopo:

<https://servizi.comune-qa.bugliano.pi.it/lang/api/doc#jobs>

Questi speciali oggetti sono dei processi onerosi che vengono creati e poi eseguiti in modo **asincrono** dalla piattaforma.

Esempio di interazione tra un sistema esterno e le API dei jobs:

{% @mermaid/diagram content="sequenceDiagram
Client->>Piattaforma: POST /jobs
Piattaforma->>Client: return job id
Client->>Piattaforma: GET /jobs/{id}
Piattaforma->>Client: return job status" %}

In fase di creazione del **Job** viene specificato tramite il parametro type il tipo di processo (**type**) che verrà eseguito dal sistema.&#x20;

{% hint style="warning" %}
In base al tipo di processo creato i parametri **attachment** e **args** possono cambiare.\
Attualmente l'unico processo disponibile è **import\_dovuti**
{% endhint %}

### Creazione di un Job

Per poter creare un Job bisogna eseguire una chiamata **POST** all' endpoint  `api/jobs`

Il payload per la creazione di un Job è così composto&#x20;

```json
{
  "attachment": {
    "name": "string",
    "mime_type": "text/csv",
    "file": "ZXNlbXBpbw== OR www.example.com"
  },
  "type": "string",
  "args": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}
```

Dove:

**attachment** -> è il file in base64  che verrà processato

**type** -> è il tipo di processo che deve essere eseguito

**args** -> sono dei parametri necessari al tipo di processo

L' API rispondere con un codice `HTTP 201` e con l'id del Job creato

### Recupero delle informazioni di un Job

Per poter recuperare informazioni su Job bisogna eseguire una chiamata **GET** all' endpoint  `api/jobs/{id}`

Il payload di risposta delle API è così composto:

```json
{
    "attachment": {
      "name": "string",
      "mime_type": "text/csv"
    },
    "id": "string",
    "type": "string",
    "status": "string",
    "args": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "output": "string",
    "running_output": "string",
    "started_at": "2024-05-31T09:19:18.779Z",
    "terminated_at": "2024-05-31T09:19:18.779Z",
    "created_at": "2024-05-31T09:19:18.779Z",
    "updated_at": "2024-05-31T09:19:18.779Z"
}
```

Dove:

**status** -> è lo stato attuale del job e può assumere i seguenti valori `pending, cancelled, running, finished, failed`

**output** -> l'output finale del processo, può contenere un errore in caso di processo `failed`

**running\_output** -> l'output corrente (Es. la riga del file che si sta processando)

Uno degli utilizzi più significativi che si può fare con i Job è l'**importazione di contenuti** come ad esempio l'importazione dei dovuti

&#x20;