PRUVAN SUPPORT CENTER

Follow

Dynamic Survey Templates

Survey templates can be loaded dynamically when orders are sent to Pruvan.  This can be used to simply avoid maintaining a survey template in Pruvan Online, or to load updated default answers and answer validations.  This article will go over how to attach a survey template JSON object to a work order for import and how to construct the survey template JSON.

How to Build a Survey Template

To build a survey template you need to be familiar with JSON.  Alternatively you can use Pruvan's Survey Builder to construct your template and grab the JSON using the Export JSON tool.  This is also a good way to see what the template JSON should look like if you're already familiar with Pruvan's Survey Builder.

A survey template is a JSON object that contains 2 keys, a 'meta' object and a 'questions' array.  Fields marked with a '*' are required, though some fields may only be required for certain answerTypes and those are marked with '(answerType*)'.  The type of value is at the end of the description '[string]', the default value (if applicable) will be displayed as well '[boolean = true]'.

{
    "meta": {
            "surveyTemplateId": "mySurvey"
        },
    "questions": [
        {
            "id": "question1",
            "answerType": "yesNo",
        }, {
            "type": "section",
            "questions": [{...},{...},{...}]
        }
    ]
}

meta

This object contains the survey template's identifying information.

  • surveyTemplateId * - This is a unique template ID; no spaces or hyphens allowed [string]
  • version - This is the survey system version the template conforms to [number = {current version}]
  • name * - This is the display name of the survey [string]

"meta": {
    "surveyTemplateId": "v3master",
    "version": 3.1,
    "name": "Master v3 Test Survey"
}

questions

This array contains an array with the definitions for all of the survey's questions and sections.

"questions" : [{...},{...},{...}]

Each question object contains all of the necessary information for the survey engine to render the question and for the user to provide information.

  • id * - The question ID, unique to this survey template [string]
  • question * - The displayed question text [string]
  • uuid - A unique UUID [string = {autogen}]
  • required - Whether the question must be answered to submit the survey (when enabled) [boolean = true]
  • enabledByDefault - If the question shows up in the question list without first being triggered [boolean = true]
  • answerType * - The type of answer picker that the survey should display [string]
    • yesNo - Allows 'yes' or 'no'
    • chooseOne - Allows a single choice from a defined list
    • chooseOneQuantity - Allows a single choice from a defined list and a quantity and price
    • chooseMultiple - Allows multiple choices from a defined list
    • text - Allows free-form text
    • dateTime - Allows either a date, time, or both to be chosen
    • integer - Allows whole numbers
    • number - Allows floating point numbers
    • currency - Allows floating point numbers, but adds a US currency marker ('$')
    • none - Does not allow a choice, used to make statements or request photos
    • phoneNumber - Allows a 10 digit number, formatted to US standard ('(aaa) ppp-xxxx')
  • options - (chooseOne*, chooseOneQuantity*, chooseMultiple*) The list of answer option objects [array]
    • An answer choice [object]
      • answer * - The ID of the answer choice [string]
      • display * - The display text for the answer choice [string]
      • min - (chooseOneQuantity) the minimum quantity allowed [integer]
      • max - (chooseOneQuantity) the maximum quantity allowed [integer]
      • price - (chooseOneQuantity) the preset price (no currency marker) [string]
  • modeOptions - Used in dateTime and text answerTypes to declare options [object]
    • dateEnabled - (dateTime*) whether the user is allowed to select a date [boolean]
    • timeEnabled - (dateTime*) whether the user is allowed to select a time [boolean]
    • multiLine - (text) whether the text field is a multi-line area field [boolean = false]
  • commentEnabled - Whether comments are allowed or not [boolean = true]
  • answerRequiresPics - An object stating any photo requirements for the question [object]
    • {key} - The key is the answer ID of the answer choice you want to require photos for, optionally use '*' to require photos for any answer [object]
      • minPics * - the minimum number of photos required [integer]
      • maxPics * - the maximum number of photos require [integer]
  • answerEnables - What questions answers to this question should enable [object]
    • {key} - The answer ID of the answer choice you want to trigger a list of questions, optionally use '*' to trigger off of any answer choice [array]
      • The question IDs you want to enable based on this answer
  • mode - (chooseOne, chooseOneQuantity, chooseMultiple) Set the display mode [string = combo]
    • list - list the options on the screen with radio buttons or checkboxes
    • combo - display a dropdown menu of options
  • validate - Check whether a given answer matches a pre-defined value and display a given message if false [object]
    • answers - A list of answer IDs [array]
      • The answer ID you are validating against [string]
    • message - The message text you want to display if the chosen answer ID does not match the one of the validate.answers IDs [string]
  • hint - Displayed hint text to assist the user in answering the question [string]
  • enablePriceChange - Whether to allow pricing to be set or changed by the user of a chooseOneQuantity answerType with enablePrice set to true [boolean = false]
  • enablePrice - Whether to add pricing to a chooseOneQuantity answerType [boolean = false]
  • default - A pre-filled answer to the question [array]
    • The answer text / ID, or in the case of chooseOneQuantity, an object [string | object]
      • value * - The answer ID [string]
      • quantity - The number for the quantity field [integer]
      • price - The default price (no currency marker) [string]
  • constraints - (date, integer, number, currency) Place boundaries on acceptable answers [object]
    • min - Only allow answers at or above this value [string | integer | number | number]
    • max - Only allow answers at or below this value [string | integer | number | number]

