app_settings.json

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 settings get compiled into the app_settings.json file with the compile-app-settings action in the cht-conf tool. Manually configurable settings are added to the app_settings folder at the root of the config folder. The app_settings/base_settings.json file can be manually edited to modify individual settings. forms, schedules, and assetlinks sections can be defined in separate files named app_settings/forms.json, app_settings/schedules.json, and app_settings/assetlinks.json respectively with the settings in the files overriding what might be already present in the app_settings/base_settings.json or app_settings.json files.

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.

cht --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

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 specified 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. As of 3.11.0, places are valid subjects for any SMS workflows.

SMS recipient resolution

An outgoing SMS message configuration has the following fields:

recipient values and resolutions:

Message context

The message context object consists of:

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 formatting dates.

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.

The syntax aims to mimic C-like languages. You can use logical operators, ternaries, nested “blocks” (rule && (some || nested || rules)) and validation functions (validationFunction("arg1", "arg2")).

String parameters for validation functions, such as the regex in the “regex” function, should be quoted.

Non-quoted parameters will be cast to floats (numbers with decimals).

For each validation function, there is also a matching function prepended by other that allows you to run functions on other values than the one the rule string is for. This can be useful for fields that have differing requirements depending on another field. For example:

{
  "state": "otherEquals('country', 'US') ? lenMin(2) : lenMin(0)"
}

This rule validates the length state property if the country is set to “US”, but skips validation otherwise.

Validation function arguments can be either strings or numerical values. Numerical arguments should not be wrapped in quotation marks or apostrophes: lenMin(5).

Operators

The available operators are:

Rules

The following functions are available by default:

Sample usage

To ensure the patient_id is 5 digits and not already registered.

[
  {
    "property": "patient_id",
    "rule": "regex(\d{5}) && unique('patient_id')",
    "translation_key": "patient_id_invalid"
  }
]

For case-insensitive comparison, use iEquals function, and you can use || for logical OR. So the rule iEquals("mary") || iEquals("john") matches “mary”, “Mary”, “john”, “John”, and “JOhN”, but not “maryjohn”

Combining rules

Prior to 4.15.0 you could not combine certain rules. Check this bug report for more information.