direct-file/direct-file/submit/README.md

MEF Submit

If you use a proxy, first see MAVEN_OPTS in the project readme and the OMB Connect readme for information about ensuring your proxy settings are passed to all build steps.

Prerequisites

Setup dependencies and build

Note

For setup please see the most up-to-date instructions which are found in the Onboarding docs.

• Set an environment variable, MEF_REPO, whose value is the path where you want the MeF SDK repo cloned to. You can set this up in your shell dotfile to have it loaded each time automatically. E.g.

  echo EXPORT MEF_REPO="~/irs/mef-sdk" >> ~/.zprofile
  

• Build and install the dependencies and build the submit app.

  INSTALL_MEF=1 ../scripts/build-project.sh
  

• Verify that java files exist in the efile directory

Running the application locally

• Follow the pre-requisite steps
• Set the 'MISSING' application.yaml properties. Setting test values for etin, asid, and efin listed below should work for local development where a connection to a MeF client is not required for your development work. NOTE: If you need to connect to the Mef client for your development work, you will need to use a separate set of variables, set the missing keystore values, and there may be additional setup specific to the MeF Client.

  submit:
      etin: 11111
      asid: 22222222
      efin: 333333
  

• Run the application (you can do this from your IDE or the command line)

  # To use the command line run the following from the project root
  ./mvnw compile
  ./mvnw spring-boot:run -Dspring-boot.run.profiles=development
  

Docker

Ensure that the appropriate environment variables are set up depending on how you are running the application. See environment below.

Build the application:

docker compose build mef-submit

Then run it:

docker compose up -d mef-submit

The app probably failed for you due to lack of configuration. You can look at the reason why it failed to start with:

docker compose logs mef-submit

Running locally

Environment

Set the following environment variables in your local environment which will facilitate running both the applications as well as the docker containers. On MacBooks, placing the export statements below in the .zshrc (gets run and evaluated every time a shell instance is started) or .zprofile (gets run and evaluated when a user logs in) file will accomplish this. If using the bash shell, placing them in .bashrc should do (and effectively behave similar to .zshrc).

# Get the base64 encoded keystore from a fellow developer and replace the value in between quotes with the actual value
export SUBMIT_KEYSTORE_KEYSTOREBASE64="[base64-encoded-keystore]"

# Get the keystore password from a fellow developer and replace the value in between quotes with the actual value
export SUBMIT_KEYSTORE_KEYSTOREPASSWORD="[keystore-password]"

# Get the keystore alias from a fellow developer and replace the value in between quotes with the actual value
export SUBMIT_KEYSTORE_KEYSTOREALIAS="[keystore-alias]"

# Get the ASID value for the submit application from a fellow developer and replace the value in between quotes with the actual value
export SUBMIT_ASID="[submit-asid]"

# Get the EFIN value for the submit application from a fellow developer and replace the value in between quotes with the actual value
export SUBMIT_EFIN="[submit-efin]"

# Get the ETIN value for the submit application from a fellow developer and replace the value in between quotes with the actual value
export SUBMIT_ETIN="[submit-etin]"

# Replace wa with your own initials *** NOTE: characters must be lowercase ***
export SUBMIT_ID_VAR_CHARS="wa"

You'll also need to set up the LOCAL_WRAPPING_KEY following the instructions in the backend README

export LOCAL_WRAPPING_KEY="[local-wrapping-key]"

Maven command for running the application locally:

./mvnw spring-boot:run -Dspring-boot.run.profiles=development

Developer Notes

Files in the direct-file/submit/src/main/java/gov/irs/directfile/submit/gen directory are generated by the direct-file/utils/mef-code-generator application.

Static Analysis

We use SpotBugs and PMD for static code analysis in this app. The app is configured to have pre-commit hooks run SpotBugs and PMD.

Spotbugs and PMD both generate static analysis reports that can be used to resolve issues in the project.

PMD is configured view an xml file that specifies the linting rules we adhere to

How do I see the reports?

To see a formatted html page for the static analysis reports you can run:

./mvnw compile site:run

This will start a site at localhost:9898. Navigate to Project Reports and then click on PMD or Spotbugs to view errors in the app.

If you want to ignore the pre-commit hook that runs spotbugs do:

git commit --no-verify

To generate each report, you can run:

./mvnw compile spotbugs:spotbugs

./mvnw pmd:pmd

The xml file this generates isn't very readable, so use ./mvnw spotbugs:gui for an interactive guild or run ./mvnw site to see an html report of the xml report.

To check if the project currently passes static analysis:

./mvnw compile spotbugs:check

./mvnw pmd:check

SpotBugs also offers a local gui that displays information based on the output of spotbugs. Calling compile before spotless:gui, ensures we have all the latest changes reflected in the spotbugs report.

./mvnw compile spotbugs:gui

I've also configured the build to generate the spotbugs report when you run ./mvnw clean compile. SpotBugs looks at the generated target folder of the project, so doing a ./mvnw clean compile will ensure you're seeing the latest spotbugs report.

For more information on Spotbugs:

Docs Site: https://spotbugs.readthedocs.io/en/latest/introduction.html

Github Repo: https://github.com/spotbugs/spotbugs

Maven Spotbugs Plugin Docs: https://spotbugs.github.io/spotbugs-maven-plugin/plugin-info.html

PMD Docs Site: https://docs.pmd-code.org/latest/index.html

PMD Java Rules: https://docs.pmd-code.org/latest/pmd_rules_java.html

PMD Maven Plugin Docs: https://maven.apache.org/plugins/maven-pmd-plugin/index.html

Health Check

The Submit App uses Spring Boot Actuator to expose a health check endpoint. When running the app locally, the health check endpoint should be available at:

http://localhost:{PORT}/actuator/health

Tests

Run tests locally with ./mvnw test