Notifications API (.notifications)

Notifications API (.notifications)

Estimated reading time: 5’

What you’ll learn

This guide presents how notifications work and can be enabled in PySyft.

Introduction

PySyft allows for responsible access to sensitive data. The nature of this kind of work is that often there will be processes may need external review, or need to happen asychronously. For instance, if a Data Scientist submits some code they’d like to be run against private data, often there will be a Data Owner who will want to manually review that code, before sending a response back.

However - how would the Data Owner know when a code request has been submitted? And how would the Data Scientist know when a response has been returned?

These kinds of scenarios that motivates the existance of notifications to PySyft. Currently we support only email notifications,thus in the rest of the guide, notification refers to an email notification, and these terms may be used interchangeably.

Email Notifications

An Email Notification alerts either the Data Scientist or the Data Owner of an event occuring. The events that trigger email notifications can be toggled. The e-mail protocol that PySyft currently supports is the Simple Mail Transfer Protocol, or SMTP. You can use a service like SendGrid to setup and create an STMP token for use with PySyft.

How it works

It is pretty simple to set up notifications:

  • Prerequisite: Data Owner setups at the SMTP credentials on the server

  • Data Owner enables the dispatch of notifications at a server-level

  • Any user of the server, data owner or data scientists configure the client to receive email notifications, or can deactivate them

It is helpful to remember that email notifications are designed to be primarily carried out on the low side server.

What notifications are dispatched?

Currently, only the most important notifications are dispatched by the system. These are:

  • When new users sign up (admins)

  • When requests are submitted (admins)

  • When requests change state (data scientists)

This allows both parties to be efficient working async by knowing when something is pending their input.

Setup SMTP credentials

To setup the SMTP credentials, one can specify them either at deployment (A) using proper secrets in both single container or k8s mode, but as well after the node is deployed (B).

The main parameteres to pass are:

  • username: Whatever name you’d like to give for this set of credentials.

  • password: The SMTP token. You can generate one using a service like SendGrid!

  • sender: The email you want the notifications to be sent from

Below you see detailed documentation on what you should to pass these.

A. During deployment

Single-container

The deployment using the single container uses multiple .yaml files during the deployment. These can be updated directly before doing the docker deployment. You can find them in the backend-statefulset.yaml as such:

# SMTP
- name: SMTP_HOST
    value: {{ .Values.node.smtp.host | quote }}
- name: SMTP_PORT
    value: {{ .Values.node.smtp.port | quote }}
- name: SMTP_USERNAME
    value: {{ .Values.node.smtp.username | quote }}
- name: SMTP_PASSWORD
    {{- if .Values.node.smtp.existingSecret }}
    valueFrom:
    secretKeyRef:
        name: {{ .Values.node.smtp.existingSecret }}
        key: smtpPassword
    {{ else }}
    value: {{ .Values.node.smtp.password | quote }}
    {{ end }}
- name: EMAIL_SENDER
    value: {{ .Values.node.smtp.from | quote}}

To secure your SMTP token, we recommend you to use Docker secrets.

Kubernetes via Helm

To specify the necessary credentials, you can update the default values.yaml values with yours. If you inspect it, you will find the following section which describes the SMTP settings.

# SMTP Settings
smtp:
  # Existing secret for SMTP with key 'smtpPassword'
  existingSecret: null
  host: smtp.sendgrid.net
  port: 587
  from: [email protected]
  username: apikey
  password: password

These can be updated via the helm operations. For more detailes, please look at the deployment in k8s guide.

B. Using the Python client

To show how email notifications can be setup and configured, we will launch now a test server for our purpose and login into it using default credentials.

import syft as sy

server = sy.orchestra.launch(name="test_server", port="auto", dev_mode=False, reset=True)

# logging in with default credentials
client = sy.login(email="[email protected]", password="changethis", port=server.port)
Hide code cell output 
Starting test_server server on 0.0.0.0:59185

Waiting for server to start Done.
SyftInfo: 
You have launched a development server at http://0.0.0.0:59185.It is intended only for local use.

Logged into <test_server: High side Datasite> as <[email protected]>
SyftWarning: 
You are using a default password. Please change the password using `[your_client].account.set_password([new_password])`.

To do this, we’ll have to specify three fields:

  • email_username: Whatever name you’d like to give for this set of credentials.

  • email_password: The SMTP token. You can generate one using a service like SendGrid!

  • email_sender: The email you want the notifications to be sent from, e.g. noreply@specialorg.org

  • email_server: The SMTP server address

  • email_port: The port where the SMTP is accesible

Note that all start with email since we are working with email notifications. We are working to support more notifications formats!

client.settings.enable_notifications(
    email_username="..", 
    email_password="..", 
    email_sender="..", 
    email_server="..", 
    email_port="..")

Enable server notifications

Data Owner can check the current server settings as:

client.notifications.settings()

class NotifierSettings:
  id: str = e8de70b00fb348daa3cbeb2204e40fad
  active: str = False
  email_enabled: str = True

To update them to enable or disable notifications, we can update the settings as:

client.settings.disable_notifications()
SyftSuccess: 
Notifications disabled succesfullly

client.settings.enable_notifications()
SyftError: 
You must provide both server and port to enable notifications.

Activate notifications as an user

To start receiving notifications for the events happening on the server that could be of interest to you, you can simply do:

client.notifications.activate()
SyftSuccess: 
Notifications enabled successfully!

To see the current status of your notifications, you can look into client.account, which gives an overview of your account:

client.account.notifications_enabled

{<NOTIFIERS.EMAIL: 1>: True,
 <NOTIFIERS.SMS: 2>: False,
 <NOTIFIERS.SLACK: 3>: False,
 <NOTIFIERS.APP: 4>: False}

We are working to offer support for further notifications system, but enabling notifications via SMS or Slack is not yet possible. In case you would like to stop receiving the notifications, please proceed with:

client.notifications.deactivate()
SyftSuccess: 
Notifications disabled successfully!

On This Page