Notifications

action.notification.notify permet à une exécution d’automatisation de prévenir la personne pour qui elle s’exécute. Elle crée une notification dans l’application pour la personne Run As de l’exécution, dans l’organisation de l’exécution. Son réglage Email me about new notifications décide si elle est aussi envoyée par e-mail (voir Notifications).

L’appel ne nomme que ce qui est dit. Qui est prévenu, et dans quelle organisation, vient de l’exécution elle-même : l’entrée n’a aucun champ de destinataire, d’utilisateur ou d’organisation, et un appel qui en ajoute un est refusé.

Dans un workflow, sélectionnez l’outil Scrydon Notify me parmi les outils d’un bloc Agent. Il n’existe pas de bloc Notify me. Les résumés planifiés que Cortex crée utilisent le même outil (voir Créer une automatisation depuis le chat).

// Inside a reviewed Scrydon tool that lists "action.notification.notify"
// in its platformOperations.
const { notificationId, status } = await ctx.action.notification.notify({
  title: 'Solar digest',
  body: 'Two new results today.\nhttps://example.com/a',
  link: { url: 'https://example.com/a', label: 'Read it' },
  idempotencyKey: 'digest',
})

Qui peut l’appeler

• Seulement une exécution de workflow ou de process flow. Un tour Cortex en cours est refusé, car la personne est déjà dans cette conversation ; Cortex ne propose jamais l’outil dans un chat. Un appel fait avec un jeton autonome, hors de toute exécution, est refusé aussi.
• Seulement une exécution dont le Run As est une personne encore membre active de l’organisation. Une exécution sous un compte de service, ou sous personne, est refusée.
• Seulement l’outil Notify me de Scrydon. L’outil d’une autre extension est refusé même si son manifeste liste l’opération.

Entrée

@scrydon/sdk/platform exporte les bornes (NOTIFICATION_NOTIFY_TITLE_MAX_CHARS, NOTIFICATION_NOTIFY_BODY_MAX_CHARS, NOTIFICATION_NOTIFY_LINK_URL_MAX_CHARS, NOTIFICATION_NOTIFY_LINK_LABEL_MAX_CHARS, NOTIFICATION_NOTIFY_IDEMPOTENCY_KEY_MAX), pour vérifier une entrée avant de l’envoyer. Les champs inconnus sont refusés.

La clé est propre à l’exécution. Une nouvelle tentative dans la même exécution avec la même clé renvoie la première notification au lieu d’en envoyer une seconde, et l’exécution de la semaine suivante du même workflow, qui envoie la même clé littérale, notifie à nouveau.

La politique de prévention des pertes de données de votre organisation s’applique au titre, au corps et au libellé du lien, et contrôle le lien.

Résultat

notificationId, et status : created, ou deduplicated quand cette exécution a déjà envoyé une notification sous la même clé.

La notification a le type automation.result.

Erreurs

Un refus est une erreur FORBIDDEN dont le message commence par un code stable, également présent dans details.refusal. Un outil ne voit que le message : reconnaissez donc son code initial.

INVALID_REQUEST signifie que l’entrée n’a pas passé la validation, par exemple un champ de destinataire ou un lien http://. PROVIDER_UNAVAILABLE signifie que la notification n’a pas pu être créée à ce moment ; une nouvelle tentative avec la même clé est sans risque.