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 formsidfield_start
,idfield_length
: Which part of theidfield
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 ID80001-31-V01
, then$idfield_start=0
and$idfield_length=8
would match the IDs80001-31-V01
and80001-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 typetoday
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 toyes
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 datadata
: can see the actual data inside the forms; what fields are visible to what user can be set by different values foraccess
. see Example of access restrictionsforms
: can upload and delete.xls
forms (see Uploading form template)sms
: can send messagesadmin
: can change the configuration fileconfig.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 columnform2
- 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 calledID
in the groupINFO
, then the name of the field will probably beINFO_ID
).- when no
formid
is specified, the field refers to the form from columnform2
- 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 thelist
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 theremark
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 ofoption:value
pairs. The possible options are:
sms
: Specify what short message should be generated based on this rule. The value of this option is the name of a template. If the template title is followed by an exclamation mark!
, then the corresponding message is also sent autonomously.
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 thenotify_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 toyes
, performance information is added to thecron
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 thedefault_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 deliveredparams
: 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 signphone_numbers
defines where phone numbers can be found in the forms. every entry has the formform_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 byphone_numbers
- every
{FORMID\FIELD}
is replaced with the content of the specified form for the given patient. only fields that have a access column withsms
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.