< Descriptif des entités

< API Partenaires

Kiosque GED : Récupération de documents et leurs données métiers liées

Présentation du Kiosque GED

Le Kiosque GED est un bouquet d’API dédiées aux documents permettant de récupérer des documents du Portail des Aides et leurs données métiers associées. Votre organisme ou votre collectivité peut en effet avoir besoin de récupérer les documents utiles pour d’autres applicatifs comme, par exemple, une GED transverse.

Ces données métiers associées seront utiles pour :

  • Choisir les documents à récupérer.
  • Avoir les données nécessaires pour le classement ou le traitement du document.

Ces données métiers peuvent être personnalisées afin qu’elles correspondent à ce que connait l’applicatif. Dans ce cas, un administrateur peut définir un mapping entre les données du portail des aides et les données attendues par l’applicatif de l’organisme client du portail des aides.

APIs disponibles

Le Kiosque GED est disponible sous forme d’APIs semi-publiques. Les appels vers le Kiosque GED sont à réaliser en POST sous format GraphQL sauf la récupération du binaire du document qui est un GET https. Le Kiosque GED a pour nom technique « Agent GED ».

Une fois l’installation du module réalisée et ses utilisateurs créés, une phase d’administration des mappings est nécessaire si des données métiers liées au documents doivent être récupérées.

Une fois ces prérequis effectué, un traitement peut faire la récupération des données d’une liste de documents puis la récupération des documents sous forme de binaire.

Un premiers filtre sur la récupération des documents permet de cibler les événements potentiellement intéressants. Dans un second temps, les données métiers liées au documents peuvent permettre au traitement client de choisir de récupérer ou non le contenu du document.

Opérations GraphQL

L’url est de la forme :

https://{{fqdn}}/pda-semi-public-api/api/agent-ged/graphql

L’interface pour la documentation technique et pour tester unitairement est également disponible à cette URL. Il faut être authentifié avec un utilisateur connu du Kiosque GED pour pouvoir la consulter.

Pour tous les appels, les informations suivantes sont nécessaires dans le Header :

  • Authorization : de type basic avec l’utilisateur concerné par l’appel
  • X-tenant-id : tenant de la plateforme

Exemple de header :

{« X-tenantId »: « portaildesaides », « Authorization » : « Basic dGVzdHRlc3R0ZXN0OnRlc3R0ZXN0dGVzdA== »}


Le {fqdn} et le {tenant} de la plateforme peuvent être déduit le l’url de l’espace usager :

Chaque opération GraphQL dispose de droits spécifiques pour être appelée.

Query documentEvents :

Le droit pour cette opération est : « recupererListeEvenementsDocumentAgentGED »

Cette requête permet de récupérer une liste d’événements de documents en fonction d’un filtre et d’un mapping (« mappingId »).

Filtres possibles en entrée de documentEvents :

La liste d’événements doit être filtrée afin de rester performante et pertinente. Plusieurs filtres peuvent être appliqués en même temps. Les filtres possibles sont :

  • Type d’événement (eventType), le filtre ne se fait que sur une égalité stricte (equals) sur une ou plusieurs des 3 valeurs possibles :
    • DOCUMENT_CREATED : Pour récupérer les documents créés
    • DOCUMENT_DELETED : Pour récupérer les documents supprimés
    • METADATA_UPDATED : Pour récupérer les documents dont les métadonnées ont été modifiées.  (comme par exemple la description du document.)
    • DOCUMENT_UPDATED : Pour récupérer les documents dont une nouvelle version est disponible.
  • Date (eventDate), elle corresponds à la date de l’évènement. Ce filtre est très fortement recommandé en production pour le cas d’un traitement voulant récupérer des documents à intervalles réguliers. Le filtre se fait :
    • Sur une égalité stricte avec une date de la forme YYYY-MM-DD (equals)
    • Avant une date de format DateTime (before)
    • Après une date de format DateTime (after)
    • Entre 2 dates de format DateTime (after et before)
  • Référence de la pièce (pieceReference). Le filtre se fait sur la référence de la pièce paramétrée dans le référentiel pièce de l’Espace d’Administration :
    • Egalité stricte (equals) : pour récupérer les événements de document dont la référence de la pièce est strictement égale au libellé indiqué dans le filtre
    • Contient (contains) : pour récupérer les événements de document dont la référence de la pièce contient le libellé indiqué dans le filtre
    • Commence par (startsWith) : pour récupérer les événements de document dont la référence de la pièce commence par le libellé indiqué dans le filtre
    • Inclus dans une liste (in) : pour récupérer les événements de document dont la référence de la pièce est strictement égale à l’un des libellés de la liste indiquée dans le filtre
  • Entité métier (Kind) : Ce filtre est indispensable dans la requête pour appliquer un mapping sur les données métiers liées aux documents. Le filtre sur fait sur une égalité stricte (equals) de codes. Les codes pour les différents référentiels métiers sont les suivants :
    • DEMANDE_FINANCEMENT
    • DEMANDE_PAIEMENT
    • DOSSIER_FINANCEMENT
    • INSTANCE
    • TIERS
    • CONVENTION
    • JUSTIFICATION
  • Nom du fichier (fileName) : égalité stricte (equals) sur le nom du fichier.
  • Identifiant du document (objectId) :  égalité stricte (equals). Ce filtre est pour récupérer les données concernant un document en particulier.
  • Nature (nature) : égalité stricte (equals) sur la nature de a pièce paramétrée dans l’espace d’administration.
  • Auteur (author) : égalité stricte (equals) sur le nom de l’auteur.
  • Description (description) : égalité stricte (equals) sur la description du document
  • Fonction du document (fonction) : égalité stricte (equals) sur la fonction du document. La fonction du document est une donnée technique qui permet de savoir à quelle fonctionnalité du référentiel est rattaché le document.
