Récupérer une vue

La syntaxe permettant de récupérer le résultat d’une vue est la suivante:

curl --insecure --silent \
     -H "Authorization: Bearer <bearer_token>" \
     --json '{"field":"value"}' \
     -X POST
     'https://<host>/SNV4SRV-ws-war/api/v1/<taskId>'

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

Info:

Il est également possible d’utiliser les méthodes HTTP PATCH et PUT pour des raisons de rétrocompatibilité.

Si le code de retour HTTP est 200, la réponse sera structurée comme ceci:

{
  "metadata": {
    "apiVersion": "1.0",
    "taskId": "<taskId>",
    "taskType": "<type>",
    "domainId": "<domain>"
  },
  "data": {
    "gridViewId": "SYSUS_VUE1",
    "screen": {
      "1": {
        "key": "1",
        "value": "Renseignements de base"
      }
    },
    "columns": [
      {
        "id": "1",
        "datafieldId": "SYSUSR.USER_PK",
        "format": "String",
        "label": "Identifiant"
      },
      {
        "id": "2",
        "datafieldId": "SYSUSR.FULLNAME",
        "format": "String",
        "label": "Nom"
      }
    ],
    "rows": [
      {
        "cells": [
          "aa-10-lecteur",
          "Lecteur 10"
        ]
      },
      {
        "cells": [
          "aa-20-msp",
          "MSP"
        ]
      },
      {
        "cells": [
          "aa-50-admin",
          "Administration"
        ]
      }
    ]
  }
}

Clé	Description
`processId`	Identifiant du processus pour les vues longues (type `W`).
`gridViewId`	Identifiant de la grille de retour. Cette grille dépend généralement du type de vue sélectionnée.
`screen`	Contient les paramètres utilisés pour le lancement de la vue (y compris ceux chargés par défaut par le système).
`columns`	Liste des colonnes présentes dans la grille de retour avec leur données respectives.
`rows`	Liste des lignes. Chaque ligne contient une propriété `cells` avec la liste des cellules sous forme de `String`. Le nombre de cellules correspond au nombre de colonnes.

Paramètres de lancement

Afin de lancer la vue, 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 vue se compose d’un champ permettant de sélectionner le type de vue désiré (ce qui influence la structure -les colonnes- du résultat) et d’un autre champ permettant de filtrer les données à retourner. Il peut également y avoir d’autres paramètres supplémentaires.

La vue ci-dessous est lancée sans paramètres particulier, en utilisant les paramètres par défaut du système:

curl --insecure --silent \
     -H "Authorization: Bearer <bearer_token>"  \
     --json "{}" \
     -X POST \
     'https://<host>/SNV4SRV-ws-war/api/v1/SYSUS'

Voici un exemple de lancement en filtrant les utilisateurs de type ADMIN et SUPERADMIN:

curl --insecure --silent \
     -H "Authorization: Bearer <bearer_token>"  \
     --json "{\"2\":\"\$SYSUSR.CATEGORYLIST LIKE '%ADMIN%'\"}" \
     -X POST \
     'https://<host>/SNV4SRV-ws-war/api/v1/SYSUS'

Formats de retour

Les valeurs des différentes cellules sont sous forme de chaîne de caractère avec les formats suivants:

Format	Valeur
`String` / `MultiLineString`	Ceci est une chaîne de caractères
`Boolean`	`true` ou `false`
`Date` / `DateTime` / `Time`	2018-04-11T00:00:00+0200
`Integer` / `Year`	42
`Financial` / `Percentage` / `Float` / `Double`	1237.00000000

Note:

Il existe plusieurs autres formats (Filter, Enum, …). Ceux-ci peuvent simplement êtres considérés comme des chaînes de caractères (String).

A noter que le nombre de cellules dans une ligne est toujours égal au nombre de colonnes. Les valeurs vides sont représentées par une chaîne de caractère vide ("").

Vues longues (Type `W`)

Les tâches de vues longues (type W) sont généralement prévues pour avoir des temps de traitement dépassant les timeout par défaut des outils qui attendent une réponse. Elles peuvent durer plusieurs minutes avant de fournir un résultat.

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 récupérer le résultat 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

Cette solution est la plus simple d’un point de vue utilisation, mais peut se heurter à des problèmes de timeout, typiquement si un élément de réseau se situant entre le poste de l’utilisateur et le serveur SAINet (typiquement un Proxy ou un Firewall) ferme la connexion.

Il est généralement possible de modifier le timout du coté client avec la commande suivante:

curl --insecure --silent --max-time 600 \
     -H "Authorization: Bearer <bearer_token>"  \
     --json "{}" \
     -X POST \
     'https://<host>/SNV4SRV-ws-war/api/v1/GTPLC'

Note:

Il n’y a pas de timeout coté serveur SAINet. Toutefois, il est impossible de contrôler les configurations des éléments réseaux entre le client et le serveur.

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 "{}" \
     -X POST \
     'https://<host>/SNV4SRV-ws-war/api/v1/GTPLC?wait=false'

Ensuite, le processId peut être utilisé pour récupérer l’état d’avancement du processus.

curl --insecure --silent \
     -H "Authorization: Bearer <bearer_token>"  \
     'https://<host>/SNV4SRV-ws-war/api/v1/GTPLC/processes/1840668C32B-54C-0242C0-P35HNA'

Une fois que le processus est terminé (le status est SUCCESS ou FAILURE), le résultat peut être récupéré comme suit:

curl --insecure --silent \
     -H "Authorization: Bearer <bearer_token>"  \
     'https://<host>/SNV4SRV-ws-war/api/v1/GTPLC/processes/1840668C32B-54C-0242C0-P35HNA/result'