As mentioned in the previous post, one of the files that will be in the patient’s chart will be “contacts.ini”. So lets break it down:
The .ini file format
Rather than re-inventing the wheel, we can just use a format that many toolkits and other APIs already use: the .ini file. You can read the details of how a .ini file looks like by reading the Wikipedia article on it.
Why go with .ini files?
First of all, a .ini file is human readable. If all else fails, somebody can read the file using a text editor and see the data. This also makes is much easier to debug.
Secondly, it does allow features like sections, being able to assign clear labels for each value, and adding comments.
The third (but not final) reason is that Qt (which Clear Dental will use as the front end) has a built in .ini parser that is fast and light weight. It can also store and serialize strings, integers, etc. all transparently without any issues.
What is wrong with all the other file formats?
XML is not a good choice because although it can be human readable, it can be overly verbose and unnecessarily complex. Also, the lack of hierachy in .ini is more a feature than a bug in this case because we actually want to discourage a fully complex dataset when all we need is just simple data about the patient. This is why JSON probably would not be a good idea either despite being much better than XML.
A .CSV file would not work well either because we normally store things in a simple “key” and “value”. Therefore, the entire file would just be two columns and we also wouldn’t get other features like groups.
YAML could work but would require 3rd party libraries which have their own maintenance required and may not be supported with Qt.
However, in the future, we could move from a .ini file to something else like a .yaml by simply converting the files from one format to another which would be simple because we are working with the file system, not a complex SQL database.
How .ini files will work in this system
The front end software should work even if all fields are missing. Although the presentation would be nonsensical, it should not crash due to lack of data. Therefore, all fields are either “recommended” or “optional”.
The term “recommended” simply means the person entering the data should put it in. If the field is blank, the UI should warn the user that it is blank but the user can still override the system and allow it to move on.
The term “optional” means that there are no warning if the field is missing. This means the UI has to be able to present the data without the field. From here on out, all optional fields will be in italics.
Back to our regularly scheduled program: personal.ini
The file will have the following groups:
- Emergency Contact
Lets now go in to each group in detail:
Holds everything related to the patient’s name. The name group will have the following keys:
FirstName: The patients first name
NamePhonetic: How to say the patient’s first name (or preferred name) phonetically
MiddleName: The patient’s middle name or middle initial
LastName: The patient’s last name
PreferredName: What the patient would preferred to be called
PreviousName: In case of a name change, what they used to be named (in case insurance has the old name)
[Name] FirstName=Jacqueline NamePhonetic=Say "Jack" with an "e" at the end MiddleName=Betty Lastname=Smith PreferredName=Jackie PreviousName=Jacqueline Doe
Holds everything related to the patient’s personal data. Please note that things like family relationship is stored as symbolic links in the “family” folder. Things like social security number are stored in the “finance” folder. The personal group will have the following keys:
DateOfBirth: The date of birth of the patient, in the format “MM/dd/yyyy” (American format).
Sex: The sex of the patient (“male” or “female”)
Gender: The gender of the patient (which is independent of sex). This field can include “Male”, “Female”, “Transman”, Transwoman”, “Genderqueer” or “Other”. The patient’s gender will override the sex field when it comes to “he” vs. “she” vs. “they”.
Race: In case you are working in a public health facility and need to kept records of race. This is using the CDREC race codes (the concept field)
Ethnicity: In case you are working in a public health facility and need to kept records of ethnicity. This is using the CDREC ethnicity codes (the concept field)
[Personal] DateOfBirth=07/12/1972 Sex=Female Gender=Female Race=White Ethnicity=Not Hispanic or Latino
This will hold all the basic information about the physical address. In theory, these fields will be “localized” to the region of the practicing doctor (which is why .ini files are nice because they can be extendable and still valid). The address has the following keys:
StreetAddr: The full address including the street number (like “123 Main Street”). In situations where additional lines are needed (like “Apartment 23E”), the escape character “\n” will be used to append additional lines.
City: The city, town or village
State: The state, commonwealth, prefecture, etc. Use the normal postage prefix like “MA” for Massachusetts or “CA” for California.
PostalCode: Zip or postal code
Country: Nation or country using the ISO 3166-1 Alpha-2 code
[Address] StreetAddr=123 Main Street City=Burlington State=VT Zip=05401 Country=US
Basic phone numbers. This whole section is optional. It will have the following keys:
HomePhone: Telephone number of the land line. Recommended to have area code but country code is optional. No dashes but a “+” will be used for country codes.
CellPhone:Cellphone number. Recommended to have area code but country code is optional. No dashes but a “+” will be used for country codes.
[Phones] HomePhone=1234567890 CellPhone=+442079460625
Emails can include any form including traditional email or other social networking sites (assuming they have a messaging service). This whole section is optional. The Emails group has the following keys:
Email: This is the traditional email in the format “email@example.com”
Facebook: Facebook id of the patient
Instagram: Instagram username of the patient
WhatsApp: WhatsApp phone number
[Emails] Emailfirstname.lastname@example.org Facebook=JoneDoneh Instagram=daviddobrik WhatsApp=1234567890
Everything related to work. This whole section is optional. The Work group has the following keys:
WorkAddr: Work address. As with personal address, the “\n” is used for additional lines needed
WorkCity: Work city
WorkState: State in which the work location is
WorkPhone: Phone number to contact the patient during work
WorkEmail: Email that the patient uses while at work
[Work] WorkAddr=The ACME Company\n123 Main Street WorkCity=Burlington WorkState=VT WorkPhone=1224567890 WorkEmailemail@example.com
This section relates to how to get in touch with the patient’s emergency contact. The Emergency Contact group has the following keys:
EmergencyName: Full name of the emergency contact
EmergencyPhone: Phone number of the emergency contact
EmergencyRelation: The relationship with the person and the emergency contact
[Work] EmergencyName=Joe Smith EmergencyPhone=1234567890 EmergencyRelation=Father
This section is what the patient has preferences for which can make their experience better. This entire section is optional. The preferences group has the following keys:
PreferredLanguage: The language the patient prefers to communicate in (in ISO 639-1 two letter code)
AvailableDays: Which type of days the patient is available for. The days of the week are abbreviated as “Su M Tu W Th F Sa”. For example, if the patient is only available on Mondays and Thursdays, the value would be “M Th”. If the patient can come in any day of the week, then you would see all “Su M Tu W Th F Sa”.
AvailableTime: Which time of day the patient prefers to come in. These are in a series of ranges which are in 24H format. For example, lets say the patient can come in anytime before noon, then it will have the value “0-12” (the zero is for midnight and 12 hours is noon time). Lets say the patient can come in anytime after 3PM. Then it would have a value of “15-23” (15 being 3PM and 23 being 11PM). Lets say the patient can only come in before 8AM but anytime after 4PM, then it would be “0-8,16-23” with the “,” to separate the ranges.
PreferredContact: How the patient likes to be contacted (appointment reminders, etc.). It can be “homephone”, “cellphone”, “email”, “text”, “workphone”, “workemail”, “facebook”, “instagram”, “whatsapp” or some other text value a human can understand.
PreferredDoctor: Which doctor the patient would like to see. If the patient likes to see Dr. Smith, then the value would be “Dr. Smith”. If the patient likes all the doctors except for Dr. Joe, it would be “-Dr. Joe” (the “-” prefix means patient does not like this particular doctor).
[Preferences] PreferredLanguage=en AvailableDays=Th F AvailableTime=3-23 PreferredContact=text PreferredDoctor=Dr. Willis
As with all the .ini files in this system, there will be an “others” section for any kind of additional data that was not originally in this spec. For now, it will have this one field:
SpecVersion: The version of the spec that this file follows. In theory, this should not matter as it should be backwards compatible but sometimes mistakes happen so it would be nice to have a good “get out of jail free” card.
And that’s it!
Please leave a comment on anything that should be changed or added with the specs.