Messagerie¶
Conversations par messages¶
DHIS2 dispose d'un mécanisme permettant d'envoyer des messages à des fins tels que le retour d'information des utilisateurs, les notifications et les informations générales à l'intention des utilisateurs. Les messages sont regroupés en conversations. Pour interagir avec les conversations de messages, vous pouvez envoyer des requêtes POST et GET à la ressource messageConversations.
/api/33/messageConversations
Les messages sont transmis à la boîte de réception DHIS2, mais ils peuvent également être envoyés aux adresses électroniques et aux téléphones portables de l'utilisateur sous forme de SMS. Dans cet exemple, nous verrons comment utiliser l'API Web pour envoyer, lire et gérer des messages. Nous allons nous faire passer pour l'utilisateur Administrateur DHIS2 et envoyer un message à l'utilisateur Mobile. Nous allons ensuite nous faire passer pour l'utilisateur mobile et lire notre nouveau message. Ensuite, nous allons gérer la boîte de réception de l'utilisateur administrateur en marquant et en supprimant des messages.
Écrire et lire des messages¶
La ressource avec laquelle nous devons interagir pour envoyer et lire des messages est la ressource messageConversations. Nous commençons par visiter le point d'entrée de l'API Web à l'adresse http://play.dhis2.org/demo/api, où nous trouvons et suivons le lien vers la ressource messageConversations à l'adresse http://play.dhis2.org/demo/api messageConversations. La description nous indique que nous pouvons utiliser une requête POST pour créer un nouveau message en utilisant le format XML suivant pour l'envoyer à plusieurs utilisateurs :
<message xmlns="http://dhis2.org/schema/dxf/2.0">
<subject>Voici le sujet</subject>
<text>Voici le texte</text>
<users>
<user id="user1ID" />
<user id="user2ID" />
<user id="user3ID" />
</users>
</message>
Pour l'envoi à tous les utilisateurs appartenant à un ou plusieurs groupes d'utilisateurs, nous pouvons utiliser :
<message xmlns="http://dhis2.org/schema/dxf/2.0">
<subject>Voici le sujet</subject>
<text>Voici le texte</text>
<userGroups>
<userGroup id="userGroup1ID" />
<userGroup id="userGroup2ID" />
<userGroup id="userGroup3ID" />
</userGroups>
</message>
Pour l'envoi à tous les utilisateurs connectés à une ou plusieurs unités d'organisation, nous pouvons utiliser :
<message xmlns="http://dhis2.org/schema/dxf/2.0">
<subject>Voici le sujet</subject>
<text>Voici le texte</text>
<organisationUnits>
<organisationUnit id="ou1ID" />
<organisationUnit id="ou2ID" />
<organisationUnit id="ou3ID" />
</organisationUnits>
</message>
Puisque nous voulons envoyer un message à notre ami l'utilisateur mobile, nous devons rechercher son identifiant. Nous le faisons en allant au point d'entrée de l'API Web et en suivant le lien vers la ressource utilisateurs à /api/users. Nous continuons en suivant le lien vers l'utilisateur mobile à /api/users/PhzytPW3g2J où nous apprenons que son identifiant est PhzytPW3g2J. Nous sommes maintenant prêts à rassembler nos messages XML pour former un message dans lequel nous voulons demander à l'utilisateur mobile s'il a déclaré des données pour janvier 2014 :
<message xmlns="http://dhis2.org/schema/dxf/2.0">
<subject>Rapport sur les données de mortalité</subject>
<text>Avez-vous déclaré des données pour l'ensemble de données sur la mortalité pour janvier 2014 ?</text>
<users>
<user id="PhzytPW3g2J" />
</users>
</message>
Pour le tester, nous enregistrons le contenu XML dans un fichier appelé message.xml. Nous utilisons cURL pour envoyer le message à l'instance de démonstration DHIS2 où nous indiquons que le type de contenu est XML et où nous nous authentifions en tant qu'utilisateur admin :
curl -d @message.xml "https://play.dhis2.org/demo/api/messageConversations"
-H "Content-Type:application/xml" -u admin:district -X POST
La charge correspondante en JSON et la commande POST ressemblent à ceci :
{
"subject": "Hey",
"text": "How are you?",
"users": [
{
"id": "OYLGMiazHtW"
},
{
"id": "N3PZBUlN8vq"
}
],
"userGroups": [
{
"id": "ZoHNWQajIoe"
}
],
"organisationUnits": [
{
"id": "DiszpKrYNg8"
}
]
}
curl -d @message.json "https://play.dhis2.org/demo/api/33/messageConversations"
-H "Content-Type:application/json" -u admin:district -X POST
Si tout se passe bien, nous recevons un code de statut HTTP 201 Créé. Notez également que nous recevons un en-tête HTTP Localisation qui nous informe de l'URL de la ressource de conversation de messages nouvellement créée - celle-ci peut être utilisée par un utilisateur pour effectuer d'autres actions.
Nous allons maintenant nous faire passer pour l'utilisateur mobile et lire le message qui vient d'être envoyé en envoyant une requête GET à la ressource messageConversations. Nous fournissons un en-tête Accepter avec l'application/xml comme valeur pour indiquer que nous sommes intéressés par la représentation de la ressource XML et nous nous authentifions en tant qu'utilisateur mobile :
curl "https://play.dhis2.org/demo/api/33/messageConversations"
-H "Accept:application/xml" -u mobile:district
En réponse, nous obtenons le fichier XML suivant :
<messageConversations xmlns="http://dhis2.org/schema/dxf/2.0"
link="https://play.dhis2.org/demo/api/messageConversations">
<messageConversation name="Mortality data reporting" id="ZjHHSjyyeJ2"
link="https://play.dhis2.org/demo/api/messageConversations/ZjHHSjyyeJ2"/>
<messageConversation name="DHIS2 version 2.7 is deployed" id="GDBqVfkmnp2"
link="https://play.dhis2.org/demo/api/messageConversations/GDBqVfkmnp2"/>
</messageConversations>
Dans la réponse, nous pouvons lire l'identifiant du nouveau message envoyé, qui est ZjHHSjyyeJ2. Notez que le lien vers la ressource spécifique est intégré et peut être suivi pour lire le message complet. Une fois que nous connaissons l'URL, nous pouvons répondre directement à une conversation sur un message existant en incluant le texte du message dans la charge de la requête. Nous sommes maintenant en mesure de créer une URL pour envoyer notre réponse :
curl -d "Oui, l'ensemble des données sur la mortalité a été déclaré"
"https://play.dhis2.org/demo/api/messageConversations/ZjHHSjyyeJ2"
-H "Content-Type:text/plain" -u mobile:district -X POST
Si tout s'est déroulé comme prévu, vous recevrez un code de statut 200 OK.
Dans la version 2.30, nous avons ajouté un paramètre de recherche d'URL :
queryString=?&queryOperator=?
Le filtre recherche des correspondances dans l'objet, le texte et les expéditeurs pour les conversations de messages. L'opérateur de requête par défaut est token (jeton), mais d'autres opérateurs peuvent être définis dans la requête.
Gérer les messages¶
Au fur et à mesure que les utilisateurs reçoivent et envoient des messages, les conversations commencent à s'empiler dans leur boîte de réception, ce qui devient éventuellement difficile à suivre. Nous allons maintenant voir comment gérer la boîte de réception des messages d'un utilisateur en supprimant et en marquant des conversations par l'intermédiaire de la Web-API. Pour ce faire, nous allons effectuer quelques opérations de maintenance dans la boîte de réception de l'utilisateur « Administrateur DHIS ».
Commençons par supprimer quelques messages de la boîte de réception. Notez bien que toutes les opérations de suppression décrites ici ne suppriment que la relation entre un utilisateur et une conversation de messages. En termes pratiques, cela signifie que nous ne supprimons pas les messages eux-mêmes (ni aucun contenu d'ailleurs) mais que nous supprimons simplement le fil de messages de l'utilisateur de sorte qu'il ne soit plus listé dans la ressource /api/messageConversations.
Pour supprimer une conversation de messages de la boîte de réception d'un utilisateur, nous devons envoyer une requête DELETE à la ressource identifiée par l'identifiant de la conversation de messages et l'utilisateur participant. Par exemple, pour supprimer l'utilisateur avec l'identifiant xE7jOejl9FI de la conversation avec l'identifiant jMe43trzrdi :
curl "https://play.dhis2.org/demo/api/33/messageConversations/jMe43trzrdi
Si la demande a abouti, le serveur répondra par un 200 OK. Le corps de la réponse contient un objet XML ou JSON (selon l'en-tête "accepter" de la demande) contenant l'identifiant de l'utilisateur supprimé.
{
"removed" : ["xE7jOejl9FI"]
}
En cas d'échec, l'objet renvoyé contiendra un message qui décrit l'erreur.
{
"message" : "No user with uid: dMV6G0tPAEa"
}
Le lecteur observateur aura déjà remarqué que l'objet renvoyé en cas de succès dans notre exemple est en fait une liste d'identifiants (contenant une seule entrée). Ceci est dû au fait que le endpoint prend également en charge les suppressions par lots. La requête est faite à la même ressource messageConversations mais suit une sémantique légèrement différente. Pour les opérations par lots, les identifiants de conversation sont donnés en tant que paramètres de la chaîne de requête. L'exemple suivant supprime deux conversations de messages distinctes pour l'utilisateur actuel :
curl "https://play.dhis2.org/demo/api/messageConversations?mc=WzMRrCosqc0&mc=lxCjiigqrJm"
-X DELETE -u admin:district
Si vous disposez d'autorisations suffisantes, vous pouvez supprimer des conversations au nom d'un autre utilisateur en indiquant un paramètre facultatif, l'identifiant de l'utilisateur.
curl "https://play.dhis2.org/demo/api/messageConversations?mc=WzMRrCosqc0&mc=lxCjiigqrJm&user=PhzytPW3g2J"
-X DELETE -u admin:district
Comme indiqué, les suppressions par lots renvoient le même format de message que pour les opérations individuelles. La liste des objets supprimés reflétera les suppressions effectuées avec succès. Les demandes partiellement erronées (c'est-à-dire les identifiants inexistants) n'annuleront donc pas l'ensemble de l'opération par lots.
Les messages comportent une propriété booléenne read (lire). Cette propriété permet de savoir si un utilisateur a vu (ouvert) un message ou non. Dans un scénario d'application typique (par exemple, le portail web DHIS2), un message est marqué comme lu dès que l'utilisateur l'ouvre pour la première fois. Cependant, les utilisateurs peuvent vouloir gérer le statut « lu » ou « non lu » de leurs messages afin de garder une trace de certaines conversations.
Le marquage des messages comme lus ou non lus suit une sémantique similaire à celle des suppressions de lots, et supporte également les opérations par lots. Pour marquer des messages comme lus, nous envoyons un POST à la ressource messageConversations/read avec un corps de requête contenant un ou plusieurs identifiants de message. Pour marquer des messages comme non lus, nous envoyons une requête identique à la ressource messageConversations/unread. Comme pour les suppressions, un paramètre de requête optionnel utilisateur peut être fourni.
Marquons quelques messages comme lus par l'utilisateur actuel :
curl "https://play.dhis2.org/dev/api/messageConversations/read"
-d '["ZrKML5WiyFm","Gc03smoTm6q"]' -X POST
-H "Content-Type: application/json" -u admin:district
La réponse est un 200 OK avec le contenu JSON suivant :
{
"markedRead": ["ZrKML5WiyFm", "Gc03smoTm6q"]
}
Vous pouvez ajouter des destinataires à une conversation de messages existante. La ressource est située à l'adresse suivante :
/api/33/messageConversations/id/recipients
Les options de cette ressource sont une liste d'utilisateurs, de groupes d'utilisateurs et d'unités d'organisation. La requête doit ressembler à ceci :
{
"users": [
{
"id": "OYLGMiazHtW"
},
{
"id": "N3PZBUlN8vq"
}
],
"userGroups": [
{
"id": "DiszpKrYNg8"
}
],
"organisationUnits": [
{
"id": "DiszpKrYNg8"
}
]
}
Pièces jointes aux messages¶
La création de messages avec des pièces jointes se fait en deux étapes : le téléchargement du fichier dans la ressource attachments (pièces jointes), puis inclure un ou plusieurs pièces jointes lors de la création d'un nouveau message.
Une requête POST à la ressource attachments téléchargera le fichier sur le serveur.
curl -F file=@attachment.png "https://play.dhis2.org/demo/api/messageConversations/attachments"
-u admin:district
La demande renvoie un objet qui représente la pièce jointe. L'identifiant de cet objet doit être utilisé lors de la création d'un message afin de lier la pièce jointe au message.
{
"created": "2018-07-20T16:54:18.210",
"lastUpdated": "2018-07-20T16:54:18.212",
"externalAccess": false,
"publicAccess": "--------",
"user": {
"name": "John Traore",
"created": "2013-04-18T17:15:08.407",
"lastUpdated": "2018-03-09T23:06:54.512",
"externalAccess": false,
"displayName": "John Traore",
"favorite": false,
"id": "xE7jOejl9FI"
},
"lastUpdatedBy": {
"id": "xE7jOejl9FI",
"name": "John Traore"
},
"favorite": false,
"id": "fTpI4GOmujz"
}
Lors de la création d'un nouveau message, les identifiants peuvent être transmis dans le contenu de la requête pour lier les fichiers téléchargés au message en cours de création.
{
"subject": "Hey",
"text": "How are you?",
"users": [
{
"id": "OYLGMiazHtW"
},
{
"id": "N3PZBUlN8vq"
}
],
"userGroups": [
{
"id": "ZoHNWQajIoe"
}
],
"organisationUnits": [
{
"id": "DiszpKrYNg8"
}
],
"attachments": [
"fTpI4GOmujz",
"h2ZsOxMFMfq"
]
}
Lorsque vous répondez à un message, les identifiants peuvent être transmis en tant que paramètre de la requête.
curl -d "Oui, l'ensemble des données sur la mortalité a été déclaré"
"https://play.dhis2.org/demo/api/33/messageConversations/ZjHHSjyyeJ2?attachments=fTpI4GOmujz,h2ZsOxMFMfq"
-H "Content-Type:text/plain" -u mobile:district -X POST
Une fois qu'un message avec une pièce jointe a été créé, il est possible d'accéder à la pièce jointe à l'aide d'une requête GET à l'URL suivante :
/api/messageConversations/<mcv-id>/<msg-id>/attachments/<attachment-id>
Où
Notifications des tickets et des résultats de validation¶
Vous pouvez utiliser l'outil « écrire un feedback » pour créer des tickets et des messages. La seule différence entre un ticket et un message est que vous pouvez donner un statut et une priorité à un ticket. Pour définir le statut :
POST /api/messageConversations/<uid>/status
Pour définir la priorité :
POST /api/messageConversations/<uid>/priority
Dans la version 2.29, les messages générés par l'analyse de validation peuvent désormais être utilisés dans les propriétés de statut et de priorité. Par défaut, les messages générés par l'analyse de validation héritent de la priorité de la règle de validation en question, ou de la plus grande importance si le message contient plusieurs règles.
Dans la version 2.30, les règles de validation peuvent être affectées à n'importe quel utilisateur, alors que les tickets doivent toujours être affectés à un utilisateur appartenant au groupe des destinataires du retour d'information du système.
Tableau : Liste des valeurs de statut et de priorité valides
| Statut | Priorité |
|---|---|
| OUVRIR | BAS |
| EN ATTENTE | MOYEN |
| INVALIDE | ÉLEVÉ |
| RÉSOLU |
Vous pouvez également ajouter un message interne à un ticket, qui ne peut être vu que par les utilisateurs ayant les permissions « Gérer les tickets ». Pour créer une réponse interne, vous devez inclure le paramètre « interne » et le définir sur:
curl -d "Ceci est un message interne"
"https://play.dhis2.org/demo/api/33/messageConversations/ZjHHSjyyeJ2?internal=true"
-H "Content-Type:text/plain" -u admin:district -X POST