Populating Forms and Generating Payloads

The Form Engine converts between REST payloads and form values through a set of value adapters. They work in both directions: populateForm writes values from an existing encounter into the form's controls, and generateFormPayload reads the form back out into a payload you can POST to the OpenMRS REST API.

All adapters are provided by FormEntryModule, so you can inject them directly:

import {
  EncounterAdapter,
  ObsValueAdapter,
  OrderValueAdapter,
  PersonAttributeAdapter
} from '@openmrs/ngx-formentry';
 
constructor(private encounterAdapter: EncounterAdapter) {}

Populating a form from an existing encounter

Pass a REST-representation encounter to the EncounterAdapter:

this.encounterAdapter.populateForm(this.form, encounter);

The adapter sets the encounterDatetime, encounterProvider, and encounterLocation questions from the encounter's fields, then delegates the encounter's obs, orders, and diagnoses arrays to the corresponding child adapters. Each populated control also records its initial value, which is what makes diff-based editing work when the form is submitted again.

Generating a submission payload

Before generating, set the form's valueProcessingInfo — contextual values that the form itself doesn't capture:

this.form.valueProcessingInfo = {
  patientUuid: 'patient-uuid',
  visitUuid: 'visit-uuid',
  encounterTypeUuid: 'encounter-type-uuid',
  formUuid: 'form-uuid',
  encounterUuid: 'encounter-uuid', // when editing an existing encounter
  utcOffset: '+0300',
  locationUuid: 'location-uuid'
};
 
if (this.form.valid) {
  const payload = this.encounterAdapter.generateFormPayload(this.form);
  // POST payload to the encounter REST endpoint
}

generateFormPayload assembles:

• encounterDatetime: the encounter date question's value, formatted with the configured utcOffset (defaults to +0300).
• encounterProviders: the provider question's value, with the default "unknown provider" encounter role.
• location: the location question's value.
• patient, visit, encounterType, form, and the encounter uuid, taken from valueProcessingInfo.
• obs, orders, and diagnoses arrays, generated by the child adapters.

For a form that was populated from an existing encounter, the obs adapter diffs each control's current value against its initial value: new answers become new obs, changed answers carry the existing obs uuid with the new value, and cleared answers are emitted with voided: true.

The individual adapters

You can also use each adapter on its own when you only need part of the payload: