To update the metadata in the distro/configuration folder (e.g., adding new forms, concepts, etc.), follow these steps:

Step 1: Stop the Running Instance

If your instance is currently running, first bring it down:

docker compose down

This command stops and removes the current containers, ensuring a clean start for your updated metadata.

Step 2: Build the Local Docker Image

To reflect the updated metadata in your instance, you'll need to build a local Docker image. Ensure your configuration files follow the accepted conventions for each configuration, as incorrect formats might prevent the metadata from appearing in the instance as expected.

TAG=your-custom-tag docker compose build

Replace `your-custom-tag` with any unique tag of your choice. It’s advisable to use a tag not found on Docker Hub (e.g., `qa` or specific release versions) to avoid conflicts.

Step 3: Run the Instance with the Updated Image

Next, start your instance using the locally built image:

TAG=your-custom-tag docker compose -f docker-compose.yml up -d

Ensure that the `TAG` variable matches the one you used in the previous step. This command launches the instance using your locally built image instead of pulling one from Docker Hub.

Step 4: Wait for the Instance to Start

The backend script should start running at this point. To verify if the instance is running, refer to the step 4 of the dev guide of setting up an instance of O3.

Updating the address template

For an example, consider the patient registration which looks like below by default:

To update the address template, go to the Legacy admin found under the System Administration under the App Menu. In the legacy admin UI, under the section Location section, go to Manage Address Template.

Lets change it to have the fields House number, Avenue, Neighbourhood instead.

To do so, we have to modify the AddressTemplate to the following,

<org.openmrs.layout.address.AddressTemplate>
	<nameMappings class="properties">
		<property name="address1" value="Location.address1" />
		<property name="address2" value="Location.address2" />
		<property name="address3" value="Location.address3" />
		<property name="address4" value="Location.address4" />
	</nameMappings>
	<sizeMappings class="properties">
		<property name="address1" value="10"/>
		<property name="address2" value="40"/>
		<property name="address3" value="40"/>
		<property name="address4" value="40"/>
	</sizeMappings>
	<lineByLineFormat>
		<string>address1</string>
		<string>address2</string>
		<string>address3 address4</string>
	</lineByLineFormat>
	<requiredElements>
		<string>address1</string>
	</requiredElements>
</org.openmrs.layout.address.AddressTemplate>

To change the strings that would display as the labels instead of address1, address2, etc. Add a folder called messageproperties to the reference application repository distro/configuration folder. Add separate files for each language that you wish to support. Eg:-

In a addresslabel_en.properties file,

Location.address1=House Number
Location.address2=Avenue
Location.address3=Street
Location.address4=Neighbourhood

To add support for french, in a addresslabel_fr.properties file,

Location.address1=Numéro de maison
Location.address2=Rue
Location.address3=Commune
Location.address4=Quartier