Portal

COVID Alert is now retired: For more information, visit the Government of Canada COVID Alert home page.

The COVID Alert Portal is a web-based application that allows healthcare workers to generate one-time keys. It is designed as a simple and flexible solution for provincial health authorities to adopt and for healthcare workers to embed within existing workflows.

Related blogs

• Meeting the needs of healthcare authorities to roll out COVID Alert across Canada

Portal research

How the one-time key may be received during a time of stress

We understood the public health authorities to be the best people to distribute the one-time keys, as they were the people that were in direct contact with the positive case (limit false notifications and fewer touchpoints for the app user). To understand the impacts of this design, we first conducted secondary research on how patients receive bad news. We also referred to other design research studies on GAEN apps where available.

Methodology:

• Phone interviews
• Discovery research survey
• Secondary research

When: July 2020

Learnings:

• Patients are likely to be stressed and unable to work with information. They’ll need time to process information about their positive test result and the one-time key.
• Not only is this situation stressful for the app users, but case investigators need to navigate difficult conversations.
• Jargon on the app could contribute to further confusion.
• Using the phonetic alphabet was helpful for the Netherlands’ GAEN app.

Receiving the one-time key

The one-time key distribution is an important part of the service because if there’s an error, the whole design of the service falls apart. To learn how the healthcare worker and app user might experience the one-time key distribution, we had a colleague at CDS act as a healthcare worker during the sessions with app users. In the following study (Distributing the one-time key), we had an actor act as the app user during the sessions with healthcare workers.

Methodology: Usability testing

Participants: 9 participants (early adopters of the technology and were app users)

When: August 2020

Learnings:

• There were logistical issues with people picking up the call from the healthcare worker (e.g. wary of spam/scam calls and connection issues).
• People needed to put the call on the speaker in order to write down the key.
• App users had to read the screens on the app while listening to the healthcare worker.
• Some app users needed extra direction from the healthcare worker to know how to switch to the app from the call, where to click to enter the key, where the key was upper or lower case.
• Participants worried about their emotional state and their ability to remember information if they had received a real phone call about their test result. One participant suggested providing follow-up instructions.

Distributing the one-time key

The goals for the study were similar to the Receiving the one-time key study, except to learn about the healthcare workers’ experience. We had a CDS colleague act as the app user during the sessions with the healthcare workers.

Methodology: Usability testing, one-to-one sessions

Participants:

• 9 participants
• Portal users, some who had received COVID Alert training, others who hadn’t

When: October 2020

Learnings:

• The app is complex and not easy to explain to people on the phone. The case investigators we spoke to describe themselves as not “techy”. Yet, they’re having to explain a very technical thing to people over the phone.
• Healthcare workers have already been through many changes in their work. The COVID Alert system is a lot to learn. The case investigators are having to learn the ins and outs of a very complicated product in order to talk to a small percentage of their cases about the one-time key.

One-time key metrics

There are multiple ways/channels a one-time key is distributed. This metrics review aimed to understand how the different channels compared in terms of distribution and ‘conversion’ rates (how many positive people input their one-time key into their app).

Methodology: Metrics review

When: October-November 2020

Learnings:

• For every new case, the website was seeing the most one-time keys generated. But, for some reason, there was a lower percentage of app users who got their one-time key from the website who input their one-time key into the app.
• For every new case, the Québec model (where app users make the call, instead of receiving the call) was seeing the least one-time keys generated. But, it was seeing the highest one-time keys being input into the app. This was likely because people were at a time and space where they were ready to input a one-time key.
• When a public health nurse called an app user, the rate of generated one-time keys being input was lowest (close to the website). This distribution channel also had a low rate of one-time keys being generated.

Portal invite and registration flow

With a couple of proxy users, we learned about the invitation and registration flow on the portal. We wanted to ensure the invitation and registration flow were as seamless as possible, especially considering the busy and hectic nature of healthcare workers’ work.

Methodology: Usability testing

Participants:

• 2 participants
• Proxy participants who worked in healthcare but were not delivering COVID-19 test results

When: Sept 2020

Learnings:

