hmpps-electronic-monitoring-create-an-order-api

Contents

• About this project
• Get started
  • Using IntelliJ IDEA
• Usage
  • Running the application locally
    • Calling endpoints
      • Generate a token for a HMPPS Auth client
    • Running the application locally with the UI

About this project

An API used by the Create an Electronic Monitoring Order UI, a service that allows users to create electronic monitoring orders. It's built using Spring Boot and Kotlin as well as the following technologies for its infrastructure:

• AWS - Services utilise AWS features through Cloud Platform.
• CircleCI - Used for our build platform, responsible for executing workflows to build, validate, test and deploy our project.
• Cloud Platform - Ministry of Justice's (MOJ) cloud hosting platform built on top of AWS which offers numerous tools such as logging, monitoring and alerting for our services.
• Docker - The API is built into docker images which are deployed to our containers.
• Kubernetes - Creates 'pods' to host our environment. Manages auto-scaling, load balancing and networking to our application.

Get started

Using IntelliJ IDEA

When using an IDE like IntelliJ IDEA, getting started is very simple as it will handle installing the required Java SDK and Gradle versions. The following are the steps for using IntelliJ but other IDEs will prove similar.

1. Clone the repo.

git clone git@github.com:ministryofjustice/hmpps-electronic-monitoring-create-an-order-api.git

2. Launch IntelliJ and open the hmpps-electronic-monitoring-create-an-order-api project by navigating to the location of the repository.

Upon opening the project, IntelliJ will begin downloading and installing necessary dependencies which may take a few minutes.

3. Enable pre-commit hooks for formatting and linting code.

./gradlew addKtlintFormatGitPreCommitHook addKtlintCheckGitPreCommitHook

Usage

Running the application locally

To run the application using IntelliJ:

1. Run docker compose pull && docker compose up --scale hmpps-electronic-monitoring-create-an-order-api=0 , which will just start a docker instance of the database and HMPPS Auth.
2. Create a .env file in the root level of the repository with the following contents. Populate variable values from Kubernetes secret serco-secret

SERCO_AUTH_URL=
SERCO_CLIENT_ID=
SERCO_CLIENT_SECRET=
SERCO_USERNAME=
SERCO_PASSWORD=
SERCO_URL=

3. Click the drop-down button for the HmppsElectronicMonitoringCreateAnOrderApi run configuration file in the top right corner, and select Edit Configurations.
   • For the 'Active Profiles' field, put 'local'
   • You may also need to set the JDK to openjdk-23 or openjdk-21
   • Click on Modify options -> Choose Environment Variables
   • For the 'Environment Variables' field, put path to .env file
   • Apply these changes
4. Click the run button.

Or, to run the application using the command line:

setup environment variables:

run setup script

./scripts/create-env.sh

and then

SPRING_PROFILES_ACTIVE=local ./gradlew bootRun

Then visit http://localhost:8080/health.

Calling endpoints

As part of getting the HMPPS Auth service running locally, the in-memory database is seeded with data including a number of clients. A client can have different permissions i.e. read, write, reporting, although strangely the column name is called ​​autoapprove.

If you wish to call an endpoint of the API, an access token must be provided that is generated from the HMPPS Auth service.

Generate a token for a HMPPS Auth client

curl -X POST "http://localhost:8090/auth/oauth/token?grant_type=client_credentials" \ 
-H 'Content-Type: application/json' \
-H "Authorization: Basic $(echo -n hmpps-electronic-monitoring-cemo-ui:clientsecret | base64)"

This uses the client ID: hmpps-electronic-monitoring-cemo-ui and the client secret: clientsecret. A number of seeded clients use the same client secret.

A JWT token is returned as a result, it will look something like this:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...BAtWD653XpCzn8A",
  "token_type": "bearer",
  "expires_in": 3599,
  "scope": "read write",
  "user_name": "CEMO.INTEGRATION",
  "sub": "CEMO.INTEGRATION",
  "auth_source": "none",
  "jti": "Ptr-MIdUBDGDOl8_qqeIuNV9Wpc",
  "iss": "http://localhost:8090/auth/issuer"
}

Using the value of access_token, you can call this API using it as a Bearer Token.

There are a couple of options for doing so such as curl or Postman.

Running both the UI And the API locally

The Create an Electronic Monitoring Order UI uses HMPPS Auth in development (rather than locally with Docker).

To interact with the API using the front end, with both running locally:

1. In the application-local.yml file in the API, change the HMPPS Auth URL value from http://localhost:8090/auth to https://sign-in-dev.hmpps.service.justice.gov.uk/auth
2. Run the UI locally, using the UI documentation
3. Run the API locally using the same steps outlined in get started, but replacing the command in step 1 with docker compose pull && docker compose up --scale hmpps-electronic-monitoring-create-an-order-api=0 --scale hmpps-auth=0 to start a docker instance of the database but not HMPPS Auth.

There is no need to generate a HMPPS Auth token, as authentication is handled by the front end. Valid personal credentials will be needed to sign in via the UI.

Running integration test locally

1. For running integration tests locally, start localstack of SQS queues by:

   docker compose -f docker-compose-test.yml up

2. Using command line to run integration test:

   ./gradlew integration