Send Letter Service

Architectural Diagram

You can edit this diagram by importing ./doc/arch/diagram.drawio into draw.io.

Swagger API Specs

Table of Contents

• Overview
  • Bulk Print
  • Send Letter Service
• Running the application
  • Prerequisites
  • Quick Start
  • Locally
  • Docker environment
• Onboarding new services
• License

Overview

Bulk Print

Send Letter is a key part of the Bulk Print system infrastructure. At a high level, Bulk Print is a system that allows a Document Owner (DO) to send a request to a 3rd party Printing Company (PC). The PC will then print and post the letter to a Recipient.

Send Letter Service

Send Letter Service's role in the system is to:

• Receive the requests from the DOs and store this information (PDF byte data) to its database
• Periodically check these letter requests and upload the letters to the server of the PC. (UploadLettersTask)
• Periodically fetch reports from the PC's server checking if the letter has been posted and updating its database accordingly. (MarkLettersPostedTask)
• Send daily report of uploaded letters
• Send weekly report of letters that were uploaded more than six days before current date but have not been posted (stale letters)

Running the application

Prerequisites

• JDK 17
• Project requires Spring Boot v3.x to be present

Quick Start

An alternative faster way getting started is by using the automated setup script. This script will help set up all bulk scan/print repos including send-letter-service and its dependencies. See common-dev-env-bsbp repository for more information.

Locally

Follow list of required environment variables defined in ./docker/env.list in order to be able to run application. Additionally local application will require configured database so add/amend LETTER_TRACKING_DB_* variables as needed. Once everything is set up, run application by simply:

$ ./gradlew bootRun

Docker environment

For convenience there is a docker compose configuration file docker-compose-sample.yml. Default properties have been provided to allow the functional and smoke tests to be run against the docker images.

$ docker-compose up -d

Test:

$ curl http://localhost:8485/health

{"status":"UP","details":{"diskSpace":{"status":"UP","details":{"total":62725623808,"free":57405022208,"threshold":10485760}},"db":{"status":"UP","details":{"database":"PostgreSQL","hello":1}},"liveness":{"status":"UP"},"refreshScope":{"status":"UP"},"hystrix":{"status":"UP"}}}

curl -X POST -H "Content-Type: application/json" "http://localhost:4552/testing-support/lease" -d '{"microservice":"send_letter_tests"}'

S2S_TOKEN

curl -X POST -H "Content-Type: application/vnd.uk.gov.hmcts.letter-service.in.letter.v2+json" -H "ServiceAuthorization: Bearer S2S_TOKEN" "http://localhost:8485/letters" -d '{"documents":["aGVsbG8="],"type":"BPS001"}'

{"letter_id":"f015a4dd-cfa5-4b2b-9fb0-e43ad6ceea35"}

Document provided in sample is not actual document. It has to be valid PDF.

Swagger spec can be found here.

Onboarding new services

Before a service can be onboarded, it needs to be set up in service-auth-provider-app (S2S) (see its README). Once microservice becomes known to S2S, it can be set up in Send Letter Service's application config.

Creating a new folder on the FTP server

Each request to send a letter results in Send Letter Service uploading a zip file to a service-specific folder on the FTP server that belongs to an external provider which prints and posts physical letters. In order to enable Send Letter Service to work with a new service, an appropriate folder needs to be created on the FTP server (both production and test instance). The change needs to be done by the service provider.

Changes in application.yaml

This section describes the changes that need to be made in application.yaml file.

Reports section

Under reports.service-config add a new entry that will provide a displayable name for the service. This is needed for creating reports.

reports:
  service-config:
    - service: ...
      ...
    - service: {name of the service in S2S, e.g. divorce}
      display-name: {displayable name of the service, e.g. Divorce}

FTP section

Under ftp.service-folders add a new entry that will provide information about the FTP folder where letters from the service should be uploaded. Each service should have its own folder assigned.

ftp:
  service-folders:
    - service: ...
      ...
    - service: {name of the service in S2S, e.g. divorce}
      folder: {destination folder name, e.g. DIVORCE}

Note! This can only be deployed once ftp provider has created folder in all relevant environments.

Using the service

This section contains some helpful information about talking to Send Letter Service. Swagger specification for the API can be found here

Sending a letter request

In order to request sending a letter, retrieve a token from S2S and call the send letter endpoint. Here's an example curl command for this:

curl -X POST -H "Content-Type: application/vnd.uk.gov.hmcts.letter-service.in.letter.v3+json" -H "ServiceAuthorization: Bearer {s2s_token}" "http://rpe-send-letter-service-{env}.service.core-compute-{env}.internal/letters" --data @body.json

where

• env is the environment name
• s2s_token is the service authentication token retrieved from S2S
• body.json is a file whose content follows the following format:

{
  "documents": [
    {
      "content": "{Base64-encoded content of the PDF file}",
      "copies": {number of copies to print, e.g. 2}
    },
    ...
  ],
  "type": "{document type, as agreed between product teams}",
  "additional_data": { ... }
}

The order of documents in the envelope will be the same as provided in the request. additional_data is an optional JSON object where services can store any additional information about the letter, e.g. a corresponding ID in their system.

You can get the Base64-encoded content of a pdf file by executing the below command, this will copy the base64 output for you:

base64 -i test_file.pdf | pbcopy

If your request is successful, you should receive a response containing the ID of the newly created letter:

{"letter_id":"f015a4dd-cfa5-4b2b-9fb0-e43ad6ceea35"}

A response like this means Send Letter Service has registered the request. The process of posting a letter is asynchronous and takes days.

Checking the status of a letter

Once the request to send a letter is accepted, the status of the letter can be checked using the status endpoint. Here's an example command that sends the request:

curl -X GET  "http://rpe-send-letter-service-{env}.service.core-compute-{env}.internal/letters/{id}"

where

• env is the environment name
• id is the ID of the letter in Send Letter Service, as returned by send letter endpoint

Here's what a response body should look like:

{
    "id": "0001307e-69e5-4ffe-b5f6-1acd73db95bb",
    "status": "Posted",
    "message_id": "4fd61ac3f28b4df5ef1a5c10dffa2eb7",
    "checksum": "401b30e3b8b5d629635a5c613cdb7919",
    "created_at": "2020-01-12T01:02:03.123Z",
    "sent_to_print_at": "2020-01-13T01:02:03.123Z",
    "printed_at": "2020-01-14T01:02:03.123Z"
}

A letter can be in one of the following statuses:

• Created - request has been accepted and is awaiting further processing
• Uploaded - Send Letter Service has uploaded the letter to the external provider's system
• Posted - letter has been physically posted
• Aborted - processing of the letter has been aborted (result of a manual intervention)
• Skipped - letter was skipped due to an unrecoverable issue (requires manual action)

License

This project is licensed under the MIT License - see the LICENSE file for details