Unsupported
Thumb_icon

Active Questionnaire

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

Description

share this page via facebook share this page via LinkedIn share this page via Twitter share this page via Google+ share this page via email More sharing services

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

 

Parameters

  • Scripts
    • Questionnaire Definition - Contains the JS definition of the questionnaire using the SURVEYJS library.
    • Action JS Script - Contains the JS script that is run on the server after completing the questionnaire.
  • Advanced
    • Progress Bar - Allows to display 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 for the 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. 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 at the last page.
  5. The client side validation that's built into the questionnaire is executed.
  6. All answers and the content of the Action JS Script widget parameter are forwarded to the core.
  7. The Action JS Script is executed.
  8. Information about the script execution result is then returned to the client and rendered.

 

How to Install

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

 

Available Features and Context Contents

The Questionnaire

  • Since the questionnaire uses the SURVEYJS library, it can be easily configured using a simple online editor on page https://surveyjs.io/Editor/Editor/.
    • 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.
  • 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 a 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/Examples/Library/.

Questionnaire Definition

  • This widget parameter supports the usage of Velocity scripting.
    • The Java Script code that configures the rendered questionnaire can be fully or partially generated by Velocity.
    • Available objects:
      • The context allows for access to all built-in objects. (See part 8 of the Widget SDK for details.)
        • $transaction - ReadOnlyTransaction
        • $localization - SharedLocalization
        • $me - Current user ID
        • $objectFactory - ObjectFactory
        • $trackerService - ITrackerService
        • $projectService - IProjectService
        • $securityService - ISecurityService
        • $platformService - IPlatformService
        • $testManagementService - ITestManagementService
      • 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 JS code for a specific question's list of values as enumeration options, from the specific Enumerations or sets of Objects.
          • Has two methods:
            • getEnumerationAsJS(String enumId, String wiType, String projectId);
              • wiType - If empty, the method looks for general Enumerations.
              • projectId - If empty, the method looks for Enumerations on the repository level.
              • Example:
                $enumToJS.getEnumerationAsJS("environment", "", "TestProject")
            • getObjectsAsJS(String objectType, String query, Integer limit, String sort, Boolean renderWorkItemIdInTitle);
              • objectType - Available values are: Category, Document, Plan, Project, RichPage, TestRun, TimePoint, User, WikiPage and WorkItem.
              • query - If empty, the method returns all Objects of a specific objectType in the repository.
              • limit - If specified, it limits the number of results; 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:
                $enumToJS.getObjectsAsJS("WorkItem", "project.id:TestProject AND type:myWiType", -1, "~title", false)
          • General Use Examples:
            {
                type: "dropdown",
                name: "question_automates_system",
                title: "Which system will it 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)
            },
            {
                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())
            }
      • The context also allows access to all other custom Velocity Context plugins deployed on the Polarion instance.

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 Java Script context with access to multiple JS objects.
    • The default built-in JS objects:
      • trackerService - ITrackerService
      • projectService - IProjectService
      • scriptingUtil - ScriptingUtil
      • engine - RhinoScriptEngine
      • context - SimpleScriptContext
    • The other JS objects added by the Active Questionnaire widget:
      • actionContext - RichPageWidgetActionContext
      • page - ProxyRichPage - shortcut for $actionContext.page()
      • transaction - WriteTransaction - shortcut for $actionContext.transaction()
      • surveyData - Contains a serialized version of the questionnaire's results.
        • Its content is created by calling JSON.stringify() upon the JavaScript object with the results of the questionnaire and then forwarded as a String to the core.
        • Next, the results are parsed and a JsonElement object surveyData is created.
        • Specific values can be accessed using 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 setup a new Work Item of the Tool type:
          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 3 – Get the first of several answers to a question:
          surveyData.getAsJsonObject().get('question_select_three_options') .getAsJsonArray().iterator().next().getAsString();
      • errorMessage - Empty by default - Allows for the forwarding of an error message back to the client.
        • Enables the 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 context.executeJavaScript() method at the end of the Java Script 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 Java Script code on the client, after the execution of the Java Script finishes.
        • Survey – The execution of JS code on a client gives you access to the original survey JS object created at the time that 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 of the result of the questionnaire's Action JS Script execution.
            • surveyDivId - Contains the ID of the <div> element used for rendering of the questionnaire itself.
        • Examples of Use
          • The first example uses the questionnaire's <div> element to display additional information upon the script's successful execution:
            var text = actionContext.getClass().toString();
            otherJS = "document.getElementById(survey.getVariable('surveyDivId')) .innerHTML = '" + text + "';";
          • The second example executes JS on the client and displays an alert window with the id of the <div> element used for the rendering of the Java Script execution result:
            otherJS = "window.alert(survey.getVariable('surveyResultId'))";
          • The third example accesses the answer to the questionnaire's question with the_only_question ID and displays it as a window alert on the client:
            otherJS = "window.alert('" + surveyData.getAsJsonObject().get('the_only_question').getAsString() + "')";

 

What's New in Version 1.0.5

Updated October 2018

1.0.4 - 1.0.5

  • Minor improvements and defect fixes.

 

 

Information

Vendor Siemens PLM
Published Version 1.0.5 - October 2018
Categories
Price Free
184 Downloads
Unsupported Extension This extension is not supported by Siemens PLM.
Requirements Access to the server's file system
Polarion 2017 SR3 (17.3) and later
(older releases supported but not tested)

Related Extensions