View source for Questionnaire Designer

{{Academy|14|Resco Inspections}}
{{Inspections TOC}}
'''Questionnaire Designer''', also called '''Inspections Designer''' is a web application that runs in a web browser. It is one of the main components of '''[[Resco Inspections]]''' that allows users to build questionnaires in a data-driven user interface. It utilizes a per-record architecture (not per-entity), so you don’t need to work with metadata when creating questionnaire forms – no need to have system admin access privileges and mess around with potentially risky data scheme changes.

Instead, any skilled user can design one-of-a-kind questionnaires and select the best from the wide variety of available question types: Inspectors can be asked to fill out checkboxes, select picklists, scan barcodes, take and edit photos, and much more. Conceptually, this list of questions serves both as a guidance for workers and a control tool for checking the process of inspection.

You can set up a custom business logic for your questionnaires, utilizing smart elements or questionnaire rules. Once your questionnaire is ready, you can instantly deliver it to your field team via the app.

{{YT|EBjSiAGmkMU}}

== Questionnaires and snippets ==

'''Questionnaire''' is the main tool of Inspections scenarios. It is a structured form consisting of set of components or question groups designed to collect, manage and store data (information) on specific topics from users.

Generally, a questionnaire is the data collecting technique that serves for:

* Fieldwork operations – provides instructions and collects feedback from respondents.
* Communication purposes – collects information about various issues and topics as a first-hand communication channel with respondents.

Sometimes, when the distinction is important, we use the term '''questionnaire template''' to denote the questions and set them apart from the answers. Use the designer to prepare the templates, then use the app to fill in the answers.

