Changes in this release are almost entirely related to security.
New Features
Form/Session based authentication for the User Interface
This means you will no longer see a pop-up dialog when you logon. Instead you will be taken to a logon page.
Token based authentication for the API
A new version of the API has been created that uses token based authentication. This has only been implemented for the data API. Hence you can use the new URL /api/v2/data with security tokens.
A token can be obtained for a user by clicking on the user profile button and selecting “API Key”.
The key provides the same level of access to the server as the user who created it.
Example of using tokens with Power BI
In Power BI desktop select “Get data from another source”. Then click on “Other”
2. Select “Web” and then click on “Connect”
3. Get the version 2 API URL for the survey whose data you want to use. This can be found by selecting the API module then selecting version 2 and the survey you want.
4. Select “Advanced” in the Power BI dialog and paste the API URL into the first of the “URL parts”. Then get your API key by logging on to the server, selecting the user profile icon on the main menu and then selecting “API Key”. Add a header called x-api-key and paste the key as the value of this header. Then press “OK”.
5. Then click on connect and you should see your data.
Support for Ubuntu 24.04
If you are installing your own server you should now use the latest 24.04 LTS version of Ubuntu to maximise the length of support that you will get.
Formatting of Dates and Times in Server calculations
Say you want to create a PDF with the format of a date or date/time looking like “22/05/2024”. If you just include your date in the PDF it will show as “2024-05-22”. Now you can create a server calculation using the “to_char” function:
to_char(${date_question},'DD/MM/YYYY')
Include this new server calculation in your PDF and set the date question to hidden.
Other Changes
Session timeout after 10 minutes of inactivity.
The service worker has been removed. This means you can no longer install WebForms as an app in a browser. This may be added back in a later release.
Logout now works properly in Firefox
DTD processing is disabled when parsing XML files
Error messages now do not include the version of the software that generated the error
This release includes 3 user requested changes. Hopefully they will prove useful to others
New Features
Notifications on Server Calculation Changes
Server Calculations can change anytime, for example if the calculation depends on the current date. Previously it was not possible to trigger a notification when the calculated value changed but now it is.
In notifications select a trigger of “Server Calculation”. You will also need to:
Specify the survey containing the server calculation
The Server Calculation question
The value that will trigger the notification. Note this value should be text and quotes are not required.
Web Form History
The history of submissions from WebForms is now stored in your browser. You can access this history from a menu on the server WebForms page or by opening the draw at the left of a WebForm and pressing the history button.
The history page shows the surveys that have been completed and submitted over the last 100 days. The action can be Submitted, Saved or Deleted. The instanceId is useful for connecting a Submission entry in the History to a record in the Console of the server.
Note the webform history is not stored on the server, so if you are reconciling somebody’s work you will have to ask them to talk through what they see in their history.
Download of shared CSV files in the format they were uploaded
Downloading a reference file from the shared resource page will now download the file that was last uploaded instead of downloading the data always in CSV format. This may be a spreadsheet in XLSX format rather than CSV format. The server will have converted the XLSX file to CSV for use in FieldTask but you don’t need to know that when you want to edit the reference data.
This avoids problems with the formatting of data loaded from a CSV file into a spreadsheet. For example I was working on a reference file that included assessments of distance vision such as 6/5 and 6/9. Every time I opened the CSV file, downloaded from the server, these values would be converted to dates. You can address this type of problem by working in Excel’s XLSX format and setting the format of the cells to text. You can then upload the XLSX file to the server so it can be used as a reference file and this XLSX file will be the one downloaded when you download the reference file for editing.
Other Changes
An integer representing the identifier of an email is now automatically added to the subject line of emails. This addresses a problem where email clients such as gmail do not effectively differentiate between multiple emails with the same subject. This can cause problems if you do multiple password resets in succession, you may end up clicking on the old link to reset your password.
This release contains a simple little change to allow WebForms to launch another survey to update an existing record. For example you can have a survey that searches for a patient record and then launches a survey to edit that record. This feature only works online but will make it easier to implement fully functional systems without requiring any coding.
I am considering extending this capability to FieldTask however at the moment I am not sure whether the functionality in FieldTask should be offline, online or both so I will defer it till another release.
New Features
Launching a new survey from a Survey now available in WebForms
When launching a survey form you can include a parameter with the instance id of the record to be updated. This will cause the launched survey to be pre-populated with the data from the record you want to update.
To do this create a survey that will look up records.
Add a way of selecting the instance id of the record in another survey. This could use pulldata or the search() appearance in a select one question. Using search() is supported by the online survey editor.
Add a “Child Form” or “Parent Form” question type. If you are not sure which one to use then either will be fine.
Add a parameter that identifies the instanceid to use. For example “instance=${get_instance}”
The following video shows this functionality.
You can pass initial data to the started surveys that override the value in the instance.
“Restore Data” from Archive moved to background
The process that restores a table of data for a survey using the original submissions has always run in the background. However on larger installations the original submissions may be backed up to low cost storage. Copying these back to the server can take some time causing timeouts and reports of errors. However this retrieval of submissions from archive is now also done in the background. It is treated as a background report so an entry will be shown in the reports page with the result of the request.
In summary you may notice the following changes when requesting a restoration of data:
No more error messages!
There may be a lengthy delay of several minutes before the submissions start being re-applied
You can check on the progress of the request in the reports module, once this shows the request is complete you can follow progress of the re-application of the submissions using the monitoring page.
Other
Allow a super user to reapply failed uploads from the monitoring page for a survey that requires a security role even when they do not have that role. A super user should not be constrained by RBAC.
Instead of entering a value of “yes” or “true” in the “required” column of the XLSForm, to indicate that a question is required, you can specify an expression. The question will then only be set required if that expression evaluates to true.
type
name
label
required
required_message
select_one yes_no
required_question
Should the next question be mandatory?
text
situation
Describe the situation
${required_question} = ‘yes’
You must answer
Making a question required during a survey
This feature is available for both FieldTask and WebForms.
You can also set the required expression in the online editor. First click the button to make the question required and then enter the expression.
Dynamic Read Only Questions
Like dynamic required questions, you can also make a question be read only or editable depending on an expression. For example you may pre-fill address questions with existing values and make these read-only but then use a question called “changed” to make them editable.
type
name
label
readonly
default
select_one yes_no
changed
Changed?
text
address
Address
not(${changed} = ‘yes’)
Fleet Street
Making an address question read-only if the address has not changed
Note: Unlike the conditional required feature this is not available for WebForms.
Other
Dynamic Defaults inside of a repeat. Using both FieldTask and WebForms you can now set a default value for a question inside a repeat that is calculated from previous repeat instances. Documentation is here.
Performance Improvements. Hopefully you will find accessing the online editor and the console faster.
Updated some infrastructure libraries to the latest version including Jersey and the PostgreSQL JDBC driver.
Previously case management alerts were generated if a case was not closed and it was older than the specified interval. You can now also add a filter so that the alert can conditionally be created depending on it’s data. For example you could create an alert. “Serious issue is Late”, with a filter ${criticality} = ‘serious’.
Note: you can refer to any data in the case using the ${} syntax.
Extendable Initialised Repeats
Previously, when you added a repeat count to a sub form, the number of repeats was set by the value of that count and the person filling in the form would not be asked if they wanted to add another record. This is probably what you want if the repeat count is set inside the form or is fixed. However you may have the situation where you are filling out a sub form using initial data from another survey so the repeat count is set by the number of existing records but you still want to allow the user to add additional records.
FieldTask version 6.814 is required to use this feature in FieldTask.
The specific user scenario where this requirement arose was for a list of suspects in a police case. We created a form that allowed the existing suspect information to be updated but we also wanted to allow additional suspects to be added.
This can now be done in WebForms and FieldTask by setting the appearance “extendable” on the “begin repeat”.
Rate Limiting APIs
An improved rate limiter has been added. This now limits the number of requests per minute, per organisation. By default the rate per minute is set to 0 which means no limit. However you can change this in the settings for your server. You need to have server owner privileges to do this.
If the rate is exceeded then an error message is returned with the request. Currently if you set an API rate limit it will apply to the following services:
api/v1/data
api/v1/data.csv
surveyKPI/items (Called when you view a table of data for a survey on the analysis page)
Automatic Sentiment Analysis of Text Responses
A sentiment can be automatically calculated for text responses entered in any of the following languages; English, German, Spanish, Italian, Portuguese, French, Japanese, Korean, Hindi, Arabic and Chinese. This is done using Amazon Web Services (AWS) Comprehend service. The sentiment can have one of the following values; Positive, Negative, Neutral or Mixed. A confidence value in the sentiment can also be generated.
To add the sentiment to a text question include the following parameters:
auto_annotate=true
sentiment=yes
from_lang={the language you are getting the sentiment from}
source={the question name that has the text – no curly brackets around the name}
Note the online editor assists you in setting most of the above. Although you will have to add sentiment=yes yourself as an “other” parameter. This is shown below.
Other Changes
Improved the performance of the shared resources page for sites with a lot of resources
Improved performance of submissions. Notifications and other events triggered by a submission are now processed in a separate queue so that the submission manager can get straight on to the next submission.
Server side validation to detect invalid characters in names for projects, users, roles and so on
Server side sanitation of html for labels to remove executable scripts now done when the text is entered as well as when it is used
Fixed issues with the script that does a fresh install of the server
Reduced the volume of log entries written by automatic scripts, now these will only write one entry per day, not every time they run
Allowed a notification that sends a periodic report to be disabled
Allowed dateTime type questions to be updated in an oversight form
Previously the log page showed the last 10,000 entries. It wasn’t possible to go further back in time than this which was starting to become a problem for high volume users. 10,000 was also quite a lot of entries to retrieve in one hit and it could be quite slow.
The change included in this release is to require a month to be selected and then all log entries for that month will be shown. There are also now forward and back buttons so you can easily page through the data to find the log entries that you need.
Convert Date/Time values to FieldTask Format in CSV files
If you have been using the pulldata() or lookup() function to get a Date/Time value from one survey to use in another survey, then you will have seen some significant limitations:
The data is returned in a format that cannot be used in a Date/Time question! So you have to put it into a text question.
The timezone is UTC so if you are using it as a text value, and showing it to a user completing a different survey, then the value shown will be misleading.
Date/Time values are now returned in fieldTask format. They are still in the UTC timezone but if you load the value into a Date/Time question then it will be displayed in the timezone of the device. You can also now use date functions to convert the value to the local timezone and then format it for display as text.
2. Getting the date value and displaying it as text in the local time zone
Note in example 2 above the date() function converts the UTC value into the local timezone and the format-date() function then converts this local date into text.
Always send an email to a person assigned to a case
This change builds on last months update which added the ability to select a checkbox to email a user who has been automatically assigned a case. Now if you manually assign a case to a user, and if they have an email address, then they will be automatically notified by email.
People have previously approached me about adding the automatic generation of reports but I haven’t considered it a high priority until now. In the case of M&E surveys it is very important to monitor submissions so that you can identify interviews that didn’t happen or problems with the survey design but these surveys usually only last for a few weeks or months and you can do this monitoring using a web browser.
However as more organisations use Smap for case management, the management of new records is required on an ongoing basis and it would be useful to get a regular email containing new and updated cases.
Hence I have added this capability to Smap. You can of course also use this new feature to monitor your M&E surveys by generating a spreadsheet automatically each day containing the previous day’s completed surveys.
Periodic Reports
These consist of two parts:
The report
A notification that generates a report covering submissions for a period of time and emails it to recipients.
The specification of reports has not changed. You can create them in the reports module under the “Public Reports” tab. However the date question, start date and end date will all be ignored when the report is generated from a notification. The date used will be the date of submission of the record to the server. The start and end dates that determine which records will be included will be determined by the notification. There is also a restriction that only spreadsheet reports can be generated periodically, so no PDF reports.
A new trigger has been added to notifications called “Periodic”. The only target permitted is “Email” so an email will be sent with the attached report.
You can then specify the period as one of:
Daily
Weekly
Monthly
Yearly
Depending on the selection additional fields will be shown allowing you to specify day of the week, day of the month and month of the year.
You can set the time when the report will be generated. The data included in the report will depend on the selected period:
Daily. All submissions on the day before the report is generated.
Weekly. All submissions for the week before the report is generated.
Monthly. All submissions for the month before the report is generated. So if you have specified that the report is generated on the 9th day of the month then included submissions will be up until midnight on the 8th day.
Yearly. All submissions for the year before the report is generated.
Other Changes
Improve the performance of the generation of usage reports.
Include deletion of a record, and restoration of a deleted record, in the history of that record
This release addresses some long standing issues with shared resources. As usual it was during a training course when these shortcomings became obvious with a dozen people updating the same shared CSV file.
Shared Resources
The name of the shared resource can be specified on upload
Just like when loading a survey template you can now specify the name of the resource when you upload it. Previously the shared resource name was set to the same as the filename.
Shared CSV files are shown separately to other media files
A CSV reference file is quite different to a picture and these are now shown in their own tab on the shared resources page.
XLSX format spreadsheets can be loaded as reference CSV files
The file will be converted on upload into a CSV file that can be loaded into fieldTask and WebForms. No longer do you need to save your spreadsheet data as CSV format while being careful to specify the name that will be used to reference the CSV file from the survey form. You can load your spreadsheet directly and specify the name on upload.
Separation of upload and replace
Now if you try and upload a shared resource with the same name as an existing resource, the upload will be rejected. Instead you have to select the replace button next to the name of the resource in a similar manner to replacing a survey form. This will reduce the chance of accidentally changing an existing resource.
Note the above picture also shows the new download and history buttons.
Shared Resource History
A history is kept of all changes to shared CSV and media files. You can look at this to see who made a change and when. You can also download the original file that was uploaded. So if an XLSX spreadsheet was uploaded you can download that spreadsheet from the history view whereas if you select the download button on the shared resource you will get the CSV version.
In a related change the uploading of a shared resource file and its deletion are both logged. Amazing to think that they weren’t.
Other Changes
An informative error is now shown when uploading a survey, as an XLSForm, that has an invalid choice filter name in the choices list. These names are restricted and cannot, for example, include spaces.
Allow filtering on meta data in a report even if the meta data is not included in the report. For example you may only want to report on records uploaded within the last two days but don’t want to include meta data such as _upload_time in the output.
It has been a busy few months of training which has contributed to a delay of 3 months since the last monthly update. However here at last is a new release for May.
New Features
A new Change password page
Previously a user clicked on the user profile menu item and then, in the dialog that popped up, they would select “Reset Password”. Now when you click on the user profile menu item you will see three sub menus.
“User Profile” takes you to the user profile dialog where you can change your current organisation, timezone, name etc.
“Change Password” takes you to the new Change Password page
Logout, logs you out of the application. This was previously also in the user profile dialog.
The change password page includes a button that will generate a random password for you. After you change your password and move to another page you will be asked to logon again. After you have done that your browser can remember, if you agree, the new password that you have used.
Improved role security
Previously if a survey had a role then an administrator, who also had that role, could add a new survey to the same bundle. This could be a problem if the role on the survey had column or row restrictions as the administrator could then by pass these restrictions. Now only an administrator who also has security manager privilege, can bundle new surveys to a survey that has roles. The security manager can then set any required row or column filtering on the new bundled survey.
Add the ability to force password expiry
The date a password is set is now recorded and the server owner can specify that all passwords older than that must be updated.
Console escalations
When automatically escalating a case to a new user after a console alert or record update you can now also send an email to someone notifying them of the escalation.
Another new feature is that a checkbox can be selected to send an email to the person who has been assigned, notifying them of their new case. This only works if the assigned user has an email specified in their profile.
Allow a form to explicitly set the key value
A user can specify that a survey form has a unique key and a key policy. Then records submitted with that key will be treated according to the key policy, merge, replace, discard or none (append).
However some times it is not possible to identify the components of the key when completing a survey. For example the key could be defined as:
${surname}-seq(surname)
So in the above case submissions with the same surname will not be considered as duplicates instead a unique number will be append. For example:
Smith-1
Jones-1
Smith-2
So to update these records you can use tasks and case management. But what if you wanted to do an ad-hoc update. This might occur if you go to a location and realise that there is new information to add to the record.
You can use the search() function in your survey form to download the key, such as “Jones-2”. This search function can use multiple questions such as name, age, address, gender to uniquely identify the record to be updated. If you now store the results of the search function in a question with name “_hrk” then that value will be used as the unique key on submission.
Other changes and bug fixes
Remove the warning that used to be shown when a survey form was created that had a group filled only with calculations.
In the console you can filter directly on the user name who submitted a record and the name of the user that the record is assigned to.
Clear the saved advanced query in the console if it causes an error.
Improve the efficiency of the uploading of submissions so that is uses less CPU and is faster.
Fix an issue with the API call to get a submissions list which would fail if GPS coordinates were malformed
Fix an issue with the preservation of a record’s unique key between record updates if that key inlcuded a seq() or serial() function.
Added additional event logging
Prevent a new organisation name from being specified that differs only in case. So we won’t now have organisations like Acme and acme and aCme registered on the SG server.
Fixed an issue that prevented initiating tasks from the console.
Allow administrators to move projects to one of their private organisations.
Remove the ability to move a user to new organisation Users should instead be granted access to organisations in their user settings by an administrator. They can then move themselves using the user profile dialog.
Fix issues when uploading empty data into a survey form from a file. This empty data was being set to text without characters, or in the case of a geopoint question, to a location of 0.0 0.0. The values will now be set to undefined as they would be if submitted from fieldTask.
Fix an issue where an non valid period to wait for a console alert could be set. This non valid period would stop processing of console alerts.
Fixed an error that prevented polygons from being used as default areas when accessed by the pulldata() function from a WebForm.
Fixed an issue with generating the default link to a survey form in a campaign email when the location of the link was not specified in the email content.
On the analysis page allow charts to group data by “note” type questions. This change recognizes that people are commonly setting values to note questions using dynamic defaults.
Add improved validation of XLSForms that have non valid headings on the choices worksheet.
Group outputs in the administration usage report by the survey identifier rather than the survey id. This means that replaced surveys will be considered the same survey in the report.
Add an option to the administration usage report to not include “All time” usage.
Upgraded multiple software libraries that had become out of date and had security issues flagged against them.
Fix an issue where the cache of a WebForm was not being updated when the survey definition had changed. This was occurring if the WebForm opened an existing record.
Increase the maximum number of records shown in a map, on the analysis page, to 10,000 from 1,000.
The main change in this release is the upgrade of all pages to JQuery 3.5.1 and Bootstrap 4.5. Most pages were updated some time ago but some of the older, more complicated ones, had remained with the old version of these libraries.
The change you will notice is that the appearance of pages is more consistent. Those pages that used the older libraries such as the online editor should now have the same theme as Form Management.
The one exception to this improved consistency is the analysis page. JQuery has been updated, but it still uses jQuery-UI and not Bootstrap to set its appearance. Probably this page will never be converted to Bootstrap, but one day we will write a new Analysis page starting from scratch to replace it.
Other Changes
Added the “today” meta item to the list of meta items supported in the online editor.
Support added for the “user” meta item in WebForms.
Choice names can now have spaces. This only works with select_one questions which is the reason it was previously not allowed. Be carefully using this if you are going to change the question type to a select multiple.
Allow the user currently assigned to a case to be used as a filter in a search() function
Allow read only questions to be added to exports in predefined reports
Sanitise the HTML used in WebForms to restrict it to a limited set of permitted HTML elements
Removed automatic conversion of text to uppercase when using the grid format in WebForms