This project was generated using Nx. Nx is a set of Angular CLI power-ups for modern development.
30-minute video showing all Nx features
- Docker
- Python 2
- NodeJs 14.x
- @angular/cli (
npm install -g @angular/cli)
The following environment variables are required to run the application:
- S3 Credentials to be populated in
docker-compose.ymland withinapps/server/confg/default.jsonunder payload bucket and key - SMTP details if you want to send emails to users. These can be populated in
apps/server/config/default.jsonunder email
To get started quickly, you can use the docker-compose.yml file in the root of the project. This will start a FHIR server, a KeyCloak server, and the ERSD server. The FHIR server and KeyCloak server will be pre-configured with the necessary data to run the ERSD server, however an additional step is needed to configure the KeyCloak with the ERSD client.
To start the servers, run the following command from the root of the project:
npm install && npm run build
docker compose up
Once the servers are running, you must configure the ERSD client in KeyCloak. To do this, you can run the script at in the root of the project:
./apps/keycloak/configure
While developing the application, you can run npm run dev to hot reload latest changes.
After the servers are running, you can access the ERSD application at http://localhost:3333 and login with:
username: johndoe
passowrd: password
npm run build
cd DEPLOY_LOCATION/server
node main.js
When developing the application, DEPLOY_LOCATION is the "dist" directory. The server must be run from the DEPLOY_LOCATION so that the "config" directory is relative to the working directory of the server.
- Build both the client and the server
- Copy both "client" and "server" directories from the "dist" directory into your destination deployment directory
- Run the server
Add the --watch flag to both "ng build" commands to have the application automatically re-built when changes are detected to source code (.ts files).
DEPLOY_LOCATION is the "dist" directory while developing.
Run ng test to execute the unit tests via Jest.
Run ng e2e to execute the end-to-end tests via Cypress.
The application uses the config module to provide environment/deployment configurations to the server. A portion of the configuration is dedicated to the client/browser application. When the client/browser application launches, the client/browser application asks the server for the client config.
To override the default configuration for a specific deployment, either
- Create a "local.json" file in the config directory of the server app
- Create sn environment-specific json file in the config directory of the server app (such as "production.json") and create an environment variable on the server called "NODE_ENV" with a value of "production" (for example).
The overriding config file can be a complete copy of the default.json file with modifications, or it can include only the properties that you want to override in the default.json.
| Property | Description |
|---|---|
| server | Generic configuration properties for the entire server |
| port | The port that the server application runs on |
| authCertificate | The certificate that should be used to validate authentication tokens provided by the UI |
| fhirServerBase | The base url of the FHIR server that provides data to the ERSD components |
| subscriptionCriteria | The criteria to be used for each of the subscriptions that the end users setup. See here for more details. |
| enableSubscriptions | Primarily for debugging purposes. When false, modified subscriptions are disabled (off). When true, modified subscriptions are submitted to the FHIR server with a status of "requested". See here for more details. |
| restrictedResourceTypes | A list of resource types that are restricted from the FHIR proxy provided by the server. It is suggested that at least Person and Subscription be restricted, because these are resources directly influenced by the server and may include sensitive user information |
| contactInfo | Configurable properties related to contact information expiration reside in this group |
| checkDurationSeconds | Represents how often the ERSD server should check for expired contact information. Every iteration will pull down a full list of the people registered in ERSD (the FHIR server) and check each of their last modified date to determine whether their information has expired. |
| checkCountPerPage | Represents how many people can be requested from the FHIR server in a single page. HAPI has a maximum of 50 per page. ERSD will repeatedly request every page until no more pages of data are left to retrieve (to get the full list of people). |
| maxNotifications | How many notifications should be sent before the system stops sending notifications. One interval after the last notification, the user's subscriptions are suspended. |
| expiration | Represents how long a user's contact information is valid for. |
| value | A numeric value |
| unit | The unit of measurement for the numeric value. Valid values are: 'month','months','m','year','years','y','day','days','d' |
| notificationInterval | How often emails should be sent to notify the user that their contact information is about to (or has) expired. The first expiration starts one interval prior to the actual expiration of the user's contact information. |
| value | A numeric value |
| unit | The unit of measurement for the numeric value. Valid values are: 'month','months','m','year','years','y','day','days','d' |
| templates | Templates for the emails that should be sent for contact information expiration. |
| expiring | The information that is used to send the email notifying the user that their contact information is about to expire. |
| subject | The subject of the email |
| html | The HTML template to use for the email |
| text | The TEXT template to use for the email |
| expired | The information that is used to send emails notifying the user that their contact information has expired. |
| subject | The subject of the email |
| html | The HTML template to use for the email |
| text | The TEXT template to use for the email |
| Configuration that allows administrators to send emails to all users | |
| from | The from address that emails are sent from. Should be in the format "[email protected]" |
| host | The host address of the SMTP server |
| port | The port for the SMTP server |
| tls | Whether to require TLS |
| username | Optional. The username to authenticate with the SMTP server. Both username and password must be provided to authenticate with basic credentials. |
| password | Optional. The password to authenticate with the SMTP server. Both username and password must be provided to authenticate with basic credentials. |
| client | Anything in the section is sent to the client/browser application when the client/browser application launches |
| keycloak | Information about the keycloak installation, so that the browser knows where to send the user when they ask to login |
| url | The URL of the keycloak server. Ex: https://keycloak.somedomain.com/auth |
| realm | The realm that the keycloak application is registered within |
| clientId | The id of the client application in keycloak |
This property must take the form of "------ BEGIN CERTIFICATE ------\n.............\n------ END CERTIFICATE -----". In other words, it must be wrapped with
----- BEGIN CERTIFICIATE -----
Followed by a line break
Followed by the actual certificate contents
Followed by a line break
----- END CERTIFICATE -----
Changing the criteria in the config does not automatically update already-existing subscriptions. Only new subscriptions are affected by the updated criteria.
The templates used to email may contain the following parameters:
| Parameter | Description |
|---|---|
| {first_name} | The first name of the user |
| {last_name} | The last name of the user |
| {expiration_date} | The date that the user's contact information expires |
| {portal_link} | An http:// value/link to the ERSD portal |
HAPI does not currently accept storing any Bundle resources with a type that is not "collection". If you attempt to upload a Bundle with a type of "searchset" or "transaction", the HAPI FHIR server will respond to the ERSD server with the following error:
Unable to store a Bundle resource on this server with a Bundle.type value of: searchset
The HAPI team has been asked to change this so that Bundle resources may be stored with all possible "type" values. They have agreed to make the change, but have not committed to a date.
You must properly configure the "Web Origins" and "Valid Redirect URIs" properties of the application in KeyCloak. For example, if your ERSD installation is installed at https://ersd.mycompany.com then you must set the "Web Origins" property to "https://ersd.mycompany.com" and the "Valid Redirect URIs" should be "https://ersd.mycompany.com/*".
To successfully reverse proxy a KeyCloak installation, you must modify the standalone.xml file to include proxy-address-forwarding="true" and redirect-socket="proxy-https" to the <http-listener> element and change the <socket-binding> element to have a port of "443". For example:
<http-listener name="default" socket-binding="http" proxy-address-forwarding="true" redirect-socket="proxy-https" enable-http2="true"/>
<socket-binding name="https" port="443"/>
ERSD attempts to reuse information from the KeyCloak account to make the registration process in ERSD quicker/easier for the end-user.
"First Name", "Last Name" and "Email" should always be available from KeyCloak to ERSD, as those are required fields for KeyCloak and are automatically provided to ERSD during authentication.
The following table indicates what KeyCloak custom attributes are recognized by ERSD. These custom attributes can be captured as part of custom templates used by the KeyCloak registration screen; custom configuration of KeyCloak would be required to have KeyCloak capture these custom attributes.
| ERSD Field | KC Attr 1 | KC Attr 2 | KC Attr 3 |
|---|---|---|---|
| Mobile Phone | mobile | cell | |
| Office Phone | office | ||
| Street Address | street | address | line |
| City | city | ||
| State | state | st | |
| Postal Code | postal | postalCode | zip |
Refer to the this link for guidance on how to create a custom keylcoak template that captures custom fields (such as the fields listed in the table above).