View source for Modernized Questionnaire Player

{{Gen2 TOC}}{{Inspections TOC}}{{WIP}}
Questionnaire Player is a Resco component that is responsible for displaying questionnaires to users. We are preparing the second generation of the questionnaire player that overcomes some of the shortcomings of the older player and opens new integration opportunities. Gen 2 brings modern user interface with accessibility features baked in.

== Why a new generation? ==

;Woodford dependency
:The gen 1 questionnaire player requires Woodford (or, more precisely, access to a mobile [[app project]] in [[Woodford]]) in order to display. By decoupling the player from Woodford, you can go beyond [[Resco Mobile CRM]] or Power Platform/Dynamics, you can display the player almost anywhere.

;Technology limitation
:The first generation of the player is based on the [[form]]s used in Resco Mobile CRM. Any questionnaire changes require custom development effort for each of the affected platforms (iOS, Android, Windows, web). Gen 2 brings a modern, platform-agnostic, and future-proof technology stack and allows for much faster development cycles.

;Outdated design
:Given the constraints of the gen 1 player, some features were impractical to implement. For example, a frequently desired feature, nested groups, is almost impossible for gen 1.

== Feature highlights ==

Gen 2 questionnaires bring new features. The feature list below is not complete. Also, not all features are available in the first preview.

;Improved navigation
:Thanks to a new, automatically generated '''table of contents''', you can jump straight to the question group that’s relevant for you. There’s also a new '''search function''' that allows you to find the question you need directly.

;Better descriptions 
:You can now use formatted text to provide clear instructions to your inspector. Edit the text in a WYSIWYG editor: add colors, styles, text decoration, images, or links. The content is saved in industry-standard Markdown format.

;Semantic colors and global styles
:Colors and styles are now streamlined and easier to use.

;Form validation
:When a user attempts to save or complete a questionnaire, the Questionnaire Player validates all visible questions. If it finds any responses that fail the validation, the list of validation errors is displayed. The player scrolls to the first invalid response. Users can fix it and proceed to the next invalid response.

;Enhanced image editor
:The image editor is embedded directly in the Questionnaire Player. It allows users to modify the captured or selected image without the need for an external application. The editor lets the users zoom in for precise editing. An intuitive toolbar includes all the standard editing features including cropping, adding text, shapes, freehand drawing, etc. You can select features like text font/size, color, line thickness, and much more.

{{YT|yR7NsvQK37U}}

== Data model, answer storage, template format ==

Gen 2 questionnaires use only three tables:
* Resco_questionnaire for templates
* Resco_questionnaireanswer for answers
* Resco_questionnairefolder to keep templates organized in the Questionnaire Designer

If you are familiar with the generation 1 data model, you may notice that the resco_question and resco_questiongroup tables are not listed. We’re doing away with them, even in templates; all questions are now serialized (in gen 2 templates). Do not remove resco_question and resco_questiongroup tables from your server: they are needed in the Questionnaire Designer to support gen 1 questionnaires. 

If you are already using the latest gen 1 answer storage options, nothing changes. Gen 2 supports only the latest data model:
* latest JSON schema (minimal JSON and flexible JSON)
* Resco_questionnaireanswer as the storage table
* Full template dependency

== Features unavailable for preview ==

