> For the complete documentation index, see [llms.txt](https://docs.opencityitalia.it/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.opencityitalia.it/stanza-del-cittadino/sviluppatori-e-partner-tecnologici/integrazioni/processi-asincroni-job.md).

# Processi asincroni (job)

In questa pagina viene fatta una breve descrizione delle API per la gestione dei Jobs (processi asincroni)

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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.