Running the Form Engine against an OpenMRS 3.x frontend

Presently, OpenMRS 3.x (opens in a new tab) (O3) ships with a custom version (opens in a new tab) of the Form Engine.

This version leverages the Carbon design system (opens in a new tab) to get its look and feel to match that of O3.

ℹ️

You can track the progress of carbonizing the Form Engine via the 3.0.0.carbonize (opens in a new tab) branch. Alternatively, you could follow the OpenMRS fork (opens in a new tab) of the Form Engine.

If you wish to modify the Form Engine and test it within O3 (or any other O3-based frontends), follow the steps outlined below:

Prerequisites

You need to have yarn (opens in a new tab) installed on your system. You can check for whether yarn is installed by running:

  yarn -v

If this doesn't return a version number, you likely don't have it installed. To install it on your system, run:

npm install -g yarn

Additionally, the openmrs-esm-patient-chart (opens in a new tab) repository expects you to have Node.js v16.x.x or higher installed on your system.

Steps

Fork and clone the AMPATH formentry (opens in a new tab) repository.
cd into your clone and checkout the 3.0.0-carbonize branch.
Install dependencies by running:
```
npm install
```
Make changes to the library.
Create a production build of the library by running:
```
npm run build:lib
```
Note the full path to the dist/ngx-formentry directory created in this step. It will be needed further ahead.
Next, open your local openmrs-esm-patient-chart clone. Install dependencies using:
```
yarn
```

We'll then install the dist/ngx-formentry directory from the previous step inside of packages/esm-form-entry-app. To do so, run:

cd packages/esm-form-entry-app
yarn add ...
 
# where ... is the path to your dist/ngx-formentry directory from the previous step. It could look like: /Users/johndoe/code/ampath/ngx-openmrs-formentry/dist/ngx-formentry.

If you are using yarn 3, run :

cd packages/esm-form-entry-app
yarn add esm-form-entry-app@file:...
 
# where ... is the path to your dist/ngx-formentry directory from the previous step. It could look like: /Users/johndoe/code/ampath/ngx-openmrs-formentry/dist/ngx-formentry.

ℹ️

If you're using Windows, you might need to wrap your path in double quotes.

It is very important that this step works correctly to establish the link between the formentry library and the frontend.

Next, cd into the form-entry package in your local patient chart copy:
```
  cd packages/esm-form-entry-app
```
And then spin up our local of formentry by running:
```
  yarn serve
```
This command should fire up a dev server on port 4200.
Next, log into your 3.x frontend (could be AMPATH 3.x, KenyaEMR 3.x, or a community server like dev3) in your browser.
Make sure that import-map overrides are enabled. If they are, you should see a small grey box at the bottom right hand corner of your screen. If you don't see the overrides icon:
- Open your browser devtools console and run:
```
localStorage.setItem('openmrs:devtools', true);
```
- Reload your browser window for the changes to take effect.
Next, click the box icon to launch the devtools overrides panel. From the search box, find the import map entry for @openmrs/esm-form-entry. Click on the item in the list - this should launch a modal where you can type in your override URL. Type in:
```
http://localhost:4200/openmrs-esm-form-entry-app.js
```
Reload your browser window for the changes to take effect.
Congratulations! You should now be running the local version of formentry in your application. To test your changes anew, rebuild the library again by running npm run build:lib in your local formentry clone. The frontend should pick up the changes automatically.
To test, search for a patient and open their chart. Find the forms widget and launch a clinical form in the workspace. Any changes made to the formentry app should propagate into the form displayed in the workspace.

ℹ️
Note that O3 caches the forms you've opened in your browser's localStorage. If you're not seeing the latest changes when you load your form in the workspace, it could be because you're viewing a cached version. Make sure to find and delete the localStorage entry for your form and then reload to fetch it anew.
To propagate your changes to your server, you'd need to test them and once satisfied that they're working as they should, package them in a pull request and get them merged to the formentry repository. You'd then need to deploy those changes to your server.
Profit!

Troubleshooting

I get an `Invalid webpack configuration` error when I run `yarn serve`

If you're using Windows, you may see the following error when you run yarn serve in the esm-form-entry directory:

An unhandled exception occurred: Invalid configuration object. Webpack has been initialised using a configuration object that does not match the API schema.

configuration.entry['main'] should not contain the item 'C:\Workspace\example\project-example\node_modules\webpack-dev-server\client\index.js?http://0.0.0.0:0&sockPath=/sockjs-node' twice.
-> A non-empty array of non-empty strings

This is a known issue with single-spa-angular (opens in a new tab). To work around this, you can modify the yarn serve script entry in the package.json file in the esm-form-entry package as follows:

"serve": "ng serve --port 4200 --live-reload false",

I don't see my changes propagated in my SPA environment

Make sure you have saved your changes in the formentry library and run:
```
npm run build:lib
```
To ensure you have the very latest changes in the patient chart, make sure to rerun yarn add {path-to-dist/ngx-formentry} in your esm-form-entry package directory.
If you still don't see your changes, make sure you're overriding the esm-form-entry-app in the import map overrides panel.

Extending the Form Engine