LUA scripting in EFS Survey filters and the LUA question type offer users with programming skills more flexibility and convenience. The LUA question type, found in "Advanced", provides an efficient scripting interface to the survey environment, allowing users easily recoding of the survey's variables, execution of complex calculations, verification or processing of user input and extended quota calculations. The question type provides two code boxes, the first one is executed before sending the page to the participant, the second code box is executed when a user submits the page containing the LUA question type. You can also include your own function libraries from the media library (global or project specific, text files with the extension .txt or .lua), allowing you to reuse frequently used functions across projects. Hiding conditions can be employed and you may define whether the script should be executed every time the page is called or only once (e.g. when using a page trigger or the back button).
Many filters which need a lot of effort when working with EFS standard filter definitions or alternative filter conditions can be realized more easily with the LUA filters. E.g. a function is available which simplifies handling of system missings in filter conditions.
This manual presents examples of frequent scenarios when programming with LUA in EFS and is not intended to be a general introduction to LUA, for which several good resources exist [https://www.lua.org/manual/5.1/, https://www.lua.org/pil/contents.html].
EFS Survey uses LUA Version 5.1 in its LUA filters and LUA question type and provides access to almost all default LUA libraries. For security reasons, functions dofile, load, loadfile, print, require, rawequal, rawget and rawest and the os library are not available in the LUA environment. The functions os.date and os.time are available as date and time. The function mb_strlen is available as string.len.
Access to the Lrexlib is possible and allows advanced Regular Expressions within the LUA environment to search, validate or extract user input, for example, rex_pcre.find (v_1, "\\bhate") will search for words starting with hate and return false if none is found. The full documentation on rex_pcre can be found in the Lrexlib reference manual.
Survey variables are available within the LUA environment, which is accessible under the _G global table. Most variables are therefore accessible through this global table, e.g. by using _G["v_1"] or _G["code"]. Survey variables (v_xxx) are also injected into the LUA sandbox as regular variables, therefore _G["v_1"] == v_1.
LUA Cheat Sheet
Please see https://www.lua.org/manual/5.1/ and https://www.lua.org/pil/contents.html for full documentation.
EFS specific functions in LUA filters and LUA question type
setVariableValue(varName, varValue)
Assigns the given value to the specified v_, c_ or p_ variable. The variable can be anywhere in the questionnaire, shown or hidden. The LUA question type itself provides variables, which can be used to store information.
Data types
varName string - variable name
varValue string - variable value
setMasterDataValue(varName, varValue)
This function only executes in panel surveys and master data surveys. It assigns or overwrites the given value to the specified master-data variable of the current participant and stores it in the data base.
Data types
varName string - variable name
varValue string - variable value
setQuestionOutput(text)
Sets the output of the LUA-question. This function should only be used once, as subsequent calls overwrite previous values, also this function only generates output as part of code executed during rendering of the question.
Data types
text string - string to be shown in LUA-question
remove_sys_miss(varValue)
Converts the system missing (code -77) to 0 in order to ease arithmetic operations. For example, when using the calculation based LUA filter "return v_1+v_2+v_3>10", System Missings (Code -77) will negatively affect the calculations, therefore "return remove_sys_miss(v_1)+remove_sys_miss(v_2)+remove_sys_miss(v_3)>10" can be used to avoid this issue.
Data types
varValue mixed - provided answer of a variable, e.g. remove_sys_missing(_G["v_1"])
returns int
get_range_count(values, min_code, max_code)
Returns how many times the values specified are in the range provided by min_code and max_code. For example, the condition return get_range_count({v_1,v_2,v_3,v_4,v_5},1,3)>2 is true, if the participant answered more than 2 times in the first three categories of the matrix question represented by v_1-v_5.
Data types
values array - List of values, e.g. {v_1, v_2, v_3, v_4, v_5}
min_code mixed
max_code mixed
returns int
getQuotaDebitValue(id)
Returns the quota's debit value.
Data types
id int - quota ID
returns int
getQuotaCurrentValue(id)
Returns the quota's current value, e.g. setVariableValue("v_1", getQuotaCurrentValue(1))
Data types
id int - quota ID
returns int
getQuotaFillingDegree(id)
Returns the quota's filling degree. E.g. setVariableValue("v_1", getQuotaFillingDegree(1)*100 .. " %")
Data types
id int - quota ID
returns double
getQuotaIds()
Returns an array of available quota IDs.
Data types
returns array
count(condition)
Returns the number of participants which match the specified condition and can be used to display statistics to participants or dynamically routing in filters depending on answers given by other participants. WARNING! This function has impact on the performance of EFS and should only be used on surveys with low participations. For filing quotas, please use the built-in quota functionality in EFS as these are more efficient for this task.
Data types
condition string - conditional expression e.g. (v_1=1 AND v_2=2)
returns int or bool
in_list(list_id)
Checks if the current list_element is also contained in the specified list.
Data types
list_id string - Id of a list, e.g. "l_2"
returns bool
is_repeated_participation()
This function checks whether the participant has already taken part in the survey and is only applicable in Panel surveys (PA and MD).
Data types
returns int, 0 if false or 1 if true
is_assigned_in_or_below(check_metaname, metanames)
Checks whether the participant is part of the specified units or subunits in the org-structure of the ES project. Only applicable in Employee survey.
Data types
check_metaname string - metaname
metanames array - list of metanames the participant is assigned to
returns bool
is_assigned_in(check_value, codes)
Checks whether the participant's metaname code is assigned to the given unit metanames (array of codes). Only applicable in Employee survey.
Data types
check_value string - metaname
codes array - array of codes
returns bool
is_assigned_in_branch(check_metaname, metanames)
Checks whether the participant is assigned in part of specified units branch. Only applicable in Employee survey.
Data types
check_metaname string - metaname
metanames array - array of metanames the participant is assigned to
returns bool
check_character_filter_any(needle, haystack)
Checks whether the needle string is in the list provided in the haystack list of strings. Strings in haystack may be delimited by |, ",", ; or -.
Data types
needle string
haystack string
returns bool
date([format [, time]])
Replaces os.date() and returns a string or a table containing date and time, formatted according to the given string format. Please refer to os.date documentation.
time([table])
Replaces os.time() and returns the current time when called without arguments, or a time representing the date and time specified by the given table. Please refer to os.time documentation.
Examples for LUA in EFS
Blacklist specific IPs from accessing a survey using a LUA filter
If you have a manageable list of IPs, which you want to block from accessing your survey, you can use a LUA filter to screen out these participants. This example code blocks the IPs 78.34.112.1, 78.34.112.2 and 78.34.112.3 and the list can be extended by providing additional comma-separated IPs. The last item should not have a comma after it.
Example survey structure
Example code
function Set (list)
local set = {}
for _, l in ipairs(list) do set[l] = true end
return set
end
local blockedIps = Set {
"78.34.112.1",
"78.34.112.2",
"78.34.112.3"
}
if blockedIps[remote_addr] then
return false
else
return true
end
Show a item of the day to all participants
Select a random item from a list once per day, hour or minute and store it in variable v_1 for all participants for the defined time. The function math.randomseed sets the randomizing integer for the random function, by providing the same integer for other participants, the same random value will be returned. To get the size of an array, put # in front of the name, e.g. #randomRestaurants.
Example code
local randomRestaurants = {
"Indian Curry Basmati House",
"Calypso Grillbar",
"Rim Kong",
"Hayati",
"Metzgerei Kremer",
"Nakwon",
"KuroMaku Poke",
"Sushi Ninja",
"Vina Asia Express",
"485Grad",
"Osman Bey"
}
-- Initialize the randomiser with the current day, use "%y%m%d%H" for hours or "%y%m%d%H%M" for minutes
math.randomseed( date("%y%m%d") )
setVariableValue("v_1", randomRestaurants[math.random( #randomRestaurants )])
Detect first name, last name and company name from email address
This example takes the email address stored in v_1 and assigns the company, first and last name to variables v_10, v_11 and v_12. This works on email aliases using firstname.lastname@company.tld or firstname_lastname@company.tld as their format. If the first or last name are not detected, then the variables will not be assigned a value.
Example code
-- pattern for company name
setVariableValue("v_10",_G["v_1"]:match("@([%w+%-_]*)%.?"):gsub("^%l", string.upper))
-- pattern for first name
setVariableValue("v_11",_G["v_1"]:match("^([%w%-]+)[%._]"):gsub("^%l", string.upper))
-- pattern for last name
setVariableValue("v_12",_G["v_1"]:match("[%._]([%w%-]+)@"):gsub("^%l", string.upper))
Look up participant_country code in a list of countries
If you have enabled the setting "Detect participants' location using the IP address" in the survey's project properties, then EFS will store the code of the participants country in the variable participant_country. Currently, there is no possibility to recode this variable to another variable with the country's label. With the example code, the code will be looked up in an array and the country's label is stored in v_1. This can be used to pre-populate a text field when asking for a user's location and the example code can be adapted to match participant_country codes to codes in a select box for pre-selection.
Example code (long)
countries = {
[-99]="Unknown",
[1]="Satellite Provider",
[2]="Other Country",
[3]="Andorra",
[4]="United Arab Emirates",
[5]="Afghanistan",
[6]="Antigua and Barbuda",
[7]="Anguilla",
[8]="Albania",
[9]="Armenia",
[10]="Angola",
[11]="Asia/Pacific Region",
[12]="Antarctica",
[13]="Argentina",
[14]="American Samoa",
[15]="Austria",
[16]="Australia",
[17]="Aruba",
[18]="Aland Islands",
[19]="Azerbaijan",
[20]="Bosnia and Herzegovina",
[21]="Barbados",
[22]="Bangladesh",
[23]="Belgium",
[24]="Burkina Faso",
[25]="Bulgaria",
[26]="Bahrain",
[27]="Burundi",
[28]="Benin",
[29]="Saint Barthelemy",
[30]="Bermuda",
[31]="Brunei",
[32]="Bolivia",
[33]="Bonaire, Saint Eustatius and Saba",
[34]="Brazil",
[35]="Bahamas",
[36]="Bhutan",
[37]="Bouvet Island",
[38]="Botswana",
[39]="Belarus",
[40]="Belize",
[41]="Canada",
[42]="Cocos Islands",
[43]="Democratic Republic of the Congo",
[44]="Central African Republic",
[45]="Republic of the Congo",
[46]="Switzerland",
[47]="Ivory Coast",
[48]="Cook Islands",
[49]="Chile",
[50]="Cameroon",
[51]="China",
[52]="Colombia",
[53]="Costa Rica",
[54]="Cuba",
[55]="Cape Verde",
[56]="Curacao",
[57]="Christmas Island",
[58]="Cyprus",
[59]="Czechia",
[60]="Germany",
[61]="Djibouti",
[62]="Denmark",
[63]="Dominica",
[64]="Dominican Republic",
[65]="Algeria",
[66]="Ecuador",
[67]="Estonia",
[68]="Egypt",
[69]="Western Sahara",
[70]="Eritrea",
[71]="Spain",
[72]="Ethiopia",
[73]="Europe",
[74]="Finland",
[75]="Fiji",
[76]="Falkland Islands",
[77]="Micronesia",
[78]="Faroe Islands",
[79]="France",
[80]="Gabon",
[81]="United Kingdom",
[82]="Grenada",
[83]="Georgia",
[84]="French Guiana",
[85]="Guernsey",
[86]="Ghana",
[87]="Gibraltar",
[88]="Greenland",
[89]="Gambia",
[90]="Guinea",
[91]="Guadeloupe",
[92]="Equatorial Guinea",
[93]="Greece",
[94]="South Georgia and the South Sandwich Islands",
[95]="Guatemala",
[96]="Guam",
[97]="Guinea-Bissau",
[98]="Guyana",
[99]="Hong Kong",
[100]="Heard Island and McDonald Islands",
[101]="Honduras",
[102]="Croatia",
[103]="Haiti",
[104]="Hungary",
[105]="Indonesia",
[106]="Ireland",
[107]="Israel",
[108]="Isle of Man",
[109]="India",
[110]="British Indian Ocean Territory",
[111]="Iraq",
[112]="Iran",
[113]="Iceland",
[114]="Italy",
[115]="Jersey",
[116]="Jamaica",
[117]="Jordan",
[118]="Japan",
[119]="Kenya",
[120]="Kyrgyzstan",
[121]="Cambodia",
[122]="Kiribati",
[123]="Comoros",
[124]="Saint Kitts and Nevis",
[125]="North Korea",
[126]="South Korea",
[127]="Kuwait",
[128]="Cayman Islands",
[129]="Kazakhstan",
[130]="Laos",
[131]="Lebanon",
[132]="Saint Lucia",
[133]="Liechtenstein",
[134]="Sri Lanka",
[135]="Liberia",
[136]="Lesotho",
[137]="Lithuania",
[138]="Luxembourg",
[139]="Latvia",
[140]="Libya",
[141]="Morocco",
[142]="Monaco",
[143]="Moldova",
[144]="Montenegro",
[145]="Saint Martin",
[146]="Madagascar",
[147]="Marshall Islands",
[148]="Macedonia",
[149]="Mali",
[150]="Myanmar",
[151]="Mongolia",
[152]="Macao",
[153]="Northern Mariana Islands",
[154]="Martinique",
[155]="Mauritania",
[156]="Montserrat",
[157]="Malta",
[158]="Mauritius",
[159]="Maldives",
[160]="Malawi",
[161]="Mexico",
[162]="Malaysia",
[163]="Mozambique",
[164]="Namibia",
[165]="New Caledonia",
[166]="Niger",
[167]="Norfolk Island",
[168]="Nigeria",
[169]="Nicaragua",
[170]="Netherlands",
[171]="Norway",
[172]="Nepal",
[173]="Nauru",
[174]="Niue",
[175]="New Zealand",
[176]="Oman",
[177]="Panama",
[178]="Peru",
[179]="French Polynesia",
[180]="Papua New Guinea",
[181]="Philippines",
[182]="Pakistan",
[183]="Poland",
[184]="Saint Pierre and Miquelon",
[185]="Pitcairn",
[186]="Puerto Rico",
[187]="Palestinian Territory",
[188]="Portugal",
[189]="Palau",
[190]="Paraguay",
[191]="Qatar",
[192]="Reunion",
[193]="Romania",
[194]="Serbia",
[195]="Russia",
[196]="Rwanda",
[197]="Saudi Arabia",
[198]="Solomon Islands",
[199]="Seychelles",
[200]="Sudan",
[201]="Sweden",
[202]="Singapore",
[203]="Saint Helena",
[204]="Slovenia",
[205]="Svalbard and Jan Mayen",
[206]="Slovakia",
[207]="Sierra Leone",
[208]="San Marino",
[209]="Senegal",
[210]="Somalia",
[211]="Suriname",
[212]="South Sudan",
[213]="Sao Tome and Principe",
[214]="El Salvador",
[215]="Sint Maarten",
[216]="Syria",
[217]="Swaziland",
[218]="Turks and Caicos Islands",
[219]="Chad",
[220]="French Southern Territories",
[221]="Togo",
[222]="Thailand",
[223]="Tajikistan",
[224]="Tokelau",
[225]="East Timor",
[226]="Turkmenistan",
[227]="Tunisia",
[228]="Tonga",
[229]="Turkey",
[230]="Trinidad and Tobago",
[231]="Tuvalu",
[232]="Taiwan",
[233]="Tanzania",
[234]="Ukraine",
[235]="Uganda",
[236]="United States Minor Outlying Islands",
[237]="United States",
[238]="Uruguay",
[239]="Uzbekistan",
[240]="Vatican",
[241]="Saint Vincent and the Grenadines",
[242]="Venezuela",
[243]="British Virgin Islands",
[244]="U.S. Virgin Islands",
[245]="Vietnam",
[246]="Vanuatu",
[247]="Wallis and Futuna",
[248]="Samoa",
[249]="Yemen",
[250]="Mayotte",
[251]="South Africa",
[252]="Zambia",
[253]="Zimbabwe",
[254]="Kosovo",
[255]="Serbia and Montenegro",
[256]="Netherlands Antilles"
}
setVariableValue("v_1",countries[_G["participant_country"]])
Get current GMT time
This code will always return the time in GMT and can be used for date related calculations. By putting an exclamation mark (!) in front of the formatting in the date function, the returned date will always be using the GMT time zone.
Example code
setVariableValue("v_1", date("!%H %M"))
Comparing the Frequency of completed Interviews
The following alternative filter condition checks which of several possibilities the participants preferred so far:
(count['v_1 = 1'] > count['v_2 = 1'] ) AND (count['v_1 = 1'] > count['v_3 = 1'] ) OR (count['v_2 = 1'] > count['v_1 = 1'] ) AND (count['v_2 = 1'] > count['v_3 = 1'] )
If at the point in time when a participant passes the filter, v_1 or v_2 were selected more frequently, the filter condition is fulfilled.
If v_3 has been selected more frequently, the condition does not apply for the current participant.
Using LUA instead of the alternative filter function has several advantages:
Speed: Each count strains the server. In the alternative filter condition above, count requests are executed repeatedly for the same variable. In the LUA condition above, only one count request is necessary for each variable.
Shortness and overview: The more variables are to be checked, the longer and more confusing the alternative filter condition will become. In the LUA filter below, additional variables are simply added to the “configuration” section.
Easier to maintain and configure:
– When making changes, all you need to do is modify the two arrays in the “configuration” section.
– Non-programmers can re-use the condition, by doing simple copy&paste and a few minor modifications.
Example code
-- configuration
vars={"v_1","v_2","v_3"}
relevant_filter_vars={"v_1","v_2"}
-- no need to change anything below
counts={}
max=nil
max_var=nil
for k,v in ipairs(vars) do
local count=count(v)
if max==nil or max<count then
max_var=v
max=count
end
end
for k,v in pairs(relevant_filter_vars) do
if v==max_var then
return true
end
end
return false
Comparing Answer Patterns
The filter checks if the sum of answers in a 1st branch equals the sum of answers in a second branch. In the following example, for the sake of briefness, only one of these sums is created. The survey contains variables in the range v_135 to v_173.
The syntax ( v_x > 0 ? 1 :0) used in the alternative filter condition ensures that hiding conditions and unanswered items are considered appropriately:
If the participant has answered v_x > 0. With v_x > 0 ? 1 the value is uniformly set to = 1.
If the participant has not seen or not answered an item, i.e. v_x smaller or equal 0, the corresponding factor will be set = 0. This is necessary because missing values, as e.g. -77, prevent a proper calculation of the sum.
(( v_135 > 0 ? 1 :0) + ( v_136> 0 ? 1 :0) + ( v_137 > 0 ? 1 :0) + ( v_138 > 0 ? 1 :0) +( v_139 > 0 ? 1 :0) +( v_140 > 0 ? 1 :0) + ( v_141 > 0 ? 1 :0) + ( v_142 > 0 ? 1 :0) + ( v_143> 0 ? 1 :0) + ( v_144 > 0 ? 1 :0) + ( v_145 > 0 ? 1 :0) + ( v_146 > 0 ? 1 :0) + ( v_147 > 0 ? 1 :0) + ( v_148 > 0 ? 1 :0) + ( v_149 > 0 ? 1 :0) + ( v_150 > 0 ? 1 :0) + ( v_151 > 0 ? 1 :0) +( v_152 > 0 ? 1 :0) +( v_153 > 0 ? 1 :0) +( v_154 > 0 ? 1 :0) +( v_155 > 0 ? 1 :0) +( v_156 > 0 ? 1 :0) +( v_157 > 0 ? 1 :0) +( v_158 > 0 ? 1 :0) +( v_159 > 0 ? 1 :0) + ( v_160 > 0 ? 1 :0) + ( v_161 > 0 ? 1 :0) + ( v_162 > 0 ? 1 :0) + ( v_163 > 0 ? 1 :0) + ( v_164 > 0 ? 1 :0) +( v_165 > 0 ? 1 :0) +( v_166 > 0 ? 1 :0) +( v_167> 0 ? 1 :0) +( v_168 > 0 ? 1 :0) +( v_169> 0 ? 1 :0) + ( v_170 > 0 ? 1 :0) +( v_171 > 0 ? 1 :0) +( v_172 > 0 ? 1 :0) +( v_173 > 0 ? 1 :0)) [...etc]
With LUA, this can be achieved much easier, by creating a for loop and passing a counter ranged from 135 to 173, alternatively an array of specific variable ids could be supplied to the for loop.
Example code
sum=0
for i=135,173 do
if _G["v_"..i]>0 then
sum=sum+1
end
end
My code is not working, what should I do?
First of all, check if there are any trigger errors reported on the survey menu, EFS does not display LUA errors to survey participants. You can also go to Test and validation -> Project check, click on errors in "Errors while processing the survey" to get a list of all trigger errors in your survey. Also check the execution time of the LUA code, whether it is processed when the page is loaded or only when the page is submitted, and whether all required variables have already been filled in by the participant when the LUA code is executed.
If this does not help use external LUA sandboxes where debugging is easier, for example online at repl.it or in a local LUA 5.1 sandbox on your computer. You will have to create any EFS variables or EFS-specific functions in the external LUA sandbox, see the end of this page for an example.
Please note, that Questback's EFS support team is unable to assist you in bug fixing your LUA code.
Useful LUA resources
Programming in LUA 5.0, free for personal use
Lrexlib reference manual (Regular Expressions)
Repl.it provides a convenient LUA 5.1 online environment for writing and debugging LUA code in a controlled environment. Some EFS functions can be emulated by rewriting them, see example below.
Example functions for use in repl.it
-- EFS function getQuotaCurrentValue with array of example quota-values function getQuotaCurrentValue(a) b = {8, 4, 2, 3, 3, 2, 3, 2, 2, 2, 2, 2, 3, 2, 3, 3, 3, 5, 3, 1, 5, 4} return b[a] end -- EFS function setVariableValue function, outputs value to console as v_1=1 function setVariableValue(a,b) print(a .."="..b) end