Éditer une liste

Les tâches de liste permettent d’effectuer des traitements sur les données et de retourner un résultat sous forme de document (typiquement un fichier PDF).

Lancer une liste

La syntaxe permettant de lancer une liste simple est la suivante:

curl --insecure --silent \
     -H "Authorization: Bearer <bearer_token>" \
     --json '' \
     -X POST \
     'https://<host>/api/v1/<taskId>'

Info:

Par défaut, toutes les pages sont regroupées dans un seul et unique PDF.

La méthode HTTP doit être POST afin de pouvoir fournir les paramètres de l’écran en tant que body de la requête. Le Content-Type du body doit être application/json (ce qui est automatiquement fait par cURL avec l’option --json).

Si le code de retour HTTP est 200, la réponse est un objet JSON structuré contenant l’identifiant du fichier généré:

{
  "metadata": {
    "apiVersion": "1.0",
    "taskId": "<taskId>",
    "taskType": "L",
    "domainId": "<domain>"
  },
  "data": {
    "processId": "019D906B-6086-752F-A747-802F458A2471",
    "screen": {
      "PRESENTATION": {
        "key": "1",
        "value": "Liste standard"
      },
      "OUTPUT": {
        "key": "4",
        "value": "Un fichier PDF unique"
      }
    },
    "result": {
      "fileName": "liste.pdf",
      "fileId": "a3f8c21b-4d7e-4b1a-9c2d-0e5f6a7b8c9d"
    }
  }
}

Clé	Description
`processId`	Identifiant du processus (uniquement pour les listes longues - type `M`).
`screen`	Contient les paramètres utilisés pour le lancement (y compris ceux chargés par défaut par le système).
`result`	Présent dès que le fichier est disponible. Contient `fileName` (nom du fichier) et `fileId` (identifiant pour le téléchargement).

Note: par défaut, la propriété result sera toujours présente car le système attend que l’output soit généré, que ce soit pour une liste courte (type L) ou longue (type M). Ce comportement ne peut pas être modifié pour les listes courtes, mais il est possible de récupérer la main directement en utilisant le paramètre wait dans une liste longue afin de pouvoir suivre (par polling) l’avancement du traitement via l’état du processus.

Paramètres de lancement

Afin de lancer la liste, il est nécessaire de passer les paramètres de l’écran. Les champs possibles sont décrits dans le descripteur OpenAPI et dépendent de chaque tâche.

De manière générale, une tâche de liste se compose:

d’un champ PRESENTATION permettant de sélectionner le type de liste désirée (ce qui influence la structure du résultat).
d’un champ OUTPUT permettant de sélectionner le format de sortie (typiquement 4 pour un fichier PDF unique).
d’un champ FILTER optionnel permettant de filtrer les données à traiter.

La valeur du champ FILTER est une condition SQL au format SAINet (ex: $TABLE.COLONNE LIKE 'A%'). Le préfixe FROM $TABLE WHERE est ajouté automatiquement par le système.

Voici un exemple de lancement d’une liste de type SYS12 avec un filtre:

curl --insecure --silent \
     -H "Authorization: Bearer <bearer_token>" \
     --json "{\"PRESENTATION\":\"1\",\"OUTPUT\":\"4\",\"FILTER\":\"\$SYSUSR.USER_PK LIKE 'aa-%'\"}" \
     -X POST \
     'https://<host>/api/v1/SYS12'

Télécharger le fichier via fileId

Une fois la réponse JSON reçue (pour les tâches de type L ou M), le fichier peut être téléchargé via son fileId:

curl --insecure --silent \
     -H "Authorization: Bearer <bearer_token>" \
     --output result.pdf \
     'https://<host>/api/v1/<taskId>/download/<fileId>'

Le fileId est fourni dans le champ result.fileId de la réponse JSON. La réponse est directement le contenu binaire du fichier. Si le fileId est inconnu ou a expiré, le serveur retourne un code HTTP 404.

Note:

Le fichier peut être récupéré pendant 30 minutes, après quoi il sera détruit.

Téléchargement direct (ddl)

Pour obtenir le fichier binaire directement sans passer par la réponse JSON intermédiaire, utiliser l’endpoint ddl:

curl --insecure --silent \
     -H "Authorization: Bearer <bearer_token>" \
     --json '{}' \
     -X POST \
     --output result.pdf \
     'https://<host>/api/v1/<taskId>/ddl'

Cet endpoint fonctionne pour les tâches de type L et M. Pour les tâches de type M, le serveur attend implicitement la fin du traitement avant de retourner le fichier. La réponse est directement le contenu binaire du fichier.

Listes longues (Type `M`)

Les tâches de liste longues (type M) fonctionnent de manière asynchrone. Elles démarrent un processus et retournent un identifiant de processus (processId).

Il y a deux possibilités:

garder la connexion ouverte en attendant le résultat (exécution synchrone).
lancer le processus de manière non bloquante, vérifier l’avancement du processus (polling) et télécharger le fichier une fois terminé (exécution asynchrone).

Paramètres	Type	Description
`wait`	Boolean	Permet de ne pas attendre le résultat et de reprendre la main. `true` par défaut pour une utilisation synchrone.

Exécution synchrone

Par défaut, la connexion reste ouverte jusqu’à la fin du processus:

curl --insecure --silent --max-time 600 \
     -H "Authorization: Bearer <bearer_token>" \
     --json '{"OUTPUT":"4"}' \
     -X POST \
     'https://<host>/api/v1/ADRS2'

La réponse contient un objet JSON avec l’identifiant du processus, les paramètres de l’écran et le fichier généré:

{
  "metadata": {
    "apiVersion": "1.0",
    "taskId": "ADRS2",
    "taskType": "M",
    "domainId": "<domain>"
  },
  "data": {
    "processId": "019D906B-6086-752F-A747-802F458A2471",
    "screen": {
      "OUTPUT": {
        "key": "4",
        "value": "Un fichier PDF unique"
      }
    },
    "result": {
      "fileName": "adresses.pdf",
      "fileId": "b7d4e92a-1c3f-4a8b-8e6d-2f0a1b2c3d4e"
    }
  }
}

Clé	Description
`processId`	Identifiant du processus.
`screen`	Contient les paramètres utilisés pour le lancement (y compris ceux chargés par défaut par le système).
`result`	Présent lorsque le processus est terminé (`wait=true`). Contient `fileName` (nom du fichier) et `fileId` (identifiant pour le téléchargement via l’endpoint `download`).

Télécharger le fichier résultat

Une fois que le processus est terminé (vérifiable via l’endpoint des processus), le fichier résultat peut être téléchargé via son processId:

curl --insecure --silent \
     -H "Authorization: Bearer <bearer_token>" \
     --output result.pdf \
     'https://<host>/api/v1/ADRS2/processes/<processId>/result'

La réponse est directement le contenu binaire du fichier.

Il est également possible de télécharger le fichier via son fileId (disponible dans result.fileId de la réponse JSON) en utilisant l’endpoint download.

Exécution asynchrone (polling)

Il est possible d’utiliser le paramètre wait pour lancer le processus et reprendre la main:

curl --insecure --silent \
     -H "Authorization: Bearer <bearer_token>" \
     --json '{"OUTPUT":"4"}' \
     -X POST \
     'https://<host>/api/v1/ADRS2?wait=false'

Lorsque wait=false, le champ result est absent de la réponse JSON car le processus n’est pas encore terminé. Ensuite, le processId peut être utilisé pour vérifier l’état d’avancement du processus et télécharger le fichier résultat une fois terminé.