efs-submission-api

The Emergency Filing Service API is responsible for handling and processing EFS applications submitted by users.

API users (including efs-submission-web) interact with efs-submission-api by sending HTTP requests containing JSON to service endpoints. Service endpoints available in efs-submission-api as well as their expected request and response models are outlined in the Swagger specification file.

The service integrates with a number of internal and external systems. This includes FES, chs-notification-api (via Kafka) and efs-document-processor (via AWS SQS) to notify applicants and internal users if/when an application has been submitted, converted, accepted or rejected.

Fees

See this document for details and how to implement a change: Upload a Document (EFS) Service - Fees.

Requirements

To build efs-submission-api, you will need:

• Git
• Java
• Maven
• MongoDB
• Apache Kafka
• Internal Companies House core services

You will also need a REST client (e.g. Postman or cURL) if you want to interact with any efs-submission-api service endpoints.

Certain endpoints (e.g. POST /efs-submission-api/events/submit-files-to-fes) will not work correctly unless the relevant environment variables are configured.

Building and Running Locally

1. From the command line, in the same folder as the Makefile run make clean build
2. Configure project environment variables where necessary (see below).
3. Ensure dependent Companies House services are running within the Companies House developer environment
4. Start the service in the CHS developer environment
5. Send a GET request using your REST client to /efs-submission-api/healthcheck. The response should be 200 OK with status=UP.
6. A database named efs_submissions and the following collections are required:

Collection name	Description	Data
submission	id, dates, presenter, form & file details	this and the database will be created by the service upon starting a submission, then populated as the user enters their data
category_templates	the 'groupings' for the forms	reference data manually populated from: src/main/resources/category_templates.json
form_templates	the form ids, names etc.	reference data manually populated from: src/main/resources/form_templates.json
company_auth_allow_list	emails of IP's who are allowed to see and submit Insolvency forms	manually populated e.g. {"emailAddress": "[email protected]"}
payment_charges	payment templates required by payment service	reference data manually populated from: src/main/resources/payments_templates.json

Configuration

System properties for efs-submission-api are defined in application.properties. These are normally configured per environment.

Certain form types will be sent by efs-submission-api to FES while other form types will be emailed to the relevant org unit. Properties relevant to either scenario are labelled accordingly.

