Survey Management Tool

This directory contains survey configurations that are published to user-feedback.xml for consumption by Devolutions products (RDM, DVLS, Hub).

Overview

Surveys are Markdown files in this directory. Product Marketing (or a developer) edits them in git; the Astro build publishes /api/user-feedback.xml.

How It Works

1. Survey Files: Each survey is a Markdown file in this directory
2. Build Process: Astro publishes /api/user-feedback.xml from enabled surveys (astro:build:done, and the same generator in astro:dev)
3. Applications: RDM, DVLS, and Hub fetch and display surveys based on criteria

File Naming Convention

Files should be named descriptively to indicate their purpose:

• Format: {product}-{platform}-{language}.md
• Examples:
  • rdm-windows-feedback-english.md
  • rdm-linux-feedback.md
  • dvls-windows-admin-survey-french.md

Survey Fields

Required Fields

Optional Fields (Supported since 2025.3)

Metadata Fields

Important Notes

Survey ID Management

⚠️ CRITICAL: The surveyId must be identical for all language variants of the same survey.

For example, if you have a survey in English, French, and German targeting the same audience:

• rdm-windows-feedback-english.md → surveyId: 781bce4c-c31e-4514-b08a-ab70638136d4
• rdm-windows-feedback-french.md → surveyId: 781bce4c-c31e-4514-b08a-ab70638136d4 (same!)
• rdm-windows-feedback-german.md → surveyId: 781bce4c-c31e-4514-b08a-ab70638136d4 (same!)

This allows the application to track that a user has already seen the survey, regardless of which language version they saw.

Version Support

Not all product versions support all fields:

• Legacy versions (< 2025.3): Only support basic fields (Data, ID, Message, Platform, MinVersion, EndDate, Type)
• 2025.3+: Support additional filtering fields (Datasource, Language, License, Product, UserType)

The build system will include all fields in the XML, but older application versions will simply ignore fields they don't understand.

Empty Fields Warning

Optional fields may be left empty if you want to target:

• Older product versions that don't support those fields
• All users regardless of datasource, language, etc.

Creating a New Survey

1. Create a new .md file in apps/website-devolutions/content/surveys/
2. Copy the structure from an existing survey in this folder
3. Fill in all required fields
4. Commit and push to trigger the site build

Editing Existing Surveys

1. Open the survey .md file in this directory
2. Make your changes
3. Commit and push — the next site build republishes /api/user-feedback.xml

Disabling a Survey

To stop showing a survey without deleting it:

1. Open the survey .md file
2. Set _enabled to false
3. Commit and push

The survey will be excluded from the next XML generation.

Deleting a Survey

1. Delete the survey .md file
2. Commit and push

Note: Deleted surveys are permanently removed. Consider disabling instead if you might want to reuse it later.

Multi-Language Surveys

When creating surveys in multiple languages:

1. Create one survey per language
   • Example: Create 3 files for EN, FR, DE
2. Use the SAME surveyId for all language variants
   • This prevents users from seeing the same survey multiple times
3. Set the language field appropriately
   • English, French, German, or Other
4. Translate the message field
   • This is what users see in their application
5. Keep the surveyUrl the same OR use language-specific survey links
   • Depends on your survey platform setup

Example: Multi-Language Survey

English version (rdm-windows-feedback-english.md):

surveyId: '781bce4c-c31e-4514-b08a-ab70638136d4'
surveyUrl: 'https://example.com/survey?lang=en'
message: 'Share your RDM experience'
language: 'English'
platform: 'Windows'
minVersion: '2025.3.14.0'
endDate: '2026-09-30'
# ... other fields

French version (rdm-windows-feedback-french.md):

surveyId: '781bce4c-c31e-4514-b08a-ab70638136d4'  # SAME ID!
surveyUrl: 'https://example.com/survey?lang=fr'
message: 'Partagez votre expérience RDM'
language: 'French'
platform: 'Windows'
minVersion: '2025.3.14.0'
endDate: '2026-09-30'
# ... other fields

Testing

Viewing Generated XML

1. Build the site locally: pnpm run build:website-astro
2. Open dist/api/user-feedback.xml in a text editor
3. Verify your survey appears with correct data

Testing in Development

1. Start the Astro preview: dashboard or pnpm --filter @devolutions/website run dev
2. Navigate to http://localhost:8080/api/user-feedback.xml
3. Check that only enabled, non-draft surveys appear

Testing in Applications

Product teams can test surveys by:

1. Pointing their app to the staging/production XML URL
2. Ensuring their version meets minVersion requirement
3. Verifying survey appears based on filters (platform, language, etc.)

XML Output Format

The generated XML follows this structure:

<?xml version="1.0" encoding="UTF-8"?>
<UserFeedback>
  <FeedbackEntities>
    <FeedbackEntity>
      <Data><![CDATA[survey URL here]]></Data>
      <Datasource>All</Datasource>
      <EndDate>2026-09-30</EndDate>
      <ID>unique-guid-here</ID>
      <Language>English</Language>
      <License>All</License>
      <Message>Survey message here</Message>
      <MinVersion>2025.3.14.0</MinVersion>
      <Platform>Windows</Platform>
      <Product>RDM</Product>
      <Type>Survey</Type>
      <UserType>All</UserType>
    </FeedbackEntity>
    <!-- More surveys... -->
  </FeedbackEntities>
</UserFeedback>

Troubleshooting

Survey Not Appearing in XML

Check:

• Is _enabled set to true?
• Is _draft set to false?
• Has the site been rebuilt after your changes?
• Are all required fields filled?

Survey Showing in Wrong Language

Check:

• Is the language field set correctly?
• If the user's app language doesn't match, they might see "Other" or "All" language surveys

Survey Not Showing in Application

Check:

• Does the user's version meet minVersion?
• Does the user's platform match the platform field?
• Has the survey endDate passed?
• Do the filtering fields (datasource, license, etc.) match the user's setup?

Duplicate Surveys Appearing

Check:

• Are multiple language variants using different surveyId values?
  • Solution: Use the same ID for all language variants

Migration from Manual PR Process

This tool replaces the previous manual process where surveys were added via Pull Request to user-feedback-dynamic.njk (renamed to user-feedback-dynamic.liquid as part of the Nunjucks → Liquid migration, see WEB-3202).

Old Process:

1. Developer manually edited user-feedback-dynamic.njk
2. Added XML <FeedbackEntity> blocks
3. Created PR, reviewed, merged
4. Deployed

New Process:

1. Product Marketing (or a developer) adds/edits a Markdown file in this directory
2. Commit and push
3. The site build republishes /api/user-feedback.xml

Security & Access

• Git access: Product Marketing edits via PR, or a developer commits on their behalf
• Branch Protection: Master is protected; changes go through a pull request

Support

For questions or issues:

• Technical Issues: Contact Web Development team
• Survey Content: Contact Product Marketing

Related Files

• XML Generator: Astro cutover endpoint user-feedback.xml
• Temp XML: public/api-temp/user-feedback.xml

Last Updated: November 12, 2025
Maintained By: Web Development Team