Community
Thumb_icon

Active Questionnaire

 This widget renders a custom questionnaire and runs any JavaScript code on the server.

Description

This widget can be used to configure a custom questionnaire, get the results, and use them in a JavaScript code executed on the server.

 

Widget Parameters Overview

Scripts

  • Questionnaire Definition - Contains the JS definition of the questionnaire as JSON String using the SurveyJS library.
    • The title of this parameter contains the version number of the installed SurveyJS library.
  • Questionnaire Data - Contains the optional default values of the questionnaire as JSON string.
  • Additional Survey Script - Contains additional script that should be executed in the survey itself like functions for custom actions.
  • Action JS Script - Contains the JS script that runs on the server after completing the questionnaire.


Advanced

  • Progress Bar - Allows displaying a Progress Bar on the Top/Bottom of each questionnaire page.
  • Announce Successful Action Script Execution - Controls whether an information message is displayed after the successful execution of the Action Script.
  • Additional HTML - This HTML code is injected before the questionnaire itself. It allows an addition of HTML content, the ability to override the CSS styles, etc...

 

How This Widget Works

  1. The widget's configuration is loaded from the Questionnaire Definition widget parameter.
  2. If specified, the default values for the questionnaire are loaded from the Questionnaire Data widget parameter.
  3. The content of the Additional HTML widget parameter is processed and rendered.
  4. The questionnaire is then constructed and rendered.
  5. The user fills in the questionnaire and clicks Complete on the last page.
  6. The client-side validation that's built into the questionnaire is executed.
  7. All answers and the Action JS Script widget parameter content are forwarded to the Polarion server.
  8. The Action JS Script is executed.
  9. Information about the script execution result is then returned to the client and rendered.

Since the questionnaire uses the SurveyJS library, it can be easily configured using a simple online editor at https://SurveyJS.io/create-free-survey. The last section of this description explains how the library can be updated. When done with the design and the questionnaire configuration, switch to the JSON Editor tab and copy all the code into the Questionnaire Definition widget parameter.

The final JS configuration code can be improved using advanced settings and parameters described in the SurveyJS documentation. The documentation is available here: https://SurveyJS.io/Documentation/Library/?id=surveymodel.

One handy parameter is showCompletedPage: false. It forces the questionnaire not to display the final page with text to hide the whole questionnaire after successful completion. This option is recommended because it follows the use case criteria of a questionnaire on a Polarion LiveReport page. Another reason to use this parameter is that after the Action JS Script is executed on the server, the widget always renders info about the execution status. (You do not need the built-in final page.)

Example:

{
  "pages": [
    {
      "name": "The Only Page",
      "elements": [
        {
          "type": "text",
          "name": "the_only_question",
          "title": "The only question in this form."
        }
      ]
    }
  ],
  "showCompletedPage": false
}

More examples of the questionnaire's configuration can be found here: https://surveyjs.io/form-library/examples/nps-question/jquery.

 

How to Install This Widget

  1. Download and unzip the packaged extension.
  2. Move folder binary/com.polarion.alm.activequestionnaire from the zip file com.polarion.alm.activequestionnaire_<version>.zip into: <Polarion Installation Folder>/polarion/extensions/.
  3. Remove folder <Polarion Installation Folder>/data/workspace/.config.
  4. Restart Polarion.

 

Detailed Parameters Description

Questionnaire Definition

In the widget properties, you find the version number of the currently loaded SurveyJS library behind the name of this parameter.

This widget parameter supports the usage of Velocity scripting. Velocity can fully or partially generate the JSON code that configures the rendered questionnaire. The context allows access to all built-in objects (see section 10 of the Widget SDK for details) and all other custom Velocity Context plugins deployed on the Polarion instance.

The context also allows for access to other objects added by the Active Questionnaire widget:

  • $actionContext - RichPageWidgetRenderingContext of the widget
  • $page - RichPage - shortcut for $actionContext.page()
  • $enumToJS - A helper class that generates JSON code from Polarion Enumerations or sets of Objects. An overview is provided in a separate section below.
  • $fieldToJS - A helper class that generates JSON code from Polarion Object fields. An overview is provided in a separate section below.


For Polarion versions up to 22 R2 (3.22.2), it is theoretically possible that users who can edit the configuration of this widget can elevate their permissions by using methods doAsSystemUser(...) or doAsUser(...) of ISecurityService. To prevent this, administrators can set the following widget configuration property in the config.properties file in the webapp folder of the widget:

SECURITY_SERVICE_DISABLE=true

This property completely disables the ISecurityService with all its methods for the Active Questionnaire widget.

Questionnaire Data

