For the task of ...

I need to ...

Linking Questionnaires to another Component

Questionnaires are stored in a dedicated component - named "Questionnaire".

• In Component Management, select the Component which needs to be linked to Questionnaires (for example: Audits, Inspections or Take 5)
• Add a 1:1 relationship to the "Questionnaire" component.
  IMPORTANT: you cannot use any other relationship type for this purpose.
• Also, answer the question "Delete [RELATED component record(s) when [THIS component] record(s) are deleted" with YES.

Adding the Questionnaire interface to a Form

• Open the target form in the Form Designer tool.
• At the intended position for the questionnaire, add a row with a single column.
• Drag and drop the relationship to the Questionnaire component created in the previous step onto the form.
• The system will automatically apply the correct input type of a Questionnaire Field.
• Enter the field properties as required.
• Optional: Keyword
• Optional: Related Record
  This option allows a subform (related records) to be linked to individual questions in a Questionnaire.
  If you want to use this option, you must have the subform which is representing this relationship on the form which is containing the Questionnaire.
  Please read "Creation of related records from within a Questionnaire" for further details.

Defining Keyword Filters to ensure users only see relevant Questionnaires

Keywords are used to filter the list of available Questionnaire templates to show only those with a matching keyword.

If you leave the keyword field empty, all active templates will be available in the selection list.

There are three ways to configure Keyword filters:

• using a 'static' Keyword, which will always be used to find any matching Questionnaire templates.
• nominate a specific field (text, lookup, or component lookup) on the form, and the system will show any templates whose keywords match any of the text found in the nominated field.
  In the case of component lookup fields, the system will match on any of the text shown in the component lookup list view.
• defining 'conditional' Keywords': you can define multiple Conditions, and the system will retrieve the templates that match the keywords whose conditions evaluate to "true".

If you define a 'static' AND 'field'/'conditional' keywords, then the system will retrieve all templates matching the static keyword, PLUS those which may match any of the conditions.

To default the Questionnaire to a Questionnaire template, enter the matching keyword which is defined in the template. Make sure that there is only one template with this keyword.

This will ensure that the Questionnaire will be defaulted to this template when a user creates a new record.

Having separate fields for

• selecting the Questionnaire Template
• and the Questionnaire field itself (for example on a different page).

For circumstances when it is necessary to separate the Template Picker from the Questionnaire itself, follow these steps:

• In the Component Management tool, add a TEXT field to the Component which is linked to the Questionnaire (for example: Audit).
• In the Form Designer, go to Form Elements, and drag the Element "Questionnaire Template Select" to the desired position.
• Now drag this new text field onto the Form Element.
• If required, apply Keywords (see above).
• To populate the actual Questionnaire Field with the selected template, it will be necessary to make use of Analytics Rules.

Saving and publishing the changes

To make the changes available to users, perform a publish and restart Tomcat.

NOTES

• Do not use the Questionnaire component as the root component for either a Form, or List view.
• Fields from the Questionnaire component (such as Overall Score) may be used within the form for
  - page visibility and
  - action conditions.
• They can be placed on a page - but in such cases need to be set as Read Only.
• Apply Dynamic Row Visibility on the row containing the Questionnaire field is not recommended as the Questionnaire data cannot be cleared if the row is hidden.

IMPORTANT:

A predefined Excel spreadsheet is provided to configure Questionnaire Templates.

The predefined Excel spreadsheet can be downloaded from the Questionnaire Templates form in the Admin menu.

It is essential that the structure of this spreadsheet is not modified, since the process used to import these files relies on the defined format.

You must also adhere to these rules:

• There must be an empty row between the last question of a Section and the header of the following Section.
• If you use slashes ('/') for any of the Names for Answer Values, you must include a space before and after the slash. For example: Yes / No.

For the task of ...

I need to ...

Defining and grouping Lookup Answer values for a questionnaire.

These answer values can be displayed in the web application as:

• Radio Buttons
• Dropdowns

Please note:
The display format in Roam is fixed and cannot be influenced by this selection.

• In the Lookup Answer Values sheet, build a list of Answer Values (similar to lookup items) and group them logically (similar to lookups).
• Define a Score for each of these values.

It is important that you define a unique "name" for each of these collections, so they can be easily distinguished and selected when building the Questionnaire Template.

