Send notifications

The notify.send node delivers a notification through a channel. Each channel is a connection: a Slack workspace (@posos/slack), an SMTP server (@posos/mail) or an HTTP endpoint (@posos/notify). A node designates the connection it uses; a node that designates none uses the port bound by the instance (ports.notification, the console in development). This recipe declares a Slack and a mail connection and points nodes at them.

For connections in general (origins, defaults, secrets), see Manage connections. For the mechanism that lets a node pick an adapter by its connection, see Plugin manifest — Connections that serve a port.

Before you start

The plugins @posos/notify, @posos/slack and @posos/mail are loaded (they are core plugins, in the API image and in the repository's PLUGINS_PATH).
For Slack: a Slack app with the chat:write scope (and users:read.email to address a person by e-mail), installed in the workspace, its bot token (xoxb-…), and the bot invited to each target channel.
For mail: the host, port and, if any, the account of the SMTP server, and the sender address it accepts.

1. Declare the connections

In the instance manifest (connections:), or in the console (Connexions → Nouvelle connexion):

connections:
  slack-pharma:
    type: slack
    label: Slack pharmacie
    baseUrl: https://slack.com/api
    defaultChannel: "#garde-pharma"
    auth: { scheme: bearer, token: env:SLACK_BOT_TOKEN }
  relais-chu:
    type: smtp
    label: Relais SMTP du CHU
    baseUrl: smtp://relais.chu.local:25
    from: "Meridian <meridian@chu.fr>"
    defaultTo: pharmacie@chu.fr

Type	`baseUrl`	Auth	Parameters
`slack`	`https://slack.com/api`	`bearer` (bot token)	`defaultChannel`: channel used when the node names none (id `C0123456789` or name `#garde-pharma`); `patientContext`
`smtp`	`smtp://host:port` (STARTTLS when the server offers it; port 25 by default) or `smtps://host:port` (TLS from the start; port 465 by default)	`none`, `basic` (account and password)	`from` (required): sender address; `defaultTo`: addresses used when the node names none; `requireTls`: refuse a `smtp://` server without STARTTLS; `patientContext`
`notification-webhook`	the endpoint that receives the notification	`none`, `basic`, `header`, `bearer`	`patientContext`

The smtp type gives its credential to the mail plugin, which authenticates itself (the connection form says so). A Slack incoming webhook URL is not supported: the secret would sit in the connection's URL.

2. Designate the connection on the node

In the editor, select the notify.send node and pick the connection in Connexion; the list shows the connections whose type serves the notification port. In YAML:

nodes:
  alerte_garde:
    type: notify.send
    connection: slack-pharma
    config: { severity: critical }
  mail_pharmacie:
    type: notify.send
    connection: relais-chu
    config: { severity: warning, recipients: "pharmacien.garde@chu.fr, cadre@chu.fr" }

recipients lists the destinations in the channel's terms (Slack channels, Slack people by identifier or e-mail, mail addresses), separated by commas; absent, the connection's defaultChannel or defaultTo applies. One node uses one connection: to notify Slack and mail, chain two nodes. Saving and publishing refuse a connection that does not exist or does not serve the notification port, and a connection used by a published workflow cannot be deleted.

3. Decide what goes to the channel

The title and body are sent as they are. Slack is not a health data host: keep patient data out of a Slack message unless your organisation allows it. The identifier of the patient in context is added to the message only when the connection sets patientContext: true (false by default).

Verify

Simulate the workflow in the editor: the simulation records the notification without sending it. Then run it on the instance and check the channel. A failed delivery fails the node with the channel's answer, for example:

[slack] chat.postMessage (connexion « slack-pharma », canal #garde) : refusé par Slack (not_in_channel). — invite the bot to the channel.
[mail] envoi refusé par relais.chu.local:25 (connexion « relais-chu ») : … — the SMTP server refused the message (5xx): check the sender and the recipients.

The plugins retry a delivery in the node, up to three attempts: a network error, a Slack 429 (after its Retry-After) or 5xx, an SMTP 4xx reply. A retry after a timeout can deliver the same message twice.

Manage connections — declare, create, designate connections.
Manage credentials — the token and SMTP account of a console connection.
Decide validations in Slack — validation requests with buttons, on the same slack connection.
Bundled plugins — @posos/notify, @posos/slack, @posos/mail.
Workflow DSL — connection — the node field.