MORE-Specific Repackaging of Limesurvey
This repository contains a docker-compose.yaml to launch Limesurvey locally for development and testing.
Before starting the services, copy the example environment file and adjust the values if needed:
cp .env.example .envAfter starting the Compose using docker compose up -d, Limesurvey is available at http://localhost:8080.
To access the configuration backend, login via http://localhost:8080/index.php/admin/authentication/sa/login.
For authentication in MORE we use SSO based on OAuth with Keycloak. With the plugin https://github.com/SondagesPro/limesurvey-oauth2, we can use our account we use for the MORE Study-Manager to sign in to Limesurvey.
The OAuth-plugin is shipped within this docker-image, but needs to be "loaded" before it can be
enabled and configured.
Go to Configuration > Settings > Plugins, press the Scan files-Button, and select the
AuthOAuth2-Plugin.
Then continue with the configuration of the plugin:
- Client ID:
limesurvey - Client Secret can be found in the limesurvey client on Keycloak
- Authorize URL: https://auth.more.redlink.io/realms/Auth-Client-Test/protocol/openid-connect/auth
- Scopes:
openid - Access Token URL: https://auth.more.redlink.io/realms/Auth-Client-Test/protocol/openid-connect/token
- User Details URL: https://auth.more.redlink.io/realms/Auth-Client-Test/protocol/openid-connect/userinfo
- Key for username in user details:
preferred_username - Key for e-mail in user details:
email - Key for display name in user details:
name - Check "Create new users", which creates a new user after successfull login
You can set global roles for new users. Roles can be created as administrator under
Configuration > Users > User roles > Add user role. Once a new role is created,
it can be added as a global role for new users.
Finally, enable the plugin in the Overview.
NOTE: Even if you enable OAuth2 as the default login mechanism, you can always switch to the default
(local database) login by directly going to ${BASE_URL}/index.php/admin/authentication/sa/login/authMethod/Authdb.
Permissions for roles and users can only be managed by the admin account or by a superadministrator.
If a user needs additional permissions beyond their assigned role, grant those permissions directly to that individual user. Do not add extra permissions to a shared role unless every user with that role should receive the same access.
To edit permissions, go to:
Configuration > Users > User roles > Select a user or role > Edit permissions
This is the default role for newly created users. It grants users the permissions they need to create and manage their own surveys and user groups.
Required permissions:
- Survey groups:
Create - Surveys:
Create - User groups:
Create
This role is intended for users who manage LimeSurvey at application level, but who should not have unrestricted access to server configuration, permissions, all survey data, or every user's surveys.
It is important to keep this role restricted. Do not grant broad survey or survey group permissions unless the user should be able to access all surveys or all survey groups.
Required permissions:
- Central participant database:
All - Label sets:
All - Settings & Plugins:
All - Survey groups:
Createonly, or leave blank. Do not grant broader permissions unless this user should access all survey groups. - Surveys:
Createonly, or leave blank. Do not grant broader permissions unless this user should access all surveys. - Themes:
All - User groups:
All - Users:
All - Superadministrator:
Createto manage user roles only. - Use internal database authentication:
All
Depending on which plugins are enabled, assign the following additional permissions to the relevant roles or users.
If the OAuth2 plugin is enabled:
- Use OAuth authentication:
All
If the AuthSurvey plugin is enabled:
- Save plugin settings:
AllorUpdate
Limesurvey uses JSON-RPC. This has to be enabled first before it can be used in
Configuration > Settings > Global > Interfaces as such:
To use the API, you first need to get a session key. Only then you can use it. The most important requests for us are:
- get_session_key
- add_survey (creates a new survey)
- activate_tokens (creates a participant table, which is needed to import participants)
- add_participants (creates participants with defined parameters, such as token or uses left)
- activate_survey
- copy_survey
- list_surveys (lists all surveys belonging to a user)
- delete_survey
We must modify the default settings in Limesurvey and ensure that these feature are activated within the Global Survey Settings:
under the Presentation section turn on Automatically load end URL when survey complete:
Configuration > Settings > Global survey > Presentation
under the Participant settings trun on Allow multiple responses or update responses with one access code:
Configuration > Settings > Global survey > Participant settings
under the "Notifications & Data" section you must enable "Date stamp" to store the date-timestamp
Configuration > Settings > Global survey > Notifications & Data
The built-in Audit Log plugin provided by Limesurvey logs actions performed within the admin interface. This makes it a solid foundation for tracking and analyzing activities on the admin panel side. The recorded data can be accessed via the terminal for further inspection and analysis.
Configuration > Plugins > Auditlog (activate via button)
Once activated, the buildin AuditLog will track any action on the admin interface. You can access the data via the terminal as follows:
docker exec -it [Lime DB Docker Container] psql -U limesurvey -d limesurvey -c "\dt lime_audit*"Example Output:
| Schema | Name | Type | Owner |
|---|---|---|---|
| public | lime_auditlog_log | table | limesurvey |
docker exec -it [Lime DB Docker Container] psql -U limesurvey -d limesurvey -c "\d lime_auditlog_log"Example:
| Column | Type | Nullable | Description |
|---|---|---|---|
| id | integer | NOT NULL | Primary key, auto-increment |
| created | timestamp | - | When the action occurred |
| uid | varchar(255) | - | Limesurvey user ID who performed the action |
| entity | varchar(255) | - | What was affected (e.g. token, survey) |
| entityid | varchar(255) | - | ID of the affected entity |
| action | varchar(255) | - | What happened (e.g. create, update, delete) |
| fields | text | - | Which fields were affected |
| oldvalues | text | - | Values before the action |
| newvalues | text | - | Values after the action |
# Get the last 20 entries
docker exec -it [Lime DB Docker Container] psql -U limesurvey -d limesurvey -c "SELECT * FROM lime_auditlog_log ORDER BY created DESC LIMIT 20;"Example: Creating a participant in the participant table:
| Field | Value |
|---|---|
| ID | 1 |
| Created | 2026-04-07 13:21:08 |
| User ID (uid) | 1 (admin) |
| Entity | token_376198 |
| Action | create |
| Fields | sent, remindersent, remindercount, completed, usesleft, emailstatus, firstname, lastname, email, token, language, validfrom, validuntil, tid, participant_id, blacklisted, mpid |
| Old Values | (empty) |
| New Values | firstname: Test, lastname: Patient, email: test@test.at, token: (empty), completed: N, usesleft: 1, sent: N, emailstatus: OK, language: en |
The UserAuditLogPlugin records a complete audit trail of participant interactions with LimeSurvey surveys. It logs page loads, answer changes, and survey submissions to the flat lime_user_audit_log table. This is intended for eCRF and GDPR compliance use cases and is compatible with LimeSurvey 6.x.
The plugin is separate from LimeSurvey's built-in Auditlog plugin. For complete eCRF/GDPR traceability, use all three sources together:
- the
.lsssurvey structure export, - the built-in
lime_auditlog_logtable, - the
lime_user_audit_logtable created by this plugin.
The plugin should be installed in this docker image by default. It still needs to be added to LimeSurvey via the plugin manager scan and then activated globally before it can be enabled for individual surveys.
-
The
UserAuditLogPluginfolder should be already included in the docker image at:limesurvey/plugins/UserAuditLogPlugin -
Add the plugin to LimeSurvey by scanning the installed plugin files:
Configuration > Settings > Plugins > Scan files -
Select the UserAuditLogPlugin from the scan results and add it.
-
Activate the plugin from the LimeSurvey admin interface:
Configuration > Plugins > UserAuditLogPlugin > ActivateAlternatively, activate it from the terminal:
php application/commands/console.php plugin activate UserAuditLogPlugin
-
On first activation, the plugin automatically creates and migrates the
lime_user_audit_logdatabase table.
To build a ZIP file that can be uploaded through the LimeSurvey plugin manager, run:
bash scripts/build.shThe resulting file is created at:
dist/UserAuditLogPlugin.zip
The plugin is opt-in per survey. Activating it globally does not start logging automatically.
For each survey that should be tracked:
-
Open the survey in the LimeSurvey admin interface.
-
Go to:
Survey settings > Plugins > UserAuditLogPlugin -
Set Audit log for this survey to Activated.
-
Save the plugin settings.
After this is enabled, the plugin writes participant interactions for that survey to lime_user_audit_log.
The plugin provides a survey-specific datatable view. To browse and filter audit entries without leaving LimeSurvey, go to:
Survey > Plugin actions > UserAuditLogPlugin
Read audit events from the lime_user_audit_log table. For example, to fetch all events for one survey:
SELECT * FROM lime_user_audit_log
WHERE survey_id = 123456
ORDER BY created_at ASC;To fetch all events for one participant in one survey:
SELECT * FROM lime_user_audit_log
WHERE survey_id = 123456
AND participant_token = 'abc123'
ORDER BY created_at ASC;To fetch only answer changes:
SELECT * FROM lime_user_audit_log
WHERE survey_id = 123456
AND event_type = 'answer_change'
ORDER BY created_at ASC;To export a survey's audit log to CSV from the PostgreSQL CLI:
docker exec -it [Lime DB Docker Container] psql -U limesurvey -d limesurvey -c "COPY (SELECT * FROM lime_user_audit_log WHERE survey_id = 123456 ORDER BY created_at ASC) TO STDOUT WITH CSV HEADER" > audit_123456.csvThe plugin records the following event types:
survey_openpage_loadanswer_changesurvey_submit
For answer_change events, the table stores field-level old and new values together with survey, participant, session, page, group, question, sub-question, column, ranking, and input type metadata.
Text fields are logged when the user leaves the field, not for every keystroke.
The main table created by the plugin is lime_user_audit_log.
| Column | Description |
|---|---|
id |
Row identity |
created_at |
Timestamp of the event |
survey_id |
LimeSurvey survey ID |
participant_token |
Survey access token; resolves to the participant via lime_tokens_{surveyId} |
oauth_user_id |
Authenticated user ID, or NULL for guests |
oauth_username |
Authenticated username, or NULL for guests |
event_type |
survey_open, page_load, answer_change, or survey_submit |
page_number |
Current page or step index |
group_id |
LimeSurvey question group ID |
question_id |
Numeric LimeSurvey question ID |
sub_question_id |
Numeric sub-question ID for matrix, array, or multi-field questions |
column_id |
Numeric column question ID for supported array question types |
rank_position |
Ranking position for ranking questions |
input_type |
Readable input category, such as text-question/short-text or array/array |
old_value |
Value before the change |
new_value |
Value after the change |
session_id |
PHP session ID |
ip_address |
IP address, including IPv6 support |
For answer_change events, LimeSurvey question types are normalized into readable input_type values. Examples include:
| LS Code | Description | input_type |
|---|---|---|
L |
List radio | single-choice/list-radio |
! |
List dropdown | single-choice/list-dropdown |
Y |
Yes / No | mask-question/yes-no |
M |
Multiple choice | multiple-choice/multiple-choice |
S |
Short text | text-question/short-text |
T |
Long text | text-question/long-text |
D |
Date / Time | mask-question/date-time |
N |
Numerical | mask-question/numerical |
R |
Ranking | mask-question/ranking |
A |
Array five-point | array/five-point-choice |
F |
Generic array | array/array |
: |
Array numbers | array/numbers |
; |
Array text | array/text |
Display-only question types such as boilerplate and computed equation questions are not logged as answer changes.
UserAuditLogPlugin does not enforce authentication by itself. It logs the authenticated user if one is present and stores NULL identity values for guest access.
For surveys that must only be completed by authenticated users, enable the AuthSurvey plugin for the same survey. When both plugins are active, audit log rows can include the authenticated user's oauth_user_id and oauth_username.
Additional plugin documentation is available in the plugin repository:
docs/AuditLogSpecification.md— schema design decisions, storage approach, and event typesdocs/AuditlogQuestionTypes.md— how each LimeSurvey question type is represented in the audit log tabledocs/UserGuide.md— how to activate the plugin, enable logging per survey, and access the audit log
The AuthSurvey plugin allows selected surveys to be displayed and submitted only by authenticated users. Each survey can have its own authentication policy, so the plugin can be enabled only for surveys that require access protection.
-
The
AuthSurveyfolder should be already included in the docker image at:limesurvey/plugins/AuthSurvey -
Add the plugin to LimeSurvey by scanning the installed plugin files:
Configuration > Settings > Plugins > Scan files -
Select the AuthSurvey plugin from the scan results and add it.
-
Activate the AuthSurvey plugin from the plugin overview.
-
Update the required user permissions. The plugin needs permission to save plugin settings. Go to:
Configuration > Users > User roles > Select a user or role > Edit permissionsThen enable:
Allow user to save plugin settings
AuthSurvey is configured per survey. To enable it for one survey:
-
Go to:
Surveys > Select desired survey > Simple pluginsAlternatively, open the survey plugin settings directly:
${BASE_URL}/index.php/admin/survey/sa/rendersidemenulink/surveyid/{survey_id}/subaction/plugins -
Open the Settings for plugin AuthSurvey accordion.
-
Enable the plugin by checking the Enabled checkbox.
After AuthSurvey is enabled for a survey, the survey can only be viewed and submitted by authenticated users according to that survey's plugin configuration.
The survey-specific settings are managed from the survey plugin settings page:
When an unauthenticated or unauthorized user tries to open or submit a protected survey, LimeSurvey displays an unauthorized access error instead of the survey:
These permissions only apply for a single survey. If you want to set permissions for the whole system, you can use global permissions. These permissions can be offered either to a single user or to a user group.
To change the survey permissions, click the Settings tab. Then, click Survey permissions and choose to whom would you like to offer permissions. The permissions can be offered either separately to specific users or to a user group.
By default, an user (non-admin) cannot grant survey permissions to users that are not part of the same group as the survey administrator. This is a security option enabled by default in Limesurvey. To change this, you need to deactivate option Group member can only see own group, located in the Global settings, under the Security tab. However, if you feel unsure about disabling this option, you can create groups containing those users that can be seen and be granted survey permissions by a survey creator.
Check the following link for further information: https://manual.limesurvey.org/Manage_users#Set_permissions_for_a_single_survey
To answer a questionnaire, a user needs an access token and the url of the survey. They can then answer the survey and the answers are stored in the limesurvey database.
Limesurvey allows custom scripts for a theme. With this feature, custom functionality can be added, when a user submits an answer, for example. This could be useful in the future.
To ensure safe and predictable deployments, this repository uses a semantic versioning tagging strategy.
Tags must follow the format: v<Major>.<Minor>.<Patch> (e.g., v1.0.1).
The Docker build and publish workflow is triggered on:
- Push to branches:
main,develop - Push of tags:
v*.*.* - Pull requests
When a Git tag is pushed, the following Docker tags are automatically generated:
v<Major>.<Minor>.<Patch>v<Major>.<Minor>v<Major>latest(only on default branch)
After updating to Limesurvey 6, surveys originally created in Limesurvey 5 may not be fully compatible with the new version. In such cases, errors can occur when accessing or completing these surveys.
The following errors in the user interface, when answering a survey, are related to this issue:
To resolve this issue, the following approach can be used:
- The MORE Studymanager Limesurvey Observation was extended to allow linking a new Limesurvey ID even if the survey already started..
- Existing surveys that were created in Limesurvey 5 and have those issues can be easily exported (.lss or .lsa) and reimported inside the MORE Limesurvey Server. During the import process, Limesurvey 6 automatically adjusts and cleans the survey schema to ensure compatibility.
- After linking the newly imported survey to the corresponding Limesurvey observation, functionality is restored and the survey behaves as expected.
-
Go to the MORE Limesurvey server and locate your survey using the linked ID. Open the survey you want to fix and click on the Export button.
-
Choose either the .lss or .lsa format for export.
-
Import the survey again into Limesurvey 6. During this process, potential incompatibilities are automatically resolved..
-
Copy the new survey ID and navigate to the MORE StudyManager to relink the new survey within the existing Limesurvey observation.
