Configuration

This chapter is a reference documentation for the settings in the configuration file config.xls that contains all the user-modifiable settings for the webapp. Some settings (such as database connection parameters) cannot be changed by the user of the webapp, but only by the sysadmin (see setting up an instance).

When using odk_planner for the first time, please have a look at the tutorial.

All configuration is done by first downloading and then editing the file config.xls locally (using Excel or LibreOffice), before uploading the updated file to the server. To do this, log in with an account that has “admin” rights and then click on the admin link in the top navigation menu.

The following subsections are structured the same way as the sheets in the file config.xls

settings sheet

This sheet contains general information on how the data in the ODK database is structered and how it should be accessed as well as the email configuration.

  • idfield : Name of field that links forms together (e.g. study participant ID). If a form does not have this field, it will not be displayed in the Overview entered forms
  • idfield_start, idfield_length : Which part of the idfield should be used to match different rows into the same column. For example, if IDs include a variable part at the end, such as the visit identifier -V01 in the ID 80001-31-V01, then $idfield_start=0 and $idfield_length=8 would match the IDs 80001-31-V01 and 80001-31-E03
  • datefield : Specify which form field should be used to determine when the form was filled in. Normally, such a field would be specified as type today in the .xls form. If a given form does not have the specified field, the submission date is taken (auto generated by ODK).
  • title : The title is showed on the login site and in the menu; particularly handy if using multiple instances.
  • opentabs : set to yes if you want data and sms related pages to automatically open in a new tab.

users sheet

Access to odk_planner is restricted by username/password. Different users can have different access rights. The username/password/access rights are stored in the columns name, password, rights and access.

The following rights are defined (specify any combination separated by commas):

  • overview : can dispaly the main overview table of entered data
  • data : can see the actual data inside the forms; what fields are visible to what user can be set by different values for access. see Example of access restrictions
  • forms : can upload and delete .xls forms (see Uploading form template)
  • sms : can send messages
  • admin : can change the configuration file config.xls and view the logs

overview sheet

This sheet specifies which IDs should be grouped together into one overview table. For example, a project can contain two groups of subjects with a partly overlapping set of forms for each. Instead of generating one big overview containing all subjects and all forms, it would then be more clearly laid out to have an different overview table for every group. The id_rlike field contains an expression that matches all IDs for the given group – a ".*" (without double quotes) is a wildchar that matches any number of characters (read more about MySQL regular expressions; and a relatively easy tutorial can be found here). In addition to the ID-based separation, it is also possible to use arbitrary fields from submitted forms to define what cases should be shown in which overview (by specifying a condition; see below for the format of the conditions). A given ID may appear in any combination of overviews.

Example : show all forms of all IDs in same big overview table

id_rlike name subheading condition forms
.*        

Example : If the IDs of patients start with 80 and the IDs of controls start with 83, then the following table would generate two overview tables, showing the CRFs and the LRFs respectively, each overview split into tables with subheadings for cases and controls.

id_rlike name subheading condition forms
^80.* Clinic Cases   CRF1,CRF2,CRF3
^83.* Clinic Controls   CRF1,CRF2,CRF3
^80.* Lab Cases   LRF1,LRF2
^83.* Lab Controls   LRF1,LRF2

Example : Split IDs into two overviews showing the same forms, depending on whether the field CRF1\sex is male or female:

id_rlike name subheading condition forms
.* Men   CRF1\sex=”male” CRF1,CRF2,CRF3,LRF1,LRF2
.* Women   CRF1\sex=”female” CRF1,CRF2,CRF3,LRF1,LRF2

colors sheet

Every row in this sheet defines a timing constraint that is visually displayed in the overview table. A timing constraint is defined between two forms. Once the form specified by the column form1 is entered, a timer is started. When this timer reaches delay days and the form form2 is not yet entered into the database, then the corresponding table cell will get the CSS style specified in the style column (defaults to background-color property). If more than one row apply to a cell, then its styles are applied in the same order as the rows in the table.

As a special case, the cell of a form can be colored independent of any other form. This way, forms can be highlighted depending on their content (using conditions). In this case, specifying only form2 is enough (see example below).

As a special special case, only form2 is specified and it’s set to a single asterisk * which will allow to color the row header (where the ID is shown).

Optionally, this coloring can be made dependent on any number of conditions that must all be fulfilled in order for this coloring rule to apply to the given forms. These conditions are specified in the column condition.

field1 > 1 & (formid1\field2 = "value with space" | field3 < 5)

Remarks:

  • when no formid is specified, the field refers to the form from column form2
  • only the operators <, >, = and != are allowed
  • if the value contains spaces, it must be enclosed in double quotes
  • logical or | as well as logical and & can be used to connect different expressions (and takes precedence over or)
  • arbitrarily complex logical expressions can be constructed using grouping parenthesis
  • an expression with a non-existing field (e.g. because a form has not been submitted) always evaluates as false; therefore, an expression like FORM\FIELD>"" will therefore evaluate to false if the form is not submitted, the field is not found in the form, or the value of the field is the empty string – in all other cases the expression would evaluate to true (regardless of the datatype of the value)

