About Custom Questions

Custom Questions (CQ) allows you to create new survey question experiences, and reuse them.

Each custom question consists of two main parts:

• CQ runtime component (package in-survey ResponsiveRendering (RR) question customization as reusable component).

• CQ settings page (custom per-question settings available in SurveyDesigner ("Custom settings" tab on question details page) and available in CQ runtime).

The CQ developer must specify the base Forsta question type (for example, SingleForm). The Forsta Plus application then uses the base type to determine how to store the CQ answers in a database, and which question RR model will be used in the runtime component.

The Web developer can create the CQ and upload the CQ bundle to Forsta.

CQ zip bundle

The CQ bundle is a zip archive containing a question metadata json file and a number of static files (html/js/css) which will be stored and hosted by FileLibrary. One CQ bundle contains one CQ.

The bundle contains three elements:

• Metadata

• Runtime Component

• Settings Page

Key differences from Flex (Forsta Question Extensions):

• Client-side only rendering

• RR API for runtime customization

• Support for SD and Askme/Capi mobile apps

• Static resources hosted from the FileLibrary.

Limitations

• Can be used only in RR surveys

• Can only be added or its settings changed in SD

• Cannot have server-side logic

• FileLibrary limitations (file size, file extensions, per-company quotas).

Custom Question templates

• Static files - Basic but fully functional template. Contains only required pieces.

• NodeJS pipeline - Out-of-the-box support for Dev Mode, JS code transpilation, and CQ zip bundle generation.

Notes

• A metadata.json file is required for any custom question.

• The custom question folder structure is defined by the metadata.json; the structure generated by templates is a reasonable starting point.

• Autogenerated files which have "// DO NOT MODIFY THIS FILE" content (for example, custom-question-bridge.js) should not be modified by the user.

• Custom questions use unique global identifiers (GUID) generated on the client, so the same custom question will have the same ID on different SaaS environments. Note that surveys with custom questions store only references to them (similar to table lookup and hierarchies), so when you import/export surveys you must also import/export any associated custom questions.

• Currently you can only implement Custom Questions with default rendering disabled. This is the same effect as when you have "Disable default rendering" enabled in the layout’s question skin’s settings.

• The CQ zip bundle must have the metadata.json file in the root.

• To update the custom question, upload the zip bundle again. Changes are applied immediately to surveys without relaunch, but note that the original layout may be cached by the browser.

• The survey package stores the Custom Question reference and its Runtime dependency links, so if you change dependencies then you need to relaunch the survey.

• All files you upload as custom questions are available to anyone via the FileLibrary with no access restrictions, so do not put sensitive data there.

Development

See the Getting Started, Runtime Component, Settings Page and Dev Mode topics for details.

Metadata

All custom question metadata are stored in the metadata.json file.

This is the only required file in a CQ bundle. Files and folders can have any desired structure, but entry points for design/runtime and runtime dependencies must be registered in the metadata.json file. Files which are not listed in metada.json will still be available from a static file server but will not be injected into the page automatically.

metadata.json

{
  "id": "58c35869-24e6-4b3c-96e7-3e40fede4d77",
 "schemaVersion": 3,
  "name": "My custom question",
  "description": "My description",
 "nodeType": "Text",
  "disableDefaultRendering": true,
  "iconUrl": "design/icon.png",
  "designEntryPoint": "design/index.html",
  "runtimeEntryPoint": {
    "component": "runtime/component.js",
    "deps": {
      "scripts": [],
      "styles": ["runtime/styles.css"]
    }
  }
}

Metadata fields:

Field	Required	Description	Comments
id	required	global unique identifier	Automatically generated by npx tool or CQ client app wizard.
schemaVersion	required	CQ schema version	Controls the server behavior for this CQ. Recommended to use latest schemaVersion available.
name	required	CQ name	Visible in CQ app and in SD add question page.
description	optional	CQ description	Visible in CQ app.
nodeType	required	Forsta base question type	Value is the same as in survey schema (exported xml survey definition).
disableDefaultRendering	optional		Switches off rendering of the original question on which the custom question is based.
iconUrl	optional	relative path to the CQ icon	Recommended image resolution 48x48. Can be any image format allowed by FileLibrary (jpg/png/svg etc). CQ icon is visible in CQ app, in SD questionnaire tree and in SD add question page.
designEntryPoint	optional	relative path to the CQ settings html page	See Settings page.
runtimeEntryPoint.component	required	relative path to the CQ runtime js file	See Runtime component.
runtimeEntryPoint.deps.scripts	optional	relative or absolute paths to the CQ runtime js dependencies	Will be rendered as <script src={dependency}> on the survey page where the CQ is included.
runtimeEntryPoint.deps.styles	optional	relative or absolute paths to the CQ runtime css dependencies	Will be rendered as <link href={dependency}> on the survey page where the CQ is included.