Update docs and scripts

.gitignore

@@ -1,6 +1,7 @@
 .env
 .vscode
 .DS_Store
+local_env.sh
 
 node_modules/
 

api/package.json

@@ -16,7 +16,7 @@
     "start:ts": "npm run build && node --inspect=0.0.0.0:9222 --nolazy build/server.js",
     "start:dev": "nodemon --watch 'src/**/*.ts' --exec \"npm run start:ts\"",
     "tunnel": "myapp_guid=$(cf app --guid $APP_NAME) && TUNNEL=$(cf curl /v2/apps/$myapp_guid/env | jq -r '[.system_env_json.VCAP_SERVICES.\"aws-rds\"[0].credentials | .host, .port] | join(\":\")') && echo 'Rat tunnel active' &&cf ssh -N -L 5432:$TUNNEL $APP_NAME",
-    "tunnel:stage": "APP_NAME=assessment-staging npm run tunnel",
+    "tunnel:stage": "APP_NAME=assessment-tool-stage npm run tunnel",
     "tunnel:demo": "APP_NAME=smeqa-demo npm run tunnel",
     "tunnel:prod": "APP_NAME=assessment-tool npm run tunnel",
     "watch": "tsc -w -p ."

assessmentHurdleExamples/readme.md

@@ -0,0 +1,73 @@
+# Creating a new hiring action
+
+For any hiring action that you create you will need 5 files:
+
+- `applicants.csv`
+- `assessmentHurdle.json`
+- `competencies.json`
+- `specialties.json`
+- `users.json`
+
+Examples of these are all located in `resumeYesNoOnlySmall`, with more details below.
+
+## Applicants.csv
+These should be exported from USA Staffing after the hiring action has been set up correctly to export and import candidates. This file should not be changed at all, but should be able to be uploaded directly into the tool. 
+
+There are exceptions to this, for example when doing complex hiring actions or hiring for multiple positions/grades.
+
+Fields that you need to pay specific attention to here are:
+`Vacancy ID`, `Assessment ID`, and `Rating Combination`
+
+The Vacancy ID and Assessment ID should match those in the `assessmentHurdle.json` and the Rating Combination should match the `localId` field in the `specialties.json` file.
+
+## assessmentHurdle.json
+
+This file sets up your hiring action with both meta details and also also decides how many evaluations will be required for each action.
+
+Due to the prototype nature of this application, there are some fields that are not used, which will be listed below:
+
+- departmentName: String
+- componentName: String
+- positionName: String
+- assessmentName: String - e.g. Resume Review or Written Assessment
+- positionDetails: String - e.g. GS 10
+- locations: String
+- startDatetime: Datetime - unused
+- endDatetime: Datetime - unused
+- hurdleDisplayType: integer - use 1
+- evaluationsRequired: integer
+- hrEmail: string
+- hrName: string
+- vacancyId: string
+- assessmentId: string
+
+## competencies.json
+
+This file lists out all the competencies and possible selections for them. 
+
+A competency has:
+- name: string - the name of the competency
+- localId: string - an unexposed unique identifier for the competency that will be used in the `specialties.json` file.
+- definition: string -  this is shown in an expandable field when evaluators want to review their understanding of the competency/field.
+- requiredProficiencyDefinition: string - this is always shown above the selectors for an evaluator.
+- displayType: integer - This is used to change how the competency is displayed, default to 1 unless you have a specific, known, use case.
+- sortOrder: integer
+- screenOut: boolean - whether a failure in this field overrides point value summations that could pass a candidate, usually true.
+- selectors: These are the possible radio values that an evaluator will see when doing an evaluation:
+    - displayName: string - the text next to the radio button
+    - defaultText: string - what will be filled in for the reason when this is selected.
+    - sortOrder: integer
+    - pointValue: integer - this determines how many "points" this selector is worth. These points are used to determine if a candidate passes, meets, or exceeds a specialty.
+
+## specialties.json
+
+This file contains all the specialties that an action is evaluating. Due to the prototype nature of the application we recommend only using one.
+- name: string - unused by the frontend, but useful for auditing and understanding what is going on.
+- categoryRatings: the only valid categories are "does_not_meet", "meets", and "exceeds". "Exceeds" is not required, but "meets" and "does_not_meet" are.  The points are the sum total of all competency points required to pass. If any of the competencies failed were `screenOut` competencies, then the applicant will fail this specialty regardless of their total sum of points. The `nor` code is what will be put into the exported file from the tool for re-upload into USA Staffing.
+- localId: string - this should match the `Rating Combination` from the `applicants.csv` that is being evaluated by this specialty.
+- competencyLocalIds: `[string]` - a list of the `competencies.json` `localId`s that comprise the evaluation of this specialty.
+
+## users.json
+
+There are two roles: 
+Role of type `1` are HR uses, role of type `2` are SME users.

assessmentHurdleExamples/written_test/applicants.csv

@@ -1,6 +1,6 @@
 Vacancy ID,Assessment ID,Application ID,Application Rating ID,Applicant Last Name,Applicant First Name,Applicant Middle Name,Application Number,Rating Combination
