# 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
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.

{% 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

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.opencityitalia.it/sviluppatori-e-partner-tecnologici/integrazioni/processi-asincroni-job.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.