Running the Form Engine against an OpenMRS 3.x frontend

The Angular Form Engine lives in the openmrs-ngx-formentry (opens in a new tab) repository and is published to npm as @openmrs/ngx-formentry (opens in a new tab). It leverages the Carbon design system (opens in a new tab) to match the look and feel of OpenMRS 3.x (opens in a new tab) (O3). O3 frontends consume it through the esm-form-entry-app (opens in a new tab) package in the Patient Chart.

ℹ️

O3 has two form engines. The current Reference Application ships the React Form Engine (opens in a new tab) (@openmrs/esm-form-engine-app) by default; this Angular engine is used by distributions that explicitly include the esm-form-entry-app frontend module. This guide covers the Angular engine.

If you wish to modify the Form Engine and test it within an O3 frontend that uses it, follow the steps outlined below.

Prerequisites

Node.js ^20.19.0 || ^22.12.0 || >=24.0.0 (the range Angular 20 supports).
Yarn 4, provisioned via Corepack (opens in a new tab): run corepack enable once and the packageManager field in each repository takes care of the rest. Recent Node.js releases no longer bundle Corepack, so install it first with npm install -g corepack if the command is missing.
Local clones of openmrs-ngx-formentry (opens in a new tab) and openmrs-esm-patient-chart (opens in a new tab).

Steps

In your openmrs-ngx-formentry clone, install dependencies and make your changes:
```
yarn install --immutable
```
Create a production build of the library:
```
yarn build:lib
```
This produces a dist/ngx-formentry directory. Yarn requires a lockfile in the folder you link, so create an empty one:
```
touch dist/ngx-formentry/yarn.lock
```
Next, link the built library into the Patient Chart's form entry package. Yarn's link command accepts a path directly:
```
cd ~/openmrs-esm-patient-chart/packages/esm-form-entry-app
yarn link /path/to/openmrs-ngx-formentry/dist/ngx-formentry
```
ℹ️
If you're using Windows, you might need to wrap your path in double quotes.
Fire up a dev server from the Patient Chart repository root:
```
cd ../..
yarn start --sources packages/esm-form-entry-app
```
This runs the openmrs develop (opens in a new tab) tooling, which serves the form entry app and automatically overrides its import map entry against the dev3 community server.
To test, search for a patient and open their chart. Find the forms widget and launch a clinical form in the workspace. Rebuild the library (yarn build:lib) after each change to the engine to propagate it into the running app.

ℹ️
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.
Once you're satisfied with your changes, package them in a pull request against the formentry repository (opens in a new tab).

Running against an arbitrary O3 server

If you want to test against a server other than dev3, serve the form entry app directly and override the import map by hand:

Run yarn serve inside packages/esm-form-entry-app. This fires up a dev server on port 4200.
Log into your O3 frontend in the browser and enable the devtools overrides panel. If you don't see the small grey box at the bottom right hand corner of your screen, open your browser devtools console and run:
```
localStorage.setItem('openmrs:devtools', true);
```
Then reload your browser window.
Click the box icon to launch the devtools overrides panel. Find the import map entry for @openmrs/esm-form-entry-app and set the override URL to:
```
http://localhost:4200/openmrs-esm-form-entry-app.js
```
Reload your browser window for the changes to take effect.

Extending the Form Engine