Accès aux méthodes Web Services SOAP/WSDL (xml)

Avertissement

Les WS SOAP sont dépréciés, veuillez utiliser les Web Services RESTful (json) qui proposent plus de fonctionnalités et sont plus performants.

Présentation

Il est possible d’accéder à iA.Délib via Web Services utilisant le standard SOAP/WSDL.

Pour cela, l’application iA.Délib doit être configurée pour accepter des connexions entrantes (appels aux méthodes publiées) et publier un descriptif WSDL d’accès à ces méthodes.  Techniquement, le package imio.pm.ws doit être configuré et installé.

Une fois le package installé, le fichier WSDL (ws4pm.wsdl) est disponible et décrit l’accès aux méthodes suivantes :

  • test de connexion (testConnection) : permet de tester si le paramètres d’identification renseigné (nom d’utilisateur/mot de passe) sont corrects

  • obtention d’informations sur la configuration (getConfigInfos) : retourne différentes informations sur la configuration utilisée

  • obtention d’informations sur un utilisateur (getUserInfos) : retourne des informations concernant l’accès de cet utilisateur

  • obtention d’informations sur un point (getItemInfos) : retourne des informations pour un point en particulier

  • recherche de points (searchItems) : effectue une recherche de points

  • savoir si un élément a déjà été envoyé (checkIsLinked) : permet de savoir si un élément à déjà été créé

  • obtenir un document généré (getItemTemplate) : permet de déclencher la production d’un document dans iA.Délib

  • créer un point (createItem): permet de créer un point dans iA.Délib

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. Les différentes actions ne pourront être faites que si l’utilisateur renseigné dans l’authentification en a le droit dans iA.Délib…

Test de connexion (testConnection)

Cette méthode permet de vérifier si les données de connexion renseignées pour accéder au Web Services sont correctes.

Paramètres d’entrées :

Aucun

Sortie :

Retourne “1” si la connexion a pu être établie, “0” sinon.  Retourne également dans “version”, la version des WS

Obtention d’informations sur la configuration (getConfigInfos)

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, … …

Paramètres d’entrées :

showCategories : (obligatoire) “1” pour montrer les catégories et “0” pour ne pas les montrer.  En fonction de la configuration, la catégorie utilisée pour un point est soit le groupe proposant, soit une catégorie supplémentaire.  Si les catégories supplémentaires sont utilisées, elles seront affichées, sinon, rien ne sera affiché au niveau des catégories.  Si les catégories sont utilisées/affichées, le passage de l’identifiant de la catégorie à utiliser est obligatoire lors de la création d’un point.
userToShowCategoriesFor : (optionnel) dans iA.Délib, certaines catégories peuvent être restreintes à certains groupes d’utilisateurs.  Pour être sûr qu’un utilisateur peut utiliser une catégorie donnée, on peut passer “l’identifiant de cet utilisteur” à la méthode pour retourner la liste exhaustive que l’utilisateur peut effectivement utiliser.

Sortie :

Retourne la liste des Configuration de séances (MeetingConfig), des organisations iA.Délib (organization) et des catégories (categories) si le paramètre “showCategories” était à “1” lors de l’appel et si elles sont effectivement utilisées par la Configuration de séance.

Obtention d’informations sur un utilisateur (getUserInfos)

Cette méthode permet d’obtenir des informations sur un utilisateur.

Paramètres d’entrées :

userId : (obligatoire) l’identifiant de l’utilisateur.
showGroups : (obligatoire) montrer les groupes iA.Délib auxquels l’utilisateur appartient (tous “sous-groupes Plone” confondus).  “1” pour montrer les groupes et “0” pour ne pas les montrer.
suffix : (optionnel) paramètre utilisé conjointement avec le paramètre “showGroups” à “1”.  Le suffixe d’un “sous-groupe Plone” doit être renseigné.  Les groupes retournés pour l’utilisateur seront ceux pour lesquels l’utilisateur est dans le sous-groupe mentionné.
Les suffixes par défaut sont :
  • creators : retourne les groupes pour lesquels l’utilisteur est un créateur de points

  • reviewers : retourne les groupes pour lesquels l’utilisateur est un validateur de points

  • advisers : retourne les groupes pour lesquels l’utilisateur est un donneur d’avis

D’autres suffixes peuvent exister en fonction de la configuration spécifique de iA.Délib

Sortie :

Retourne les infos sur l’utilisateur : “Nom complet” et “Adresse e-mail”.  Si “showGroups” était à “1”, retourne également la liste des groupes iA.Délib (MeetingGroup) adéquats.

Obtention d’informations sur un point (getItemInfos)

Cette méthode permet d’obtenir des informations sur un point.  A 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 (createItem)) via des Web Services ou lors d’une recherche de points (Recherche de points (searchItems))

Paramètres d’entrées :

UID : (obligatoire) l’identifiant universel du point.
showExtraInfos : (obligatoire) valeur à “0” ou “1”.  Montre d’avantages d’informations concernant le point.  Laisser à “0” si ces informations supplémentaires ne sont pas nécessaires.
showAnnexes : (obligatoire) valeur à “0” ou “1”.  Montre les annexes du point.  Laisser à “0” si pas nécessaire car les fichiers annexes retournés peuvent ralentir la réponse en fonction de la taille de ceux-ci…
include_annex_binary : (obligatoire) valeur à “0” ou “1”.  Ramener le binaire des annexes.  Par défaut à “1”.
allowed_annexes_types : (optionnel) permet de spécifier les types d’annexes à prendre en compte.
showAssembly : (obligatoire) valeur à “0” ou “1”.  Affiche l’assemblée pour le point de manière textuelle.
showTemplates : (obligatoire) valeur à “0” ou “1”.  Montre les documents générables pour ce point.
inTheNameOf : (optionnel) un nom d’utilisateur au nom duquel effectuer l’opération.  Ceci permet de renseigner un seul utilisateur pour la connexion au WS et d’effectuer les opération au nom d’autre utilisateur.