• It’s not clear from the invite email what would happen if the invite had expired. We could also consider what people would do if they had started the process but didn’t complete it within 24 hours.
• To respond to the invite email, invitees may need a reminder of what the app and portal are, and why they need an account.
• “Username” on the login screen implies that there might be a username set that was separate from their email.

Portal design

We designed the COVID Alert portal in a human-centered way, acknowledging that some portal users were healthcare professionals already dealing with COVID-19 challenges such as an increased workload.

This section highlights the guidelines and principles we followed to design the portal, and portal design artifacts.

Guidelines and principles

Portal content design

• Avoid using the acronym HCW for health care workers in the portal, as it may not be familiar.
• Use “log in code” instead of “security code”, as it’s more specific to the function of logging in.
• Generally avoid Latin terms – exception with “per”, since health care workers are likely familiar with “per”, and it makes the meaning clear and specific in this context (e.g. “Only give one key per patient”).
• Use “re-send” instead of “resend”, as it’s more readable. While Merriam-Webster and Cambridge both use “resend” for “resend email”, past research on Notify showed “resend” causes problems as a screen reader would read “resent” to sound like “resentment”.
• Use “stats” instead of “statistics”, as it’s shorter and familiar to health professionals.
• Use title case for COVID Alert Portal. ”Alert” needs to be capitalized. When the full title has been used earlier in a document, then refer to “the portal” lowercase.
• Use punctuation for red instructional text or red support text. If it can make sense as a sentence, the pause allows for a better experience with immersive readers. Punctuation is not necessary for helper text which has a pause because it has elements before and after it.
• Use “mobile phone” as it’s more prevalent than “smart phone”.

Portal interaction design

• Make it as easy and automatic as possible → Giving out one-time keys doesn’t require any manual input. The healthcare worker is able to go from patient to patient with 3 simple steps on the portal.
• Reduce possibility for mistakes → Encourage confirmation. Guidance at every step. The steps could be read as a script, which eases the cognitive load of using the portal as an interface between healthcare worker and patient.
• One thing per page → We usually apply this on form pages because it reduces the cognitive load into smaller chunks. The same principle can be used to break the interaction between the healthcare worker, the diagnosed patient and the portal. Each page contains a limited set of instructions read by the healthcare worker to the patient, like a script.
• Stay in sync with how the app works → This was important to avoid confusion on the user’s end. It was also important to synchronize app and portal updates if the one-time key app flow changed.

Phonetic alphabet

To help people receive their one-time key over the phone, we developed a new phonetic alphabet that would be more accessible to diverse community members. This alphabet is meant to be used by the portal users to clearly communicate the letters included in the one-time key, which is composed of 10 alphanumeric characters. The goal was to reduce the potential for incorrect one-time keys.

We used the following principles to choose the words used in the phonetic alphabet:

• the words are similar in English and French;
• they are cross-cultural nouns;
• they are at least 2 syllables;
• they have evocative spoken sounds;
• they don’t have negative connotations.

Related blog post: Communication is key: A phonetic alphabet for COVID Alert

Design artifacts

Onboarding user flow

This onboarding flow represents the path of a person using the COVID Alert portal for the first time.

The user first receives an invitation to a training. If they can attend, they attend the training to learn more about the COVID Alert app, the health portal, and one-time keys, and they receive training material. If they can’t attend, they will be provided with the training material.

Then, the user receives an email invitation to use the portal. They click the link in the email. If the link is expired, they’re instructed on how to get a new invitation. If the link is valid, they can start creating their account by entering their personal information. If the user has a mobile phone, they’ll receive a two-factor authentication code by text message. If they don’t have a mobile phone, they’ll be provided with 10 single use codes.

Then, the user authenticate themselves using an authentication code. If the code is not correct, they can ask to resend it by text message or re-enter it. If the code is correct, they land on the welcome page. They click on Continue and land on a page to generate a key. They click on Generate key and land on a page with the one-time key to read out.

Portal information architecture

This diagram represents the information architecture of the COVID Alert portal.

When a user is not authenticated, they can create an account or log in on the home page. They can also see the About section and the Support page from the top navigation menu. In the About section, they can get information on: COVID Alert in general, generating one-time keys, and managing teams. In the footer, they can access Contact us, Privacy, and Terms of use.

