Getting started with ucam-user-notify¶

This page describes how to install and get started using the ucam-user-notify library.

Installation¶

Usually you will specify this library as a dependency for your Python code. How you do this depends on the packaging tool you are using.

Poetry¶

If not already present, add a uis-devops source for packages:

poetry source add --priority=explicit uis-devops \
    https://gitlab.developers.cam.ac.uk/api/v4/groups/5/-/packages/pypi/simple

Then add the ucam-user-notify library as a dependency:

poetry add --source=uis-devops ucam-user-notify

requirements.txt¶

Since we'll be using a custom index URL and the --index-url option in requirements.txt files is global, create a new file named gitlab-requirements.txt:

gitlab-requirements.txt

# This file lists Python package requirements which should *only ever* be fetched from GitLab.
# We need to use a separate file because "--index-url" is a global option.
--index-url https://gitlab.developers.cam.ac.uk/api/v4/groups/5/-/packages/pypi/simple
ucam-user-notify

Specify a version requirement

It's a good idea to specify an exact version requirement based on the most recent package and let renovatebot take care of keeping the dependencies up-to-date.

Reference the gitlab-requirements.txt file from your requirements.txt file:

requirements.txt

# ... rest of the file ...

-r gitlab-requirements.txt

Deployment¶

For a minimal deployment you will need:

the "service id" of your service as registered with the User Notify service. This will usually be the base name of the service description file located in the services/ directory.
at least one Google Service Account registered with the user notify service as being allowed to send email.

The ucam-user-notify library assumes that it is deployed in an environment with access to Google Cloud credentials. When deployed to Cloud Run, for example, these will be for the service account associated with the Cloud Run service. When running locally, these will be the credentials authenticated via gcloud auth application-default login.

The credentials must correspond either to a service account authorised by the user notify service to send email or a service account which can impersonate a sufficiently authorised service account.

The common case is to deploy your Cloud Run service with an identity registered with the user notify service. In that case to send email you need only instantiate a ucam_user_notify.Service class passing the service role ARN as the first argument to the constructor.

Sending email¶

Suppose that you have a Cloud Run service deployed whose associated service account has been registered with the User Notify service as being able to send email on behalf of the service with id punt-booking. You'll firstly need to import some classes from the ucam_user_notify package:

from ucam_user_notify import EmailMessage, Session

You'll need to create a Session instance. When constructed, a session will fetch the service configuration from the User Notify service and prepare any authentication credentials necessary to send email. This can be made into a one-time overhead if the session instance is shared between incoming request handlers.

session = Session.for_service("punt-booking")

You send email by passing an EmailMessage instance to Session.send_email. For example:

session.send_email(
    EmailMessage(
        to_addresses=["success@simulator.amazonses.com"],
        subject="testing",
        body_text="This is a test.",
    )
)