Skip to content
This repository has been archived by the owner on Jan 31, 2024. It is now read-only.

Latest commit

 

History

History
171 lines (125 loc) · 9.92 KB

DEVELOPMENT.md

File metadata and controls

171 lines (125 loc) · 9.92 KB

FHIR Works on AWS Development Instructions

Prerequisites for development

Note
Please complete the FHIR Works on AWS Deployment Installation and deploy the initial fhir-works-on-aws code to your AWS account. If you use Implementation Guides with your deployment, follow these steps to deploy locally:

FHIR Works on AWS is written in TypeScript. We recommend that you configure your IDE to render TypeScript errors and warnings. To ensure your IDE displays TS properly, see this guide on code formatting using ESLint.

This repository uses Rush as the monorepo manager and pnpm as its package manager. Please complete the Developer tutorial to learn about Rush.

  1. Clone the repo: git clone https://github.com/aws-solutions/fhir-works-on-aws
  2. Open to the directory: cd fhir-works-on-aws
  3. Install rush: npm install -g @microsoft/rush
  4. Run rush update.
    This ensures rush is setup, which includes installing NPM packages as defined in the package.json files.

Local development flow

  1. After you have deployed the initial fhir-works-on-aws code your AWS account, create a feature branch from develop: git pull; git checkout develop; git checkout -b feature/<feature>.

    See FHIR Works on AWS Deployment Installation, if you have not yet deployed the initial code.

  2. Run either:

    • rush build - performs incremental build. See rush build -h for more options.
    • rush rebuild - performs a full clean build. See rush rebuild -h for more options.
  3. Run rush test to test and update the code coverage summary in the README file for each package. See rush test -h for more options.

    Alternatively you can use: rush build-test to perform rush build && rush test for each package. See rush build-test -h for more options.

  4. Run rush lint-fix to fix issues with ESLint.

Note
To install new packages or dependencies, do not use npm install. Refer to the documentation on modifying package.json for more details.

Packages can be added/updated in two ways:

  • Run rush add -p <PACKAGE_NAME> --caret.
    Always use the --caret or version with the caret symbol (example-lib@^1.2.3). Not including the caret installs tilde versions(e.g. ~1.2.3) by default. See rush add -h for more options.
  • Update the package.json in your package and run rush update.

Staging a Pull Request

Note
For information on our process for contributing via pull request, see Contributing via Pull Requests.

  1. Follow Local Development Flow to make changes locally.
  2. Ensure you are on a feature branch; from the develop branch:
    git pull;
    git checkout develop;
    git checkout -b feature/<feature>
    
  3. Once you complete your code changes and it passes test, push your changes to your feature branch:
    git add -A;
    git commit
    

    Note
    The commit must be in conventional commits format.

  4. Fill out any required commitizen fields triggered by git commit.

    Note
    We have pre-commit git-hooks. These are used to inspect the snapshot that's about to be committed, to see if you've forgotten something, to make sure tests run, or to examine whatever you need to inspect in the code. We currently support:

    • git-secrets prevents you from committing passwords and other sensitive information to a git repository
    • prettier automatically formats your code on commit. If you want to format your code manually you can just run git add -A; rush prettier.
    • generate code coverage summary in the root README file

    We have commit-msg git-hook configured:

  5. Run git push.

Further checks are triggered on a Pull Request.

Rush everyday commands

rush update
This ensures rush is setup, which includes installing NPM packages as defined in package.json files.

rush update --purge
The --purge option deletes temporary files created by Rush. This is useful if you are having problems and suspect that cache files may be corrupt.

rush install
The rush install command installs package dependencies for all your projects, based on the pnpm-lock.yaml file that is created/updated using rush update.

Run either:

  • rush build
    Performs incremental build. See rush build -h for more options.
  • rush rebuild
    Performs a full clean build. See rush rebuild -h for more options.

rush test
Runs test and updates code coverage summary in README file for each package. See rush test -h for more options

rush add
Adds a specified package as a dependency of the current project (as determined by the current working directory), and then runs rush update. Always use the --caret or version with caret symbol(example-lib@^1.2.3). Not including the caret installs tilde versions(e.g. ~1.2.3) by default.

  • rush add -p example-lib --dev --caret
    Adds package to the devDependencies only for the current project (cd /path-to-your-project first)
  • rush add -p example-lib --all --dev --caret or rush add -p example-lib@^1.2.3 --all --dev
    Caret specifier for SemVer dependencies
  • rush add -p example-lib --all --dev --caret --make-consistent
    Make all devDependency for a package consistent across all projects
  • rush add -p [email protected] --all --dev or rush add -p example-lib --exact --all --dev
    Adds package to all the projects as devDependencies (installs the exact version, use this if there is a need for exact version or else always install dependencies and devDependencies with --caret option)

By default, using rush commands triggers them for all of the projects in the monorepo, but if you want to trigger a command just for a specific package then (for example trigger commands just for fwoa-core/interface package):

  1. Go to projects root folder - cd ./fwoa-core/interface.
  2. Instead of running commands using rush use rushx, example:
    • run build - rushx build
    • run test - rushx test
    • run lint:fix - rushx lint-fix

Commands applicable for developers with existing GitHooks

rush cinstall/cupdate usage instructions:

  1. git checkout develop
  2. git checkout -b < your new branch >
  3. rush install --bypass-policy (This will install the cinstall and cupdate commands)
  4. Start using rush cinstall or rush cupdate instead of rush install or rush update.

Fix pnpm audit errors

  1. In <rootDir>/common/config/rush/pnpm-config.json update:

    "globalOverrides": {
        "`<packageName>`":  "`<suggestedVersion>`"
    }
    
  2. rush update --recheck --bypass-policy

  3. rush cinstall/cupdate

  4. cd common/temp; pnpm audit --prod -> this should report no vulnerabilities

Getting support for rush

Getting Support

Troubleshooting

Accessing Logs and Debugging on FWoA

FWoA logs and debugging are handled by Amazon CloudWatch, and you can utilize FWoA CloudWatch logs alongside identity provider (IdP) logs to identify past API search requests. For more information, see What is CloudWatch.

Identifying past API searches requires cross analyzing timestamps between the two log sources to correlate the issuance of a credential to past FWoA API requests.

Note
Amazon CloudWatch retains search query content for GET requests, but not POST requests.

To obtain and analyze FWoA logs:

  1. Sign in to the AWS Console and navigate to CloudWatchLog Groups.

  2. From the list of log groups, select the Lambda function or API Gateway service that you would like to debug:

    • /aws/lambda/smart-fhir-service-{STAGE}-fhirServer
      Contains all logs from the FWoA API server, including transactions and requests. In most cases, this will be the primary log group to check when receiving errors from the FWoA server.
    • /aws/api-gateway/fhir-service-{STAGE}
      Contains all logs related to the API Gateway setup for FWoA.
    • /aws/lambda/smart-fhir-service-{STAGE}-ddbtoES
      Contains all logs from the process of writing DynamoDB resources to ElasticSearch.
  3. Select a stream to view the output for the function. If applicable, the Lambda function version will be prefixed in square brackets ([]) to help identify which stream corresponds to which version (example: YYYY/MM/DD/[{VERSION}]).

  4. (Optional) To further refine the output of the function, filter the events in a stream using the options at the top of the list. Additionally, you can perform broader searches through Logs Insights located on the left panel.

  5. To compare FWoA logs with your third-party IdP’s logs, match the FWoA Cloudwatch log stream log events with timestamps from the IdP logs.