From 5f747a59f78dbd6d04c2dc4eaca10c720cbfe97e Mon Sep 17 00:00:00 2001 From: Enoch <94776262+basrem@users.noreply.github.com> Date: Wed, 14 Feb 2024 09:57:37 +0300 Subject: [PATCH] Update csv_conventions.md Minor edits to improve on grammar and spelling but maintaining the meaning. --- readme/csv_conventions.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/readme/csv_conventions.md b/readme/csv_conventions.md index bc5eec502..ab25fe9d7 100644 --- a/readme/csv_conventions.md +++ b/readme/csv_conventions.md @@ -1,6 +1,6 @@ ## Conventions for CSV files -There are a number of conventions that apply to CSV files across all domains, typically the meaning of certain columns (or headers). Headers are in general optional, it is up to the implementor to provide or not the fields that are required to create or edit the OpenMRS objects. Mandatory headers will be specifically indicated. -
Each CSV line is meant to provide enough data to create, edit or void/retire an OpenMRS object of the domain. +Several conventions apply to CSV files across all domains, typically the meaning of certain columns (or headers). Headers are in general optional, it is up to the implementor to provide or not the fields that are required to create or edit the OpenMRS objects. Mandatory headers will be specifically indicated. +
Each CSV line is meant to provide enough data to create, edit, or void/retire an OpenMRS object of the domain. ###### Header `Uuid` (mandatory) * If the value under this header is missing the OpenMRS object will be created with a new random UUID. @@ -11,12 +11,12 @@ There are a number of conventions that apply to CSV files across all domains, ty ###### Header `Void/Retire` Set this to **true** to indicate that the OpenMRS object with the provided UUID should be voided or retired. -
When `Void/Retire` is set to true, the parsing of the remaining of the CSV line is interrupted since the only objective is to retire the concept. And to this end, only the UUID and the retire flag are needed. +
When `Void/Retire` is set to true, the parsing of the remaining part of the CSV line is interrupted since the only objective is to retire the concept. And to this end, only the UUID and the retire flag are needed. ###### Localized Header `Display` -This is a locale specific header that should not be used as such ; it should be used with a locale ISO code appended to it, eg: `Display:en` or `Display:fr` or `Display:es` ... etc. The values under those display headers for each locale are used to localise the display string of the OpenMRS metadata entity being defined on the CSV line. Under the hood this sets up Java localization messages that comply to the so-called _UI Framework convention_ (see more on this [here](https://github.com/mekomsolutions/openmrs-module-initializer/issues/95#issue-813691920)). +This is a locale-specific header that should not be used as such; it should be used with a locale ISO code appended to it, eg: `Display:en` or `Display:fr` or `Display:es` ... etc. The values under those display headers for each locale are used to localize the display string of the OpenMRS metadata entity being defined on the CSV line. Under the hood, this sets up Java localization messages that comply with the so-called _UI Framework convention_ (see more on this [here](https://github.com/mekomsolutions/openmrs-module-initializer/issues/95#issue-813691920)). -For example for an OpenMRS metadata entity display string to be localised in English (locale 'en') and French (locale 'fr'), simply name the headers `Display:en` and `Display:fr` and give them the corresponding localised values respectively in English and French making sure the 'uuid' field is filled and not left blank: +For example for an OpenMRS metadata entity display string to be localized in English (locale 'en') and French (locale 'fr'), simply name the headers `Display:en` and `Display:fr` and give them the corresponding localized values respectively in English and French making sure the 'uuid' field is filled and not left blank: | UUID | ... | Display:en | Display:fr | ... | Void/Retired | ...| | --- | --- | --- | --- | --- | --- | --- | @@ -35,7 +35,7 @@ ui.i18n.Location.name.eb96c0d4-6248-476b-a079-0aaabfa2f614=Salle d'urgences org.openmrs.Location.eb96c0d4-6248-476b-a079-0aaabfa2f614=Salle d'urgences ``` -In general, for each locale, a pair of messages are created as such +In general, for each locale, a pair of messages is created as such ``` ui.i18n..name.= org.openmrs..= @@ -46,10 +46,10 @@ Special headers are used to provide metadata information about the CSV file itse
All metadata headers start with an underscore, eg. `_version:1`, `_order:1000`, ... etc. ###### Header `_order:*` -This metadata header specifies the order of loading of the CSV file _within the domain_. In many cases the creation of OpenMRS objects relies on the existence of other OpenMRS objects that are referred to. This use case is covered by the order header that allows to control the order of loading of files in a given domain. +This metadata header specifies the order of loading of the CSV file _within the domain_. In many cases, the creation of OpenMRS objects relies on the existence of other OpenMRS objects that are referred to. This use case is covered by the order header that allows control of the order of loading of files in a given domain.
For example `_order:1000` indicates that all CSV files with an order smaller than 1,000 will be processed _before_ this file within the domain. -
If the order metadata cannot be parsed or is missing, then the file will be processed last after all the ordered CSV files of the domain. However if several CSV files have no order defined, then the loading order between them is undefined. +
If the order metadata cannot be parsed or is missing, then the file will be processed last after all the ordered CSV files of the domain. However, if several CSV files have no order defined, then the loading order between them is undefined. ###### Header `_version:*` Versions are primarily introduced to allow for evolutions in the implementation of CSV parsers. Those evolutions may require to modify the CSV headers which will likely lead to backward compatibility issues. Using versions works around this by ensuring that specific parsers are used based on the version specified via the CSV file header. -
When no version header is provided the initializer will fallback on a default one or may complain in its log messages that no version was specified. +
When no version header is provided the initializer will fall back on a default one or may complain in its log messages that no version was specified.