When a user is authenticated, they gain access to generating one-time keys. The steps for this features are listed. They also have access to Manage your account, where they can manage their personal information. Admins have access to Manage team, where they can view and manage team members, add new accounts, and manage portal invitations.

Portal technical overview

The COVID Alert portal allows healthcare workers to generate one-time keys that they can give to patients diagnosed with COVID-19. Keys are good for 24 hours, and each account can generate 100 keys in a 24-hour period.

The main goals of the service are to make it easy to use for healthcare workers distributing codes to patients and for it to be extremely difficult for unauthorized actors/users to gain access to the application. The portal complements the COVID Alert app.

Source code information and repository

The COVID Alert portal is a Django application: it can be run as a python process or using docker-compose

• Running the COVID Alert portal locally as a python process requires python3 and a database, although an SQLite database will be created if no connection string exists.
• Using docker-compose, you’ll need Docker installed.

The GitHub portal repo contains all code pertaining to the COVID Alert portal.

The code is organized in different apps. The main app is portal, but we have several other supporting custom apps created for the project – about, announcements, covid_key, invitations, contact, backup_codes, profiles, register and outbreaks. In the main directory (i.e. covid-alert-portal) the .env file contains all the settings for any API keys, authorization keys/details, database URLs and any other configuration details not contained in the settings.py file.

Repository Structure

Folder	Purpose
/.github/workflows	CI/CD pipelines/workflows
/about	About app
/announcements	Announcements app
/backup_codes	Backup codes app
/config	AWS infrastructure and Terraform configuration
/contact	Contact app
/covid_key	Covid Key app
/google_analytics	Google analytics code and configuration
/locale/fr/LC_MESSAGES	French translations and language settings
/outbreaks	Outbreaks app
/portal	Main app
/profiles	Profiles app
/protoc-3.15.4-linux-x86_64	Binary version of the protocol buffer compiler (protoc)
/register	Register app (QR code)
/staticfiles	Home of all static files generated

Please read the Portal README file to know more about:

• how to build and run the app;
• continuous development and feature development;
• automated tests;
• application versioning.

Technology stack

• Python
• Django framework
• PostgreSQL DB (or SQLite DB if no connection info is provided)
• AWS infrastructure:
  • Fargate – Serverless compute
  • Elastic Container Registry – Container registry
  • Route 53 – Domain name services
  • Certificate Manager – TLS certificates
  • Elastic Load Balancing – Load balancing
  • CloudFront – Content delivery network
  • WAF – Web application firewall
  • Terraform – Management

Third party tools used

We use several third-party services for an improved development workflow and continuous security.

• GitHub is a cloud-based service that stores our source code, tracks code changes and facilitates code reviews.
• GitHub Actions is a Continuous Integration and Deployment (CI/CD) service that allows us to test and deploy our code right from GitHub.
  • CI/CD services abound, but we used GitHub Actions because it was easy to set up, and with its yml-based configuration it would be easy to move away from.
• Heroku is a fully-managed platform as a service. We use Heroku Review Apps to build disposable applications per pull request, facilitating code reviews.
• Docker is a platform as a service that uses OS-level virtualization to deliver software in containers. Containers encapsulate an application and bundle application code together with all of the related configuration files, libraries, and dependencies required for it to run. Portal can run as an app on a Docker container.
• Terraform is an infrastructure as code (IaC) tool that allows you to build, change, and version infrastructure. Portal uses terraform scripts to deploy to AWS.
• Snyk is a software as a service product that scans through our dependencies for packages with known issues. It alerts us when a version of a package we’re using has a known exploit.
• LGTM is a software as a service product for continuous security analysis. It analyzes each pull request for potential security vulnerabilities.
• Flake8 is an advanced linter that analyzes python code.
• Black is a python code formatter.

Security and privacy

The following security features have been implemented in the COVID Alert portal:

• 2 factor authentication for registered users (django_otp, otp_notify, otp_yubikey);
• defence against Cross Site Request Forgery (CSRF);
• cross site scripting (XSS) protection;
• SQL injection protection;
• SSL and HTTPS only requests;
• host header validation;
• same origin referrer policy;
• session security.

Accessibility

Accessibility guidelines followed based on CDS Accessibility Handbook.