hmpps-electronic-monitoring-datastore-ui

UI application to access historical data from the Electronic Monitoring Datastore.
This is a front end for the Electronic Monitoring Datastore API.

Contents

• hmpps-electronic-monitoring-datastore-ui
  • Contents
  • Oauth2 Credentials
    • Auth Code flow
    • Client Credentials flow
  • Dependencies
    • HMPPS Auth
    • REDIS
  • Running the app
    • Running the app via docker-compose
    • Running the app in VS Code for development
    • Logging in with a test user
  • Linting and testing
    • Run linter
    • Run unit tests
    • Run integration tests using Cypress
  • Custom Component details
    • EMS Service Information
    • EMS Sortable Table
    • EMS Date Filter
    • EMS Search Form
    • EMS Button Grid
  • Mock API
  • Test Utils

Oauth2 Credentials

The app is set up to run with two sets of credentials, each one support a different oauth2 flows.

Auth Code flow

These are used to allow authenticated users to access the application. After the user is redirected from auth back to the application, the typescript app will use the returned auth code to request a JWT token for that user containing the user's roles. The JWT token will be verified and then stored in the user's session.

These credentials are configured using the following env variables:

• AUTH_CODE_CLIENT_ID
• AUTH_CODE_CLIENT_SECRET

Client Credentials flow

These are used by the application to request tokens to make calls to APIs. These are system accounts that will have their own sets of roles.

Most API calls that occur as part of the request/response cycle will be on behalf of a user. To make a call on behalf of a user, a username should be passed when requesting a system token. The username will then become part of the JWT and can be used downstream for auditing purposes.

These tokens are cached until expiration.

These credentials are configured using the following env variables:

• CLIENT_CREDS_CLIENT_ID
• CLIENT_CREDS_CLIENT_SECRET

Dependencies

HMPPS Auth

To allow authenticated users to access your application you need to point it to a running instance of hmpps-auth. By default the application is configured to run against an instance running in docker that can be started via docker-compose.

NB: It's common for developers to run against the instance of auth running in the development/T3 environment for local development. Most APIs don't have images with cached data that you can run with docker: setting up realistic stubbed data in sync across a variety of services is very difficult.

REDIS

When deployed to an environment with multiple pods we run applications with an instance of REDIS/Elasticache to provide a distributed cache of sessions. The template app is, by default, configured not to use REDIS when running locally.

Running the app

Running the app via docker-compose

The easiest way to run the app is to use docker compose to create the service and all dependencies:

Run docker compose pull then docker compose up

If you want to run both the UI and the API locally:

Run docker-compose -f docker-compose-with-api.yml up.
This will run all services in the same network so they can talk to one another.
You may need to change the reference in the docker-compose-with-api.yml file to point to your local API project source if it isn't in a sibling folder to your UI project.

Running the app in VS Code for development

1. Install dependencies using npm install, ensuring you are using node v20

   Note: Using nvm (or fnm), run nvm install --latest-npm within the repository folder to use the correct version of node, and the latest version of npm. This matches the engines config in package.json and the CircleCI build config.

2. Start the services required for the UI app using:
   docker compose up --scale=hmpps-electronic-monitoring-ui=0

3. Build the assets and start the app with esbuild: npm run start:dev

   This uses an .env file replicating the environment variables in docker-compose.yml (which themselves replicate/simulate the values in the .helm folders). Rename .env.example -> .env to use these values.

   Environment variables set in here will be available when running start:dev

Logging in with a test user

Once the application is running you should then be able to login with:

username: AUTH_USER password: password123456

To request specific users and roles then raise a PR to update the seed data for the in-memory DB used by Auth

Linting and testing

Run linter

• npm run lint runs eslint.
• npm run typecheck runs the TypeScript compiler tsc.

Run unit tests

npm run test

Run integration tests using Cypress

1. For local running, start a wiremock instance: docker compose -f docker-compose-test.yml up

2. Ensure you have built the app by running npm run build

3. Then, run the server in test mode: npm run start-feature (or npm run start-feature:dev to run with auto-restart on changes)

4. Either, run tests in headless mode with npm run int-test or run tests with the cypress UI with npm run int-test-ui.

Custom Component details

A small number of bespoke components were created for this project. They are listed below. Each of these components' names are prefixed with EMS (Electronic Monitoring Service) to help developers distinguish between them and pre-existing GOV.UK / MoJ components.

EMS Service Information

This is a simple info banner that is shown on every page. It provides information abut the data that can be accesed using this service.

EMS Sortable Table

The MoJ design system includes a sortable table. Columns can be sorted by clicking on a column heading. However this component was not designed to work with pagination. When records are sorted, only the current page's records are reordered.

The EMS sortable table combines sortable columns and pagination. When records are sorted, all of the pages of records are reorganised.

The EMS sortable table takes an object of records as an argument, and converts these into a paginated sortable table.

EMS Date Filter

CMT needs to be able to filter some tables and timelines by date.

The EMS date filter is designed for this.

It is currently designed to work with the EMS Sortable Table. It can be extended to work with a customised version of the MoJ Timeline component.

It includes some client-side date input validation.

EMS Search Form

Currently this javascript component just adds client-side date input validation to the search page. It could be extended to include additional client-side input validation.

EMS Button Grid

This is a simple responsive grid of buttons used in the order summary page. It was created by applying some custom styles to a govuk-button-group component.

Mock API

As this repo isn't currently connected to a live data source, pages are populated using mock data. To facilitate API integration in the future, this data is obtained using mock APIs.

• /server/data/mockData contains simple typescript scripts that return objects of mock case data.
• /server/data/ contains mock API endpoints that retrieve and return this data.
• server/routes/index.ts access these endpoints when routes are accessed, then route the user to the appropriate page populated with the mock data.
• In some cases the mock data is processed before being passed into the page template. For example, an array of data objects may be converted into an array of HTML elements that can be used in a page template. The scripts for such transformations are in /server/utils. They are imported & used in server/routes/index.ts.

Test Utils

Test utilities for hmppsAuthClient and datastoreClient are found in ./server/data/testUtils/mock.ts. As paths differ between running the application normally (in dist) and where ts-jest runs it, ApplicationInfo has to be mocked first. Otherwise, Import from '..' (server/data/index.ts) fails