microsoft/community-organization-operations-suite

Applications & tools for Community-Based Organizations (CBOs) to work together more effectively

Community-Based Organization Operations Suite (CBO Suite)

The CBO Suite is a case-management web application that enables CBOs and members of CBOs to work together more effectively.

Developing

Prerequisites

• NodeJS LTS Release
• Yarn v1 global installation (npm i -g yarn)
• docker-compose OR a MongoDB connection string defined in the environment variable DB_CONNECTION_STRING.

If you are using GitHub Codespaces with the provided devcontainer, these prerequisites are provided.

To start the application:

> yarn
> yarn start:db // (optional) for local development
> yarn assets:
> yarn start:

Branch & Release Strategy

Environments & Mapped Branches:

• dev branch: synchronized w/ integration environment.
• staging branch: synchronized w/ staging environment.
• main branch: synchronized w/ production & demo environments.

Active development is performed in feature branches and synchronized into the dev branch as it stabilizes. When a sprint completes, the dev branch is merged into the staging branch. When the release is approved, the staging branch will be merged into the main

Development Branches: The following branch naming patterns are utilized for different kinds of efforts within the project. All branches should target the dev branch, except for hotfix branches, which may target both dev and main.

• Bugfixes: fix/*
• Features: feature/*
• Hotfix: hotfix/*
• CI: ci/*
• Documentation: docs/*
• Testing: test/*
• Refactoring: refactor/*

Testing

Please refer to the readme in packages/acceptance-tests for testing instructions.

Localization

The application is developed to support multiple locales. Text displayed to the user, either directly on the site or through emails (ex: password reset) will use the locale selected by the user to determine the language. To achieve this, all text displayed to the user must be read from asset files and must not be hardcoded in the application.

There are two places in the application where localized strings exist:

• GraphQL API
• Web Application

Both of those projects have a locales subfolder (src/locales). In turn, each supported locale will have a subfolder in the locale folder. The text to display is captured in JSON files structured by locale folder. The JSON files are heirarchical key -> value pairs that map keys to their display text values. For example, the following details basic text keys for the page title and account header.

{
  "pageTitle": "My Profile",
  "_pageTitle.comment": "Page title displayed in the browser tab",
  "account": {
    "header": {
      "title": "My Profile",
      "_title.comment": "Header title text",
      "userName": "Username",
      "_userName.comment": "Username field label",
      "userSince": "User since",
      "_userSince.comment": "User since field label",
      "numOfAssignedEngagements": "# of Currently Assigned Requests",
      "_numOfAssignedEngagements.comment": "# of Currently Assigned Requests for Assistance field label",
      "totalEngagementCompleted": "Total Requests Completed",
      "_totalEngagementCompleted.comment": "Total Requests Completed field label"
    }
  }
}

A few things to note from the above:

• account.header.title would be used in the application to display My Profile
• The keys starting with an _ and ending with .comment do not need to be translated as they are informational only

When it comes time to display text to the user, the application will use the specified locale to lookup the text to use by key. The locale will default to en-US if not otherwise specified. Furthermore, if a key does not exist for the specified locale, then the text will be taken from the en-US locale file.

To update the displayed text, it is sufficient to update the locale JSON files. Once these files have been updated and pushed to the appropriate branch, the updated text will be picked up by the application.

Operations & Deployment

The GitHub Actions CI workflow is used to automate the deployment of the app in accordance with the branching strategy described above. The infrastructure required for an instance of the application is:

1. A MongoDB compatible database. We use CosmosDB with MongoDB driver.
2. A NodeJS web-server environment for the GraphQL API.
3. A static website deployment (Azure Blob Storage/S3) for the web application. This may be CDN-hosted or self-hosted in static storage.
4. A SendGrid account for sending automated emails (e.g. password reset emails).
5. (optional) A Firebase account for In-App Notifications.

Configuration

The application uses the config package to manage configuration settings per hosted environment. The following environment variables may be defined to override configuration settings:

• API environment variables

  • DB_CONNECTION_STRING (required): The MongoDB connection string for the database.
  • JWT_SECRET (strongly recommended): A secret, random string used for salting JWT tokens.
  • SENDGRID_API_KEY (required for email): The SendGrid API key.
  • EMAIL_FROM (required for email): The email address used for sending automated emails.
  • CONTACT_US_EMAIL (required for email): The email address used for customer support.
  • PORT (optional): the port the application is running on. This is provided by default from the Azure App Service runtime.
  • FIREBASE_AUTH_URI (optional): The Firebase Auth URI for the Firebase account.
  • FIREBASE_TOKEN_URI (optional): The Firebase Token URI for the Firebase account.
  • FIREBASE_AUTH_PROVIDER_X509_CERT_URL (optional): The Firebase Auth Provider X509 Cert URL for the Firebase account.
  • FIREBASE_TYPE (optional): The Firebase type for the Firebase account.
  • FIREBASE_PROJECT_ID (optional): The Firebase project ID for the Firebase account.
  • FIREBASE_PRIVATE_KEY_ID (optional): The Firebase private key ID for the Firebase account.
  • FIREBASE_PRIVATE_KEY (optional): The Firebase private key for the Firebase account.
  • FIREBASE_CLIENT_EMAIL (optional): The Firebase client email for the Firebase account.
  • FIREBASE_CLIENT_ID (optional): The Firebase client ID for the Firebase account.
  • FIREBASE_CLIENT_X509_CERT_URL (optional): The Firebase client X509 Cert URL for the Firebase account.

• Web App environment variables

  • API_URL (required): The URL of the GraphQL API this webapp will communicate with.
  • SOCKET_URL (required): The URL of the sockets API this webapp will communicate with.

community-organization-operations-suite's Issues

Delete specialist confirmation has no text

"Delete Specialist" button opens a dialog that has no text showing!

Test Issue 1

AB#148627

Modal sheet close button is sometimes blocked by fields

In some cases the X button to close the model sheet can be blocked by fields. We've seen this happen with the Add Client form as well as the Edit Service Record form. See screenshot

Redesign the requests/dashboard page to avoid stacked lists

The current design of the dashboard has three lists of requests on top of each other (My requests, Requests, and Closed requests). This is inefficient and makes it hard to add features such as sort or filter, because you would need to put them on each of the three lists.

Whether using tabs or another solution, this issue tracks a new design for the page (TBD).

Reporting: Default to most recent service (or first)

When on the reporting page selecting services, the system should default to the most recently viewed service (by that user). If no service has been viewed by that user, then the system should default to the first service listed.

Add a visual indication that lets you know which environment you're in (prod/demo/integ)

Right now all of the environments look identical. It's hard to remember if im in demo or production. Let's add some visual indication. Here is a recommended design.

Improved design of quick actions

Today's quick actions on the dashboard page feel out of place and we have not heard of any CHW using them. We believe in some cases CHWs will still want to quickly access this functionality. Let's seek to better understand what would be helpful and redesign this functionality.

Warn user when possibly entering a duplicate client

We should warn users if they are about to enter a client with the same name as an existing name, so they avoid duplicates. Note this is NOT the same as issue #324. We want to make the case where two people really have the same name easier, and we want to help users avoid adding duplicates if they are talking about the same person.

Tables: Long single words don't wrap

In a table if we have a word that is longer than the space it is given (for example, a request title) it will overflow into the next column. We should consider an ellipsis or wrapping in this case.

Paging Lists

All queries for lists of data should be updated to allow for paging. Initially, the page size will be 20 rows. Note that the UI elements already use paging. However, that paging is on the client side only. The client queries for the complete set of data, and then displays only the relevant data (caching the rest).

This feature is to be implemented to minimize the negative impacts of low bandwidth. In situations where a large amount of data exists and the user has a slow connection, trying to download MBs of data on every request provides a very poor UX.

Requests: Set title character limit to 200

Right now the character limit on requests titles is too short, 50. Let's up it to 200.

Tables: Improved column spacing

In today's data tables the column spacing is very inefficient. Some columns with lots of content get squeezed while others with short or no content get more space than they need. We should revisit the way column spacing works.

Replace Tag Pulldown Select Filter With Table Column Filter

On the Tags page, the pulldown select filter should be removed. Instead, The tag listing table should allow the user to filter by tag.

Tables: Reusable table component

Right now reporting has a table with lots of functionality that is not present on the other pages. We should consider a cleaned up table that brings some of that functionality to other pages. Including:

• Filtering on columes
• Sort by any column
• Hide/show columns
• Moving the page controls to the top
• optional search field
• Export and print

Improve navbar responsiveness to use space more efficiently

As you move to a smaller device or window, today's navbar loses the most important links first before the less commonly used language and setting buttons. Let's improve on this design.

There are a few subtasks here:

• Ensure page titles stick around as long as they can
• Remove "hello" from the username
• Remove language from the navbar
• Put language on the Account page (requires reorg of page, see below)

Screenshot from Tom showing some of the issues:

Always use "Start" service, not "Record"

In the Service Quick Start on the dashboard, the buttons to enter kiosk mode say "record service" instead of "start service" which is what we use elsewhere. Let's be consistent.

Steps:

• Go to dashboard
• Click Start a Service, under Service Quick Start

In the sheet that opens you'll see the title says "Start a service" but the buttons say "Record Service". Let's make the buttons say "Start Service"

Requests: description field has a weird character limit

The description field on a request seems to have a character limit of 2. It won't let you enter 1 character, but 2 is ok. This is an optional field, let's just remove the limit.

Requests: Improve design of assigned specialist vs "added" specialists

Currently there are two relationships specialists can have to a request. One specialist at a time can be "assigned" the request to handle. This means its in their queue. Specialists can also be "added" meaning they get a notification to take a look.

The exact difference and the UI around these two things is confusing. Let's revisit the use case for adding and redesign this functionality.

Telemetry: Service Added Event Tracking

The system should track key events to help determine use of the system as well as potentially identify problem areas.

Why:
To track feature usage, as well as time from signup to value

Where:
User clicks Create Service to save a new service

What:

• Organization ID
• Client-Linked (boolean whether the service is set to link with clients)

Cant use same email on two different environments

Summary: It won’t let me create an account on demo if I use that email on prod.

Steps to reproduce:

• Create an account on production (I actually have one on prod with a real CBO, I use [email protected])
• Log in to demo (you can use [email protected] / worHem-pogsy9-sigpir if you want)
• Go to Specialists
• Click Add Specialist
• Fill out the info for the new person you want. Use the same email address you have on production.

Results:
Expected - it lets me create the account in demo since I havent used that email yet
Actual - Nothing happens, but in console I see an error about using the same email (see screenshot).

Note:
I’m not sure if this is a feature or a bug! What do you think? Maybe we shouldn’t allow the same email on two environments. Maybe instead we just fix the “+” issue and force folks to use a “+” in their email so they are clear which one is demo and which is production?

Clients Table Sorting

When in the clients view, the table should be sortable by the user. The user should be able to sort the table by any column. The user should be able to specify whether to sort in ascending order or descending order. The user should be able to remove the chosen sort order. Sorting should only be done by one column at a time.

Clients: Improvements to Other option for demographics fields

Let's improve the Other field where it's used on client demographics.

• If the textbox is selected automatically choose Other
• If Other is selected and then the user clicks one of the other radio buttons, clear the text field

Requests: add label to description when looking at detail view

Currently when you look at the details of a request (click on the request title), the description is shown but without a label. Let's add a label for clarity.

Revisit the language of services/requests/clients

We've been calling the main objects in HCH services, requests, and clients. There has been some confusion over services and requests with CHWs new to the tool. Let's revisit the terms used and the mental model of the application to see if we can better match how CBO staff see their work. Research needed.

Some field inappropriately suggesting autofill with address

Some fields in the client form are using the browser's autofill feature to suggest filling them with the user's contact info, when they should not. Let's disabled autofill for these fields.

Clients: Rename field from "Additional tags" to just "Tags"

Change label to just read "Tags"

Merge “reporting” page back in the other pages

The reporting page is duplicative with the other pages, except with filtering. For example, there is a Clients page with one list of clients and the same list in reporting, just with filter buttons. Let's look at folding the filter and sort functionality back into the other pages, leaving room for a "proper" reporting page.

Bug: Emails with “+" don't work

(Filing on Daniel's behalf)

Background:
It’s important for testing that testers be able to create more than one account, while being able to get any emails that are sent to that account. It’s also important for customer support folks to have an account on the demo environment, even if they have one on production. A convention for doing this is to add “+something” in the email before the @ in the address. Email servers know to send [email protected] to [email protected]. Unless there is some better solution we should play nice with this convention.

Steps to reproduce:

• Log into the demo environment
• Go to specialists
• Add a new specialist with your email but with +test in it, like [email protected] or [email protected].
• Check your inbox for the sign up email
• Click the button to log in with that email and the password the email contains

Results:
Expected - log in to a new account
Actual: I get the error messages below

Searching services is broken

The search field on Services is broken. You can only search for "e"!

New copy and design for the logged out page to reflect “HCH”

The logged out page needs to have its copy and design revamped to reflect HCH. The new copy is pending.

Telemetry: Tag Added Event

The system should track key events to help determine use of the system as well as potentially identify problem areas.

Where:
User clicks Create Tag to save a new tag

Fields:

• Organization ID
• Category

Persist Displayed Fields

In the reporting page, the displayed fields for a given table should be persisted on a per user basis. Whenever the user navigates back to the reporting page and selects a report they had previously selected, the previous list of displayed fields needs to be used when building the table. Whenever the user updates the list of displayed fields, the updated list should be remembered so that it can be used the next time the user navigates to the same table. The list of fields to display selected by one user should not impact the list of fields to display for another user.

The system needs to remember the field list even if the user logs out or shuts down the system.

Reporting: Ability To Reorder Columns

In the reporting page, users should be able to reorder the columns in any table. Reordering should be done by letting the user move a column left or right one position at a time.

Telemetry: Request Added Event

The system should track key events to help determine use of the system as well as potentially identify problem areas.

Where:
User clicks Create Request to save a new request

Fields:

• Organization ID
• Page (page the request was added from)
• Client Count
• Has Due Date
• Specialist Assigned
• Has Tags

Telemetry: Request Closed Entry

The system should track key events to help determine use of the system as well as potentially identify problem areas.

Why:
How many CBOs are using requests.

Where:
User clicks Request Complete

Fields:

• Organization ID
• Time open (in seconds)
• Timeline Entry Count (number of entries in timeline)

Requests: In new/edit request form, separate tag and specialists fields from description field.

Currently, in the form where you would add, edit or update a request, the description field has buttons for other fields "on the bottom". This adds an extra step if you want to, for example, add a tag. You have to click Add Request Tag and THEN choose your tag. We should make these their own fields with labels.

Note there are two places to improve. The form used to add or edit a request has Add Request Tag attached to the description field (first screenshot). If you go to update a request (click on the request title, instead of the "Edit" button) you'll see you can add a tag OR specialist (second screenshot).

Help CHWs differentiate between clients that have the same name

Sometimes CBOs serve two people with the same name. We want to help them easily distinguish between the two. Design TBD.

Reporting: Basic Print Command

In the reporting page, users need to be able to print the table data. A new action should be added to the top of the table to let the user print the contents of the table. The printed version of the data should respect the filtering, the selecting fields, and the ordering of the table from which it was generated. The printed version should repeat the header whenever a page break occurs.

Telemetry: Service Entry Added Event

The system should track key events to help determine use of the system as well as potentially identify problem areas.

Why:
Understand usage over time, part of active, usage by platform

Where:
User clicks Submit after filling out a service's form

Fields:

• Organization ID

Dashboard - Waiting for Requests to load block the quick actions

While the dashboard is waiting to be loaded with Requests the quick action panels are not rendered/usable.

Screen.Recording.2022-02-16.at.10.56.07.mov

Footer Visual Style

Footer shouldn't have a shadow, visually conflicts with pockets on reporting page.

Requests: Put a label on the description field

Currently the description field has no label. Let's add one so it's clearer what's going on!

Tables: User can sort by any column

On the reporting page, the user should be able to sort rows in every table by any column. The user should be able to sort in ascending or descending order. Sorting should only be done on one column at a time.

Clients: add a notes field

Let's add a notes field on the client object. In new/edit client forms let's put it below Tags and above the demographics.

Service row fails to update

I observed a CHW attempt to edit a service record from the reporting page. Upon clicking submit a red banner appeared saying "Failed to update service record".

Steps to reproduce:

• CHW was on Firefox
• Went to reporting page, selected a service
• Clicked "Edit" on the top row
• In the sheet that opened she changed one thing (it was a required single-select field)
• She clicked Submit at the bottom

Results:
Expected - the service record is updated
Actual - we got an error message (see attached)

Notes:
I had her open the console. There were no errors and no messages that seemed relevant.

Screenshots:
Small screenshot to keep PII out

Delete Tags

The user should be able to delete tags. Right now, users can created tags, edit them but are unable to remove them. Users should have the ability to delete existing tags. When a user deletes a tag, the deleted tag should be removed from every entity that currently has the tag.

Persist Selected Filters

In the reporting page, the selected filters for a given table should be persisted on a per user basis. Whenever the user navigates back to the reporting page and selects a report they had previously selected, the previous list of filters needs to be used when building the table. Whenever the user updates the list of filters, the updated list should be remembered so that it can be used the next time the user navigates to the same table. The list of filters selected by one user should not impact the list of filters for another user.

The system needs to remember the filter list even if the user logs out or shuts down the system.

Telemetry: Tag Applied Event

The system should track key events to help determine use of the system as well as potentially identify problem areas.

Where:
Upon clicking Save after adding a tag to a client, request, or service

Fields:

• Organization ID
• Tag ID
• Used On (type of data it's used on)

Requests: Improved design for closing requests

Currently there are two buttons for closing requests. "Request Complete" and "Close Request". This is confusing. We have also had CBO feedback that they would like to require CHWs to add a note when closing a request. So let's revisit this design entirely.

Add Webapp Tests

The webapp package has basically no tests. Simple unit tests to increase code coverage and build confidence when modifying the code should be added. It is not necessary to aim for complete coverage, but core functions should be tested, as well as a bit more general testing to hit key areas of the application.