For example:

Defining Numeric Answers.

These answers will be displayed as a

• Number Field

Define ranges in the sheet Number Answer Values.

Each range consists of a Name, Min Value, Max Value and Decimal Places.

For example:

In the web application, users will only be able to enter a number within the given range.

The Score of the answer will be identical to the selected value.

Please see above for the process to Enabling Comments.

Defining a Yes/No, True/False Answer (boolean answer).

These answers will be displayed in the web application as a

• Checkbox

Please note:
The display for checkboxes in Roam devices will be in the form of two panels.

Checkboxes can only be used for boolean type answers.

For example:

The Score will be calculated as follows:

• When checked: 1
• When unchecked: 0

Enabling Comments for Answers

For each Value, it is possible to define

• if a comment field is displayed or not. This is done by a flag for "Show Comments", with the options being:
  - Always: the comment field will be shown once an answer has been selected.
  - Optional: this will display a symbol next the answer, and a user can select to enter a comment.
  - [blank]: if the "Show Comments" field is left empty, no comment can be entered.
• an explanatory label for this comment field.

Mapping the resulting score to an Outcome.

When the Questionnaire is answered, the system will calculate the total score for

• each Section
• the complete Questionnaire

These 'numerical' values can be mapped to an outcome in two different ways:

• Percentage:
  - for example: When the score reaches 80% or more of the total score, then the outcome is Compliant.
  - to use Percentage, the values in the column Equal or Over need to be entered in the format 'x%'.
  - these mapping are very generic, and can be applied to anywhere, regardless of the total maximum score.
  
• Score:
  - for example: When the total score is 8 points or more, then the outcome is Compliant.
  - to use Score, just enter the target number
  - these mappings are very specific, since they need to match the section or Questionnaire.

To visually highlight the outcome in the web application, it is also possible to

• define in which format the results are displayed:
  - Percent only: e.g. 80%
  - Score only: e.g. 4/5
  - Both: in the web application, the system will display percents (e.g. 80%),and score will be shown via mouse-over (e.g. 4/5). For Roam devices, the display will be for example 80% - 4/5
• color code each outcome,
• and/or display an indicator (tick or cross)

To define these settings, use the sheet Result Mappings.

For example:

The above would translate to the following example:

• if the score is between 25 and 39, the value is 'Avg. Supplier'
• if the score is between 40 and 59, the value is ' Good Supplier'

NOTE:
Result Mapping will use the 'weighted score' for a Section, or for the Questionnaire.

Branching a Questionnaire

You can configure basic Branching of Sections, or individual Questions - i.e. Sections or Questions can be shown or hidden, depending on the Answer given to a previous Question.

• The controlling Question must be either a Lookup or a Checkbox.
  To control a Section or a Question, enter the following:
• Controlling Section: enter the Section ID of the controlling Question
• Controlling Question: enter the Question ID of controlling Question
• Branch Answer: enter the value required in the controlling field to reveal the controlled Section/Question:
  - for Lookups: enter the lookup value - e.g. Very High
  - for Checkboxes: enter Checked or Unchecked

Completing the Questionnaire Template in Excel

When completing the questionnaire template, it is important to adhere to the following rules:

For the QUESTIONNAIRE define:

• Questionnaire Name [255 char max]: after importing a Questionnaire into the application, this is the name which will be used to list and select Questionnaires (not the file name of the spreadsheet itself).
• Result Mapping: select from a lookup list of existing entries (which have been defined in the sheet Result Mappings)
• Show Result: user selects from a lookup, with the options of:
  - Show: the web application will display the score in the questionnaire.
  - Hide: the scores will be hidden in the web application.
• Keyword: the keyword can be used to limit the selection of available Questionnaires for the end user within a form . This needs to be also defined in the Questionnaire's Field Properties.
  Only ONE keyword can be entered.

For each SECTION define:

• Number: can be alpha-numeric (e.g. Sec-001, Sec-002)
  The numbers do not have to be unique.
• Section Name [1,000 char max]: enter the name for this section
• Result Mapping: user selects from a lookup list of existing entries (which have been defined in the sheet Result Mappings)
• Weighting: define how much Weight this section has compared to other sections in this Questionnaire.
• Branching (optional): to implement branching for a section, enter the Controlling Section/Question and the Branch Answer (see above for details).