'''Snippet''' is a portion of a questionnaire that you can save separately. You can reuse them in the same questionnaire at multiple locations, or even in different templates. Snippets can include questions and/or groups. See this [https://blog.resco.net/2019/05/02/quick-tip-how-snippets-speed-up-the-setup-of-resco-inspections-questionnaires/ blog] for tips how to speed up the setup of questionnaires using snippets. {{Badge|Blog}}

=== Life cycle of a questionnaire template ===
[[File:Lifecycle of questionnaire templates.png|alt=Lifecycle of a versioned template|thumb|right|Lifecycle of a versioned template]]
Over time, you might need to modify your questions. You have two options for managing your templates.

; Non-versioned templates
: These templates have a simple life cycle. They start in draft status. You can then '''Activate''' them to make them available in the app, or '''Deactivate''' them to disable them. You can edit non-versioned templates at any point; it can happen that your app users manage to launch the questionnaire while you're in the middle of a change.

{{Note|We're deprecating non-versioned templates. See [[Deprecations#Active_deprecations|Deprecations]] for details.}}

; Versioned templates
: These are useful if you expect more frequent editing of your templates and you want to avoid the potential pitfalls. Once you enable '''Versioning''' for a template, this process cannot be reversed. These templates also start in draft status. You have the option to '''Stage''' them, i.e., make them available in the app, but only for test users. You can '''Publish''' them to make them available for all users. <small>(You can use [[Sync_Filter_examples#Active_questionnaire_templates_and_recent_answers|sync filter]] to ensure staged questionnaires are available in the app.)</small>
: Once published, you cannot edit a template. However, you can '''Revise''' it to create a new version in draft status, while your app users continue to use the published version. Once you're happy with your draft or staged revision, you can publish it; moving the previously published version to archive. You can also access the version history and easily return to an older version of the template.

{{Note|Use staged questionnaires for testing only. Staged templates can be modified at any point, rendering old template-dependent answers incompatible with the changed template.|Warning}}

When revising a questionnaire template, you can set whether existing associations should remain intact:
* Association with an [[Questionnaire_Designer#Actions_group|existing entity record]]
* Association with a [[Mobile_reports_for_Resco_Inspections#Custom_report:_edit_in_the_Report_Designer|custom mobile report]]

[[File:Questionnaire lifecycle revise.png|alt=Questionnaire lifecycle revise dialog|xxxxxxx]]

When publishing a questionnaire template, you can enter custom publish notes that are displayed in the version history of the template.

[[File:Questionnaire lifecycle publish.png|alt=Questionnaire lifecycle publish dialog]]

To control which questionnaires can users see in their app, use [[Inspections#Filters|filters]]. For information about status code numbers, see the [[Resco Inspections data model]].

See also: [https://blog.resco.net/2020/03/18/versioning-folders-inspections-guide/ Quick guide to versioning and folders] {{Badge|Blog}}

<small>Using versioned templates means that old template versions gain the archived state. Sometimes, the sync filter for the Questionnaire entity is configured to exclude archived templates. If you attempt to view old answered questionnaires (that use an archived template with [[Best_practices_for_deploying_Inspections#Rapidly_increasing_database_footprint|medium or high dependency level]]) in the app in offline mode, you may encounter the Questionnaire template not found! error. In this case, consider modifying the sync filter to make archived templates available in the offline mode.</small>

=== Feature Version ===

As we keep adding features to questionnaires, every now and then, we might introduce breaking changes. To make sure that [[Resco mobile apps]] can gracefully handle this formatting change, we are using '''Feature version''' (property of the questionnaire template). Whenever a breaking change is introduced, the required feature version increases. If you attempt to open a questionnaire with unsupported features in an older app, an error message is displayed, and users are urged to update their app.

Alternatively, you can edit the questionnaire template in the [[Questionnaire Designer]] and decrease the feature version to ensure that the questionnaire stays compatible with older app versions (click '''Options''' and go to the '''Features''' tab). However, some newer questionnaire features will be unavailable. If you're familiar with Woodford projects, this is similar to [[Publishing_app_projects#Publishing_with_older_version|publishing app projects with older Publish Version]].

{| class="wikitable sortable"
! Feature version || Release || Description
|-
| 1 || [[Releases/Spring 2022|15.0]] || Introduction of feature version
|-
| 2 || [[Releases/Summer_2023|16.1]] || Rename "[Clear]" option in option sets<br>Add label position "BorderTop"<br>Use supporting text for descriptions
|-
| 3 || [[Releases/Winter_2024|17.0]] || Use optical character recognition (OCR) to answer questions
|-
| 4 || [[Releases/Spring_2024|17.1]] || Use resco_questionnaireanswer table for storing answers
|}

== Accessing the designer ==

; Microsoft Power Platform/Dynamics 365
: Log in to the [[Power Platform]]/[[Dynamics]]. In the list of published apps, search for [[Resco Suite]]. Select '''Inspections > Questionnaire Designer'''.

; Resco Cloud
: Log in to your [[Resco CRM server#Logging_in|organization]] and select '''Questionnaire Designer'''.

; Salesforce
: Log in to Salesforce, start the App Launcher, then select '''Questionnaire Designer'''. Requires [[Resco managed package]].

== Managing questionnaires ==

The designer main screen shows a list of your questionnaire templates. If you have many templates, you can use the left menu to filter the entries. You can also access snippets here.

[[File:Questionnaire Designer.png|alt=question designer overview|600px]]

The top right corner has a pair of buttons that allow you to switch between grid layout (default) and list layout.

The main toolbar offers the following functions (not all functions are available for snippets).

=== Actions group ===
* New – Create a new questionnaire or snippet from scratch.
* Edit – Open the selected item for editing.
* Delete – Permanently delete the selected questionnaire, snippet, or folder.
* Clone – Create a copy of the selected item. You are prompted to enter a new name for the duplicate.
* Activate / Deactivate – Mark a template as active or inactive. Active templates are available in the app.
* Associate – Use this function to add or remove entities to which the questionnaire should be associated. See also this [https://blog.resco.net/2019/03/06/how-to-dynamically-filter-questionnaire-templates-on-the-appointment-entity-form-based-on-appointment-type/ blog post]. {{Badge|Blog}}

=== Data group ===
* Import – Select a qbuilder file (or a zip file with multiple questionnaire templates) and import it.
* Export – Export the selected questionnaires, folders, or snippets in XML format (qbuilder or zip file).
* Select / Deselect – Select multiple items for bulk operations.

{{Note|While in theory, you can edit a qbuilder file in an XML or text editor and upload the changes back to the Questionnaire Designer, Resco cannot officially support such questionnaire templates.

Also, do not modify any questionnaire-related records (questionnaire, question group, question) directly, for example, using the Admin Console. Such changes can break your questionnaires and crash your apps.|Warning}}

=== Versioning group ===
* Versioning – Enable versioning for a template. This cannot be reversed.
* Version History – Show a list of versions available for this template.
* Publish – Make the questionnaire available in the app. Similar to Activate for non-versioned questionnaires. Published templates cannot be edited.
* Stage – Make the questionnaire available for test users in the app. Staged templates can still be edited.
* Revise – Change the status of a template to Draft (makes it available for editing). Available for published or archived versions.
* Archive – Mark a published template as archived: This will make the template unavailable in the app.
* Discard – Permanently delete current draft version.

=== Folders group ===
Use folders to keep your questionnaires organized.
* New Folder – Create a new folder.
* Rename Folder – Rename a folder.
* Move To – Move a template or folder to a folder.
You can also click Delete in the Actions group to delete a folder including all templates and subfolders.

{{Note|Folders only serve to organize templates in the designer; they have no impact on questionnaire availability in the app. To modify which questionnaires are available in the app, use the [[View#Edit_filter|view filters]].}}

=== Library group ===
* Sample Templates – Import sample questionnaires. Select templates from different industry verticals, such as manufacturing, property maintenance, or energy.

{{Note|Additional templates are available for [https://www.resco.net/library/ free download on Resco web] (see also [[How to use a template from the Resco Template Library|instructions]]).|Tip}}

== Creating a new questionnaire ==

# Select '''New''' from the toolbar or click '''New Questionnaire''' from the questionnaire list to start the new questionnaire wizard.
# Review the questionnaire settings:
#* '''Versioning''': Versioned templates grant you more control over the lifecycle of questionnaire templates.
#* '''Dependency''': Determines whether the questionnaire answers are saved in a self-contained way or depend on the original questionnaire template (saves storage).
#* '''Answer Storage''': Defines how the questionnaire answers are stored.
#* '''Answer Entity''': Defines where the questionnaire answers are stored (in which table).
#* '''Score''': [[Questionnaire_Designer#Scoring|Scoring]] allows you to assign a score to each answer.
#: Check the [[Best practices for deploying Inspections]] and also [[Deprecations#Active_deprecations|Deprecations]] related to some of the legacy options.
# Do one of the following:
#* Click '''Create''' to continue with your current settings.
#* Click '''Set to recommended''' to apply the optimal questionnaire settings, then click '''Create'''.
#* Click '''Settings''' and finetune the questionnaire settings to your preference. Click '''Create''' to conclude the wizard.

<gallery mode=packed heights=300px style="text-align:left">
Create new questionnaire.png
New questionnaire wizard 0.png
New questionnaire wizard 1.png
New questionnaire wizard 2.png
</gallery>

=== Import XLS/CSV ===

Since [[Releases/Autumn_2021|Release 14.2]], you can import questions from CSV or Excel files into the Questionnaire Designer as a new template.

# Select '''New''' from the toolbar or click '''New Questionnaire''' from the questionnaire list to start the new questionnaire wizard.
# Select '''Import from Excel''', then click '''Select file''' and upload the file with your questions.
# Select the questions and groups that you want to import. You can also modify labels and question types as needed.
# Conclude the wizard as described above.

[[File:New questionnaire wizard 3.png|alt=import questionnaire template from Excel|300px]] [[File:Select which questions to import.png|alt=edit questionnaire template imported from excel|300px]]

The spreadsheet file must be in a specific format. To get started, you can copy the table below (including the header row) into a suitable editor and save it as a CSV/Excel file; or you can download a sample file from [https://resco.net/downloads/inspections_import_template.zip our web].

{| class="wikitable"
! Group name || Repeatable group || Question name || Question type || Question options 
|-
|  ||  || Root text question || Text ||  
|-
|  ||  || Root number question || Decimal Number ||  
|-
| Group 1 || TRUE || Group 1 text question || Text ||  
|-
| Group 1 || TRUE || Group 1 number, question || Whole number ||  
|-
| Group 2 || FALSE || Group 2 text question || Text ||  
|-
| Group 2 || FALSE || Group 2 number question || Whole number ||  
|-
| Group 3 || FALSE || Group 3 single choice q || Single-select || <nowiki>a|b|c</nowiki>
|-
| Group 3 || FALSE || Group 3 multiple choice q || Multi-select || <nowiki>a|b|c</nowiki> 
|-
| Group 3 || FALSE || Group 3 option set q || Option Set || <nowiki>a|b|c</nowiki>
|-
| Group 3 || FALSE || Group 3 yes no q || Yes/No || <nowiki>Yeah|Nope</nowiki>
|}

=== Generate using AI ===

Since [[Releases/Spring_2025#Generate_questionnaire_templates_using_AI|Release 18.1]], you can generate new questionnaires using AI. We support two options as input:
* Enter a text prompt: describe the questionnaire in your own words.
* Upload a source document.

Generative AI will analyze the input and suggest questions and groups for you, including appropriate question types, formatting, and styling. You can fine-tune all generated elements before finalizing the template.

=== Good questionnaire (webinar) ===

If you are looking for tips on designing a good questionnaire, you can look at our webinar from December 2023. Join our product consultant in creating a questionnaire from scratch, including smart rules, buttons, snippets, styles, tagged image, preview feature, reports, and much more. Learn '''how''' to do it and understand '''why''' the features help the end users.

[https://www.resco.net/webinars/power-platform-masterclass-2/ What to keep in mind to create a good questionnaire] {{Badge|Webinar}}

== Editing a questionnaire ==


=== Main toolbar ===
Main toolbar is in the top section of the application. These are the commands available on the main toolbar.

[[File:Questionnaire-designer-main-toolbar.png|600px|alt=main toolbar in the Questionnaire Designer]]

; Publishing group
* Save – Save the questionnaire
* Save & Close – Save the questionnaire and returns user to the home screen.
* Publish – Make a versioned template available in the app. 
* Stage – Make a versioned template available for test users in the app.
* Options – Set up some properties and enable features of the questionnaire template. See [[Questionnaire_Designer#Questionnaire_options|questionnaire options]] below.

; Rules group
* [[On Create]] – Executed when a questionnaire instance is about to be created
* [[On Load]] – Executed when a user starts filling out the questionnaire
* [[On Save]] – Executed when a user completes the questionnaire
* [[On Change]] – Executed each time a value of a question is changed by the user
* [[On Repeat]] – Executed when a new instance of a question group is created
* [[On Delete]] – Executed when an instance of a question group is removed from the questionnaire

; Mapping group
* Link Lookup – Create multiple mapped questions at once, all related to the lookup question target.
* Link Regarding – Create multiple mapped questions at once, all related to the record from which the questionnaire was opened.

; Commands group
* [[Command editor|Commands]] – Select which commands should be available in the app for users who fill out a questionnaire.
* [[On Can Execute]] – Using rules, configure when a command is available.
* [[On Execute]] – Using rules, configure what happens when a command is executed.

; Automatic report group
* Preview Report – Preview the report for the questionnaire in your browser (not available for Dynamics and Salesforce backends).
* Settings – Configure your report preview.
* Themes – Select one of the preconfigured themes for your reports.

; Localization: Use localization to define language mutations for your questionnaire.

=== Questionnaire options ===

Click '''Options''' on the toolbar to set up some properties and enable features of the questionnaire template. The options are organized in multiple tabs.

[[File:Options-of-a-questionnaire-template-rules-tab.png|alt=Options of the questionnaire template|400px]]

;Features tab
* Score – Enable or disable [[Questionnaire_Designer#Scoring|scoring]].
* Data mapping – Enable or disable [[Mapping_questions_to_fields|data mapping]].
* Reuse answers – Select whether answers from previously completed questionnaires should be prefilled on new questionnaires:
** Never: Do not reuse.
** First Match: Take answers from the first completed questionnaire that the system can find.
** Ask User: User can decide whether to prefill answers or not.
** Select by User: User can select from a list of previously completed questionnaires.<br>You can customize the looks by creating a view called "Reuse". If it does not exist, the default view is used.
* Reuse Fetch – Click '''Edit''' to display the [[Filter editor]] where you define or modify the list of questionnaires available for reuse.
* Feature version – Track compatibility of new questionnaire features with older apps. See [[Questionnaire_Designer#Feature_Version|Feature Version]] for more information.

;Rules tab
* Script Path – Path to the offline JavaScript file that offers enhanced logic to the questionnaire.
* Rules version – Select which version of rules to use. In general, use "Latest". See [[Questionnaire_Designer#Rules_version|Rules version]] for more information.{{Anchor|Validate}} 
* Validate on – Select when to validate answers: when saving or when completing the questionnaire.

;User interface tab
* Group expanding – Choose "Single group" if you want to keep only a single question group expanded when answering questionnaires. All other groups are collapsed to better focus your attention.
* Layout – Use '''List''' to display one question per row. Use '''Grid''' if you want to organize multiple questions in a row. See [[Questionnaire_Designer#Grid_layout|grid layout]] for more information.
* Grid layout – Click '''Edit''' to arrange top-level questions into a grid.

;Storage tab
* Template dependency – Should the questionnaire answers be saved in a self-contained way (independent from the questionnaire template, duplicating all template data), or save only answers and link to the original questionnaire template. See [[Best_practices_for_deploying_Inspections#Rapidly_increasing_database_footprint|performance considerations]] for details.
* Answer storage – Select how should the answers be stored. {{Anchor|Storage}} See [[Resco Inspections data model]] more for details.
** Records: This is the default option. Each answer is transferred and saved as a single record during synchronization. This may make synchronization slower, but ensures the best compatibility with the backend servers and allows you to leverage existing tools to visualize the data.
** JSON (Legacy): All answers are saved in a single field of the questionnaire entity. JSON offers improved synchronization performance, however, not all tools understand JSON.
** JSON (New): Revised customizable JSON format is customizable and requires less database storage.
* JSON Compression – If you are using JSON, you can optionally compress it to save even more space.
* Configure JSON – When using the new JSON formats, you can either select the '''minimum''' variant or the configurable '''flexible''' format. See [[JSON storage for questionnaires]].

;Auto report tab
* Generate automatic report – Enable if you want to generate a mobile report from your questionnaire and you want to set up this report directly in the Questionnaire Designer. See [[Mobile_reports_for_Resco_Inspections#Automatic_report:_edit_in_the_Questionnaire_Designer|Mobile reports for Resco Inspections]] for more information.
* Include unanswered – Do you want to include unanswered questions in the report?
* Header style – Select the style for the header block displayed on the mobile report.
* Footer style – Select the style for the footer block displayed on the mobile report.

=== Editing toolbar ===

A smaller toolbar is available directly in the central designer pane with the following commands:

[[File:Editing-toolbar-in-the-questionnaire-designer.png|alt=editing toolbar overview|600px]]

* Delete – Delete the selected component
* Clone – Clone/duplicate the selected component
* Move Down – Move down the selected component
* Move Up – Move up the selected component
* Collapse All – Collapse all components in the central pane and in the Navigation pane
* Expand All – Expand all components in the central pane and in the Navigation pane
* Multiselect - Allow you to select multiple components. You can use the selection for example to create a snippet.

* Preview Form – Preview the questionnaire in your browser. You must save the questionnaire at least once to allow preview. Keep in mind that some rules can be ignored in preview mode.
* Styles – Use styles to modify how the questionnaire appears in the app. You can change for example text color, alignment, position of questions and answers, etc.
* Create Snippet – Select multiple components (for example using the Multiselect button), then click Create Snippet and specify a distinct name to save it for later use.

=== Navigation pane ===

The '''Navigation''' pane shows a chronological list of components within a questionnaire, similar to a table of contents. Selecting a component in the Navigation pane also selects it in the main central pane and displays the component's details in the properties pane on the right. For longer questionnaires, you can collapse groups for a better overview. You can also use Multiselect components here.

=== Components pane ===

The '''Components''' pane shows a list of available components or building blocks that you can add to your questionnaire.

The main component of a questionnaire is a '''group'''. It is a collection of questions. Typically, it is used to categorize questions by relevance.

==== Static components ====

Static components are designed to show static text, images, links, or entity links. These components cannot be changed by the user filling the questionnaire template.

{| class="wikitable sortable mw-collapsible" 
! Component
! Description
|-
| Logo
| Allows you to upload your company's logo (or any other image). Each questionnaire template can have only one logo. It is placed on top of the questionnaire. The same image can also be used for the automatic report.
|-
| Guide
| Adds a link to a [[guides|guide]]. Inspectors can study the guide to find the necessary knowledge, without leaving the questionnaire. To find the link, start the [[Guides#Guides_editor|Guides editor]], select a guide, and share it. Once you enter a correct guide link to the Questionnaire Designer, the guide title is automatically updated.
|-
| Description
| Adds a section for describing questions, questionnaire sections or for providing any other information for the user, other than a question. It consists of a label and a description part and can be used as a separator component.
|-
| Link
| Adds a static link.
|-
| Entity Link
| Adds a section with a static link on an entity record. It is possible to set the label, description of a section and label for the link. Clicking on “Click to select…” opens a window where an entity and its record that is going to be linked, is set. A typical use case for this component is to provide additional documentation (manual, scheme, or legal information) for a question.
|-
| Static Image
| Adds a section with a static image on a questionnaire template. It is possible to set the label and description of the image, as well as the maximum display width or height. The image aspect ratio is preserved and smaller images are not upscaled.
|-
| Button
| Adds a '''[[#Button|button]]''' to your questionnaire. Select from the list of predefined actions (for example, save) or define your own custom action using rules. Requires [[Releases/Summer 2021|release 14.1]].
|}

==== Questions ====

Questions are components that you can add to the questionnaire and users can or must provide an answer in some form.

{| class="wikitable sortable" 
|+ style="text-align:left;" | Single-line text
! Question || Description
|-
| Short Text || Add a question type of a single line of text.
|-
| Whole Number || Add a question that requires a whole number as an input. The number has to be in between the minimum and maximum limits if they are set.
|-
| Decimal Number || Add a question that requires a decimal number as an input. The number has to be in between the minimum and maximum limits if they are set. Users can also specify precision for the input that represents the number of decimal digits.
|-
| URL || Add an input for a specified URL.
|-
| Email || Add an input for the email address.
|-
| HTML || Add a text field. <!-- no special handling atm, perhaps in the future -->
|}

{| class="wikitable sortable" 
|+ style="text-align:left;" | Multi-line text
! Question || Description
|-
| Long text (paragraph) || Add a question type of multi-line text on a questionnaire template.
|}

{| class="wikitable sortable" 
|+ style="text-align:left;" | Date and time
! Question || Description
|-
| Date || Add a field to the questionnaire template to enter date data.
|-
| Date and Time || Add a field to the questionnaire template to enter the date and time.
|}

{| class="wikitable sortable" 
|+ style="text-align:left;" | Choices
! Question || Description
|-
| Single-select || Add a question with multiple answer options on a questionnaire template. Users can only select one of the available answers. Single-select choice also comes with a built-in search option, users can start typing their answer to quickly find it in a large list.
|-
| Multi-select || Add a question with multiple answer options on a questionnaire template. Users can select multiple available answers.
|-
| Yes/No || Provide users with a switch between two values. You can set the label for each.
|-
| Option Set || It's similar to the single-select choice question, but each item is composed of a text label and number value. The number is saved as the answer.
|}

{| class="wikitable sortable" 
|+ style="text-align:left;" | Media
! Question || Description
|-
| Image/Media || Add a question that requires one or more images as an answer. Image is stored either in an entity that supports attachments (for example, note/annotation) or in external document storage (such as Google Drive or SharePoint). Optionally, select the image question and check '''Image Description''' on the '''Properties''' pane to add an optional text field under the image.
|-
| [[Questionnaire_Designer#Tagged_image|Tagged Image]] || Add a question that requires a picture as an input. Additionally, you can mark portions of the image with tags.
|-
| Image Recognition || Add a question that requires a picture as an input. Uses [[AI Image Recognition]] for further processing.
|-
| Signature || Add an input for the signature. Signature is stored in the Note (annotation) table. The Document (documentbody) column must be enabled.
|-
| Barcode || Add a way to scan a [[barcode]].
|}
{{Anchor|Regarding_lookup_component}}
{| class="wikitable sortable" 
|+ style="text-align:left;" | Database links
! Question || Description
|-
| [[Questionnaire_Designer#Lookup|Lookup]] || Add a field to a questionnaire that can be answered by selecting an entity record.
|-
| Regarding Lookup || Regarding lookup is a special component. When you open the questionnaire from an entity record, this field is automatically filled with the record. In this case you might just want to display it on screen. Alternatively, when you start the questionnaire from the [[home screen]], this field will not be filled automatically; the user of the mobile app can select an entity record there. Just make sure that this component has its targets set to the entities you plan to use this questionnaire for.
|}

Some question types might be unavailable if your inspectors are using smartwatch or voice to perform the inspection; see [[Smartwatch_integration#Supported_question_types|supported question types]].

=== Snippets pane ===

The Snippets pane shows a list of available snippets that you can add to your questionnaire.

=== Properties pane ===

When you select a component in a questionnaire or snippet, the properties of the component are displayed on the right side of the window.

==== Basic properties ====
* '''Id''' – Each component has its own unique ID. Users can’t change it.
* '''Name''' – User can edit the displayed name for any component. It can be changed at any point; however, if the displayed names are used in any rules, you must change them as well.

{{Note|For questions, names are automatically generated from question text. Keep an eye on the length of the name. Long names are hard to read and they may consume a non-trivial amount of space in the JSON string with answers.|Tip}}

==== Properties on Questionnaire level ====
* '''Label''' – The displayed name of the questionnaire.
* '''Status''' – Questionnaire templates start in Draft status. Status cannot be changed on the Properties pane, use toolbar buttons instead. Available values depend on whether the questionnaire template is versioned or not:
** Non-versioned: Active, Draft, Inactive
** Versioned: Draft, Published, Staged, Archived
:: See [[Questionnaire_Designer#Life_cycle_of_a_questionnaire_template|lifecycle of questionnaire templates]] and [[Resco Inspections data model]] for more information.
* '''Version Name''' – Internal name of the versioned questionnaire. You set it when you enable versioning for a template; it cannot be changed afterward.
* '''Version''' – Number of the version. Assigned by the system, cannot be changed.
* '''Reuse Answers''' – Select whether answers from previously completed questionnaires should be prefilled on new questionnaires:
** Never: Do not reuse.
** First Match: Take answers from the first completed questionnaire that the system can find.
** Ask User: User can decide whether to prefill answers or not.
** Select by User: User can select from a list of previously completed questionnaires.
* '''Reuse Fetch''' – Click to display the [[Filter editor]] where you define or modify the list of questionnaires available for reuse.
* '''Validate On''' – Select when to validate answers: when saving or when completing the questionnaire.
* '''Rules version''' – Select which version of rules to use. In general, use "Latest". See [[Questionnaire_Designer#Editing_rules|Editing rules]] for more information.
* '''Scoring''' – Assign a score to each answer to quickly measure questionnaire results. See [[Questionnaire_Designer#Scoring|Scoring]].
* '''Group Expanding''' – Choose '''Single Group''' if you want to keep only a single question group expanded when answering questionnaires. All other groups are collapsed to better focus your attention.
* '''Last Modified On''' – Date and time of the last time the template was modified.
* '''Last Modified By''' – User name of the user who saved this template for the last time.
* '''Script Path''' – Path to the offline JavaScript file that offers enhanced logic to the questionnaire.
* '''Compress properties''' – Large questionnaires can run into the maximum field size limitation. Enabling compression can help. See [[Releases/Spring_2022#Compress_selected_questionnaire_fields|details]]. Originally, the feature was only available on Salesforce, but you can use it with all backends.
* '''Feature Version''' – Track compatibility of new questionnaire features with older apps. See [[Questionnaire_Designer#Feature_Version|Feature Version]] for more information.

Answered Questionnaire
* '''Dependency Level''' – Should the questionnaire answers be saved in a self-contained way (independent from the questionnaire template, duplicating all template data), or save only answers and link to the original questionnaire template. See [[Best_practices_for_deploying_Inspections#Rapidly_increasing_database_footprint|performance considerations]] for details.
* '''Storage''' – Select how should the answers be stored. {{Anchor|Storage}} See [[Resco Inspections data model]] more for details.
** Records: This is the default option. Each answer is transferred and saved as a single record during synchronization. This may make synchronization slower, but ensures the best compatibility with the backend servers and allows you to leverage existing tools to visualize the data.
** JSON (Legacy): All answers are saved in a single field of the questionnaire entity. JSON offers improved synchronization performance, however, not all tools understand JSON.
** JSON (New): Revised customizable JSON format is customizable and requires less database storage.
* '''Compression''': If you are using JSON, you can optionally compress it to save even more space.
* '''Configure JSON''': When using the new JSON formats, you can either select the '''minimum''' variant or the configurable '''flexible''' format. See [[JSON storage for questionnaires]].

{{Note|Self-contained questionnaires are being deprecated in favor of full template dependency. Legacy JSON is being deprecated in favor of newer JSON formats. See [[Deprecations#Active_deprecations|Active deprecations]] for more information.}}

Layout
* '''Layout Type''' – Use '''List''' to display one question per row. Use '''Grid''' if you want to organize multiple questions in a row. See [[Questionnaire_Designer#Grid_layout|grid layout]] for more information.

Reporting
* '''Enable Auto Report''' – Enable if you want to generate a mobile report from your questionnaire and you want to set up this report directly in the Questionnaire Designer. See [[Mobile_reports_for_Resco_Inspections#Automatic_report:_edit_in_the_Questionnaire_Designer|Mobile reports for Resco Inspections]] for more information.
* '''Include Unanswered''' – Do you want to include unanswered questions in the report?
* '''Header Style''' – Select the style for the header block displayed on the mobile report.
* '''Footer Style''' – Select the style for the footer block displayed on the mobile report.

Questionnaire Icon {{Anchor|icon}}
* '''Questionnaire Icon''' – You can upload an image that will be used as the icon for the questionnaire in the app.

==== Properties on Question level ====
* '''Style > Name''' – Choose a style how to display the question in the questionnaire
* '''Reuse''' – prefill answer for this question
* '''Format''' – some components offer the additional option to select the desired format which may affect how the component is presented in the app. For example, if you select "Multiple Lines of Text", the app displays a larger text field where the user can type the answer.
* '''Show on report''' – when enabled, the component is visible on the report.
* '''Reporting > Style''' – Choose a style how to display the question in the mobile report
* '''Preview Answer''' – Enter an answer for this question that should be used when previewing the mobile report

Lookup questions
* '''Filter''' – you can set up filter the available records or change the sort order.
* '''Allow Create New''' – users can create a new record directly from the questionnaire. 
: See [[Questionnaire_Designer#Lookup|Lookup]] for details about the lookup question type.

==== Properties of Image/Media ====

* '''Image Description''' – Enable this option to add a text field under an image question that serves as an image description. Not available for multi-image questions. Not available in grid layout.
* '''Storage Entity''' – Available for image-type components. Select where should the image be stored: Either in an entity that supports it or in external document storage.
* '''Max Count''' – Allow the user to answer a single image/media question with multiple images/files (default=1, max=100).
* '''Width (px)''' & '''Height (px)''' – Restrict the display size of images in the app.

Allowed actions (some actions might be unavailable depending on the capabilities of the device)
* '''Action Mask''' – numeric representation of the actions selected below (you can copy/paste this number to quickly reuse your actions setup for a different image question)
* '''Signature''' – allow user to answer the image question by drawing a signature
* '''Capture Photo''' – allow user to answer the image question by capturing a photo
* '''Select Photo''' – allow user to answer the image question by selecting from your existing photos
* '''Edit Image''' – allow user to edit the image
* '''Use Last Photo Taken'''
* '''Load From''' – allow user to load answer from iCloud
* '''Paste''' – allow user to answer the image question by pasting a previously copied image
* '''Select File''' – allow user to answer the image/media question by selecting from files (not supported on iOS – use Load From to add files from iCloud)
* '''Record Audio''' – allow user to answer the image/media question by recording an audio message
* '''Record Video''' – allow user to answer the image/media question by recording a video message
* '''Import''' – allow user to answer the image/media question by importing a vCard

Multi-image questions
* '''Max Width (px)''' – restrict the maximum width of uploaded images to this value in pixels
* '''Max Height (px)''' – restrict the maximum height of uploaded images to this value in pixels 
* '''Max Size (KB)''' – restrict the maximum file size of uploaded files to this value in kilobytes

See also [[Image_examples#Image.2Fmedia_in_questionnaires_FAQ|multi-image FAQ]].

Image grid – set up how multi-image questions should be displayed on the questionnaire and on the report.
* '''Images per Row''' – How many images should be displayed in a single row?
* '''Image Count''' – How many images should be displayed in total? The app indicates if the count of images/media exceeds this number.
* '''Image Fit''' – How should images be resized to fit the container?  Use '''Contain''' to preserve the aspect ratio and resize to fit the given dimensions. Use '''Cover''' to keep the aspect ratio and fill the container, clipping portions that don't fit.

==== Properties on Group level ====
* '''Repeatable''' – Repeatable groups may appear in your questionnaire multiple times.
* '''Min Repeat Count''', '''Max Repeat Count''' – Specify how many instances of a question group are allowed.
* '''Copy Values''' – When you create a new instance of a repeatable group, copy values from the old group instance to the new group instance. This is useful when most of the entered values don't change. Optionally, you can enable or disable copying for each question in the group.
* '''Show Repeat Button''' – By default, repeatable groups show a plus button in the header that creates a new group instance. You can hide this button.
* '''Show Delete Button''' – By default, repeatable groups show a delete button in the header that deletes the group instance. You can hide this button.

* '''Layout Type''' – Use '''List''' to display one question per row. Use '''Grid''' if you want to organize multiple questions in a row. See [[Questionnaire_Designer#Grid_layout|grid layout]] for more information.

* '''Show Header''' – Display group header on the report?
* '''Header Style''' – Select the style for the group header block displayed on the mobile report.
* '''Questions Layout''' – Select how the content of the group should be arranged on the report:
** Use '''Horizontal''' to display multiple questions in one row
** Use '''Vertical''' to display one question per row.
** Use '''Custom''' to design your own layout. See [[Releases/Spring_2021#Questionnaire_reports:_custom_layout_of_questions_in_a_group|instructions]].
* '''Break After''' – Used together with questions layout: set how many questions should be displayed in one row or column before continuing to the next row/column.
* '''Repeat Layout''' – Use '''Default''' to display question and answer together, or '''Compact''' to display question only in the header and then list answers.
* '''Border Type''' – What borders should be displayed in the report? No borders – Outside borders – Rows – Columns – Grid.
* '''Line Color''' – Set the color for border lines.

See also [[Questionnaire_Designer#Smart_question_properties|smart question properties]] below.

== Managing components ==

* To add components to a questionnaire or snippet, go to the '''Components''' pane and click the plus sign (+). The chosen component is added into or under the currently selected component.
* To select a component, click it - either in the '''Navigation''' pane or in the central pane.
* To move a component to a different location, click the left part of the component and drag it to the right spot. Alternatively, use the '''Move Up''' and '''Move Down''' toolbar buttons.
* To toggle visibility of a component, use the eye icon.
* To mark a question as mandatory, click the exclamation point (!).
* To create a duplicate of a component, click '''Clone'''.
* To delete a component, click '''Remove'''.

=== Question names ===

When you add or edit a question, consider reviewing also a question's '''Name''' parameter on the '''Properties''' pane. Question names are formed from the question's label. The name serves as a human-readable identifier of the component for example in rules or in reports. It is also used for file names for image-type questions when using external cloud document storage. When you change a label, verify that your rules or image links still work correctly.

If your question name is too long (hundreds of characters), you might run into operating system limitations. For example, trying to save a file with the name derived from a question may fail because the name is too long.

=== Smart question properties ===

You can add no-code [[business logic]] to your questionnaire.
* On each '''question''', you can select the "smart" option for controlling whether a question is visible, enabled, required, or whether the answer is [[Mapping questions to fields|mapped to a record field]].
* On each '''group''', you can select the "smart" option for controlling whether a group is visible and expanded.

# Select a question (or group).
# Click one of the business logic buttons [[File:Smart question properties.png|alt=smart question properties overview]] directly on the question and select '''Smart'''.
# In the Smart question editor, specify when should the question be visible, enabled, or mandatory. Build conditions by clicking and selecting the appropriate option from a drop-down list.<br>[[File:Smart question rule.png|alt=smart question rule example]]
# You can specify multiple conditions and group them using logical '''and''' or '''or''' operators.
# Click '''OK''' to save the conditions.

Use colors to identify how a particular smart property is configured:

[[File:Smart question properties with colors.png|alt=smart question properties color configuration]]
* Blue means yes or true (for example, a question is enabled or visible)
* Grey means no or false (for example, a question is hidden or not required)
* Green means smart, i.e., smart question properties are enabled for this question or group. To disable the smart logic, click the green button to open the conditions editor and then click '''Reset'''.

{{Note|Alternatively, you can use [[Questionnaire_Designer#Editing_rules|rules]] or JavaScript to add more advanced business logic to your questionnaire.}}

=== Smart default values ===

For many question types, you can configure a default value. These defaults can include values from the entity record, from which you open the questionnaire. For example, for text type questions, it might make sense to offer your record's city or the name of the current app user.

[[File:Smart default value.png|alt=example of default smart values|600px]]

You can select the value from a list. You can even combine the values with your own text, for example, the default for a favorite restaurant could be <nowiki>"The Best Sushi in {{Regarding.City}}"</nowiki>.

These smart default values work best if you are using the default entities and with default fields. The system attempts to map the selected smart default to an entity field. For example, the smart default value ''Contact Name'', if you are on the contact entity, it's simply the field contact.name; if you are on the account entity, it's the primary contact reference field.

See also: [https://youtu.be/uZ1nxS1H0wI Configuration] – [https://youtu.be/K13dMSV5QZY Smart default in action] {{Badge|Webinar|YouTube}}

=== Smart styles ===

In the case of numeric questions, option sets, and yes/no questions, you can add a specific style to the values that are answered.

[[File:Smart style.png|alt=example of smart style|600px]]

=== Groups ===

Questions are usually organized into groups. One of the advantages of groups is that they can be set as repeatable. Instead of creating a questionnaire with the same set of questions multiple times, repeatable question groups offer the ability to repeat the grouped questions either arbitrarily (not known beforehand) or precisely specified number of times.

Repeatable question groups are useful in cases such as when:
* User needs to enter multiple addresses
* User needs to enter data about more than one result of the same issue (checking 10 identical parts of a machine)
* User needs to enter multiple pictures of the same object

Use the group property ''Copy values'' if you want the answers to the questions in a repeated group to be pre-filled based on the previous answers. This is useful when most of the entered values don't change. Optionally, you can tweak the behavior for each question of the group. 

Using Woodford, it is possible to [[Questionnaire_Designer_examples#Add_custom_icon_for_questionnaire_group|add a custom icon for your question groups]].

For each question group, you can track the completion percentage using rules. See [[Questionnaire_Designer_examples#Track_group_completion|Track group completion]] for more information.

==== New instance of a repeatable group ====

Use the plus button in the top right corner to create a new instance of a repeatable group.

[[File:Repeatable group.png|alt=add a new instance of repeatable group|400px]]

Optionally, you can add a custom [[Questionnaire_Designer#Button|button]] component to your questionnaire that creates a new instance. This can be useful, for example, if you have a large group with many questions. Users won't have to scroll back to the group's top to create a new instance.

==== Question indexes ====

Individual questions have numerical indexes, question groups have alphabetical indexes, and they are sorted alphabetically.

Question groups are always displayed after the questions with numerical indexes. It is not possible to re-position question groups; only sort them by changing their alphabetical index. For example, it is not possible to put question group B between questions with indexes 2 and 3. Still, it is possible to place question group B instead of question group A, changing its position within the question group section.

=== Lookup ===

The lookup question allows the user to answer by selecting an entity record. When designing a lookup question:
* You must select one or more entities as target(s) of the lookup.
* You can configure a filter to display only the relevant records to the user.
* You can configure a custom view displayed in the app to locate the record. Click the View icon in the target entity row and define up to 7 fields that should be displayed in the view.

If this custom view does not exist, the app uses the lookup view for the entity (if any), or simply the default view.

Remember that one questionnaire can be used in different [[app projects]], and each project can have different views. As a result, the same questionnaire template can look differently depending on the app project of the inspector. Set up a view directly in the questionnaire to prevent this from happening.

[[File:Setting up a lookup question.png|alt=edit view for lookup question type|600px]]

In the app, users can select the lookup answer from the drop-down list or tap the ellipsis (...) button to open a new lookup dialog (which supports better sorting and filtering). If you enable '''Allow Create New''' in the question properties, users can create a new record from the questionnaire. "Automatic" means users can make the record directly from the drop-down list. "Manual" means that users have to use the lookup dialog.

[[File:Lookups-in-questionnaires1.png|300px]] [[File:Lookups-in-questionnaires2.png|300px]]

=== Images ===

Questionnaires may include images. Questionnaire Designer supports several image-type components in two main groups:
* static image and logo: these are added to the questionnaire at design time by the author of the questionnaire template
* dynamic images: images that the inspector can take when filling out the questionnaire

For each image, you can configure where it should be saved. Select an image-type component and on the '''Properties''' pane, configure the value of the '''Storage Entity''' property.
* Use annotation (or a different entity that supports binary attachments) if you want to save images directly in the database.
* Use one of the supported cloud document servers for storing images, such Google Drive or SharePoint. See [[Documents#Cloud_storage_for_questionnaire_images|Documents]] for more information. Cloud document storage requires a bit more effort to set up, but in general, cloud storage is cheaper than database space.

If you need to access questionnaire images on the database level, for example, when designing a [[sync filter]] or custom reports, consider the following information:
* In the annotation (or similar) entity, the Regarding/objectid field contains the reference to the questionnaire, and the Title/subject contains the reference to the question on which the image is saved.
* For the logo, the Title/subject equals "-resco_logo".
* See [[Mobile_reports_for_Resco_Inspections#Images_from_repeatable_groups|detailed instructions]] how to access images from repeatable groups.

==== Document roundtrip ====

If you add a default document to an image/media question in the Questionnaire Designer, you can use it in [[document roundtrip]] scenarios - when the inspector must edit the document during the inspection. The inspector can then tap the default document in the app, modify it in a third-party editor on the device, and save and close the editor; the modified document automatically replaces the default.

[[File:Add default document.png|alt=default document in image/media question type]]

=== Tagged image ===

The tagged image question allows the user to capture or select an image, and then drag tags onto the image. On devices that support augmented/virtual reality, such as [[HoloLens]], you can instead capture a holographic scene. In the questionnaire template, each tag is actually a question group. Users can add information to each tag. If the question groups are repeatable, the tag can be dragged to the image multiple times.

# Edit a questionnaire template.
# Go to the '''Components''' pane and add a '''Tagged Image''' to the template.
# Add one or more question groups to the template. For example, create repeatable groups called ''Person'' and ''Thing''.
# Add some questions to each group. For example, into the ''Person'' group, add a '''Text''' question called ''Name'' and a '''Whole Number''' question called ''Age''.
# Select the Tagged Image question created in step 2. On the '''Properties''' pane, check what Actions should be available: '''Capture Photo''' or '''Select Photo'''. By default, both are enabled.
# In the Allowed Groups selector under Tagged Image, select the question groups that you want to be available as tags, then click + button to add them.
# For each added group/tag, you can then:
#* Select the background color of your tag
#* Upload an icon that appears in the center of your tag.
#* Mark the tag as mandatory.

{{Note|In mobile reports generated in Resco mobile apps, tags are rendered correctly on the image. Reports generated from Dataverse (using [[Resco Reports connector]]) or from Resco web app (using [[Resco Cloud]] backend) include the image, but not the tags.}}

{{YT|IN_y4ZXSiRI}}

=== Button ===

This [[Questionnaire_Designer#Static_components|static component]] offers similar options as [[Questionnaire_Designer#Configuring_commands|questionnaire commands]]. Users tap the button to perform an action. The main difference is that buttons can be placed directly into the flow of the questionnaire.

When you add the button to your questionnaire:
# Enter a name.
# Optionally, provide descriptive text displayed above the button.
# Select the action that the button should perform.<br>[[File:Questionnaire button select action.png|alt=questionnaire button: select action|300px]]

;Tips: 
* Some actions allow you to enter additional parameters. For example, the '''Run mobile report''' action allows you to select the report to run.
* You can use styles to change how buttons are displayed in the app.
* You can define a custom action for the button using rules. For example, this simple rule toggles the visibility of question 3.<br>[[File:Questionnaire button simple rule.png|alt=custom action for the questionnaire button using rules]]
* The rule for a button applies only in the context of that button; i.e., you don't have to start with <code>If ChangedItem Equals myButton</code>.

=== Grid layout ===

Since [[Releases/Autumn_2021|release 14.2]], you have the option to display multiple questions in one row.
# Edit a questionnaire template.
# If you want to arrange questions in a group, select the group. Click the layout selector and select '''Grid layout'''.<br>[[File:Layout type for questions in a questionnaire.png|alt=Layout type for questions in a questionnaire|600px]]
# If you want to arrange top-level questions, click '''Options''' and on the '''User interface''' tab set '''Layout''' to '''Grid'''.
# In either case, click '''Edit''' or '''Edit grid''' to open the '''Edit Layout''' screen:
#* Use plus/delete buttons to add or remove rows and columns.
#* Select a row and configure its height (or use automatic height).
#* Select a column and configure its width. You can specify either an absolute value in pixels or a fraction. For example, if you have three columns with widths 100px / 1 fraction / 2 fractions, the first column will be 100 pixels wide, and the remaining space will be divided among columns 2 and 3, with the third being twice as wide as the second.
#* Select the fields (listed in the left pane) and drag them to the right spot.
#* Select a non-empty table cell to set up cell position, column span, and row span. 
[[File:Editing grid layout in questionnaires.png|alt=editing grid layout in questionnaires|600px]]

{{Note|
* After upgrading to release 14.2, you might need to [[Publishing app projects|republish your app project]] in Woodford before you can see questions in a grid layout in the app.
* Descriptions are not displayed when using grid layout, unless you switch to [[Questionnaire_Designer#Feature_Version|Feature Version]] 2 or later.
* Grid layout is '''not supported''' on the Windows desktop edition of Resco Mobile CRM.}}

=== Use optical character recognition (OCR) to answer questions ===

A regular maintenance visit, for example, inspecting a piece of machinery, can often be smooth if your questionnaire is well-designed and guides users through all the necessary steps. The process of registering a new piece of machinery into the database can be much more complicated and prone to errors. If the inspector has to read some details about a piece of machinery and enter them into the app... OCR comes to the rescue. Users can take a photo of the product label, let the device extract text from the image, and use the text as answers.

# Edit a questionnaire template.
# Go to '''Options''' and set '''Feature version''' to 3 or later.
# Select a question of the type "Text" or "Multiple Lines of Text".
# On the '''Properties''' pane, select '''Enable OCR'''.
# As '''OCR reference image''', do one of the following:
#* Select one of the existing images from the questionnaire template. The image answer will be used as an OCR source. This must be a single-image answer (Max Count=1).
#* Leave the field empty. Users can create or choose an image as usual, but the image won't be saved as part of the questionnaire.
# Save all changes.

In the app, OCR is available for Android, iOS, and Windows UWP editions of the app; both offline and online. The exact function and performance depend on the capability of the device's native OCR library. As usual, large and high-resolution images may take a while to process. Resco cannot guarantee the quality and/or performance of the OCR library.

The app displays the image with extracted text superimposed on it. Users can select which line of text from the image they want to save into a particular text field. They can edit the extracted phrase before storing it as the answer.

[[File:Questionnaires-ocr-in-action.png|300px|alt=using optical character recognition (ocr) to answer a question]] [[File:Questionnaire-with-ocr-function.png|300px|alt=a questionnaire with ocr features]]

== Scoring ==

Questionnaire scoring is a function that allows you to assign a score to each answer, and depending on the total score, you can quickly evaluate how a questionnaire was answered, for example, pass or fail.

# Enable scoring: Edit a questionnaire template, select '''Options''' from the toolbar, and on the '''Features''' tab, set '''Scoring''' to "On".
# For each question, set a score value.
#* For some questions, for example, text or image, you can assign a single score for answering the question.
#* For multiple-option questions, you can define a score for each option.
#* For numbers, you can define ranges and a score for each range.
# Optionally, scroll down to the end of the questionnaire template to the Questionnaire Result section and define labels to score ranges. Ranges can overlap; the first matching range is used as the questionnaire result.

The final score or the result is displayed for completed questionnaires in the app and also in the [[Results Viewer]].

=== Define score ranges for group results ===

Since [[Releases/Spring_2024#Define_score_ranges_for_group_results|release 17.1]], you can set question group results for each group. Define group score ranges and assign distinct labels for each range.
# Edit a questionnaire template and enable scoring as described above.
# Select a question group.
# In the '''Properties''' pane, enable '''Customize Results'''.
# At the end of the group, set up '''Question group results''': Define score ranges and assign labels.

[[File:Customize-score-ranges-for-group.png|600px|alt=customize score ranges for groups]]

== Editing rules ==

Rules describe sequences of steps that are executed when a user is filling out the questionnaire. These steps allow you to further customize the questionnaire form’s design and usage (hide or disable form fields, assign values to them, etc.). To create a rule, open the [[Rules editor]] by clicking on the corresponding event button.

* '''[[On Create]]''' rules are executed before a questionnaire instance is created.They can be used to populate variables for the reuse fetch. Requires [[Questionnaire_Designer#Rules_version|version 3]] (or later) of rules and [[Releases/Spring_2022|version 15.0]] (or later) of the mobile app.
* '''[[On Load]]''' rules are executed when the questionnaire form is displayed on the screen.
* '''[[On Change]]''' rules are executed whenever users change any value. <small>On Change rules are also executed when a questionnaire is first displayed.</small>
* '''[[On Save]]''' rules are executed when users attempt to save or complete a questionnaire. <small>Depends on the value of the [[Questionnaire_Designer#Validate|Validate On]] questionnaire property.</small>
* '''[[On Repeat]]''' rules are executed when a new instance of a repeatable group is displayed.
* '''[[On Delete]]''' rules are executed when an existing instance of a repeatable group is deleted.
* '''[[On Can Execute]]''' rules configure when a command is available.
* '''[[On Execute]]''' rules configure what happens when a command is executed.

In the rules editor, add rules and conditions using the toolbar to create your rule script.

; Steps group
* '''Step''' – Step is a specific action that can be defined within the condition branch or separately in the rule. Once it is a part of the condition branch, the step begins after its preceding condition is met. To move a step in the rule editor use arrows in the editing line. To delete it, use the delete button in the same line.
* '''Say text''' – When the rule condition is fulfilled, a message window with chosen text appears on the user’s screen. This button serves as a means of setting the message text.
* '''Scan Image''' – Allows you to initiate [[barcode scanning]] or [[image recognition]], resulting barcode or recognized image is saved to a string.
* '''Variable''' – define a variable that is added into the Property selector of the rule. This variable will be only used for the specified rule. Remember that you can only use this variable after the step where it was defined. To enter a variable into the workflow after defining it, just click elsewhere the variable editor. To delete it, click on the variable and choose the delete option in the editing line.
* '''Shared variable''' – add a variable that covers the entire questionnaire form

; Conditions group
* '''If''' – The first condition contains the label “If” and the condition string. The conditional branch consists of the condition and steps that are executed only when the condition is valid. Steps and variables are displayed in the “Then” or “Begin” section. All parts of the rule can be modified or re-ordered using the up and down arrows at the end of the editing line.
* '''Else''' – Using this option, otherwise branch of the condition will be added to the actual (selected) condition. The "Otherwise" part of the rule condition prevents the user from experiencing unexpected, incorrect behavior.
* '''Condition''' – adds another condition to the same if
* '''Group And''' / '''Group Or''' – select two or more conditions and choose whether all need to be met or only one of them
* '''Ungroup''' – Selected condition consisting of several conditions is divided into separate conditions

See [[Questionnaire Designer examples]] for a few sample rules.

=== Rules version ===

For each questionnaire, you can define the version of the rules used in the parameter '''Rules Version''' on the [[Questionnaire_Designer#Properties_pane|'''Properties''' pane]] on questionnaire level. This affects the execution of On Change rules.

* In '''version 1''', when a question is changed, all the OnChange rules are executed (the rules defined on root level and also for all groups).
* In '''version 2''', root rules are executed always. Group rules are executed if the question belongs to that group or depends on it. (The On Change rule depends on a question if it uses that question and that question is not a context question of that rule. Context questions of the rule are listed under the Questions property.)
* '''Version 3''' is the first version that supports On Create rules.
* '''Latest''' means that the questionnaire will always use the newest version of rules.

[[Resco mobile apps]] older than release 13.1 may experience instability when using rules version 2.

=== When a questionnaire is loaded ===
The following rules are executed when a questionnaire is loaded:

* For every question of the questionnaire, the On Change rules are executed.
** The IsLoaded property equals false.
** The ChangedItem property equals the name of the question.
:: (In version 1, if you had N questions and M groups, the On Change workflow was executed N*(M+1) times in the load phase. It is recommended to use IsLoaded property in On Change rules to speed up the loading process of the questionnaire.)

* The On Load rules for root level and group level are executed once.
** The IsLoaded property is set to true.

See [[On Load]] for a more information and few sample rules.

=== When a question is changed ===
The following rules are executed when a question is changed:
* The On Change rules are executed as described above.
* The ChangedItem property contains the name of the changed question
* If you have On Change rules both in the main questionnaire and in groups, the main script is executed first.

See [[On Change]] for more information and sample rules.

=== When a questionnaire is completed ===
* All On Save rules are executed.

See [[On Save]] for a more information and few sample rules.

=== When a repeatable group is repeated ===
The following rules are executed when a new instance of a repeatable group is created.
* On Change is executed for every question of the group (IsLoaded is set to false)
* On Load of the group is executed.
* On Repeat of the group is executed.

See [[On Repeat]] for a more information and few sample rules.

=== When a repeatable group is deleted ===
* On Change is executed for every question of the group
* On Delete of the group is executed

See [[On Delete]] for a more information and few sample rules.

=== Interaction with smart rules ===

Smart rules are a simplified version of the rules. The process of creating is simplified, however, under the hood, the classic rules are generated. These workflows are stored on a question and are combined at the execution time with On Change rules as follows:

* When the questionnaire loads and the scripts are initialized, the question's smart rules are appended just before the On Change rule. If the question is in a group, the smart rules are appended before the group's On Change rule; if not, the smart rules are appended before the root On Change rule. Group smart rules are always appended to the root On Change.
* The whole smart rule section of the group or root On Change is automatically placed under the condition IsLoaded == true. In this case, the same smart rules are not executed multiple times during the load phase. See section [[Questionnaire_Designer#When_a_questionnaire_is_loaded|When a questionnaire is loaded]].
* In a similar way, the smart rules are appended before the On Load rules and are executed exactly once when the questionnaire is loaded.

Advanced note: The smart value rule that sets the style and score is further encapsulated in the ChangedItem == questionname condition because only that question's value is used in its condition.

To summarize, the order of execution is as follows:
# smart rules of the questionnaire
# on change rules of the questionnaire
# smart rules of the first group
# on change rules of the first group
# smart rules of the second group
# on change rules of the second group
# etc.

=== Scoring in rules ===

With [[Questionnaire_Designer#Scoring|questionnaire scoring]], introduced in [[Release notes|release 13.1]], users can react on a change in a score or result in rules. If the score or the result of the questionnaire changes, the root On Change is executed and the ChangedItem is set to Score or Result.

=== Working with instances of repeatable groups ===

Use QuestionGroups variable to access a particular instance of a repeatable group. Or you can even work in all instances of a repeatable group in bulk.

* [[On_Execute#Expand_.2F_collapse_all_instances_of_a_repeatable_group|Expand / collapse all instances of a repeatable group]]
* [[On_Save#Example:_Check_all_instances_of_a_repeatable_group|Check all instances of a repeatable group when saving]]

== Editing styles ==

You can use hand-crafted styles to customize the design of your questionnaire. Styles apply to question blocks (combination of question and answer).

* To '''assign''' styles, select a question and then choose the style on the '''Properties''' pane. You can also change this assignment via rules.
* To '''modify''' or add new styles, click '''Styles''' to open the styles editor.

The designer comes with multiple predefined styles, grouped into two categories:
* '''Form Styles''' define how ow the question and answer appear in the app.
* '''Report Styles''' define how the question and answer appear in the report.

You can use the toolbar buttons '''Add''' or '''Clone''' to create new styles. Click '''Delete''' to remove styles.

In a style, you can define the format of the entire question block, including the question, answer, and description (supporting text).

[[File:Question-style-label-value-desc.png|alt=question description]]

See [[Style editor#Questionnaire Designer|Style editor]] for more information.

=== Report themes ===

The Questionnaire Designer comes with multiple pre-configured report themes. You can switch between themes using the '''Report Themes''' button in the toolbar. Switching to a different theme discards all your custom report styles and resets the built-in styles to the default settings.

== Localization ==

You can add multiple language mutations for your questionnaire templates. App users can answer the questionnaire in their language. In addition to the questionnaires, automatic reports are also localized (in the language of the app).

Take also [https://blog.resco.net/2020/10/21/questionnaire-localization-resco-inspections A closer look]. {{Badge|Blog}}

=== Adding a new language ===

# Click '''Localization'''.
# Click '''Add''' and select a language, then click '''OK'''. All localizable strings are displayed.
# Translate all the strings that you need. The following strings can be localized:
#* For a questionnaire, the name, description, and result.
#* For a question: label, description, on label, off label, option items, single-choice and multiple-choice strings
#* For a group: group name
#: '''Tip''': Click '''AI Translate''' to use the power of the AI to generate the translations for you.
#* You can also add custom strings, see [[Questionnaire_Designer#Localizing_custom_strings|here]].
# By default, the questionnaire is displayed in the language of the app (configured in [[Setup]]/Settings). If your app does not offer the language you need, Woodford administrator must enable the language in the organization; see [[localization]].   <br>Optionally, you can set '''Language Selection''' to '''Selected by User''' so that users can select from the full list of available questionnaire languages.
# Save everything and verify the result in the app.

[[File:Localization.png|alt=questionnaire localization|600px]]

If you want to have texts translated by a person without access to the questionnaire designer, you can export the localization to a file, have it translated, and import the result back.

=== Localizing custom strings ===

In addition to the texts for all the questions and options, you can also define custom strings that can be localized. You can then use these custom strings in rules, for example, to display a custom message to the user, or to modify the form caption (described in the example below).

# Edit a language and click '''Add custom string'''.
# As the name, enter the internal name of the string. As a label, enter the text in the default language. Optionally, you can format the string using curly braces, for example, <code>Hello, {0}.</code><br>[[File:Add-custom-string-for-localization.png|alt=localizing custom strings:img 1]]
# Click '''OK''' to save the string.
# Add the localized text, then save and close localization.
# Click '''On Load''' to add a new rule that changes the form caption to the localized string.<br>[[File:Custom string rule.png|alt=Localizing custom strings(questionnaire):img 2]]

== Configuring commands ==

You can configure commands available in the app when answering a questionnaire. This works similarly to [[Form commands]] in Woodford.

# Edit a questionnaire template.
# Click '''Edit''' to open the command configuration window.
# Move commands from the '''Available Commands''' pane to the '''Selected Commands''' pane.
# If a command has multiple options (like Run report), select it and click '''Properties''' to configure the available options.
# Click '''Save & Close'''.

{{Note|See also [[#Button|Buttons]], they can be used in similar scenarios as commands.|Tip}}

=== Available commands ===
* Save and close
* Save, close, and open new
* Complete and close
* Complete, close, and open new
* Complete with a report
* Run mobile report
* Cancel the questionnaire
* Clear answers
* View mobile report

You can also create custom commands. Use the rules On Execute and On Can Execute to make the command actually do anything, or you can define the action in a script attached to the questionnaire form.

=== Configure Run Report command ===

You can also configure the behavior of the '''Run Report''' command. For example, you can control which formats are available (PDF, Word, etc.). See [[Configure Run Report command]] for details.

== Mobile reports ==

[[Resco platform]] comes with a powerful reports function that allows app users to generate reports on their devices, even offline. See [[mobile report]] for more information about reporting in general.

In the case of questionnaires, you can automatically create a mobile report template that mirrors the structure of your questionnaire: start the [[Report Designer]] tool, create a new report for the questionnaire entity and select the appropriate questionnaire as your source.

App users have the option to ''complete questionnaires with a report'', or they can generate a report on demand.

See '''[[Mobile reports for Resco Inspections]]''' for a more detailed discussion of your reporting options in Resco Inspections.

== See also ==
* [[Resco Inspections]] - information about the solution
* [[Resco Inspections (app)]] - information about the dedicated mobile app
* [[Inspections]] - how to enable and configure Inspection features in [[Woodford]]
* [https://www.resco.net/blog/ai-chatgpt-integration-in-resco/ How AI can automate complex inspections summaries with Resco and ChatGPT] {{Badge|Blog}}




{{Feedback}}
[[Category:Resco Inspections]]
[[Category:Resco Cloud]]