Limesurvey Openclaw Skill

Automate LimeSurvey operations via RemoteControl 2 API. Use when: (1) managing surveys, questions, groups, or participants, (2) exporting responses or statis...

Security Scan

The skill's code, instructions, and required environment variables are coherent with its stated purpose (automating LimeSurvey via RemoteControl 2); there are no unexplained credential requests, hidden endpoints, or risky install steps.

Purpose & Capability

Name/description (LimeSurvey RemoteControl automation) matches what the package requests and implements: a RemoteControl URL and LimeSurvey username/password. The required env vars (LIMESURVEY_URL, LIMESURVEY_USER, LIMESURVEY_PASSWORD) are exactly what you'd expect for this integration.

Instruction Scope

SKILL.md instructs the agent to use the RemoteControl endpoint and the declared env vars. Runtime instructions and the included CLI/client code only call the provided URL, read user-provided files (e.g., participant JSON, survey .lss files) and write exports — they do not reference unrelated system files, other credentials, or external endpoints beyond the user-supplied LIMESURVEY_URL.

Install Mechanism

No install spec (instruction-only + included Python scripts). Nothing is downloaded from arbitrary URLs or written to non-standard system locations. The package uses only standard-library Python code included in the repo.

Credentials

Only three env vars are required (URL, username, password), which are proportionate and expected for a RemoteControl client. The skill explicitly recommends using a least-privilege service account and not committing credentials to source control.

Persistence & Privilege

always is false, no special persistent privileges requested, and the skill does not modify other skills or system-wide agent settings. Session handling is limited to creating and releasing LimeSurvey session keys as expected.

Assessment