For each QUESTION define:

• Number: can be alpha-numeric (e.g. Q1, Q2).
  The numbers do not have to be unique.
• Question Text [1,000 char max]: enter the question the user needs to answer
• Answer Type: from a lookup list, select how a user can answer this question. The options are:
  - Checkbox (A)
  - Date
  - Dropdown (A)
  - Label
  - Number (A)
  - Radio (A)
  - Text
• Branching (optional): to implement branching for a section, enter the Controlling Section/Question and the Branch Answer (see above for details).

Only if the Answer Type is category A):

• Answer Value: user selects from a list of the corresponding Answer Values.
• Default: you can default answers as follows:
  - Checkbox: please use 1 (for true) or 0 (for false).
  - Date: enter a date.
  - Dropdown, Radio: manually enter one of the values from the selected list of answer values.
  - Label: cannot be defaulted
  - Number: enter a number (must be within the MIN and MAX limits)
  - Text: any text (with less than 255 characters)
• Weighting: define how much Weight this Question has compared to other sections in this Section.
• Attachment:
  you can either Allow or Disallow users to attach an image to a question.
  If left blank, the system will default to Disallow.
  - In the web application, this will enable users to select existing files.
  - In Roam, this will enable users to either take or select photos from their mobile device.
  - These attachments can exclusively be viewed using the Questionnaire interface.
• Marking as N/A: if a Section or Question can be marked as "N/A" by a user, then you select "Allow". Otherwise, use "Disallow". If left blank, the system will default to Disallow.
  Please refer to the next section for information about how "N/A" is handled in the web application.
• Related Records: you can either "Allow" or "Disallow" if a user can create a related record for another component (for example, an "Action") directly from a question. If left blank, the system will default to disallow.
  For this to work, additional configuration steps may be required.

For the QUESTIONNAIRE, any SECTION, and any QUESTION, you can define:

• Information Text [500 char max]: this will display an icon, which will show the Information Text as a tool-tip when hovering with the mouse over the icon.
• Information Link [1000 char max]: this will display an icon, which will take the user to the defined link when clicking on the icon.

You can define Information Texts and Links in any combination.

NOTES:

• For the upload to be successful, the questionnaire templates must adhere to the prescribed format.
• The content and format of a Questionnaire template will only be determined when it is created from its template.
  Subsequent changes to a template will have no effect on any questionnaires which had been based on a previous version of a questionnaire template.

For the task of ...

I need to ...

Creating a Questionnaire Template in the Database by uploading the completed Excel Spreadsheet.

Uploading a completed Excel spreadsheet into the application is an Administrative Task, which requires these steps:

• Navigate to Main Menu Admin Questionnaire, and select New.
• Select the Excel Template in the field File Upload, and then Save.
• The system will load the file into the database. The import process will perform a range of format checks, and if any issues are discovered the system will list them in the Error Log.
• The name of the Questionnaire Template within the application will be determined by the field Questionnaire Name in the spreadsheet, rather than by the file name.

Making a Questionnaire Template available in the application, so that users can select it for filling a questionnaire.

Before a template can be used in the web application, it must be marked as Enabled.

• Only if this flag is selected will users be able to use this template for new records.
• Disabling a previously enabled Questionnaire Template will NOT affect any Questionnaires which have been created using this template. The only effect of disabling a Questionnaire Template is that it no longer will be available for new Questionnaires.

Updating an Existing Questionnaire Template.

Existing Templates can be changed by:

• Navigate to Main Menu Admin Questionnaire,
• Select the Questionnaire Template which needs to be modified and Edit it.
• Select Download Template to retrieve the Excel spreadsheet for the current template.
• Using Excel, edit the spreadsheet as required, and save the changes.
• Back in the web application, select the Excel Template in the field File Upload, and then Save.
• The system will load the file into the database. The import process will perform a range of format checks, and if any issues are discovered the system will list them in the Error Log.
• The name of the Questionnaire Template is determined by the field Questionnaire Name in the spreadsheet, rather than by the file name. I.e. if the Questionnaire Name of the modified version is different from the original, then the system will REPLACE/UPDATE this name.

NOTE:
This process describes how a Questionnaire Template can be translated. If you need to translate other configuration types/items (e.g. Menus, Dashboards) you will need to follow the Language export/import process.