Accès aux méthodes Web Services RESTful (json)

Présentation

Il est possible d’accéder à iA.Délib via Web Services utilisant le standard RESTful. Pour cela, l’application iA.Délib doit être configurée pour accepter des requêtes « application/json ». Le package plonemeeting.restapi doit être configuré et installé.

Une fois le package installé, différentes méthodes peuvent être appelées :

Toutes ces méthodes ne sont accessibles que si l’appel au Web Service contient les informations de connexion d’un utilisateur iA.Délib. Si l’utilisateur n’est pas authentifié, l’erreur suivante est retournée :

{
        "message": "Missing 'plone.restapi: Use REST API' permission",
        "type": "Unauthorized",
}

Les différentes actions ne pourront être faites que si l’utilisateur renseigné dans l’authentification en a le droit dans iA.Délib…

Note

Les requêtes REST doit contenir le header « Accept: application/json »

Infos génériques (@infos GET)

Cette méthode permet de vérifier si les données de connexion renseignées pour accéder au Web Services sont correctes et d’obtenir des informations sur les versions installées.

Entrée :

include_stats : (uniquement si l’authentification renseignée est un « Manager », valeur « 0 » ou « 1 »)

Exemple :

http://url/@infos
  ?include_stats=0

Sortie :

{
  "connected_user": "dgen",
  "packages": {
    "Products.PloneMeeting": "4.2b1",
    "imio.restapi": "1.0a10",
    "plonemeeting.restapi": "1.0a2"
  },
  "stats": {}
}

Obtenir des informations sur la configuration (@config GET)

Cette méthode permet d’obtenir des informations concernant la configuration mise en place sur iA.Délib. Ceci permet de connaître notamment les identifiants à utiliser lors du passage de certains paramètres pour les méthodes de création de point, recherche de points, …

Entrée :

config_id : (obligatoire) l’identifiant de la configuration, par exemple « meeting-config-college »
fullobjects : (optionnel) par défaut, seules les informations principales (title, UID, id, …) de la configuration son retournées, ce paramètre permet de retourner la configuration complète (plus lent)
extra_include : (optionnel) permet d’inclure dans les informations retournées, certains éléments supplémentaires liés à cette configuration :
  • categories : retourne les catégories

  • classifiers : retourne les classificateurs

  • proposing_groups : retourne les groupes capable de créer des points

  • groups_in_charge : retourne les groupes en charge sélectionnables

  • associated_groups : retourne les groupes associés sélectionnables

  • searches : retourne les recherches (collections)

  • pod_templates : retourne les modèles de documents (POD templates)

Les éléments sont inclus dans la réponse dans des clés commençant par extra_include, par exemple extra_include_categories

extra_include_xxx_fullobjects : (optionnel) par défaut, seules les informations principales (title, UID, id, …) des éléments définis dans « extra_include » sont retournées, ce paramètre permet de recevoir les éléments complets (attention peut être beaucoup plus lent si beaucoup d’éléments sont retournés!). Les xxx sont à remplacer par le nom souhaité, par exemple extra_include_categories_fullobjects
Quelques paramètres utiles retournés dans la réponse :
  • usedItemAttributes : la listes des attributs (champs) optionnels activés sur les points

  • usedMeetingAttributes : la listes des attributs (champs) optionnels activés sur les séances

  • title : le titre de la configuration, par exemple « Collège communal » ou « Conseil d’administration »

Exemple :

http://url/@config
  ?config_id=meeting-config-college
  &extra_include=categories
  &extra_include=pod_templates
  &extra_include=searches
  &extra_include_fullobjects

Sortie :

{
  ...
  "@id": "http://url/portal_plonemeeting/meeting-config-college",
  "@type": "MeetingConfig",
  "UID": "91c96941dbe04108a105cc69ccfbbddc",
  ...
  "extra_include_categories": [
    {
      ...
      "@id": "http://url/portal_plonemeeting/meeting-config-college/categories/divers",
      "@type": "meetingcategory",
      "UID": "5fd3f8b83cd54d7f9da9c7a2c833684b",
      "enabled": true,
      "id": "divers",
      ...
    }
  ],
  "extra_include_pod_templates": [
    {
      ...
      "@id": "http://url/portal_plonemeeting/meeting-config-college/podtemplates/pv-pdf",
      "@type": "ConfigurablePODTemplate",
      "UID": "f7a5e2ae8b5645f9bb2412a4407c91b5",
      "enabled": true,
      "id": "pv-pdf",
      ...
      "odt_file": {
        "content-type": "application/vnd.oasis.opendocument.text",
        "download": "http://url/portal_plonemeeting/meeting-config-college/podtemplates/pv-pdf/@@download/odt_file",
        "filename": "pv.odt",
        "size": 34495
      },
      ...
      "pod_formats": [
        {
          "title": "LibreOffice Writer (.odt)",
          "token": "odt"
        }
      ],
      ...
    }
  ],
  "extra_include_searches": [
    {
      ...
      "@id": "http://url/portal_plonemeeting/meeting-config-college/searches/searches_items/searchmyitems",
      "@type": "DashboardCollection",
      "UID": "ef0410ffff1b41fab7f58fbfce7b7d54",
      "id": "searchmyitems",
      ...
      "query": [
        {
          "i": "Creator",
          "o": "plone.app.querystring.operation.string.currentUser"
        },
        {
          "i": "portal_type",
          "o": "plone.app.querystring.operation.selection.is",
          "v": [
            "MeetingItemCollege"
          ]
        },
        {
          "i": "review_state",
          "o": "plone.app.querystring.operation.selection.is",
          "v": [
            "delayed",
            "accepted"
          ]
        }
      ],
      ...
      "title": "Mes points",
      ...
    },
  ],
  ...
  "id": "meeting-config-college",
  ...
}