In the early preview, some standard features are '''not yet available''':
* [[Data mapping]]
* [[Questionnaire_Designer#Tagged_image|Tagged images]]
* Reports

We will periodically release new previews. For information about new features included in preview releases, check the preview documentation for [[Releases/Winter 2026|release 19.0]].

== Preview availability ==

* A limited preview (closed beta) was available from May to September 2025.
* Public preview is planned to start on October 23, 2025.
* [[Resco Mobile CRM]] 19.0 or later ([[Preview#Apps|download the latest preview app]])

== Get started with gen 2 ==

The preview is available for the following platforms:
* Power Platform (with or without Dynamics features)
* Resco Cloud

The new player is available in several forms:
* Part of Resco Mobile CRM
* A component you can add to Power Apps.
* A component you can add to Power Pages.

{{YT|L2eAx9Co1Ko}}

=== Prepare your test environment on Power Platform ===

# Download the preview version of Resco Suite from [[Preview#Resco_Suite_for_Dataverse/Dynamics/Power_Platform|the Preview page]]. The earliest supported version for the public preview is 19.0.
# Go to make.powerapps.com and switch to a suitable sandbox/developer environment.
# If you participated in the limited preview, delete the standalone solution RescoPcfQuestionnaire.
# Install the preview version of Resco Suite.
# Wait until the installation concludes, then '''Publish all customizations'''.<br>[[File:Publish-all-customizations.png|600px|alt=publish all customizations button]]

=== Use the Resco Inspection model-driven app for testing ===

In the preview release, the Resco Suite solution includes a new model-driven demo app for testing the second generation of questionnaires: Resco Inspections.

[[File:Published-apps-with-resco-inspections.png|600px|alt=new Resco Inspections MDA]]

The app includes a welcome page with basic information and five menu items:
* [[Questionnaire Designer]] - use it to create a new questionnaire
* [[Report Designer]] - use it for creating advanced reports from questionnaires or other data
* Templates - list of questionnaire templates. Select any published template and start filling out the form.
* Answers - list of completed questionnaires.  
* [[Result Viewer]] - use it to search, filter, and export questionnaire answers

[[File:Resco-inspections-welcome-page.png|600px|alt=resco inspections welcome page]]

=== Try Power Pages ===

The new player can be added to Power Pages. We have prepared a sample page that you can add to your organization.
# Start the Resco Inspections app.
# On the Get Started page, scroll down to the section about Power Pages and download the solution file.
# Go to make.powerapps.com and import the solution. Wait for installation, then publish all customizations.
# Go to make.powerpages.microsoft.com and make sure you are in the same environment.
# Go to the '''Inactive sites''' tab and '''Reactivate''' the rescoQuestionnaire site.<br>[[File:Resco-questionnaire-inactive-site.png|600px|alt=Resco-questionnaire-inactive-site]]
# Find the demo among your active sites. It contains the questionnaire player component on the home page, and has the required tables and WebAPI permissions set.

To display an actual questionnaire:
# Open the source code in Visual Studio Code.
# Find <resco-questionnaire> component in the Home page.
# Instead of the placeholder, enter the ID of a questionnaire/answer that exists in your environment.<br>[[File:Power-page-questionnaire-id.png|600px|alt=enter a valid questionnaire id]]
# Save, Sync, and Preview. Sometimes, it might be necessary to fully reload the page to bypass the browser cache.

{{Note|The demo page uses benevolent table permissions and content security policy to simplify testing. For production use, review and adjust the settings.|Warning}}

=== Power Platform: Add questionnaire component to your forms ===

If you want to try out the gen 2 player as a PCF in a model-driven app, add the component to your forms.

# In make.powerapps.com, edit the form for the questionnaire table.<br>[[File:Edit-questionnaire-form.png|600px|alt=edit the form of the questionnaire table]]
# Using the form editor, add a new form tab. Name and order the form tabs as desired.<br>[[File:Form-add-new-tab.png|600px|alt=add a new tab to the form]]
# Select the section included in the new tab and hide its label.<br>[[File:Form-hide-section-label.png|600px|alt=hide section label]]
# In the list of components, scroll down to '''More components''' and add '''Questionnaire'''. (If you don't see the questionnaire, click '''Get more components''' to add it.)
# Select any text field as the component binding placeholder. If you are not familiar with PCF, check out also [[Resco Power Components]] documentation or [https://learn.microsoft.com/en-us/power-apps/developer/component-framework/overview Microsoft documentation about PCF].<br>[[File:Form-add-questionnaire.png|600px|alt=add questionnaire pcf to form]]
# Select the added component and hide its label, then save all changes.<br>[[File:Form-hide-and-publish.png|600px|alt=hide the label and save & publish.]]
# Repeat the same steps for the Questionnaire Answer table.

=== Prepare your test environment on Resco Cloud ===

If you don't want to test on Power Platform, you can use our [[Resco Cloud]]. Create a new preview organization or use your existing organization on https://preview.resco.net.

=== Create an app project (required for Resco Mobile CRM) ===

If you want try Gen 2 questionnaires in Resco Mobile CRM, you need to enable Feature Version fields.

# Start Woodford.
# Create a new app project. Select Inspections as your initial template.
# Go to the Questionnaire entity. Edit its view and add the field Feature Version.<br>[[File:Rc-questionnaire-view-feature-version.png|600px|alt=add field to view]]
# Go to the QuestionnaireAnswer entity. Edit its view and the field: resco_questionnaire.resco_featureversion. Ensure you are adding the correct field: for the answer entity, you must add the parent template's feature version.<br>[[File:Rc-questionnaireanswer-view.png|400px|alt=add field to view]]
# Save all changes and publish the app project.

=== Design a new questionnaire ===

# Start [[Questionnaire Designer]] (18.2 or later).
# Click '''New''' and verify that you are using Gen 2 technology. If not, go to Settings and switch to Gen 2.<br>[[File:New-gen2-questionnaire.png|400px|alt=technology gen 2]]
# Click '''Create''' or use any of the methods for faster questionnaire creation, for example, '''Generate by AI'''.<br>[[File:Ai-generate.png|300px|alt=ai generation of questionnaires]] [[File:Ai-generate-result.png|300px|alt=ai generation of questionnaires- result]]
# Add some questions and groups to your questionnaire.
# Save all changes and publish the questionnaire.

Alternatively, you can convert existing questionnaires. Edit the questionnaire, click '''Options''' and on the '''Features''' tab, click '''Upgrade (Beta)'''. then save all changes. Keep in mind that [[Questionnaire_Player_Gen_2#Features_unavailable_for_preview|some features are not yet enabled for gen 2 questionnaires]] and they might be lost in the conversion process. We recommend publishing the template before conversion to ensure you have a version to return to if you are unhappy with the conversion.

=== Play the new questionnaire ===

You can ''play'' (display and answer) gen 2 questionnaires either in Resco Mobile CRM or in the questionnaire component in model-driven apps.

Prerequisites:
* One of: Questionnaire component by Resco or Resco Mobile CRM 18.2 or later
* Preview feature enabled in your organization
* Published gen 2 questionnaire

In the case of Resco Mobile CRM, the app will autodetect gen 2 questionnaires and launch the correct player. In the questionnaire component for PowerApps, you need to switch to the proper form tab.

[[File:Sample-gen2-questionnaire-in-action.png|600px|alt=sample gen2 questionnaire in action]]

=== Business logic via JavaScript ===

The second generation of Questionnaire Player uses a new JavaScript library that can be used to manipulate the player and fetch data from the backend. See [https://www.npmjs.com/package/@resconet/qp-bridge www.npmjs.com/package/@resconet/qp-bridge].

Here's a high-level overview of using the new qp-bridge:

# Install Node.js.
# Run the command <code>npm create @resconet/qp-script</code>. A wizard will guide you through the process of creating a new TypeScript project.
# Write your code.
# Build your project.
# In the Questionnaire Designer, edit a questionnaire and upload the build output.

{{Note|You can continue using the traditional Resco JavaScript Bridge in the context of Resco Mobile CRM app for data manipulation within the questionnaire; however, it cannot be used for working with the new questionnaire user interface.}}

=== Power Pages advanced ===

The section [[Modernized_Questionnaire_Player#Try_Power_Pages|Try Power Pages]] explains how to quickly import and deploy a sample Power Page with questionnaires. If you want to build a Power Page from scratch, here are the details. We cover table permissions, web API permissions, and the procedure for adding questionnaires to a page.

==== Set up table permissions ====

Add the necessary permissions for the following tables:

* resco_questionnaire<!-- – Read, Create, Update, Delete, Append, Append to -->
* resco_questionnaireanswer
* annotation
* systemuser
* webresource
* organization – Read
* Any table accessible from your questionnaires (e.g., account, contact…)

You can decide what kind of access you want to grant users. Your web can be accessed by anonymous users or authenticated users. The access type might be global or parent, account, or contact. You can learn more about the security model of power pages in official Microsoft documentation. In this document, we describe how to grant access to the mentioned tables for anonymous users.

While editing your site, go to '''Security > Table permissions'''. For each table, repeat the following procedure:
# Click '''+New'''.
# Enter the '''Name''' of your permission, '''Website''', and the '''Table Name'''.
# Set '''Access Type''' to "Global".
# Check the required privileges, for example, '''Read'''.
# Click '''Add roles''' and check role(s) for which the permission is created. In our case, it is '''Anonymous Users'''.
# Save all changes.

==== Set up web API access ====

Questionnaire Player uses Microsoft Web API service to communicate with the underlying Dataverse organization. You must set the Web API access to the same tables as in the previous step.

# While editing your site, click the ellipsis button in the left pane (just under Set Up) and select '''Power Pages Management'''.
# Select '''Website > Site Settings''' from the menu.
# For '''each table''', create two new site settings:
#* Enable the web API for this table.
#* Set up fields that should be available via web API (or use asterisk for all).
#* For the organization table, add more restricted webapi permissions:
#** WebApi/organization/enabled Value: true
#** WebApi/organization/fields Value: organizationid

[[File:Set-web-API-access-in-site-settings.png|alt=Inspections on Power Platform: Set web API access in site settings|600px]]

==== Adding the player to Power Pages ====

# Include an external JavaScript in your page:<br><code><nowiki><script type="text/javascript" src="/_webresource/resco_questionnairePlayer/WebComponent/rescoQuestionnairePowerPageComponent.js"></script></nowiki></code>
# Use the web component in your page:<br><code><nowiki><resco-questionnaire id="q1" questionnaire-id="3ca3a54d-f2b3-f011-bbd3-7ced8d769a67" regarding='{"entityName":"account","name":"test","id":"16b373ee-b0af-f011-bbd3-7c1e52365f30"}' user-id={{user.id}} /></nowiki></code>

;<resco-questionnaire> attributes explained
* id is the unique identifier of the HTML element
* questionnaire-id is the GUID of the questionnaire (template or answer) to display
* regarding: if you supply this optional attribute, it fills the fields regardingIdName, regardingId and regardingIdLabel on questionnaire answer
* user-id: optional attribute, it can be initialized in Power Pages using Liquid <code><nowiki>user-id={{user.id}}</nowiki></code> if user is logged

==== Content security policy ====

If you want to use questionnaires with qp-bridge on Power Pages, you need to enable inline scripts in your page's content security policy settings.

[[File:Csp-script-source.png|600px|alt=content security policy - script source]]