-swelocalid,swelocalid,1,82,George,Washington,,USDSSMEQAA-1234,swelocalid
-swelocalid,swelocalid,2,67,Ginsburg,Ruth,,USDSSMEQAA-3557,swelocalid
-swelocalid,swelocalid,3,68,Smith,Adam,,USDSSMEQAA-6457,swelocalid
-swelocalid,swelocalid,4,61,Walton,Mary,,USDSSMEQAA-7457,swelocalid
-swelocalid,swelocalid,5,62,Hopper,Grace,,USDSSMEQAA-3957,swelocalid
+swelocalid,swelocalid,1,82,Test George,Washington,,USDSSMEQAA-1234,swelocalid
+swelocalid,swelocalid,2,67,Test Ginsburg,Ruth,,USDSSMEQAA-3557,swelocalid
+swelocalid,swelocalid,3,68,Test Smith,Adam,,USDSSMEQAA-6457,swelocalid
+swelocalid,swelocalid,4,61,Test Walton,Mary,,USDSSMEQAA-7457,swelocalid
+swelocalid,swelocalid,5,62,Test Hopper,Grace,,USDSSMEQAA-3957,swelocalid

db/migrations.sh

@@ -1,4 +1,6 @@
 #!/bin/bash
+# Create a local_env.sh file with the following field for the appropriate postgres server:
+# export POSTGRES=
 . ./local_env.sh
 echo ${POSTGRES}
 psql ${POSTGRES} -a -f ./migrations/01_drop_table.sql

docs/Cold Start.md

@@ -5,20 +5,41 @@ Cold Start:
     - This will also be your route
 2. Services ->micro  Create new service -> Market place service -> DB_NAME
     - RDS psql
+    - Bind to application created in step 1 - no parameters
+        - if this fails, follow the binding steps in `db/README.md`
     - For prod, ensure it's redundant
 3. Ensure that you have the correct permissions:
     - Space needs to have "trusted local_networks_egress" security group
+    - to see secuirty groups for your space: `$ cf space <space> `
+    - to update them: <EXERCISE LEFT FOR USER> 
 4. Create Github action deployment secrets:
-    - cf create-service cloud-gov-service-account space-deployer $SPACE_DEPLOYER_NAME
-    - cf create-service-key $SPACE_DEPLOYER_NAME $SPACE_DEPLOYER_NAME_KEY
-    - cf service-key $SPACE_DEPLOYER_NAME $SPACE_DEPLOYER_NAME_KEY
+    - ```sh
+        $ export SPACE_DEPLOYER_NAME=<SERVICE_ACCOUNT_NAME>
+        $ cf create-service cloud-gov-service-account space-deployer $SPACE_DEPLOYER_NAME
+        $ cf create-service-key $SPACE_DEPLOYER_NAME ${SPACE_DEPLOYER_NAME}_KEY
+        $ cf service-key $SPACE_DEPLOYER_NAME ${SPACE_DEPLOYER_NAME}_KEY
+    ```
         - This will output the CF_USERNAME and CF_PASSWORD
 5. Add service keys to github actions
     - set CF_USERNAME and CF_PASSWORD to {env}_CF_PASSWORD and {env}_CF_USERNAME in github
+    - these are referenced in `.github/workflows`
+    - ensure correct `organization` and `space` in `.github/workflows`
+    - ensure correct `name` `urls` and `services` in `.deploy${ENV}`
+    - ensure buildpack supports your node version in `api/package.json` https://github.com/cloudfoundry/nodejs-buildpack/releases
 6. Run a deployment
 7. Confirm you can connect to the DB:
-    > cf connect-to-service $APP_NAME $DB_NAME
+    > `$ cf connect-to-service $APP_NAME $DB_NAME`
 8. Update the DB by running the migrations
+    > Ensure that api/package.json has correct APP_NAME for tunnel
+    > Create Tunnel: `api $ npm run tunnel:stage`
+    > Grab the postgres uri: `cf curl /v2/apps/$(cf app --guid $APP_NAME)/env | jq -r '[.system_env_json.VCAP_SERVICES."aws-rds"[0].credentials | .uri]'`
+    > Create a `db/local_env.sh` file and ensure it has a line as follows:
+    ```
+    # Staging Env
+    export POSTGRES=postgres://<USERNAME>:<PASSWORD>@localhost:<PORT>/<DB_NAME>
+    # You should only need to replace the URL with "localhost". The username, password, port, and db name should all work.
+    ```
+    > Once this is done, you should be able to run `db/migrations.sh`
 9. Create login.gov creds: https://developers.login.gov/oidc/getting-started/
     - See `util/gencert.sh`
 10. Create an app in the login.gov partner dashboard

util/gencert.sh

@@ -3,6 +3,5 @@ export KEYDATE=$(date +"%m-%d-%y")
 
 for KEY in dev stage prod
 do
-    openssl req -nodes -x509 -days 365 -newkey rsa:2048 -keyout ${KEY}_private_${KEYDATE}.pem -out ${KEY}_public_${KEYDATE}.crt -subj "/C=US/ST=District of Columbia/L=Washingtonq/O=Office of Management and Budget/OU=United States Digital Service/CN=usds.gov/[email protected]"
-    openssl rsa -in ${KEY}_private_${KEYDATE}.pem -out ${KEY}_private_${KEYDATE}.key
+    openssl req -nodes -x509 -days 365 -newkey rsa:2048 -keyout ${KEY}_private_${KEYDATE}.pem -out ${KEY}_public_${KEYDATE}.crt -subj "/C=US/ST=District of Columbia/L=Washingtonq/O=Office of Management and Budget/OU=United States Digital Service/CN=usds.gov/[email protected]"
 done