Create new endpoint for form instructions documents (handles s3 + DB)

[chris-kuryak]

Summary

Managing form instructions documents is slow and cumbersome as it requires manually uploading the file to s3 with very specific info, and then manually insert it into the DB. To alleviate this, we want to create a new endpoint and script to automate this process.

We want to create a PUT /alpha/forms/{form_id}/form_instructions/{form_instruction_id} endpoint that will take in a file and handle uploading it to s3.

Request

The request for this won't quite be JSON as it needs to be able to take in a file, we've done this before with endpoints like our POST /application/../attachments endpoint (can reuse quite a bit of the logic from that probably). The only parameters that the request needs to take

Response

A simple success, no info needs to be returned.

Auth

This endpoint should ONLY accept api_user_key_auth (the other form endpoints accept the older deprecated auth, no need to add that here).

Similar to our PUT /alpha/forms/:form_id endpoint, we want to require a user have the UPDATE_FORM privilege to use the endpoint. Because we aren't putting the other legacy auth, we don't need the very convoluted approach to auth that the form update endpoint had. The auth should also go in the service function, not the route itself.

Logic

This is a PUT endpoint and if a form instruction file already exists, we'll want to update it. Roughly the logic should be:

• See if an existing form instruction record exists with the ID provided
• If not - create it
• Upload the file to s3 (copy a similar pattern from the POST app attachment endpoint including how to get the file name). We want to upload this file to s3://{public_files_bucket_path}/forms/{form_id}/instructions/{file_name}
• If the form instruction record already existed, if the file path on s3 wasn't exactly the same, delete the old file path.
• NOTE: At no point do we need to check if the form itself exists, due to the way the data models connect, we actually would use this endpoint first. We only include the form ID in the path so we can put it in the s3 path

This ticket is to create the endpoint.

For context, here’s what it takes to setup forms the first time in an environment: https://navasage.atlassian.net/wiki/spaces/Grantsgov/pages/2259157056/Setup+Forms+-+Nov+17th+2025

Acceptance criteria

• Endpoint created
• Tests added