Sortie :

Retourne les infos sur le point (informations principales + étendues si spécifié).  Affiche la liste des annexes si spécifié (avec fichier). Affiche la liste des document générables (sans le fichier, passer par l’obtention d’un document généré (Obtenir un document généré (getItemTemplate)) pour obtenir le fichier).

Recherche de points (searchItems)

Cette méthode permet d’effectuer une recherche de point sur base de plusieurs critères de recherche.

Paramètres d’entrées :

Critères de recherche : (obligatoire) différents critères peuvent être utilisés :

  • créateur (Creator)

  • titre (Title)

  • description du point (Description)

  • décision du point (decision)

  • type de point (Collège, Conseil, …) (portal_type)

  • état WF du point (review_state)

  • identifiant de la catégorie (getCategory)

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

  • identifiant du type de séance (meetingConfigId)

externalIdentifier : (optionnel) ce paramètre permet de passer un identifiant externe.  Lorsqu’un point est créé (createItem) 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”.
inTheNameOf : (optionnel) utiliser la méthode “au nom d’un utilisateur”.  Nécessite d’être connecté en tant que “Manager/MeetingManager” au Web Services.

Sortie :

Retourne les infos sur le point, désormais les informations reçues sur un point via searchItems sont aussi complètent que via la méthode Obtention d’informations sur un point (getItemInfos)

Savoir si un élément a déjà été envoyé (checkIsLinked)

Cette méthode permet de savoir si un élément appelant a déjà été envoyé vers iA.Délib, à condition que lors de la création du point dans iA.Délib, l’élément appelant ai soit passé un “identifiant externe”, soit stocké l’UID du point créé.

Paramètres d’entrées :

meetingConfigId : (optionnel) l’identifiant d’une Configuration de séance.  Permet de savoir par exemple si un élement a été envoyé vers un type de séance et pas un autre…
externalIdentifier : (obligatoire) il s’agit de la clé qui lie le point créé dans iA.Délib à la procédure ayant créé ce point.

Sortie :

Retourne “isLinked” à “1” si un point correspondant a été trouvé, “0” sinon.

Obtenir un document généré (getItemTemplate)

Cette méthode permet d’obtenir un document généré pour un point donné.

Paramètres d’entrées :

itemUID : (obligatoire) l’identifiant UID du point pour lequel générer le document.  Cet identifiant peut être connu en passant par la recherche de points ou lorsque le point a été créé via les Web Services.
templateId : (obligatoire) l’identifiant du document à générer. Cet identifiant peut être connu lors de l’obtention d’informations sur un point si le paramètre “showTemplates” est à “1”.
inTheNameOf : (optionnel) utiliser la méthode “au nom d’un utilisateur”.  Nécessite d’être connecté en tant que “Manager/MeetingManager” au Web Services.

Sortie :

Retourne le document généré.

Créer un point (createItem)

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

Paramètres d’entrées :

meetingConfigId : (obligatoire) l’identifiant de la configuration de séance dans laquelle créer le point.
proposingGroupId : (obligatoire) l’identifiant du groupe proposant avec lequel créer le point.
creationData : une série de données de base pour créer le point :
  • titre (title, obligatoire)

  • catégorie (category, obligatoire si catégories utilisées par la meetingConfigIf)

  • description (description)

  • description détaillée (detailedDescription)

  • motivation (motivation)

  • décision (optionnel)

  • UID de la séance souhaitée (preferredMeeting)

  • UIDs des groupes associés (associatedGroups)

  • UIDs des groupes en charge (groupsInCharge)

  • identifiants des émetteurs d’avis optionnels (optionalAdvisers)

  • identifiant externe (optionnel)

  • annexes (optionnel)

Une nouvelle valeur “extraAttrs” est disponible et permet de renseigner des valeurs pour les champs XHTML qui ne sont pas gérés par défaut, donc autres que “description”, “detailedDescription”, “motivation” et “decision”.  Ce paramètre doit recevoir une liste de dictionnaire de la forme suivante :

[{'key': 'my_xhtml_field_id', 'value': '<p>My field XHTML value.</p>'}]
cleanHtml : (obligatoire) activé par défaut (“1”), ceci nettoiera le HTML reçu et peut être désactivé si nécessaire (“0”).
wfTransitions : (optionnel) déclencher une série de transitions du WF.  Les transitions sont déclenchées en tant que Manager mais doivent exister et être renseignées dans le bon ordre.
inTheNameOf : (optionnel) utiliser la méthode “au nom d’un utilisateur”.  Nécessite d’être connecté en tant que “Manager/MeetingManager” au Web Services.

Sortie :

Retourne l’UID du point créé.  Cette information 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” passé dans le creationData ci-dessus à la même utilité mais stocke alors dans iA.Délib un identifiant provenant de la procédure appelante…  Une série d’avertissements (warnings) peut également être retournée : HTML utilisé non valide (donc corrigé), annexe passée non valide, …

Liste des séances acceptant des points (meetingsAcceptingItems)

Cette méthode permet d’obtenir la liste des séances qui acceptent des points.

Paramètres d’entrées :

meetingConfigId : (obligatoire) l’identifiant d’une Configuration de séance.
inTheNameOf : (optionnel) un nom d’utilisateur au nom duquel effectuer l’opération.  Ceci permet de renseigner un seul utilisateur pour la connexion au WS et d’effectuer les opération au nom d’autre utilisateur.

Sortie :

Retourne l’UID et la date des séances qui acceptent des points.  L’UID pourra être utilisé pour l’attribut “preferredMeeting” lors de l’utilisation de createItem.