Example : The following lines will highlight the empty cell for the follow_up form if the briefing form has has specified that a follow up should be done for this subject (field needs_follow_up). The empty cell will first be highlighted green after a week. If it’s still empty after a second week, the cell color will turn orange and then finally red. Additionally, IDs (in the row header) are underlined for these individuals.

form1 form2 delay style condition
(empty) briefing   background-color:green needs_follow_up=yes
briefing follow_up 7 background-color:green briefing\needs_follow_up=yes
briefing follow_up 14 background-color:orange briefing\needs_follow_up=yes
briefing follow_up 21 background-color:red briefing\needs_follow_up=yes
(empty) *   text-decoration:underline briefing\needs_follow_up=yes

Condition format

Conditions can be used in the condition column of the colors heet and the overview sheet. They have the following format:

field1 > 1 & (formid1\field2 = "value with space" | field3 < 5)

Remarks:

  • formid\field is the name of the field as displayed in the data viewer, this is not necessarily the field name as specified in the .xls file (for example if the .xls file defines a field called ID in the group INFO, then the name of the field will probably be INFO_ID).
  • when no formid is specified, the field refers to the form from column form2
  • only the operators <, > and = are allowed
  • if the value contains spaces, it must be enclosed in double quotes
  • logical or | as well as logical and & can be used to connect different expressions (and takes precedence over or)
  • arbitrarily complex logical expressions can be constructed using grouping parenthesis

Additional columns

  • list : The list column specifies which of these rules should be used to generate files of “missing forms”. If the list column is left empty, the form is not added to a .csv list (e.g. rules that are merely used to highlight some condition). If the column is not empty, then its content will be used as the remark column in the generated list file.
  • more : This column contains settings for additional rule-based actions. The format is the following : A space separated list of option:value pairs. The possible options are:

Example : The following lines will automatically send the message from template welcome to every participant as soon as the form briefing is submitted. If the form follow_up is not entered after one week, the participant will be added to the missing list with the remark briefing 1 week old. If the follow up is still not entered two weeks after the briefing was submitted, the web application will propose an autogenerated message, but this message will not automatically be sent (because the exclamation mark is missing). In a real configuration, these rows should be combined with the rows from the example above.

form1 form2 delay list more
(empty) briefing     sms:welcome!
briefing follow_up 7 briefing 1 week old (empty)
briefing follow_up 14   sms:follow_up_overdue

cron sheet

This sheet contains settings regarding the automatization:

  • notify_email : This address will receive an update every time the script is run autonomously.
  • notify_logs : A comma separated list of log files that are sent to the notify_email. The log files are added as .csv files and only new entries since the last email are included. If nothing changed since the last email, the log is not attached.
  • profile : If this value is set to yes, performance information is added to the cron log.
  • reports_mdays : A comma-separated list of days of the month on which a list of missing forms is attached to the email.

sms sheet

Configuration of messaging is done via the following key/value pairs:

  • default_country_prefix : if a phone number is specified with one leading zero ("0xxxxxxxx") then the default_country_prefix is automatically added in the beginning of the number (after stripping the single zero)
  • url : URL of messaging API (e.g. http://bulksms.vsms.net:5567/eapi/submission/send_sms/2/2.0 when using the bulksms API)
  • response_regexp : a regular expression (PCRE, but without the delimiters) that must match the response body sent by the server when a message was successfully delivered
  • params : default parameters that are sent with the message; include username and password here (e.g. username=XXX&password=XXX for the bulksms API)
  • param_message : name of the parameter that is used for the message (e.g. message for the bulksms API)
  • param_number : name of the parameter that is used to specify the receiver’s phone number (e.g. msisdn for the bulksms API) – the number will be formatted with country prefix but without any leading zeroes or plus sign
  • phone_numbers defines where phone numbers can be found in the forms. every entry has the form form_id\field_name and multiple entries are separated by spaces. forms that do not exist on the server, that are not found for the given patient, or that do not feature the specified field, are simply ignored.
  • template_NAME entries define the messaging templates. When writing a message using odk_planner, the message text can be chosen from these templates. The content of the templates is the only content that is allowed for autogenerated messages.
    • if this template starts with a phone number in the form +1234567890 (including country code) then the message is sent to this number instead of the number defined by phone_numbers
    • every {FORMID\FIELD} is replaced with the content of the specified form for the given patient. only fields that have a access column with sms can be sent via this mechanism

More sheets

odk_planner can be extended with additional files in the plugins/ directory that can use settings in the existing sheets or add a new sheet (with the same name as the plugin) to store settings. An example is the aforementioned sms sheets (the main plugin file is plugins/sms.php). Another example is the doughnut sheet that specifies which fields should be used to generate doughnut plots. Please see the comments in the file test/demo/config/confi.xls and in the file plugins/dougnut.php for more information how to configure these extensions.