Variable	Description	Example	Mandatory (always, email, FES)
BARCODE_SERVICE_URL	The barcode service URL (used to generate barcodes for applications sent to FES)	http://example.com	always
FILE_TRANSFER_API_URL	The file transfer API URL (used to check the anti-virus status of uploaded PDF files)	http://example.com	FES
FILE_TRANSFER_API_KEY	The file transfer API key	MYTRANSFERAPIKEY	FES
MONGO_EFS_API_DB_NAME	The name of the collection responsible for storing EFS documents	collection_name	always
MONGODB_URL	The URL of the MongoDB instance where documents and application data should be stored	mongodb://mongohost:27017	always
REF_PATTERN	The pattern that randomly generated submission numbers will follow	############	always
REF_SYMBOL_SET	Set of characters permitted in randomly generated submission numbers	abc123	always
MANAGEMENT_ENDPOINTS_ENABLED_BY_DEFAULT		false	always
MANAGEMENT_ENDPOINT_HEALTH_ENABLED		true	always
MANAGEMENT_ENDPOINTS_WEB_PATH_MAPPING_HEALTH		healthcheck	always
MANAGEMENT_ENDPOINTS_WEB_BASE_PATH		/efs-submission-api	always
LOGGING_LEVEL	Log message granularity	INFO	always
REQUEST_LOGGING_LEVEL	Request log message granularity	WARN	always
EFS_MAX_QUEUE_MESSAGES	Maximum number of submissions that will be retrieved by /efs-submission-api/queue-files	50	FES
AWS_SQS_QUEUE_URL	URL of a FIFO SQS queue that file conversion requests will be published to	http://example.com	FES
KAFKA_CONFIG_RETRIES		5	always
KAFKA_CONFIG_IS_ROUND_ROBIN		true	always
KAFKA_CONFIG_ACKS		WAIT_FOR_ALL	always
EMAIL_SCHEMA_URI		http://example.com	always
INTERNAL_REG_FUNC_EMAIL	The email address that will be used for registry power forms	[email protected]	always
INTERNAL_CHANGE_CONSTITUTION_EMAIL_ADDRESS	The email address that will be used for change constitution forms	[email protected]	always
AWS_REGION	The AWS region that efs-submission-api will use when connecting to AWS services	aws-region	always
FILE_BUCKET_NAME	The S3 bucket that uploaded PDF files will be stored	s3-bucket-name	email
AWS_ACCESS_KEY_ID	The access key ID of the AWS account that efs-submission-api will use when connecting to AWS	MYAWSACCESSKEYID	always
AWS_SECRET_ACCESS_KEY	The secret access key of the AWS account that efs-submission-api will use when connecting to AWS	MYAWSSECRETACCESSKEY	always
EFS_MESSAGE_PARTITION_SIZE	The maximum number of messages that efs-submission-api will send to AWS SQS (must be less than 10)	10	FES
TIFF_BUCKET_NAME	The S3 bucket that converted TIFF files will be retrieved from	s3-bucket-name	FES
FES_JDBC_URL	A JDBC URL referring to a FES database	jdbc:oracle:thin@chd-feshostname:1521:fesdbname	FES
FES_JDBC_DRIVER_CLASS	The fully qualified class name of the driver that will be used to connect to FES	oracle.jdbc.OracleDriver	FES
FES_JDBC_USERNAME	The username that will be used to connect to FES	username	FES
FES_JDBC_PASSWORD	The password that will be used to connect to FES	password	FES
CHIPS_JDBC_URL	A JDBC URL referring to a CHIPS database	jdbc:oracle:thin@chd-chipshostname:1521:chipsdbname	FES
CHIPS_JDBC_DRIVER_CLASS	The fully qualified class name of the driver that will be used to connect to CHIPS	oracle.jdbc.OracleDriver	FES
CHIPS_JDBC_USERNAME	The username that will be used to connect to CHIPS	username	FES
CHIPS_JDBC_PASSWORD	The password that will be used to connect to CHIPS	password	FES
FILE_LINK_EXPIRY_IN_DAYS	The number of days after which email links to uploaded PDF files will expire	7	email
INTERNAL_SCOTTISH_PARTNERSHIPS_EMAIL_ADDRESS	The email address that will be used for Scottish Partnership forms	[email protected]	always
PLANNED_MAINTENANCE_START_TIME	Datetime for start of out-of-service period (exclusive). Only applicable if the period end is also configured. Allowed format: see Notes	2 Dec 23 01:00 GMT 14 July 24 00:30 +01	optional; requires End time (see below)
PLANNED_MAINTENANCE_END_TIME	Datetime for end of out-of-service period (exclusive). Only applicable if the period start is also configured. Allowed format: see Notes	2 Dec 23 02:30 GMT 14 July 24 03:30 +01	optional; requires Start time (see above)
PLANNED_MAINTENANCE_MESSAGE	Message to return during the out-of-service period	Service is undergoing planned maintenance	optional; default value UNAVAILABLE - PLANNED MAINTENANCE

Notes

Planned maintenance format: d MMM yy HH:mm z|x where

• MMM is the 3-letter month abbrev. (case sensitive: e.g. Nov not NOV)
• z is the zone short name e.g. GMT
• x is the 2-digit zone offset from UTC e.g. +01 (= British Summer Time)

CAUTION: Use zone offset +01 for Daylight Saving Time (British Summer Time). Zone short name BST denotes Bangladesh Standard Time (UTC+06) not British Summer Time (UTC+01).

Building the docker image

mvn -s settings.xml compile jib:dockerBuild -Dimage=169942020521.dkr.ecr.eu-west-1.amazonaws.com/local/efs-submission-api

Running Locally using Docker

1. Clone Docker CHS Development and follow the steps in the README.

2. Enable the efs module

3. Run chs-dev up and wait for all services to start

To make local changes

Development mode is available for this service in Docker CHS Development.

./bin/chs-dev development enable efs-submission-api

This will clone the efs-submission-api into the repositories folder inside of docker-chs-dev folder. Any changes to the code, or resources will automatically trigger a rebuild and reluanch.

Terraform ECS

What does this code do?

The code present in this repository is used to define and deploy a dockerised container in AWS ECS. This is done by calling a module from terraform-modules. Application specific attributes are injected and the service is then deployed using Terraform via the CICD platform 'Concourse'.

Application specific attributes	Value	Description
ECS Cluster	filing-maintain	ECS cluster (stack) the service belongs to
Load balancer	{env}-chs-internalapi	The load balancer that sits in front of the service
Concourse pipeline	Pipeline link Pipeline code	Concourse pipeline link in shared services

Contributing

• Please refer to the ECS Development and Infrastructure Documentation for detailed information on the infrastructure being deployed.

Testing

• Ensure the terraform runner local plan executes without issues. For information on terraform runners please see the Terraform Runner Quickstart guide.
• If you encounter any issues or have questions, reach out to the team on the #platform slack channel.

Vault Configuration Updates

• Any secrets required for this service will be stored in Vault. For any updates to the Vault configuration, please consult with the #platform team and submit a workflow request.

Useful Links

• ECS service config dev repository
• ECS service config production repository