Description

Le service create/item permet de créer un point dans HubSessions. Dans certains HubSessions, le concept de point peut se nommer autrement, comme, par exemple, Analyse ou Section.

Tout point est créé au nom d'un groupe HubSessions. Un tel groupe représente généralement un département ou un service.

À l'instar d'un point créé via l'interface web d'HubSessions, un point créé via l'API peut donc être créé pour autant que l'utilisateur représentant le logiciel tiers soit défini comme créateur de points au sein d'un groupe HubSessions. Puisqu'un utilisateur, fut-il humain ou logiciel, peut potentiellement être défini comme créateur de plusieurs groupes HubSessions, chaque appel au service de création de points devra mentionner l'identifiant du groupe au nom duquel le point est créé.

Type de requête

Requête HTTP POST

Données en entrée

La charge utile de la requête HTTP POST de création d'un point a une structure telle qu'illustrée ci-dessous.

<?xml version="1.0" encoding="UTF-8" ?>
<Item>
 <title>Why Open Source Misses the Point of Free Software
        by Richard Stallman
 </title>
 <proposingGroup>group123</proposingGroup>
 <description>
  <![CDATA[
  <p>The terms “free software” and “open source” stand for almost the same
     range of programs. However, they say deeply different things about those
     programs, based on different values. The free software movement campaigns
     for freedom for the users of computing; it is a movement for freedom and
     justice. By contrast, the open source idea values mainly practical
     advantage and does not campaign for principles.</p>
  <p>This is why we do not agree with open source, and do not use that term.</p>
  ]]>
 </description>
 <decision>
   <![CDATA[
     <p>As the advocates of open source draw new users into our community, we
        free software activists must shoulder the task of bringing the issue of
        freedom to their attention. We have to say, “It's free software and it
        gives you freedom!”—more and louder than ever.</p>
     <p>Every time you say “free software” rather than “open source,” you help
        our cause.</p>
   ]]>
 </decision>
 <private type="bool">True</private>
</Item>

Un point est tout d'abord défini par un titre, via le tag nommé title. Comme sur l'exemple, ce titre peut contenir plusieurs lignes, pour autant qu'elles soient séparées par des caractères de retour chariot (\n) classiques.

Cet exemple illustre un point dont le contenu est unilingue. Appeler le service sur un HubSessions au contenu multilingue, dont chaque champ de texte se décline en un texte différent par langue supportée, n'est pas encore possible.

Ensuite, comme expliqué plus haut, l'identifiant du groupe HubSessions au nom duquel le point est créé doit être mentionné via le tag nommé proposingGroup.

Un point est également caractérisé par divers champs de texte dit riche, c'est-à-dire dont le format est XHTML. Comme le montre le tableau suivant, il existe une variété de ce type de champs sur un point, tout dépend de leur activation ou non sur l'HubSessions précis qui vous occupe.

Nom technique	Traduction standard	Description
description	Description	Ce champ permet en général d'introduire une description détaillée du point, qui vient en complément de son titre.
detailedDescription	Description détaillée	Un niveau de détail descriptif additionnel. Certains utilisent ce champ comme exposé détaillé dont la taille peut correspondre à plusieurs pages.
observations	Observations	Ce champ a diverses vocations. Certains l'utilisent pour commenter le statut du point ou lister certains changements qui y ont été apportés au travers du temps.
lawsText	Bases légales	Certains HubSessions activent ce champ pour y injecter la base légale d'un point représentant un texte à vocation réglementaire.
decision	Décision	Alors que, dans les étapes préalables d'un point, ce champ contient en général l'expression d'une proposition de décision à soumettre à l'organe décisionnel utilisateur d'HubSessions, en fin de processus, ce champ contiendra le texte de la décision officielle.
detailedDecision	Décision détaillée	Si le champ decision ne contient qu'un résumé de la décision complète, celle-ci peut être consignée ici.
transmitDescription	Description du point à transmettre	Si l'HubSessions courant est chaîné à un HubSessions additionnel vers lequel le point sera, à un moment donné du processus, transmis, ce champ permet d'encoder la description que le point transmis aura sur l'HubSessions tiers.