Obtenir des informations sur un utilisateur et la configuration qu’il peut utiliser (@users GET)

Cette méthode permet d’obtenir des informations concernant un utilisateur ou plusieurs utilisateurs ainsi que la configuration qu’il peut utiliser. Ceci permet de connaître notamment les identifiants à utiliser lors du passage de certains paramètres pour la méthode de création de point ou d’annexes. Les informations renvoyées sont adaptées à l’utilisateur mentionné.

Entrée :

query : (optionnel) utile lors de l’obtention d’informations pour plusieurs utilisateurs en une seule fois, passer les identifiants des utilisateurs souhaités. Pour obtenir des informations pour un seul utilisateur (cas le plus courant), l’identifiant est inclus dans l’URL lors de l’appel (voir exemples ci-dessous)`
extra_include : (optionnel) permet d’inclure dans les informations retournées, certains éléments de la configuration filtrés en fonction de l’utilisateur :
  • categories/classifiers : retourne les catégories/classificateurs utilisables par l’utilisateur, pour chacune des configurations de séance de l’application

    • extra_include_categories_configs/extra_include_classifiers_configs paramètre supplémentaire permettant d’obtenir les catégories/classificateurs pour une ou plusieurs configuration de séances

  • groups : retourne les groupes dont fait partie l’utilisateur (tout rôle confondu)

    • extra_include_groups_suffixes paramètre supplémentaire permettant d’obtenir les groupes pour un rôle spécifique de l’application, par exemple extra_include_groups_suffixes=creators ramènera les groupes pour lesquels l’utilisateur est « créateur »

  • configs : retourne les configurations de séances auxquelles a accès l’utilisateur

  • app_groups : retourne les groupes Plone de l’utilisateur (groupes techniques)

Les éléments sont inclus dans la réponse dans des clés commençant par extra_include, par exemple extra_include_categories

Exemple :

Obtenir les informations de base d’un utilisateur « agentInfo »:

http://url/@users/agentInfo

Sortie :

{
  "@id": "http://url/@users/agentInfo",
  "description": null,
  "email": "gauthier@imio.be",
  "fullname": "Agent Service Informatique",
  "home_page": null,
  "id": "agentInfo",
  "location": null,
  "portrait": null,
  "roles": [
      "Member",
      "MeetingObserverGlobal"
  ],
  "username": "agentInfo"
}

Exemple :

Obtenir les groupes pour lesquels un utilisateur est « créateur »:

http://url/@users/agentInfo
  ?extra_include=groups
  &extra_include_groups_suffixes=creators

Sortie :

{
  "@id": "http://url/@users/agentInfo",
  "description": null,
  "email": "gauthier@imio.be",
  "extra_include_groups": [
      {
          "@id": "http://url/contacts/plonegroup-organization/informatique",
          "@type": "organization",
          "UID": "7d5be335136c4173b7de3dbdc866514f",
          "created": "2018-10-25T08:41:13+00:00",
          "description": "",
          "enabled": null,
          "id": "informatique",
          "modified": "2020-10-26T08:32:50+00:00",
          "review_state": "active",
          "title": "Service informatique"
      }
  ],
  "extra_include_groups_items_total": 1,
  "fullname": "Agent Service Informatique",
  "home_page": null,
  "id": "agentInfo",
  "location": null,
  "portrait": null,
  "roles": [
      "Member",
      "MeetingObserverGlobal"
  ],
  "username": "agentInfo"
}

Exemple :

Obtenir les catégories utilisables par un utilisateur pour une configuration de séance donnée:

http://url/@users/agentInfo
  ?extra_include=categories
  &extra_include_categories_configs=meeting-config-college

Sortie :

{
  "@id": "http://url/@users/agentInfo",
  "description": null,
  "email": "gauthier@imio.be",
  "extra_include_categories": {
      "meeting-config-college": [
          {
              "@id": "http://url/portal_plonemeeting/meeting-config-college/categories/gestion",
              "@type": "meetingcategory",
              "UID": "7f5ebd71fc8b4aeea767d16fa5e8b7e2",
              "created": "2012-11-27T09:37:51+00:00",
              "description": "",
              "enabled": true,
              "id": "gestion",
              "modified": "2021-06-21T14:48:32+00:00",
              "review_state": null,
              "title": "Gestion parc informatique"
          },
          {
              "@id": "http://url/portal_plonemeeting/meeting-config-college/categories/infrastructure",
              "@type": "meetingcategory",
              "UID": "d066d46039214f529e2b8f9533763cf3",
              "created": "2012-11-27T09:37:51+00:00",
              "description": "",
              "enabled": true,
              "id": "infrastructure",
              "modified": "2021-08-26T09:36:37+00:00",
              "review_state": null,
              "title": "Infrastructure"
          },
          {
              "@id": "http://url/portal_plonemeeting/meeting-config-college/categories/logiciels",
              "@type": "meetingcategory",
              "UID": "c062934b970540e4bb1014d367a9d094",
              "created": "2012-11-27T09:37:51+00:00",
              "description": "",
              "enabled": true,
              "id": "logiciels",
              "modified": "2015-02-25T10:24:26+00:00",
              "review_state": null,
              "title": "Logiciels"
          }
      ]
  },
  "fullname": "Agent Service Informatique",
  "home_page": null,
  "id": "agentInfo",
  "location": null,
  "portrait": null,
  "roles": [
      "Member",
      "MeetingObserverGlobal"
  ],
  "username": "agentInfo"
}

Note

Les différents paramètres peuvent se cumuler pour obtenir en une seule requêtes, les groupes pour lesquels un utilisateur est créateur, les catégories utilisables par configuration de séances et les configurations auxquelles il a accès.

Rechercher des points ou séances (@search GET)

Permet d’effectuer une recherche dans les éléments de l’application. Lorsque le paramètre config_id est renseigné, la recherche de points et séances est facilitée.

Entrée :

config_id : (optionnel) l’identifiant de la configuration, par exemple « meeting-config-college » S’il est renseigné (conseillé), ceci facilite la recherche d’éléments « points » ou « séances », sinon, une recherche brute est effectuée sur base des indexes passés en paramètres. Ne pas renseigner « config_id » est utile uniquement pour effectuer des recherches d’autres éléments que « points » et « séances ».
type : (optionnel) le type d’élément à chercher, « item » (point) par défaut, peut être mis à « meeting » (séance). Si le paramètre « type » est renseigné, le paramètre *config_id* doit l’être également.
Critères de recherche : différents critères peuvent être utilisés, par exemple :
  • créateur (Creator)

  • titre (Title)

  • texte du point (SearchableText)

  • état WF du point (review_state)

  • identifiant de la catégorie (getCategory)

  • UID de la séance liée (linkedMeetingUID)

  • identifiant externe (externalIdentifier) : ce paramètre permet de passer un identifiant externe.  Lorsqu’un point est créé (Créer un point (@item POST)) par une application externe via ces Web Services, un “identifiant externe” peut être spécifié et permet dès lors de retrouver le point par la suite. Plusieurs points peuvent recevoir le même “identifiant externe”.

  • UID de l’élément (UID)

  • … N’importe quel index disponible dans le catalog.

extra_include : (optionnel) permet d’inclure dans la réponse des informations supplémentaires, dépendant du type d’élement recherché, voir Obtenir des informations sur un point (@item GET) ou Obtenir des informations sur une séance (@meeting GET)

Exemple :

http://url/@search
  ?config_id=meeting-config-college
  &Title=mon titre
  &getCategory=divers

Sortie :

Retourne les infos sur le point, les informations reçues sur un point via Rechercher des points ou séances (@search GET) sont équivalentes à celles retournées par la méthode Obtenir des informations sur un point (@item GET)

Exemple :

http://url/@search
  ?portal_type=organization
  &Title=finances

Sortie :

Retourne toutes les organisations dont le titre contient le mot « finances »

Optimiser les données retournées pour les points lors d’un GET avec fullobjects (@item GET, @search GET)

Par défaut, lors de l’utilisation de fullobjects, l’objet complet est retourné ce qui prend du temps:

  • côté iA.Délib car la sérialisation de l’élément est plus longue

  • côté appelant car la quantité de données est plus importante.

Paramètres pour limiter les données reçues :

fullobjects : passer fullobjects ou fullobjects=true permet de passer en mode « obtenir les données non indexées disponibles ». Si seules des données indexées sont nécessaires, ne pas passer fullobjects.

Paramètres supplémentaires lorsque fullobjects=true :

  • include_all : avec fullobjects toutes les données possibles sont ramenées. Passer include_all=false permet de sélectionner ce qu’on veut recevoir. Lors d’un include_all=false, include_base_data est la seule valeur à true par défaut (voir ci-dessous).

  • include_base_data : par défaut, des données minimales de base (UID, id, title, created, modified, …) sont retournées, elles sont immédiatement disponibles côté iA.Délib donc ne coûte rien à ajouter, mais si elles ne sont pas nécessaire, passer include_base_data=false permet de ne pas les retourner.

Paramètres utilisables avec et sans fullobjects=true :

  • metadata_fields : permet de spécifier les données supplémentaires à obtenir. Soit une metadonnées indexée si fullobjects n’est pas passé, soit n’importe quelle donnée disponible.

  • extra_include : le paramètre fullobjects peut être passé à un extra_include sous la forme extra_include_xxxnamexxx_xxxparamterxxx, donc par exemple extra_include_category_fullobjects=true&extra_include_category_include_all=false.

Exemple :

Imaginons un cas où on souhaite obtenir les données de base du point, en plus le champ decision ainsi que la description de la catégorie du point.

http://url/@item
  ?UID=an_item_uid
  &fullobjects
  &include_all=false
  &metadata_fields=decision
  &extra_include=category
  &extra_include_category_fullobjects
  &extra_include_category_include_all=false
  &extra_include_category_include_base_data=false
  &extra_include_category_metadata_fields=description

Sortie :

{
  "@id": "http://url/Members/dgen/mymeetings/meeting-config-college/point",
  "@type": "MeetingItemCollege",
  "UID": "57290ed333d34e4c998c92232c81856e",
  "created": "2021-03-11T11:55:37+00:00",
  "decision": {
      "content-type": "text/plain",
      "data": "<p>Ma décision.</p>"
  },
  "extra_include_category": {
      "description": ""
  },
  "id": "copy16_of_recurringagenda1",
  "is_folderish": true,
  "modified": "2021-08-09T08:14:49+00:00",
  "review_state": "accepted",
  "title": "Approuve le procès-verbal de la séance antérieure"
}

Exemple :

On peut même pousser l’optimisation en ne récupérant pas les données de base du point (include_base_data=false). Imaginons un cas où on souhaite obtenir seulement la décision et la catégorie du point, et la description du classificateur.

http://url/@item
  ?UID=an_item_uid
  &fullobjects
  &include_all=false
  &include_base_data=false
  &metadata_fields=category
  &metadata_fields=decision
  &extra_include=classifier
  &extra_include_classifier_fullobjects
  &extra_include_classifier_include_all=false
  &extra_include_classifier_include_base_data=false
  &extra_include_classifier_metadata_fields=description

Sortie :

{
  "category": {
      "title": "Travaux",
      "token": "travaux"
  },
  "decision": {
      "content-type": "text/plain",
      "data": "<p>Ma décision.</p>"
  },
  "extra_include_classifier": {
      "description": "Description de mon classificateur"
  }
}

Note

Pour obtenir une query efficace:

  • utiliser un outil tel que postman (https://www.postman.com/) afin de tester quels paramètres devront être passés

  • dans un premier temps, passer le paramètre fullobjects pour obtenir toutes les informations disponibles et vérifier les extra_include disponibles dans la clé @extra_includes

  • finalement, utiliser les paramètres include_all=false et metadata_fields pour obtenir la réponse la plus petite possible.

Aussi bien du côté de l’application appelante que de l’application appelée, un meilleur temps de réponse est un avantage.

Obtenir les annexes d’un élément (point, avis, séance) (@annexes GET)

Permet d’obtenir les annexes liées à un élément. L’appel à @annexes sur un élément retourne une liste des annexes que l’utilisateur connecté va pouvoir récupérer.

Exemple :

a) Première étape, trouver l’élément :

http://url/@item
  ?UID=uid_du_point

Sortie :

{
  "@components": {
    ...
    "annexes": {
      "@id": "http://url/Members/dgen/mymeetings/meeting-config-college/point/@annexes"
    },
    ...
  },
  "@id": "http://url/Members/dgen/mymeetings/meeting-config-college/point",
  "@type": "MeetingItemCollege",
  "UID": "1aa4f934a7d84b7fbc332273cb6dbf3a",
  ...
}

Ceci ramène une partie @components avec un lien vers le endpoint @annexes

Exemple :

b) Seconde étape, appeler l’url @annexes :

http://url/Members/dgen/mymeetings/meeting-config-college/point/@annexes

Sortie :

[
  {
    ...
    "@id": "http://url/Members/dgen/mymeetings/meeting-config-college/point/file.pdf",
    "@type": "annex",
    "UID": "2b22717d0ddb4fcf9e1ac5402e489899",
    ...
    "category_id": "annexe",
    "category_title": "Annexe",
    "category_uid": "c7b6ee927bab43d196596e8387fac14d",
    "confidential": false,
    ...
    "file": {
      "content-type": "text/plain",
      "download": "http://url/Members/dgen/mymeetings/meeting-config-college/gna-1-96/file.pdf/@@download/file",
      "filename": "file.txt",
      "size": 6
    },
    "filesize": 6,
    "id": "file.pdf",
    ...
  },
  ...
]

Une requête HTTP vers l’URL download de file permet de récupérer l’annexe.

Obtenir un document généré (@pod-templates GET)

Permet d’obtenir les documents qui peuvent être généré sur un élément donné. L’appel à @pod-templates sur un élément retourne une liste des documents que l’utilisateur connecté va pouvoir générer.

Exemple :

a) Première étape, trouver l’élément :

http://url/@item
  ?UID=uid_du_point

Sortie :

{
  "@components": {
    ...
    "pod-templates": {
      "@id": "http://url/Members/dgen/mymeetings/meeting-config-college/point/@pod-templates"
    },
    ...
  },
  "@id": "http://url/Members/dgen/mymeetings/meeting-config-college/point",
  "@type": "MeetingItemCollege",
  "UID": "1aa4f934a7d84b7fbc332273cb6dbf3a",
  ...
}

Ceci ramène une partie @components avec un lien vers le endpoint @pod-templates

Exemple :

b) Seconde étape, appeler l’URL @pod-templates :

http://url/Members/dgen/mymeetings/meeting-config-college/point/@pod-templates

Sortie :

[
  {
    ...
    "@id": "http://url/portal_plonemeeting/meeting-config-college/podtemplates/deliberation",
    "@relative_path": "/portal_plonemeeting/meeting-config-college/podtemplates/deliberation",
    "@type": "ConfigurablePODTemplate",
    "UID": "9d73acf025f74079bd3550ce61a617ef",
    ...
    "enabled": true,
    "generate_url_doc": "http://url/Members/dgen/mymeetings/meeting-config-college/point/document-generation?template_uid=9d73acf025f74079bd3550ce61a617ef&output_format=doc",
    "generate_url_odt": "http://url/Members/dgen/mymeetings/meeting-config-college/point/document-generation?template_uid=9d73acf025f74079bd3550ce61a617ef&output_format=odt",
    "generate_url_pdf": "http://url/Members/dgen/mymeetings/meeting-config-college/point/document-generation?template_uid=9d73acf025f74079bd3550ce61a617ef&output_format=pdf",
    "id": "deliberation",
    ...
  }
  ...
]

Une requête HTTP vers les URi generate_url_doc ou generate_url_pdf permet de récupérer le document généré.

Liste des séances acceptant des points (@search GET)

Cette méthode permet d’obtenir la liste des séances qui acceptent des points. Il s’agit du endpoint @search GET auquel un paramètre supplémentaire est passé.

Entrée :

config_id : (obligatoire) l’identifiant d’une Configuration de séance.
type : (obligatoire) renseigner « meeting », sinon une recherche (@search GET) s’effectue sur des points.
meetings_accepting_items : (obligatoire) renseigner « true ».

Exemple :

http://url/@search
  ?config_id=meeting-config-college
  &type=meeting
  &meetings_accepting_items=true

Sortie :

{
  "@id": "http://url/@search?config_id=meeting-config-college&type=meeting&meetings_accepting_items=true",
  ...
  "items": [
    {
      "@id": "http://url/Members/dgen/mymeetings/meeting-config-college/meetingcollege3",
      "@type": "MeetingCollege",
      "UID": "18504dcf3d3c4ae2af1fe810c2919b84",
      "description": "",
      "review_state": "created",
      "title": "15 septembre 2020"
    },
    {
      "@id": "http://url/Members/dgen/mymeetings/meeting-config-college/meetingcollege2",
      "@type": "MeetingCollege",
      "UID": "fd8534e2f76d45edb97e7f24b0198136",
      "description": "",
      "review_state": "frozen",
      "title": "15 août 2020"
    },
    {
      "@id": "http://url/Members/dgen/mymeetings/meeting-config-college/meetingcollege1",
      "@type": "MeetingCollege",
      "UID": "8e1c873a79a14343b7b472b5da7ecb24",
      "description": "",
      "review_state": "decided",
      "title": "15 juillet 2020"
    },
    ...
  ],
  "items_total": 3
}

Obtenir des informations sur un élément (@get GET)

Cette méthode permet d’obtenir des informations sur n’importe quel élément pourvu qu’on ai son UID. S’il s’agit d’un point, utilisez le endpoint @item GET (Obtenir des informations sur un point (@item GET)), s’il s’agit d’une séance, utilisez le endpoint @meeting GET (Obtenir des informations sur une séance (@meeting GET))

Note

Ce endpoint ramène l’information sommaire d’un élément (titre, url, UID, …) par défaut, si vous avez besoin de plus d’informations, il faudra passer le paramètre « fullobjects » ou des « extra_include », voir @search GET (Rechercher des points ou séances (@search GET)).

Entrée :

UID : (obligatoire) l’identifiant universel de l’élément.

Exemple (en utilisant l’UID d’une annexe) :

http://url/@get
  ?UID=uid_of_an_annex
  &fullobjects

Sortie :

{
  "@components": {...},
  "@id": "http://url/Members/dgen/mymeetings/meeting-config-college/point/annexe.pdf",
  "@type": "annex",
  "UID": "1cf7b06c476f4acb8e68792a8dc7670b",
  ...
  "category_id": "annexe",
  "category_title": "Annexe",
  "category_uid": "c7b6ee927bab43d196596e8387fac14d",
  "confidential": false,
  ...
  "description": "",
  "file": {
      "content-type": "application/pdf",
      "download": "http://url/Members/dgen/mymeetings/meeting-config-college/point/annexe.pdf/@@download/file",
      "filename": "annexe.pdf",
      "size": 48538
  },
  "filesize": 48538,
  ...
  "portal_type": "annex",
  "publishable": false,
  "signed": false,
  "title": "Annexe num 1",
  "to_print": false,
  "to_sign": false,
}

Obtenir des informations sur un point (@item GET)

Cette méthode, basée sur Obtenir des informations sur un élément (@get GET) permet d’obtenir des informations sur un point. À utiliser si on connaît l’UID du point pour lequel on souhaite des informations. On connaît l’UID d’un point si on a créé ce point (Créer un point (@item POST)) via des Web Services ou lors d’une recherche de points (Rechercher des points ou séances (@search GET))

Entrée :

UID : (obligatoire) l’identifiant universel du point.
extra_include : (optionnel) permet d’inclure dans les informations retournées, certains éléments supplémentaires liés à ce point lorsque les données de base ne suffisent pas :
  • category : retourne les détails sur la catégorie utilisée (sans cela, seul l’identifiant et le titre de la catégorie sont retournés)

  • classifier : retourne les détails sur le classificateur utilisé (sans cela, seul l’identifiant et le titre du classificateur sont retournés)

  • groups_in_charge : retourne les détails sur les groupes en charge (sans cela, seul l’identifiant et le titre des groupes en charge sont retournés)

  • associated_groups : retourne les détails sur les groupes associés (sans cela, seul l’identifiant et le titre des groupes associés sont retournés)

  • proposing_group : retourne les détails sur le groupe (organisation) utilisé (sans cela, seul l’identifiant et le titre de l’organisation sont retournés)

  • deliberation : retourne les versions du XHTML utilisés pour générer la délibération (incluant avis du Directeur financier, …)

  • meeting : retourne les détails concernant la séance dans laquelle est présenté le point (si c’est le cas), notamment la date formattée de différentes manière dans les valeurs formatted_date/formatted_date_long/formatted_date_short

  • pod_templates : retourne les modèles de documents (POD templates) qui peuvent être générés sur le point. Ceci peut être utilisé à la place de Obtenir un document généré (@pod-templates GET) afin de n’effectuer qu’une seule requête. Si les POD templates ne sont pas utiles, un second appel vers @pod-templates est recommandé et permet de les obtenir lorsque c’est nécessaire.

  • annexes : retourne les annexes du point. Comme pour les POD templates ci-dessus, ceci évite de faire 2 requêtes si les annexes doivent être utilisées directement. Sinon, un second appel vers @annexes (voir Obtenir les annexes d’un élément (point, avis, séance) (@annexes GET)) permet d’obtenir les annexes par la suite

  • linked_items: retourne les points liés. Les points liés sont de 2 types « auto » ou « manual », les liens « auto » sont gérés par l’application (point reporté, point Collège envoyé au Conseil, …), les liens « manual » représentent les points liés entre eux par l’utilisateur.

    • il est possible d’obtenir différents types de points liés via le paramètre extra_include_linked_items_mode:

      • auto (par défaut): ramène tous les points liés automatiquement par l’application, les points « précédents » et les points « suivants » le point en cours;

      • manual: ramène les points liés manuellement au point en cours;

      • predecessor: ramène le point « précédent » immédiat;

      • predecessors: ramène tous les points « précédents »;

      • sucessors: ramène tous les points « suivants » immédiats (souvent il n’y en a qu’un seul);

      • every_successors: ramène tous les points « suivants ».

    • il est possible de filtrer les points liés sur base de n’importe quel attribut stocké en passant le paramètre extra_include_linked_items_filter en séparant clé et valeur par un | :

      • extra_include_linked_items_filter=portal_type|MeetingItemCouncil ramène seulement les points « Conseil communal »;

      • extra_include_linked_items_filter=query_state|accepted ramène seulement les points dans l’état « Accepté ».

    • des paramètres peuvent être passés pour le rendu des points liés en utilisant la technique habituelle: préfixer le paramètre par extra_include_linked_items_XXX par exemple pour inclure le détail du groupe proposant, passer le paramètre extra_include_linked_items_extra_include=proposing_group ou pour obtenir la version « complète » des points liés (par défaut la version « sommaire » des points liés est retournée), passer le paramètre extra_include_linked_items_fullobjects.

Exemple :

http://url/@item
  ?UID=an_item_uid
  &fullobjects
  &extra_include=category
  &extra_include=meeting
  &extra_include=pod_templates

Sortie :

{
  ...
  "@id": "http://url/point",
  "@type": "MeetingItemCollege",
  "UID": "1aa4f934a7d84b7fbc332273cb6dbf3a",
  "all_copyGroups": [
    "2b63aa6b03dd402f90fc1db527bd0bba_reviewers"
  ],
  "all_groupsInCharge": [
    "2b63aa6b03dd402f90fc1db527bd0bba"
  ],
  ...
  "budgetInfos": {
    "content-type": "text/html",
    "data": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>"
  },
  "budgetRelated": true,
  "category": {
      "title": "Divers",
      "token": "divers"
  },
  "classifier": {
      "title": "Mon classificateur",
      "token": "mon-classificateur"
  },
  ...
  "decision": {
    "content-type": "text/html",
    "data": "<p>Ma décision en français...</p>"
  },
  "description": {
    "content-type": "text/html",
    "data": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>"
  },
  ...
  "extra_include_category": {
    ...
    "@id": "http://url/portal_plonemeeting/meeting-config-college/categories/divers",
    ...
    "@type": "meetingcategory",
    "UID": "835a00d253c943b98e3396ed994e4a48",
    "category_id": "divers category id",
    ...
    "enabled": true,
    "groups_in_charge": [],
    "id": "divers",
    ...
    "title": "Divers",
  },
  "extra_include_meeting": {
      ...
      "@id": "http://url/meetingcollege.2019-11-29.8538486961",
      "@type": "MeetingCollege",
      "UID": "bb326792b99a4463af93e79061ee539b",
      ...
      "date": "2019-11-30T03:00:00+00:00",
      ...
      "extraordinarySession": false,
      "firstItemNumber": -1,
      ...
      "formatted_date": "30/11/2019 (04:00)",
      "formatted_date_long": "30 novembre 2019 (04:00)",
      "formatted_date_short": "30/11/2019",
      "id": "meetingcollege.2019-11-29.8538486961",
  },
  "extra_include_pod_templates": [
  {
      "@extra_includes": [],
      "@id": "http://url/config/deliberation",
      "@type": "ConfigurablePODTemplate",
      "UID": "123",
      ...
      "id": "deliberation",
      "outputs": [
      {
       "format": "odt",
       "url": "http://url/point/document-generation?template_uid=123&output_format=odt"
      },
      {
       "format": "doc",
       "url": "http://url/point/document-generation?template_uid=123&output_format=doc"
      },
      {
       "format": "pdf",
       "url": "http://url/point/document-generation?template_uid=123&output_format=pdf"
      } ],
      "title": "Délibération"
  }],
  ...
  "id": "point",
  "formatted_itemNumber": "1",
  ...
}

Créer un point (@item POST)

Cette méthode permet de créer un nouveau point dans iA.Délib.

Entrée :

config_id : (obligatoire) l’identifiant de la configuration de séance dans laquelle créer le point.
proposingGroup : (obligatoire) l’identifiant du groupe proposant avec lequel créer le point (identifiant ou UID).
title : (obligatoire) l’objet du point.

Des données optionnelles peuvent être renseignées si activées :

  • category : l’identifiant de la catégorie.

  • classifier : l’identifiant du classificateur.

  • committees : les identifiants des commissions.

  • description : la description du point (XHTML).

  • motivation : la motivation du point (XHTML).

  • decision : la décision du point (XHTML).

  • associatedGroups : liste des identifiants ou UIDs des groupes associés.

  • copyGroups : liste des identifiants des sous-groupes (créateurs, validateurs, …) en copie.

  • groupsInCharge : liste des identifiants ou UIDs des groupes en charge.

  • optionalAdvisers : liste des identifiants ou UIDs des groupes devant remettre un avis.

  • preferredMeeting : UID de la séance souhaitée, dans la Liste des séances acceptant des points (@search GET).

  • externalIdentifier : identifiant externe, permet à une application externe d’inclure son propre identifiant lors de la création du point et d’utiliser cet identifiant externe pour retrouver le point.

  • in_name_of : créer le point “au nom d’un utilisateur”. Nécessite d’être connecté en tant que “Manager/MeetingManager” au Web Services.

  • : n’importe quelle zone disponible sur le point.

Note

Un nettoyage est appliqué sur le contenu des champs XHTML lors de la création de l’élément. Si ce nettoyage pose problème, il est possible de le désactiver en passant "clean_html": false.

Si l’élément a été créé, une version JSON du point créé est retournée. L’information UID pourra être stockée par la procédure appelante afin de pouvoir retrouver le point par la suite. Si la procédure appelante ne souhaite pas stocker cet UID, un “identifiant externe (externalIdentifier)” peut être passé lors de la création du point.

Des annexes peuvent être ajoutées lors de la création du point, ceci se passe via la clé __children__. Le contenu du fichier peut être inclus tel quel s’il s’agit d’un fichier non binaire ou en base64 s’il s’agit d’un fichier binaire (par défaut). Le fichier encodé en base64 fonctionnera dans tous les cas, qu’il s’agisse d’un fichier binaire ou non. La clé content_category permet de renseigner le type d’annexe, si non renseigné, le type d’annexe par défaut sera utilisé.

Des transitions de workflow peuvent être déclenchée sur le point afin de le mettre dans un autre état que l’état initial par défaut « en création ». Les transitions successives seront définies dans la clé wf_transitions. Lors de cette succession de transitions, si une n’existe pas, elle est ignorée. La suite de transitions pour présenter un point dans une séance peut être trouvée dans la configuration, onglet « Workflows » dans le paramètre « Succession de transitions à effectuer pour présenter un point: »

Exemple :

http://url/@item
Body

{
    "config_id": "meeting-config-college",
    "proposingGroup": "direction-generale",
    "title": "Mon point",
    "category": "ma-categorie",
    "classifier": "mon-classificateur",
    "description": "<p>Ma description.</p>",
    "motivation": "<p>Ma motivation.</p>",
    "decision": "<p>Ma décision.</p>",
    "wf_transitions": ["propose", "validate"],
    "__children__": [
        {
         "@type": "annex",
         "title": "My annex 1",
         "content_category": "item-annex",
         "file": {
                  "data": "123456",
                  "encoding": "ascii",
                  "filename": "file.txt"
                 },
        },
        {
         "@type": "annex",
         "title": "My annex 2",
         "content_category": "item-annex",
         "file": {
                  "data": base64_pdf_data,
                  "filename": "file.pdf"
                 },
        },
    ]
}

Sortie :

Si des zones obligatoires ne sont pas renseignées, des erreurs sont retournées :

{
  "message": "[
    {'field': 'category',
     'message': u'Veuillez sélectionner une catégorie.',
     'error': 'ValidationError'},
    {'field': 'groupsInCharge',
     'message': u'Veuillez sélectionner un groupe en charge.',
     'error': 'ValidationError'},
    {'field': 'classifier',
     'message': u'Veuillez sélectionner un classificateur.',
     'error': 'ValidationError'}]",
  "type": "BadRequest"
}

Même chose si un champ est renseignée mais pas activé dans la configuration :

{
  "message": "The optional field \"motivation\" is not activated in this configuration!",
  "type": "BadRequest"
}

Note

Il est possible d’ignorer les erreurs retournées en passant les paramètres suivants:

  • ignore_not_used_data=true permet d’ignorer les erreurs concernant des champs non activés. Dans ce cas les données sont ignorées et les champs laissés vides;

  • ignore_validation_for=["category", "classifier"] permet d’ignorer la validation pour certains champs, les champs sont laissés vides mais la création du point n’est pas empêchée. Les données devront être complétées par la suite.

Si l’élément a été créé, une version JSON du point créé est retournée. L’information UID pourra être stockée par la procédure appelante afin de pouvoir retrouver le point par la suite. Si la procédure appelante ne souhaite pas stocker cet UID, un “identifiant externe (externalIdentifier)” peut être passé lors de la création du point.

{
  ...
  "@id": "http://url/Members/dgen/mymeetings/meeting-config-college/mon-point",
  "@type": "MeetingItemCollege",
  "@warnings": [],
  "UID": "0fc7dd8abb9c47aaaa3db8540aae09b7",
  "__children__": [
    {
      ...
      "@id": "http://localhost:8081/mc30b/Members/dgen/mymeetings/meeting-config-college/mon-point/file.txt",
      "@type": "annexe",
      "@warnings": [],
      "UID": "91a1dcb2e30a42818e551a8ec85eb04b",
      ...
      "category_id": "annexe",
      "category_title": "Annexe",
      "category_uid": "c7b6ee927bab43d196596e8387fac14d",
      ...
      "file": {
        "content-type": "text/plain",
        "download": "http://localhost:8081/mc30b/Members/dgen/mymeetings/meeting-config-college/mon-point/file.txt/@@download/file",
        "filename": "file.txt",
        "size": 6
      },
      "filesize": 6,
      "id": "file.txt",
      ...
      "portal_type": "annex",
      ...
    }
  ],
  "all_copyGroups": [
    "2b63aa6b03dd402f90fc1db527bd0bba_reviewers"
  ],
  "all_groupsInCharge": [
    "b2e2ee6592634b36a5f4495cf82f9a44"
  ],
  ...
  "category": {
      "title": "Ma catégorie",
      "token": "ma-categorie"
  },
  "classifier": {
      "title": "Mon classificateur",
      "token": "mon-classificateur"
  },
  ...
  "decision": {
    "content-type": "text/plain",
    "data": "<p>Ma décision.</p>"
  ...
  "id": "mon-point",
  "review_state": "validated",
  ...
}

Ajouter une annexe à un élément existant (@annex POST)

Cette méthode permet d’ajouter une annexe sur un élément existant et acceptant des annexes (point, séance, avis) si on connait son UID. L’UID est passé dans l’URL tandis que les informations concernant l’annexe à ajouter sont passées dans le Body.

Entrée :

title : (optionnel) le titre de l’annexe, si non renseigné, le nom du fichier (« mon-fichier.pdf » par exemple) sera utilisé.
content_category : (optionnel) l’identifiant du type d’annexe à utiliser, si non renseigné, le type d’annexe par défaut sera utilisé.
decision_related : (optionnel), si mis à true, une « Annexe (après décision) » est ajoutée mais uniquement si l’élément sur lequel est ajoutée l’annexe est un « Point ».

Exemple :

http://url/@annex/UID
Body

{
  "title": "My new annex",
  "content_category": "item-annex",
  "file": {
      "data": "123456",
      "encoding": "ascii",
      "filename": "file.txt"
      }
}

Sortie :

Réponse avec statut 201 Created

{
  "@id": "http://url/file.txt",
  "@type": "annex",
  "@warnings": [],
  "UID": "323f36a40c864035909ee74df6178f04",
  "content_category": {
      "title": "Annexe",
      "token": "config_id-annexes_types_-_item_annexes_-_item-annexe"
  },
  ...
}

Obtenir des informations sur une séance (@meeting GET)

Cette méthode, basée sur Obtenir des informations sur un élément (@get GET) permet d’obtenir des informations sur une séance. À utiliser si on connaît l’UID de la séance pour laquelle on souhaite des informations. On connaît l’UID d’une séance si on a créé cette séance (Créer une séance (@meeting POST)) via des Web Services ou lors d’une recherche de points (Rechercher des points ou séances (@search GET)) et l’utilisation de extra_include=meeting.

Entrée :

UID : (obligatoire) l’identifiant universel de la séance.
extra_include : (optionnel) permet d’inclure dans les informations retournées, certains éléments supplémentaires liés à cette séance lorsque les données de base ne suffisent pas :
  • pod_templates : retourne les modèles de documents (POD templates) qui peuvent être générés sur la séance. Ceci peut être utilisé à la place de Obtenir un document généré (@pod-templates GET) afin de n’effectuer qu’une seule requête. Si les POD templates ne sont pas utiles, un second appel vers @pod-templates est recommandé et permet de les obtenir lorsque c’est nécessaire.

  • annexes : retourne les annexes de la séance. Comme pour les POD templates ci-dessus, ceci évite de faire 2 requêtes si les annexes doivent être utilisées directement. Sinon, un second appel vers @annexes (voir Obtenir les annexes d’un élément (point, avis, séance) (@annexes GET)) permet d’obtenir les annexes par la suite.

Exemple :

http://url/@meeting
  ?UID=a_meeting_uid
  &extra_include=annexes

Sortie :

{
  "@extra_includes": [
      "annexes",
      "pod_templates"
  ],
  "@id": "http://url/20220121",
  "@type": "MeetingCouncil",
  "UID": "a_meeting_uid",
  "description": "",
  "extra_include_annexes": [
      {
          "@extra_includes": [],
          "@id": "http://url/20220121/annex1.pdf",
          "@type": "annex",
          "UID": "annex1_uid",
          ...
          "file": {
              "content-type": "application/pdf",
              "download": "http://url/20220121/annex1.pdf/@@download/file",
              "filename": "annex1.pdf",
              "size": 92099
          },
          "title": "Annex 1"
      },
      {
          "@extra_includes": [],
          "@id": "http://url/20220121/annex2.pdf",
          "@type": "annex",
          "UID": "annex2_uid",
          ...
          "title": "Annex 2"
      },
  ],
  "id": "20220121",
  ...
  "review_state": "decided",
  "title": "21 janvier 2022 (17:30)"
}

Créer une séance (@meeting POST)

Cette méthode permet de créer une nouvelle séance dans iA.Délib.

Entrée :

config_id : (obligatoire) l’identifiant de la configuration de séance dans laquelle créer le point.
date : (obligatoire) la date de la séance.

Des données optionnelles peuvent être renseignées si activées :

  • start_date : la date de début de séance.

  • end_date : la date de fin de séance.

  • place/place_other : le lieu si configuré dans iA.Délib.

  • videoconference : un booléen spécifiant si la séance se fera en visioconférence.

  • observations : des observations sur la séance (XHTML).

  • : n’importe quelle zone disponible sur la séance.

Note

Un nettoyage est appliqué sur le contenu des champs XHTML lors de la création de l’élément. Si ce nettoyage pose problème, il est possible de le désactiver en passant "clean_html": false.

Des annexes peuvent être ajoutées lors de la création de la séance, ceci se passe via la clé __children__, voir exemple sur Créer un point (@item POST).

Exemple :

http://url/@meeting
Body

{
  "config_id": "meeting-config-college",
  "date": "2021-12-12 12:00",
  "observations": "<p>Mes observations.</p>"
}

Sortie :

Si des zones obligatoires ne sont pas renseignées, des erreurs sont retournées :

{
  "message": "[{'field': 'date', 'message': u'Required input is missing.', 'error': 'ValidationError'}]",
  "type": "BadRequest"
}

Mettre à jour un élément (@content PATCH)

Cette méthode permet de mettre à jour une donnée d’un élément déjà existant si on connaît son UID. L’UID est passé lors de l’appel au endpoint @content dans l’URL.

Exemple :

http://url/@content/UID
Body

{
    "title": "Mon nouveau titre",
    "category": "nouvelle-categorie"
}

Sortie :

Réponse avec statut 204 No content

Changer l’état d’un élément (@wf POST)

Cette méthode permet de changer l’état d’un élément déjà existant si on connaît son UID. L’UID ainsi que l’identifiant de la transition sont passés lors de l’appel au endpoint @wf dans l’URL.

Exemple :

http://url/@wf/UID/transition_name
Body

{
    "comment": "Commentaire lors de la transition"
}

Sortie :

Réponse avec statut 200 OK