Exemple d’appels avec filtres

Pagination en entrée de documentEvents

Il est recommandé de faire des appels à documentEvents en utilisant une pagination. Cela permet de limiter le nombre d’événements qui seront à traiter et de gérer la totalité des événements en plusieurs appels.

Les deux données pour cette gestion de pagination sont :

  • first : C’est le nombre maximum d’événements qui sont demandés pour ce filtre et ce mapping. Seul les « first » premiers seront retournés.
  • offset : c’est le numéro d’ordre du premier élément demandé.

L’usage de ces deux données se fait en complément des données liées à la pagination en retour de documentEvents : totalCount, pageInfo.hasNextPage et pageInfo.hasPreviousPage

Données en sortie de documentEvents :

Une liste d’événements concernant des documents est renvoyé par le Query documentsEvents.

Cette liste peut être paginée et contient les événements correspondant aux filtres définies en entrée de la Query.

Les données liées à la pagination sont :
  • totalCount : Nombre total d’élément correspondant à ce filtre et ce mapping
  • pageInfo.hasPreviousPage : Booléen qui indique si des éléments sont présents avant le 1er élément demandé (offset)
  • pageInfo.hasNextPage : Indique si des éléments sont présents après la liste demandé. Le prochain premier élément aura donc un offset égal à « offset + first » dans le prochain appel. Si hasNextPage est faux, il n’est plus nécessaire de faire d’autre appel.
Chaque événement peut contenir les données suivantes :
  • id : identifiant de l’instance de l’objet DocumentEvent
  • eventType : type d’événement lié au document.
    • DOCUMENT_CREATED : document créé
    • DOCUMENT_DELETED : Suppression du document
    • METADATA_UPDATED : Modification d’une méta-donnée du document (généralement, c’est l’ajout ou la modification de la description.). NB : La modification du document en lui-même n’est pas possible dans le portail des aides.
    • DOCUMENT_UPDATED : Document mis à jour (nouvelle version de disponible)
  • eventDate : date de l’événement au format DateTime
  • nature : nature du document. La nature d’un document est hérité de la nature de la pièce qui peut être paramétrée dans le référentiel pièce de l’espace d’administration.
  • fileName : Nom d’origine du fichier lors de l’ajout par l’utilisateur. Si le fichier est récupéré au moyen du Kiosque GED, il aura son nom composé de l’id du document suivi de ce nom de fichier. Dans le cas de certains fichiers généré comme les récapitulatifs, cette donnée peut ne pas être renseignée.
  • kind : entité métier auquel est rattaché le document. Tous les documents ne sont pas obligatoirement rattachés à une entité métiers. (pour le domaine de valeur du kind, voir la description du filtre Kind en entrée)
  • uri : Lien vers l’entité métier sans le FQDN. Ce lien peut être utile comme identifiant de l’entité métier.
  • file : Lien vers le document sans le FQDN. C’est ce lien qui doit être utilisé pour récupérer le binaire du document.
  • piecereference : référence de la pièce liée à ce document. (Corresponds à la référence paramétrée dans l’espace d’administration)
  • objectId : Identifiant technique du document dans la GED du portail des aides.
  • description : description du document. Cette description peut être ajouté par l’utilisateur après le téléversement du document.
  • fonction : fonction du document. Ce donnée permet d’identifier à quelle fonctionnalité du référentiel métiers est rattaché ce document. Par exemple « edition-decision » pour un document dans la section « Edition » de la décision.
  • author : Prénom et nom de l’utilisateur ayant téléversé le document.
  • metadata : Objet contenant l’ensemble des données mappée selon le mapping demandé en entrée de la query