Optionally, you can also define default values already entered into the questionnaire when loaded. For basic question types like text, comment, dropdown, tagbox, date, etc., defining the default value in the Questionnaire Definition is sufficient. However, for matrixdynamic or paneldynamic, it's necessary to add the default values to the data element of the survey object.

The content for the data element can be provided with this widget parameter in the form of a JSON string. The JSON string can be generated using the same Velocity Context as in the Questionnaire Definition (e.g., get the data from an existing work item using a URL parameter for the LiveReport page). This widget parameter will replace any default values specified in the Questionnaire Definition.

For the above example, the JSON string could look like this:

{
  "the_only_question": "The only true answer."
}

For a questionnaire containing a paneldynamic, the JSON string could look like this:

{
  "the_only_question": "The only true answer.",
  "the_panel": [
    {
      "panel_question_1": "question 1",
      "panel_question_2": "question 2"
    },
    {
      "panel_question_1": "again question 1",
      "panel_question_2": "again question 2"
    }
  ]
}

Additional Survey Script

This widget parameter supports the usage of survey scripting. You can register your function for the survey Instance. So, you can build in any fancy thing you missed in previous widget versions. Look at the example library https://surveyjs.io/Examples/Library to see what is now possible.

Example: Custom Validator

Content for Questionnaire Definition:

{
  "elements": [
    {
      "type": "comment",
      "name": "memo",
      "isRequired": true,
      "title": "Type here the text to pass to the validation.",
      "validators": [
        {
          "type": "expression",
          "text": "Your text needs to contain the word 'survey'.",
          "expression": "MyTextValidator({memo}) >= 0"
        }
      ]
    }
  ]
}

Content for Additional Survey Script:

function MyTextValidator(params)
{
  let value = params[0];
  return value.indexOf("survey");
}
// Register the function for use in SurveyJS expressions
Survey
  .FunctionFactory
  .Instance
  .register("MyTextValidator", MyTextValidator);

Action JS Script

This widget parameter also supports the usage of Velocity scripting. For more details and the content of the Velocity Context, see the Questionnaire Definition widget parameter description above.

Additionally, because the script from this widget parameter is run on the server, it also contains a JavaScript context. The JavaScript context allows access to all built-in Velocity objects (e.g., transaction - WriteTransaction, trackerService - ITrackerService, projectService - IProjectService, objectFactory - ObjectFactory of the Rendering API; see section 10 of the Widget SDK for details) and all other custom Velocity Context plugins deployed on the Polarion instance. For compatibility reasons with JavaScript, hyphens in the names are replaced with underscores.

The other JS objects added by the Active Questionnaire widget:

  • scriptingUtil - ScriptingUtil
  • engine - Graal ScriptEngine (or Rhino/Nashorn, depending on your Polarion version and server setup)
  • context - SimpleScriptContext
  • actionContext - RichPageWidgetActionContext
  • page - RichPage (Rendering API) - shortcut for $actionContext.page()
  • jsHelper - A helper class for regular activities when processing the questionnaire (see JavaScript Context Extension section below).
  • surveyData - Contains a serialized version of the questionnaire's results. Further details are provided in the subsection below.
  • errorMessage - Empty by default - Allows to forward an error message to the client. Enables server-side validation. If empty, the client does not throw an error. If not empty, it fails the completion process of the questionnaire and returns the message.
  • otherJS - Empty by default. The widget uses the context.executeJavaScript() method at the end of the JavaScript execution to return information about the status of the execution process. Setting a string value to this variable allows for the additional execution of any JavaScript code on the client after the execution of the JavaScript finishes.
  • survey – The execution of JS code on a client gives you access to the original survey JS object created at the time the questionnaire was first rendered on the Live Report page. It contains all the questionnaire data, its results, etc. - See the SurveyJS documentation for details. It also contains two variables added by the Active Questionnaire widget:
    • surveyResultId - Contains the ID of the <div> element used for rendering the result of the questionnaire's Action JS Script execution.
    • surveyDivId - Contains the ID of the <div> element used for rendering the questionnaire itself.


Example 1: Uses the questionnaire's <div> element to display additional information upon the script's successful execution.

var text = actionContext.getClass().toString();

Example 2: Executes JS on the client and displays an alert window with the ID of the <div> element used to render the JavaScript execution result.

otherJS = "window.alert(survey.getVariable('surveyResultId'))";

Example 3: Accesses the answer to the questionnaire's question with ID the_only_question and displays it as a window alert on the client.

otherJS = "window.alert('" + surveyData.getAsJsonObject().get('the_only_question').getAsString() + "')";

surveyData Documentation

