Référence — listes d'inscrits

Déposer les membres d'une classe. La route s'appelle avec une clé d'intégration : voir Conventions.

PUT /api/institutions/:institutionId/classes/by-ref/:ref/roster

Rattache une liste de personnes à une classe, en créant les comptes qui manquent. Exige roster.write — la portée roster:write.

L'essai à blanc est le comportement par défaut, à l'inverse du dépôt d'emploi du temps : appliquer une liste crée des comptes.

Corps de la requête

{
  "members": [
    { "email": "awa@ecole.fr", "displayName": "Awa Diallo" },
    { "phone": "6 99 12 34 56", "displayName": "Ben Traoré" }
  ]

}

Chaque entrée de members :

Une entrée peut porter le courriel et le téléphone. C'est le courriel, quand il y en a un, qui identifie la personne dans la liste ; le téléphone sinon.

Traitement

Chaque entrée est vérifiée dans l'ordre du tableau : courriel, téléphone, présence de l'un des deux, doublon, puis nom. La première règle qui échoue la fait refuser ; les autres entrées continuent.

Pour chaque personne retenue, un compte est cherché par son courriel, puis par son téléphone :

• Un compte existe et appartient déjà à l'établissement : il est ajouté à la classe s'il n'en était pas membre. Son nom n'est pas modifié.
• Un compte existe hors de l'établissement : il n'y entre pas d'office. Il est invité — un courriel lui est envoyé s'il en a un — et rejoint l'établissement, avec le rôle learner, puis la classe, en acceptant depuis « Mon espace ». Il figure dans awaitingAcceptance, et n'est compté ni dans addedToOrg ni dans addedToGroup.
• Aucun compte n'existe : un compte est créé avec ce courriel, ce téléphone et ce nom, et un mot de passe que personne ne connaît. Il est rattaché à l'établissement avec le rôle learner, ajouté à la classe, et un lien d'activation est émis. C'est ce lien qui permet à la personne de choisir son mot de passe.

La route ne retire jamais personne : une personne absente de la liste reste dans la classe.

Réponse

201 si la liste est appliquée, 200 si c'est un essai à blanc — dans les deux cas même si des entrées sont refusées.

{
  "dryRun": false,
  "read": 2,
  "accountsCreated": 1,
  "accountsFound": 1,
  "addedToOrg": 1,
  "addedToGroup": 1,
  "alreadyInGroup": 0,
  "joinedFromOutside": [],
  "awaitingAcceptance": ["+237699123456"],
  "rejected": [],
  "invitations": [
    {
      "email": "awa@ecole.fr",
      "phone": null,
      "displayName": "Awa Diallo",
      "link": "https://reunion.votre-etablissement.fr/app/?setup=…",
      "delivered": false
    }
  ]

}

Un rejet :

Une invitation :

Les liens d'activation

Aujourd'hui, MeetingHub n'envoie aucun courriel depuis ce dépôt : delivered vaut toujours false, et chaque lien est rendu dans link. Une personne inscrite par son seul téléphone n'en recevrait de toute façon pas. C'est à vous de remettre le lien à la personne, par votre propre messagerie, un SMS ou WhatsApp.

Un lien vaut un mot de passe : il ouvre le compte à qui le possède. Transmettez-le à la seule personne concernée, et ne le conservez pas dans vos journaux. Il est valable 7 jours — durée par défaut, que l'exploitant de l'instance peut changer — et ne sert qu'une fois : dès que la personne a choisi son mot de passe, il ne fonctionne plus.

Un lien perdu n'est pas réémis par un nouveau dépôt : le compte existe déjà, et la personne est alors comptée dans accountsFound. Un administrateur de l'établissement en émet un nouveau avec sa session, par POST /api/institutions/:institutionId/members/:accountId/activation-link, pour un compte qui n'appartient qu'à cet établissement.

Erreurs de la requête entière

La classe est cherchée avant que le corps soit lu : une ref inconnue rend 404 même si le corps est fautif.

Une liste appliquée émet l'événement roster.imported : voir Webhooks.

L'ancienne adresse

PUT /api/integration/groups/:ref/roster répond encore avec une clé d'établissement, comme alias déprécié de cette route : chaque réponse porte Deprecation: true et un en-tête Link vers la route de /api.