app_settings.json

Settings: The primary location of settings for CHT applications

The settings which control CHT apps are defined in the app_settings.json file, and stored in the settings doc in the database. Some settings can be modified in the App Management app, which updates the same settings file in the database.

The app_settings.json file can be manually edited to modify individual settings. The code for some components, like tasks and targets, gets compiled into this file with the compile-app-settings action in the medic-conf tool.

Most sections are described on their own in the Reference Documentation.

Build

To include your settings into your app, you must compile them to include modular components, then upload them to your instance.

medic-conf --local compile-app-settings backup-app-settings upload-app-settings

Optional Settings

The following settings do not need to be specified. They should only be defined when the default implementation needs to be changed.

app_settings.json

SettingDescriptionDefaultVersion
phone_validation
  • "full”: full validation of a phone number for a region using length and prefix information.
  • "partial”: quickly guesses whether a number is a possible phone number by using only the length information, much faster than a full validation.
  • "none”: allows almost any values but still fails for any phone that contains a-z chars.
“full”3.1.0
uhc.contacts_default_sort
  • "alpha”: Sort contacts alphanumerically
  • "last_visited_date”: sort contacts by the date they were most recently visited.
“alpha”2.18.0
uhc.visit_count.month_start_dateThe date of each month when the visit count is reset to 0.12.18.0
uhc.visit_count.visit_count_goalThe monthly visit count goal.02.18.0
outgoing_deny_listAll outgoing messages will be denied (unsent) if the recipient phone number starts with an entry in this list. A comma delimited list. (eg. outgoing_deny_list="253,ORANGE" will deny all messages sent to 253 543 4448 and ORANGE NET)"”
outgoing_deny_shorter_thanDeny all messages to recipient phone numbers which are shorter than this value. Intended to avoid message loops with short codes used by gateways (eg. 60396). An integer.63.3.0
outgoing_deny_with_alphasWhen true, deny all messages to recipient phone numbers containing letters (eg. Safaricom). Intended to avoid message loops with non-numeric senders used by gateways. A boolean.true3.3.0
outgoing_deny_with_alphasWhen true, deny all messages to recipient phone numbers containing letters (eg. Safaricom). Intended to avoid message loops with non-numeric senders used by gateways. A boolean.true3.3.0
task_day_limitThe number of days before a task is due to show the due date.43.9.0
app_urlThe URL of the app, eg: “https://demo.app.medicmobile.org3.10.0

SMS Workflows

Workflows involving SMS are configured by defining schedules, registrations, patient reports, and case reports. Schedules of automated messages can be sent from the server at specificied times in the future, and reports can be associated to contacts.Forms can also be configured to clear the schedule, or silence it for a period of time.

SMS recipient resolution

An outgoing SMS message configuration has the following fields:

propertydescriptionrequired
translation_keyThe translation key of the message to send out. Available in 2.15+.yes
messages(deprecated) Array of message objects, each with content and locale properties. From 2.15 on use translation_key instead.no
recipientRecipient of the message.no

recipient values and resolutions:

valueresolves to
emptysubmitter
reporting_unitsubmitter
parentprimary contact of the patient’s/submitter’s place’s parent (patient.parent.parent.contact)
grandparentprimary contact of the patient’s/submitter’s place’s grandparent (patient.parent.parent.parent.contact)
clinicprimary contact of the clinic in the patient’s/submitter’s lineage
health_centerprimary contact of the health_center in the patient’s/submitter’s lineage
districtprimary contact of the district_hospital in the patient’s/submitter’s lineage
ancestor:<contact_type>primary contact of the place of the requested type in the patient’s/submitter’s lineage
link:<tag>Linked doc that has requested tag in the patient’s / submitter’s lineage (direct mapping, not to primary contact). As of 3.10.x
link:<contact_type>primary contact of the place of the requested contact_type in the patient’s/submitter’s lineage. As of 3.10.x
custom object patha direct object path in the message context object eg: patient.parent.contact.other_phone
valid phone numberrequested phone number

Message context

The message context object consists of:

propertyvalue description
every property from the original reportunchanged unless specified below
every fields property from the original reporteg: if the report has fields.test = 'test' then context.test = 'test'
patientdeeply hydrated patient contact (resolved from patient_id, fields.patient_id or fields.patient_uuid)
patient_namepatient’s name
placedeeply hydrated place document (resolved from place_id) - only available in registration transition, when creating the place via SMS
contactdeeply hydrated submitter contact
parentdeeply hydrated health_center type document from the patient’s or submitter’s lineage
grandparentdeeply hydrated district_hospital type document from the patient’s or submitter’s lineage
clinicdeeply hydrated clinic type document from the patient’s or submitter’s lineage
health_centerdeeply hydrated health_center type document from the patient’s or submitter’s lineage
district_hospitaldeeply hydrated district_hospital type document from the patient’s or submitter’s lineage

Variables

Outgoing messages can use Mustache templating to insert variables and specify data formats. All message context fields are available as variables.

Code sample

The following translation label includes the name field of contact, along with the submitted patient_name field, and the generated patient_id field.

translations/messages-en.properties

messages.registration.report_accepted = Thank you {{contact.name}} for registering {{patient_name}}. Their ID is {{patient_id}}.

Date Format Filters

The following filter functions are available for formating dates.