The content of surveyData is created by calling JSON.stringify() upon the JavaScript object with the questionnaire results and then forwarded as a String to the Polarion server. Next, the results are parsed, and a JsonElement object surveyData is created. Specific values can be accessed with the getAsJsonObject() method and then used in the executed Action JS Script.

Example A: Get the Answer to "The Only Question"

surveyData.getAsJsonObject().get('the_only_question').getAsString()

Example B: Use answers to several questions to set up a new Work Item of the type Tool.

var projectId = page.getReference().projectId();
var project = trackerService.getProjectsService().getProject(projectId);
var typeEnum = trackerService.getDataService().getEnumerationForKey("WorkItem", "type", project.getContextId());
var enumOptT = typeEnum.wrapOption("tool");
var wiTool = trackerService.createWorkItem(project);
var toolTitle = surveyData.getAsJsonObject().get('question_title').getAsString().trim();
wiTool.setType(enumOptT);
wiTool.setTitle(toolTitle);
wiTool.setValue("version", surveyData.getAsJsonObject().get('question_version').getAsString());
wiTool.setValue("questionnaire", surveyData.toString());
wiTool.setEnumerationValue("environment", surveyData.getAsJsonObject().get('question_environment').getAsString());

Example C: Get the first of several answers to a question.

surveyData.getAsJsonObject().get('question_select_three_options').getAsJsonArray().iterator().next().getAsString();

 

Velocity Context Extension

The Active Questionnaire widget introduces the following helper methods.

$enumToJS

The following methods retrieve enumerations or objects from Polarion to create the enumeration values for a dropdown list.

String $enumToJS.getEnumerationAsJS(String enumId, String wiTypeId, String projectId);
String $enumToJS.getEnumerationWithDependencyAsJS(String enumId, String wiTypeId, String projectId, String dependencyEnumId, String dependencyFieldId);
String $enumToJS.getObjectsAsJS(String objectType, String query, int limit, String sort, boolean renderWorkItemIdInTitle);

$fieldToJS

The following methods convert the field values in the JSON format for SurveyJS to be used as default values.

String $fieldToJS.getStringFieldAsJS(@Nullable String string)
String $fieldToJS.getTextFieldAsJS(@Nullable Text text)
String $fieldToJS.getEnumFieldAsJS(@Nullable IEnumOption enumOption)
String $fieldToJS.getMultiEnumFieldAsJS(@Nullable CustomTypedList list)
String $fieldToJS.getDateTimeFieldAsJS(@Nullable Date date)
String $fieldToJS.getDateFieldAsJS(@Nullable DateOnly dateOnly)
String $fieldToJS.getTimeFieldAsJS(@Nullable TimeOnly time)
String $fieldToJS.getBooleanFieldAsJS(@Nullable Boolean bool)
String $fieldToJS.getIntegerFieldAsJS(Integer number)
String $fieldToJS.getFloatFieldAsJS(@Nullable Float number, int decimals)
String $fieldToJS.getCurrencyFieldAsJS(@Nullable Currency currency, int decimals)
String $fieldToJS.getLinkedWorkItemsAsJS(@Nullable Collection linkedWorkItemsStruct, @Nullable Collection workItemTypeIds, @Nullable Collection linkRoleIds, boolean onlyWorkItemId)

The documentation shipped with this extension provides a detailed description and some examples.

 

JavaScript Context Extension

The Active Questionnaire widget introduces the following methods to the actionJS JavaScript context.

InputStream jsHelper.getInputStreamFromBase64(String base64String)
Date jsHelper.getDateFromDateString(String dateString)
Date jsHelper.getDateFromDateTimeString(String dateTimeString)
String jsHelper.getRTEHyperlink(IWorkItem workItem, String projectId, boolean withTitle)
String jsHelper.getRTEHyperlink(IWorkItem workItem, String revision, String projectId, boolean withTitle)
String jsHelper.getRTEHyperlink(ITestRun testRun, String projectId, boolean withTitle)
String jsHelper.getRTEHyperlink(ITestRun testRun, String revision, String projectId, boolean withTitle)
String jsHelper.getRTEHyperlink(IModule module, String projectId)
String jsHelper.getRTEHyperlink(IModule module, String revision, String projectId)
String jsHelper.getAttachmentHyperlink(IAttachment attachment)
List<IWorkItem> jsHelper.getWorkItemsFromHyperlinksInHtml(String content, String currentProjectId)
String jsHelper.getEnumeration(String enumId, String wiTypeId, String projectId)
String jsHelper.getTypeFactory()

The documentation shipped with this extension provides a detailed description and some examples.

 

How to Update the SurveyJS library

  • Get the desired version of SurveyJS for jQuery (e.g. from https://cdnjs.com/libraries/survey-jquery). You should get the min versions to reduce the amount of data transmitted each time the widget is loaded. The files will need to have the names survey.jquery.min.js and survey.min.css.
  • Go to the widget's location on the Polarion Server (e.g. [Polarion Root]/polarion/extensions/com.polarion.alm.custom.activequestionnaire/eclipse/
    plugins/com.polarion.alm.custom.activequestionnaire_1.X.X/webapp/survey-jquery
    ) and update the two files in the folder.

 

What's New in Version 1.8.0

Updated August 2024

1.6.0 - 1.8.0
Kevin Schmiechen (TUM-FSD)
- Added getTypeFactory() method to JS context
- Added getEnumeration(enumId, wiTypeId, projectId) method to JS context
- Added all Velocity Context extensions (OOTB and custom) to the JS context

1.4.1 - 1.6.0
Kevin Schmiechen (TUM-FSD)
- Added getLinkedWorkItemsAsJS(...) method to the $fieldToJs Velocity context
- Added getRTEHyperlink(...) methods respecting object revision to JS context
- Added getAttachmentHyperlink(...) method to JS context
- Added getWorkItemsFromHyperlinksInHtml(...) method to JS context
- Fixed the order of JavaScript code to make sure the survey object is now available in the additional survey script
- Updated SurveyJs library from version 1.9.127 to 1.9.139

1.4.0 - 1.4.1
Kevin Schmiechen (TUM-FSD)
- Changed the return value of $fieldToJS.getTextFieldAsJS() to a correctly escaped String instead of an array for conformity with SurveyJS behavior

1.3.0 - 1.4.0
Kevin Schmiechen (TUM-FSD)
- Added $fieldToJS helper class to the Velocity Context to convert Polarion field values into the JSON format for SurveyJS
- Added jsHelper class to the JS context to help with file uploads, date conversion and create RichText Editor-like hyperlinks to Work Items, Documents, and Test Runs
- Refactored inputStreamHelper.createFromBase64(String base64String) to jsHelper.getInputStreamFromBase64(String base64String) Use find/replace in your Action JS Script when you have used this method from 1.3.0
- Added the Questionnaire Data widget parameter to inject default values into the questions - check out the updated documentation (THX to Jochen Bärthlein from Siemens PLM for his contribution)
- Updated SurveyJS library from version 1.9.117 to 1.9.127
- Moved the documentation of the jsHelper, $fieldToJS, and $enumToJS classes into a JavaDoc
- Added a readme.md file to the installation package containing the installation instructions and code examples for the Velocity and JavaScript Context helper classes

1.2.2 - 1.3.0
Kevin Schmiechen (TUM-FSD)
- Added InputStream inputStreamHelper.createFromBase64(String base64String) to the actionJS JavaScript Context to handle file uploads
- Updated included SurveyJS libraries from 1.9.55 to v1.9.117

1.2.1 - 1.2.2
Kevin Schmiechen (TUM-FSD)
- Special characters / \ ' " are now escaped in the enumerations and object names

1.1.2 - 1.2.1
Kevin Schmiechen (TUM-FSD) & Matthias Bittner (eRC-System GmbH)
- Added method $enumToJS.getEnumerationWithDependencyAsJS that provides a specified enumeration including its dependency to the other enumeration as JSON string for SurveyJS
Jochen Bärthlein (Siemens PLM)
- Added support for custom JavaScript code - register functions for advanced questionnaire functionality
- Added com.polarion.alm.shared.api.utils.velocity.ObjectFactory to ActionJS context
Kevin Schmiechen (TUM-FSD)
- Updated the included SurveyJS library to v1.9.55 - the currently installed version is now displayed in the widget parameter settings
- Added support for manual updating of the SurveyJS library (direct server access required)
- Added configuration property to optionally disable com.polarion.platform.security.ISecurityService from the extensions Velocity Context to prevent permission elevation of users
- Polarion color scheme adaptation is now applied in the extension and not hard coded in the SurveyJS library anymore
- Revised widget documentation/description
- The code was completely refactored for better maintainability
- Solved backward compatibility issues

1.1.1 - 1.1.2
- Fixed compatibility with log4j 2.*

1.0.5 - 1.1.1
- Updated surveyJS Library to version 1.8.75
- Added the testManagementService to actionsJs context

1.0.4 - 1.0.5
- Minor improvements and defect fixes

 

Information

Vendor Siemens PLM
Published Version 1.8.0 - August 2024
Categories
Price Free
1470 Downloads
Community Supported Extension This extension is not supported by Siemens PLM.
Requirements Access to the server's file system
Polarion 20 R1 (3.20.1) and later

Last tested with Polarion 2404 (3.24.4)

Related Extensions