Query mappings :

Le droit pour cette opération est : « recupererListeMappingAgentGED »

Cette requête permet de récupérer une liste de mapping.

Elle est utile pour un administrateur afin de vérifier une liste de mapping paramétrés et éventuellement pour récupérer l’identifiant des mappings.

La récupération d’une liste de mappings peut être paginée en cas de problème de performance.

Query node

Cette requête permet de récupérer un objet grâce à son Id. Cet objet peut être un mapping ou un documentEvent.

Pour la récupération d’un documentEvent, le droit nécessaire est « recupererUnEvenementsDocumentAgentGED ».

Pour la récupération d’un mapping, le droit nécessaire est « recupererUnMappingAgentGED ».

Mutation createMapping

Le droit pour cette opération est : « creerUnMappingAgentGED »

Cette requête permet à un administrateur de créer un ou plusieurs mappings.

Paramètres en entrée :

  • Titre (title) : Libellé informatif sur le mapping
  • Mapping (map) : Objet contenant le mapping.
    • Nom de la clé du mapping (key)
    • Type de mapping appliqué (type) : JSONPATH, HANDLEBARS ou CONSTANT
    • Description du mapping (description)
    • Valeur du champ (value) : Formule écrite selon le « type » donc en Jsonpath, Handlebars…
      • JSONPATH : Le Jsonpath est utilisé pour un mapping simple. Pour partir de la racine de l’entité, il faut commencer par « « $.businessEntity ». (Exemple : « $.businessEntity.reference »)
      • HANDLEBARS : Pour un mapping plus évolué, le format handlebars doit être utilisé.
        • Pour partir de la racine de l’entité métier, il faut commencer par « businessEntity » (Exemple : « {{#ifcontains businessEntity.reference ….»)
        • Pour une donnée issue de la GED, il suffit d’y faire référence directement.
      • CONSTANT : Pour appliquer une valeur constante à une donnée.

La documentation des entités métiers est disponible ici.

Données disponibles en sortie :

  • code, correspond au code http en réponse de la requête :
    • 201 : Mapping créé avec succès
    • 400 : Body invalide
    • 401 : Authentification manquante
    • 403 : Droits insuffisants pour exécuter cette requête
  • mapping : Rappel de l’objet Mapping en entrée avec l’id du mapping créé lors de cet appel.

Mutation updateMapping

Le droit pour cette opération est : « mettreAJourUnMappingAgentGED »
Cette opération permet à un administrateur de modifier un mapping existant.
En entrée et sortie de cette opération, les données sont similaires par rapport à la création de mapping avec comme différences :
En entrée :
  •  L’identifiant (id) du mapping à modifier est obligatoire.

En sortie :

  • code = 200 en cas de succès

Mutation deleteMapping

Le droit pour cette opération est « supprimerUnMappingAgentGED »

Cette opération permet à un administrateur de supprimer un mapping.

Donnée en entrée :

  • Identifiant du mapping à supprimer (id)

Donnée en sortie :

  • code, correspond au code http en réponse de la requête :
    • 204 : Mapping supprimé avec succès
    • 400 : Body invalide
    • 401 : Authentification manquante
    • 403 : Droits insuffisants pour exécuter cette requête

Opération de récupération du document sous forme binaire

Le droit pour cette opération est « recupererBinaireDocumentAgentGED »

Cet appel est un simple GET https sur une URL.

Pour constituer l’appel , il faut avoir au préalable récupérer l’attribut « file » de l’objet « documentEvent ».

https://{{fqdn}}/{{file}}

Cet appel renvoie le binaire du document et l’url complète sera de la forme :
https://{{fqdn}}/pda-semi-public-api/api/tenants/portaildesaides/agent-ged/documents/{{idDocument}}
Afin d’éviter des appels trop nombreux sur un laps de temps court, cette route est protégée par défaut par un « rate-limiting » avec les valeurs suivantes :
  • 50 requêtes maximum sur un laps de temps d’une minute
  • 25 requêtes simultanées au maximum