filterdescription
dateDisplays dates according to the date_format specified in app_settings. See doc for Moment.js format for details.
datetimeDisplays dates according to the reported_date_format specified in app_settings. See doc for Moment.js format for details.
bikram_sambat_dateDisplays dates in Bikram Sambat calendar (most commonly used calendar in Nepal). Currently display format is hardcoded to e.g. “१५ चैत २०७३”.

Validations

Validation rules are code fragments used to determine if some input is valid. For example, to say a field is only valid if the value has at least five characters, you would use the lenMin(5). They are used in registrations[].validations.list[].rule and patient_reports[].validations.list[].rule to determine if an incoming report is accepted. A report is accepted as valid only if all rules return true. If any validation rule returns false then the report is marked as invalid, and a message is automatically sent to the submitter. The content for the message is set in the translation_key associated to each rule. If a report fails multiple validations then each message will be sent. These can be combined into a single SMS by specifying "*.validations.join_responses" : true.

Operators

The available operators are:

OperatorDescription
&&and
||or
!not
a ? b : cternary, ie: if ‘a’ is true, then check ‘b’, otherwise check ‘c’
()nested blocks, eg: ‘a && (b

Rules

Validation settings may consist of Pupil.js rules and rules specific to Medic Mobile. These two types of rules cannot be combined as part of the same rule.

Not OK: rule: "regex(\d{5}) && unique('patient_id')"

OK: rule: "regex(\d{5}) && max(11111)"

If for example you want to validate that patient_id is 5 numbers and it is unique (or some other custom validation) you need to define two validation configs/separate rules in your settings. Example validation settings:

[
	{
		property: "patient_id",
		rule: "regex(\d{5})",
		message: [{
		    content: "Patient ID must be 5 numbers.",
		    locale: "en"
	}]
	},
	{
		property: "patient_id",
		rule: "unique('patient_id')",
		message: [{
		    content: "Patient ID must be unique.",
		    locale: "en"
		}]
	}
]

validate() modifies the property value of the second item to patient_id_unique so that pupil.validate() still returns a valid result. Then we process the result once more to extract the custom validation results and error messages.

Pupil.js validation functions

Available validation functions are available at https://www.npmjs.com/package/pupil#validation-functions

The following functions are available by default:

FunctionDescription
equalsComparison
iEqualsCase insensitive comparison
sEqualsType sensitive equals
siEqualsType sensitive case insensitive equals
lenMinMinimum length
lenMaxMaximum length
lenEqualsExact length
minMinimum value
maxMaximum value
betweenMinimum and maximum value
inOne of the provided values
requiredMust have a value
optionalAlways valid
numericNumbers only
integerInteger numbers only
alphaLetters only
alphaNumericNumbers and letters only
emailEmail address format
regexA custom regular expression
equalsToCompare to another field by its key
Sample usage

For case-insensitive comparison iEquals function in Pupil, And you can use || for logical OR : https://www.npmjs.com/package/pupil#rule-strings

So you can do this : rule: 'iEquals("mary") || iEquals("john")' matches “mary”, “Mary”, “john”, “John”, “JOhN”, etc. Not “maryjohn”

CHT validation functions

FunctionDescription
unique(*fields)Returns true if no existing valid report has the same value for all of the listed fields. Fields are compared to those at the top level and within fields for every report doc. To include the form type use 'form' as one of the fields. Eg unique('form', 'patient_id') checks that this form was never submitted for this patient.
uniqueWithin(*fields, time_period)Same as unique but the last argument is the time period in which to search. Eg uniqueWithin('form', 'patient_id', '1 week') checks that the same form wasn’t submitted for this patient in the past week.
exists(form_id, field)Returns true if a report matches the form_id and value for field. This is useful to check that a patient was registered for a service before reporting about it. Eg exists('REG', 'patient_id') checks that a REG form was already submitted for a patient. As of 2.12 most uses of this function are obsolete because checking for a valid patient_id is done automatically by the accept_patient_report transition using registration_not_found in the messages.event_type.
isISOWeek(weekFieldName[, yearFieldName])Returns true if the current report has a week value that is less or equal to the number of ISO weeks of the current year or the year value of the same report. The first parameter is the field name for the week and the second parameter is the field name for the year: isISOWeek('week', 'year'). If the second parameter is not specified, then the current year is used: isISOWeek('week').

.accept_case_reports

Case Reports: Defining SMS workflows with schedules and registration of case reports.

.contact_types

Hierarchy: Setting the types of places and people in the hierarchy

.dhis_data_sets

DHIS2 Integration: Instructions and schema for defining DHIS2 integrations

.forms

JSON Forms: Instructions and schema for defining JSON forms used for handling reports from SMS and external tools

.header_tabs

Configuring app header tab icons

.outbound

Outbound Push: Exchanging data between CHT applications and other tools

.patient_reports

Patient Reports: Defining SMS workflows with schedules, registration, and patient reports.

.permissions

User Permissions: Assigning fine grained settings for user roles

.registrations

Registrations: Defining SMS workflows with schedules, registration, and patient reports.

.reminders

Configure SMS reminders to users

.replication_depth

Replications: Instructions for replication depth

.roles

User Roles: Defining the roles that can be assigned to users.

.schedules

SMS Schedules: Defining SMS workflows with schedules, registration, and patient reports.

.sms

SMS Settings: Instructions and schema for defining SMS settings

.token_login

Token login: Instructions and schema for Login by SMS

.transitions

Sentinel Transitions: functions executed when database documents change