Pour connaître la liste exacte des champs de texte riche que vous pouvez utiliser dans une requête de création de points, ainsi que leur signification et leur libellé précis, pouvant varier d'un HubSessions à l'autre, veuillez contacter votre référent HubSessions.

Afin de permettre l'usage d'un format de type XML au sein même du tag d'un fichier étant déjà au format XML, emballez le contenu XHTML du champ dans un élément CDATA comme illustré.

Notez que le contenu de chaque champ peut, au contraire du contenu d'un fichier XML, contenir plusieurs tags racines. Dans les 2 exemples ci-dessus, par exemple, chaque champ contient 2 tags p racine.

HubSessions met en oeuvre la notion de point confidentiel, au travers du tag booléen nommé private. Notez bien la présence de l'attribut type de ce tag. En effet, tout attribut dont la valeur n'est pas de type string doit disposer de cet attribut.

Données de retour

Le service create/item se conforme au format de retour standardisé tel que décrit ici (à consulter notamment pour connaître la signification des différents codes de retour possibles). Au sein du sous-tag data, l'identifiant technique du point créé dans HubSessions, en cas de succès, est présent, comme illustré ci-dessous. Il est important pour l'appelant de conserver cet identifiant, qui permettra, par exemple, de réaliser sur HubSessions des appels subséquents afin, par exemple, d'ajouter des annexes au point ou s'enquérir de son statut.

<?xml version="1.0" encoding="utf-8" ?>
<Response type="object" className="Response">
 <code type="int">0</code>
 <text>WS create/item :: Item 1234 successfully created.</text>
 <data type="object" className="Object">
  <id type="int">1234</id>
 </data>
</Response>

Variante · Avec annexes

Ajouter des annexes à un point peut se faire, via l'API d'HubSessions, de deux manières:

utiliser le service create/annex autant de fois que l'on veut ajouter d'annexes à un point précédemment créé via le service create/item;
introduire, au sein même des données d'entrée du service create/item, des annexes, via le sous-tag annexes.

Cette section explique cette seconde méthode.

Dans ce cas de figure, les données en entrée, telles que décrites ci-dessus, doivent contenir un sous-tag nommé annexes, à positionner au même niveau que les autres sous-tags tels que title, proposingGroup, description, etc. Voici un exemple d'un sous-tag annexes contenant deux annexes, dont le contenu, encodé en Base64, a bien entendu été rogné.

<annexes type="list" count="2">
 <Annex type="object">
  <title>LibreOffice</title>
  <annexTypeId>libre</annexTypeId>
  <file type="file" mimeType="image/png" name="LibreOffice.png">
   <part type="base64" number="1">iVBORw0KG...</part>
   <part type="base64" number="2">rsnY99YHN...</part>
  </file>
 </Annex>
 <Annex type="object">
  <title>Microsoft Word</title>
  <annexTypeId>malware</annexTypeId>
  <file type="file" mimeType="image/png" name="Malware.png">
   <part type="base64" number="1">hElL666.-eEevIlL=-...</part>
  </file>
 </Annex>
</annexes>

Le tag annexes, représentant une liste de sous-éléments, doit définir un premier attribut nommé type valant list, ainsi qu'un second, donnant le compte de sous-éléments, nommé count.

Chaque élément contenu aura une structure similaire à celle des données d'entrées du service web create/annex, à une différence près: le tag containerId n'y figure pas, car inutile, puisque, dans ce cas de figure, le conteneur de l'annexe est bien connu, étant le point à créer en personne.

La structure des données de retour reste identique à la version sans annexes. Simplement, en cas de déboires structurels ou de valeurs corrompues identifié·e·s dans la partie annexes, des erreurs similaires à celles du service create/annex sont retournées.

Alors: create/item avec annexes ou create/annex ?

Je m'adresse à vous, chèr·e·s appelant·e·s du service. Si vous n'exagérez pas en terme de nombre d'annexes et de volume de données entrant en jeu, alors l'appel du service create/item avec annexes semble plus approprié. Par ailleurs, dès que le point est créé dans HubSessions, il ne faut pas oublier que les utilisateurs de ce dernier (encore plus chers à mes yeux) peuvent faire évoluer le point en un temps record (mais humain) et l'amener dans un état vous empêchant d'ajouter des annexes.