{
    "id": "c1",
    "uuid": "55573f35-b9b6-412b-a71f-63e6411bf405",
    "answerType": "chooseOne",
    "hint": "c1 hint",
    "question": "c1",
    "required": true,
    "answerRequiresPics": {
        "option1": {
            "minPics": 0,
            "maxPics": 5
        }
    },
    "options": [{
            "answer": "option1",
            "display": "option1 text"
        }, {
            "answer": "option2",
            "display": "option2 text"
        }
    ],
    "enabledByDefault": true,
    "commentEnabled": true,
    "modeOptions": {},
    "mode": "list"
}

sections

Sections are structured as individual survey templates inside of the main survey template.  Sections cannot be nested and sections cannot trigger other sections.

  • type - To create a section this must be set to "section"
  • repeat - How many times the section is allowed to be repeated [integer | -1 = -1]
    • Set to '-1' for unlimited repeats
  • expand - whether the first instance is automatically displayed [boolean = false]
  • name * - The section ID, unique to this survey template, also the displayed section title [string]
  • prompt - Prompt text to ask a user to name a new instance of this section [string = "Please enter a section name"]
  • anonymous - Setting this value will auto-number instance titles with this value + incremented number, otherwise it will show the prompt [string]
  • enabledByDefault - If the section shows up in the question list without first being triggered [boolean = true]
  • uuid - A unique UUID [string = {autogen}]
  • questions * - A list of question objects, may not contain additional sections [array]

{
    "type": "section",
    "repeat": 1,
    "expand": true,
    "name": "Basic Questions",
    "prompt": "",
    "anonymous": false,
    "enabledByDefault": false,
    "uuid": "bb55054f-4ddc-4c55-bff1-7593196cc309",
    "questions": [{...},{...},{...}]
}

How to Attach a Dynamic Survey Template to a Work Order

 In your work order service object load the template JSON object in to the "surveyDynamic" field.  When you import your work order the survey task will be loaded just like a regular survey task.

{
    "workOrders":[{
        "workOrderNumber": "wo1234",
        "services": [{
            "serviceName": "Dynamic Survey Test",
            "surveyDynamic": {
                "meta": {
                    "surveyTemplateId": "123456",
                    "version": 3.1,
                    "name": "Survey Dynamic Example"
                },
                "questions": [
                    ...
                ]
            }

        }]
    }]
}

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments