Active Questionnaire

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 using the SurveyJS library.
  • The title of this parameter contains the version number of the installed SurveyJS library.
• 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 page of the questionnaire.
• 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 to add 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. The content of the Additional HTML widget parameter is processed and rendered.
3. The questionnaire is then constructed and rendered.
4. The user fills in the questionnaire and clicks on Complete on the last page.
5. The client-side validation that's built into the questionnaire is executed.
6. All answers and the Action JS Script widget parameter content are forwarded to the Polarion server.
7. The Action JS Script is executed.
8. 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 configuration of the questionnaire, 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 by using advanced settings and parameters described in the SurveyJS documentation. The documentation is available here: https://SurveyJS.io/Documentation/Library/?id=surveymodel.

One especially useful parameter is showCompletedPage: false. It forces the questionnaire not to display the final page with text so that it hides the whole questionnaire after successful completion. Using 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 status of the execution. (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. The JSON code that configures the rendered questionnaire can be fully or partially generated by Velocity. The context allows for access to all built-in objects (see section 10 of the Widget SDK for details) as well as 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 specific Polarion Enumerations or sets of Objects. Its full documentation 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 extension:

SECURITY_SERVICE_DISABLE=true

This completely disables the ISecurityService with all its methods for the active questionnaire extension.

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 ever missed in previous versions of the extension. Have a 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 text to pass the validation ",
      "validators": [
        {
          "type": "expression", "text": "Your text should contains 'survey' word.",
          "expression": "MyTextValidator({memo}) >= 0"
        }
      ]
    }
  ]
};

Content for Additional Survey Script:

function MyTextValidator(params)
{
  var 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 with access to multiple JS objects. The built-in JS objects are:

• trackerService - ITrackerService
• projectService - IProjectService
• scriptingUtil - ScriptingUtil
• engine - RhinoScriptEngine (or Nashorn/Graal depending on your Polarion version and server setup)
• context - SimpleScriptContext

The other JS objects added by the Active Questionnaire widget:

• objectFactory - ObjectFactory of the Rendering API
• actionContext - RichPageWidgetActionContext
• page - ProxyRichPage - shortcut for $actionContext.page()
• transaction - WriteTransaction - shortcut for $actionContext.transaction()
• surveyData - Contains a serialized version of the questionnaire's results. Further details are provided in the subsection below.
• errorMessage - Empty by default - Allows for the forwarding of an error message back 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 for the rendering of 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 results of the questionnaire 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();

 

$enumToJS Velocity Context Extension

The active questionnaire widget introduces the following three helper methods to work with Polarion enumerations and objects.

$enumToJS.getEnumerationAsJS(String enumId, String wiTypeId, String projectId);

Description

Provides the specified enumeration as JSON string for SurveyJS.

Parameters

• enumId: The enumeration ID.
• wiTypeId: The Work Item type ID. If the parameter is empty, the method looks for general enumerations (i.e., not specific to a certain Work Item type).
• projectId: The project ID. If the parameter is empty, the method looks for enumerations on the repository level.

Example

{
 type: "dropdown",
 name: "question_environment",
 title: "What environment will the Tool be validated on?",
 description: "(list of values generated from the enumeration Environment)",
 $enumToJS.getEnumerationAsJS("environment", "", $page.getReference().projectId())
}

$enumToJS.getEnumerationWithDependencyAsJS(String enumId, String wiTypeId, String projectId, String dependencyEnumId, String dependencyFieldId);

Description

Provides the specified enumeration including its dependency on the other enumeration as JSON string for SurveyJS.

Parameters

• enumId: The enumeration ID.
• wiTypeId: The Work Item type ID. If the parameter is empty, the method looks for general enumerations (i.e., not specific to a certain Work Item type).
• projectId: The project ID. If the parameter is empty, the method looks for enumerations on the repository level.
• dependencyEnumId: The enumeration ID, the enumeration depends on. If this enumeration does not exist or there is no dependency on it, the enumeration without dependency is returned.
• dependencyFieldId: The field ID/name in the SurveyJS JSON code of the other question this question depends on.

Example

{
 type: "dropdown",
 name: "question_environment",
 title: "What environment will the Tool be validated on?",
 description: "(list of values generated from the enumeration Environment)",
 $enumToJS.getEnumerationAsJS("environment", "", $page.getReference().projectId())
},
{
 type: "dropdown",
 name: "question_method",
 title: "What is the method of validation?",
 description: "(list of values generated from the enumeration Validation Methods)",
 $enumToJS.getEnumerationWithDependencyAsJS("validation_methods", "", $page.getReference().projectId(), "environment", "question_environment")
}

$enumToJS.getObjectsAsJS(String objectType, String query, int limit, String sort, boolean renderWorkItemIdInTitle);

Description

Provides the specified objects as JSON string for SurveyJS.

Parameters

• objectType: The object type name. Available values are Category, Document, Plan, Project, RichPage, TestRun, TimePoint, User, WikiPage, and WorkItem.
• query: The query to specify which objects to return. If empty, the method returns all Objects of a specific objectType in the repository.
• limit: The maximum amount of returned objects. If 0, it defaults to 200; Use -1 for an unlimited number of results. (Use with caution.)
• renderWorkItemIdInTitle: Active only for objectType = "WorkItem"; Switches between two modes of enumeration option title rendering.

Example

{
 type: "dropdown",
 name: "question_automates_system",
 title: "Which system will be used to automate?",
 description: "(list of values generated from a set of Work Items of type QSR Requirement Topic)",
 $enumToJS.getObjectsAsJS("WorkItem", "project.id:$page.getReference().projectId() AND type:qsrtopic", -1, "title", false)
}

 

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 extension is loaded. The files will need to have the names survey.jquery.min.js and survey.min.css.
• Go to the Extension'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.