This skill appears to do exactly what it says: it connects to your LimeSurvey RemoteControl endpoint using the credentials you supply. Before installing, do the following: (1) create and use a least-privilege LimeSurvey service account (avoid full admin credentials); (2) restrict the RemoteControl endpoint to trusted networks; (3) store credentials in a secure vault or environment variables (don't commit them); (4) review the included Python files if you need to be extra cautious — they perform JSON-RPC calls to the URL you provide and decode exports locally; (5) note a functional caveat: some export paths decode Base64 to UTF-8 text (which is fine for CSV/JSON) but may mishandle binary exports like PDF/XLS if written as text — treat binary exports accordingly. If you need stronger assurance, run the skill in a staging environment with a dedicated service account first.

LimeSurvey RemoteControl 2 API

Automate LimeSurvey survey management via the RemoteControl 2 JSON-RPC API.

Prerequisites

Required Environment Variables:

• LIMESURVEY_URL — Full URL to RemoteControl endpoint (e.g., https://survey.example.com/index.php/admin/remotecontrol)
• LIMESURVEY_USER — Service account username
• LIMESURVEY_PASSWORD — Service account password

Security Recommendations:

1. Use a least-privilege service account, not your full admin credentials
2. Create a dedicated LimeSurvey user with minimal required permissions (survey management only, no system administration)
3. Use a strong, unique password; rotate periodically after initial use
4. Never commit credentials to version control — use environment variables or secure vaults only
5. Verify the RemoteControl API is accessible only from trusted networks

Setup:

export LIMESURVEY_URL='https://survey.example.com/index.php/admin/remotecontrol'
export LIMESURVEY_USER='service_account_username'
export LIMESURVEY_PASSWORD='secure_service_password'

Quick Start

Setup

Set environment variables:

export LIMESURVEY_URL='https://survey.example.com/index.php/admin/remotecontrol'
export LIMESURVEY_USER='admin'
export LIMESURVEY_PASSWORD='your_password'

CLI Usage

# List all surveys
python3 scripts/limesurvey.py list-surveys

# Export responses
python3 scripts/limesurvey.py export-responses 123456 --format csv -o responses.csv

# List participants
python3 scripts/limesurvey.py list-participants 123456 --limit 100

# Add participants from JSON
python3 scripts/limesurvey.py add-participants 123456 --file participants.json

# Send invitations
python3 scripts/limesurvey.py invite-participants 123456

# Activate survey
python3 scripts/limesurvey.py activate-survey 123456

# Get survey statistics
python3 scripts/limesurvey.py get-summary 123456

Python API Usage

from scripts.limesurvey_client import LimeSurveySession

url = 'https://survey.example.com/index.php/admin/remotecontrol'

with LimeSurveySession(url, 'admin', 'password') as client:
    # List surveys
    surveys = client.call('list_surveys', client.session_key)
    
    # Export responses
    encoded = client.call('export_responses', client.session_key, 
                         survey_id, 'csv')
    csv_data = client.decode_base64(encoded)

Common Workflows

Survey Management

List all surveys:

surveys = client.call('list_surveys', client.session_key)

Activate a survey:

result = client.call('activate_survey', client.session_key, survey_id)

Get survey statistics:

stats = client.call('get_summary', client.session_key, survey_id, 'all')
# Returns: completed_responses, incomplete_responses, token_count, etc.

Copy a survey:

result = client.call('copy_survey', client.session_key, 
                    source_id, "New Survey Name")
new_id = result['newsid']

Participant Management

Initialize participant table:

# Create table with custom attributes
client.call('activate_tokens', client.session_key, survey_id, [1, 2, 3])

Add participants:

participants = [
    {"email": "[e-mail]", "firstname": "John", "lastname": "Doe"},
    {"email": "[e-mail]", "firstname": "Jane", "lastname": "Smith"}
]
result = client.call('add_participants', client.session_key, 
                    survey_id, participants, True)

Send invitations:

# Send to specific tokens
token_ids = [1, 2, 3]
result = client.call('invite_participants', client.session_key, 
                    survey_id, token_ids)

# Or send to all pending
result = client.call('invite_participants', client.session_key, 
                    survey_id, None)

List participants with filters:

# Find unused tokens
participants = client.call('list_participants', client.session_key,
                          survey_id, 0, 100, True)

# Find by custom attribute
participants = client.call('list_participants', client.session_key,
                          survey_id, 0, 1000, False, False,
                          {'attribute_1': 'ACME Corp'})

Response Operations

Export all responses:

encoded = client.call('export_responses', client.session_key,
                     survey_id, 'csv')
csv_data = client.decode_base64(encoded)

with open('responses.csv', 'w') as f:
    f.write(csv_data)

Export only completed responses:

encoded = client.call('export_responses', client.session_key,
                     survey_id, 'csv', None, 'complete')

Export by token:

encoded = client.call('export_responses_by_token', client.session_key,
                     survey_id, 'json', ['token1', 'token2'])

Add a response programmatically:

response_data = {
    'G1Q1': 'Answer text',
    'G1Q2': '3',  # Multiple choice value
    'token': 'xyz123'
}
response_id = client.call('add_response', client.session_key, 
                         survey_id, response_data)

Question & Group Operations

List groups:

groups = client.call('list_groups', client.session_key, survey_id)

Add a question group:

group_id = client.call('add_group', client.session_key, survey_id,
                      'Demographics', 'Basic information')

List questions:

# All questions in survey
questions = client.call('list_questions', client.session_key, survey_id)

# Questions in specific group
questions = client.call('list_questions', client.session_key, 
                       survey_id, group_id)

Get question details:

props = client.call('get_question_properties', client.session_key,
                   question_id, ['question', 'type', 'mandatory'])

Export & Reporting

Generate statistics PDF:

encoded = client.call('export_statistics', client.session_key,
                     survey_id, 'pdf', None, '1')  # With graphs

import base64
pdf_data = base64.b64decode(encoded)

with open('stats.pdf', 'wb') as f:
    f.write(pdf_data)

Get submission timeline:

timeline = client.call('export_timeline', client.session_key,
                      survey_id, 'day', '2024-01-01', '2024-12-31')

for entry in timeline:
    print(f"{entry['period']}: {entry['count']} submissions")

Get survey fieldmap:

fieldmap = client.call('get_fieldmap', client.session_key, survey_id)
# Maps question codes to metadata

Error Handling

All API functions return status objects on error:

result = client.call('activate_survey', client.session_key, survey_id)

if isinstance(result, dict) and 'status' in result:
    print(f"Error: {result['status']}")
    # Common errors:
    # - Invalid session key
    # - No permission
    # - Invalid survey ID
    # - Survey already active
else:
    print("Success!")

Use try/except for connection errors:

from scripts.limesurvey_client import LimeSurveyError

try:
    with LimeSurveySession(url, username, password) as client:
        result = client.call('list_surveys', client.session_key)
except LimeSurveyError as e:
    print(f"API error: {e}")

Reference Documentation

• API Reference - Complete function reference with parameters and return values
• Examples - Practical code examples for common tasks

Available Functions

Session

• get_session_key(username, password) - Create session
• release_session_key(session_key) - Close session

Surveys

• list_surveys(session_key) - List all surveys
• get_survey_properties(session_key, survey_id, properties) - Get properties
• set_survey_properties(session_key, survey_id, properties) - Update properties
• activate_survey(session_key, survey_id) - Activate survey
• delete_survey(session_key, survey_id) - Delete survey
• copy_survey(session_key, source_id, new_name) - Duplicate survey
• import_survey(session_key, data, type) - Import from file
• get_summary(session_key, survey_id, stat) - Get statistics

Participants

• activate_tokens(session_key, survey_id, attributes) - Initialize table
• list_participants(session_key, survey_id, start, limit, unused, attributes, conditions) - List participants
• add_participants(session_key, survey_id, data, create_token) - Add participants
• delete_participants(session_key, survey_id, token_ids) - Delete participants
• get_participant_properties(session_key, survey_id, query, properties) - Get properties
• set_participant_properties(session_key, survey_id, query, properties) - Update properties
• invite_participants(session_key, survey_id, token_ids) - Send invitations
• remind_participants(session_key, survey_id, token_ids) - Send reminders

Responses

• export_responses(session_key, survey_id, format, ...) - Export responses
• export_responses_by_token(session_key, survey_id, format, tokens) - Export by token
• add_response(session_key, survey_id, data) - Add response
• update_response(session_key, survey_id, data) - Update response
• delete_response(session_key, survey_id, response_id) - Delete response
• get_response_ids(session_key, survey_id, token) - Find response IDs

Questions & Groups

• list_groups(session_key, survey_id) - List groups
• add_group(session_key, survey_id, title, description) - Create group
• delete_group(session_key, survey_id, group_id) - Delete group
• get_group_properties(session_key, group_id, properties) - Get properties
• set_group_properties(session_key, group_id, properties) - Update properties
• list_questions(session_key, survey_id, group_id) - List questions
• get_question_properties(session_key, question_id, properties) - Get properties
• set_question_properties(session_key, question_id, properties) - Update properties
• import_question(session_key, survey_id, group_id, data, type) - Import question
• delete_question(session_key, question_id) - Delete question

Export & Reporting

• export_statistics(session_key, survey_id, doc_type, language, graph) - Export statistics
• export_timeline(session_key, survey_id, type, start, end) - Submission timeline
• get_fieldmap(session_key, survey_id) - Get question codes

Notes

• Session management: Always close sessions with release_session_key or use LimeSurveySession context manager
• Base64 encoding: Export functions return base64-encoded data — use client.decode_base64() or base64.b64decode()
• Permissions: API calls respect user permissions — same as logging into admin interface
• Rate limiting: LimeSurvey has brute-force protection on authentication
• JSON-RPC: Content-Type must be application/json (handled automatically by client)

Full API Documentation

Official LimeSurvey API: https://api.limesurvey.org/classes/remotecontrol-handle.html

Manual: https://www.limesurvey.org/manual/RemoteControl_2_API