Summary
Configuration of name fields in the O3 patient registration form is too limited to support needs of different locales. Related to 03-2115 - Patient name should be collected and rendered based on name template configuration
Discussion
At present, the ‘Name’ section of the O3 Patient Registration form appears to support only limited configuration. The form allows entry of First Name, Middle Name and Family Name with options to show or hide the Middle Name field or reverse the display order of fields.
Screenshot of reference app:
Name field configuration from esm-patient-registration-app/src/config-schema.ts:
fieldConfigurations: {
name: {
displayMiddleName: boolean;
allowUnidentifiedPatients: boolean;
defaultUnknownGivenName: string;
defaultUnknownFamilyName: string;
displayCapturePhoto: boolean;
displayReverseFieldOrder: boolean;
};
This limitation is problematic in latin america, where we use given_name, middle_name, family_name and family_name2 fields.
In the O1 and O2 patient registration interfaces, the interface was defined/configured by specifying name templates via a global layout.name.format property as per Wiki: Customizing Name Layouts
Thanks to recent developments, the configured name format may be used for displaying patient names as per 03-2115. However, the patient registration app ought to support a flexible configuration of name entry fields. It probably makes sense to make this configurable via name templates.
Additional notes:
With respect to supported names, the FHIR specification supports names annotatated with their ‘use’ e.g. ‘usual’, ‘maiden’, ‘official’, ‘nickname’ etc. On the other hand, whilst the OpenMRS db allows multiple names to be stored per patient, the only associated metadata is a single boolean ‘preferred’ flag. The O2 documentation suggests collecting additional names as additional person attributes.
Design Proposal
- Enable configuration of name fields in the patient registration app by specifying which name template to use; the name template defines which fields will be displayed, and in which order.
- Enable collection of 2 names; one ‘preferred’ and one ‘alternate’. Each may use a different name template. Preferred name is mandatory (but may be ‘unknown’). Alternate name is optional.
Configuration schema would resemble:
fieldConfigurations: {
name: {
template: string; // name template to use for capturing patient's preferred name, e.g. 'short', 'long',... Default is 'short'.
// the name template defines which fields are displayed and in which order.
allowUnidentifiedPatients: boolean;
defaultUnknownPatientName: { // values supplied if patient is unknown, applied to name template.
prefix: string;
givenName: string;
middleName: string;
familyPrefix: string;
familyName: string;
familyName2: string;
familyNameSuffix: string;
degree: string;
}
displayCapturePhoto: boolean;
}
alternateName: {
label: string; // default 'Alternate Name'. But how to support localisation? Should this be a concept id?
template: string; // name template to use for capturing patient's alternative name.
// if empty (the defauly), alternative name fields are not displayed.
}
...
}
As an example of layout, the following the configuration:
fieldConfigurations: {
name: {
nameTemplate: latinamerica; // givenName, middleName, familyName, familyName2
allowUnidentifiedPatients:...
}
alternateName: {
label: 'Known As';
template: givenFamily; // givenName, familyName
}
}
could produce a layout resembling:
Full Name:
First Name:
[==============]
Middle Name:
[==============]
Family Name:
[==============]
Second Family Name:
[==============]
Known As:
First Name:
[===============]
Family Name:
[===============]
Questions:
- I think we lose the ability to label a name field as optional… for example, at present the middle name field is labelled ‘Middle Name (optional)’. Is that important?
- I’m not sure what the implications of capturing a ‘preferred’ name and an optional ‘alternative’ name might be, as opposed to the current O2 solution of using person attributes…
- What is the correct way to configure the label for the alternate name section?
Thoughts/suggestions? I’m new to OpenMRS, so be gentle… 
% in favour of making i18n/regionalization a first class concern, so these kinds of thoughts and proposals are awesome.