This part of the documentation describes functions that can be used in surveys linked to a Survey Router.
Survey Router is a Forsta add-on. If you do not have access to this functionality, contact your Forsta account manager for more information.
Survey Router surveys are set up as regular Forsta Plus surveys, and are linked to the Survey Router via the Survey Router menu. A survey can be registered in one Survey router and this is shown on the Project Management > Overview page General tab:
This setting will allow scripts in the survey to find project IDs to route the respondent/panelist to or perform the routing itself.
GetAvailableSurvey
GetAvailableSurvey is used to get a Project ID that the respondent/panelist could be routed to based upon supplied selection criteria.
GetAvailableSurvey(fieldnames{, projectList, mode})The list of question IDs supplied in fieldNames (array of Strings). Up to 5 questions IDs can be supplied (this value is configurable for On-Premise license holders) that you want to be checked by the Survey Router selection algorithm. The list of optional project ID to be included/excluded from the selection criteria supplied in projectList (array of Strings). Mode (Boolean) optional unless a projectList is supplied, determines whether the projectList is an inclusion or an exclusion list, where true demotes an inclusion list and false denotes an exclusion list.
In the following example both "gender" and "age" questions are considered in the survey selection but both project IDs "p1234567" and "p7654321" will be excluded from the selectable surveys.
JScript example:
var fieldNames : String[] = ["gender", "age"]
var projectList : String[] = ["p1234567", "p7654321"]
f("targetSurvey").set(GetAvailableSurvey(fieldNames, projectList, 0));JavaScript example:
var fieldNames = ["gender", "age"]
var projectList = ["p1234567", "p7654321"]
f("targetSurvey").set(GetAvailableSurvey(fieldNames, projectList, 0));In this example the "gender" question is to be checked. If for example the respondent has answered the "gender" question in the original survey by stating he is "male", then the survey routing algorithm will check the remaining surveys in the group and ignore any surveys where the quota for males is already full. As in this case "gender" is the only selection criteria required, the routing algorithm would now select the survey with the highest priority and open that survey for the respondent.
Figure 1 - Survey Router function in use
Availability of the respondent's quota profile does not consider Optimistically populated (currently active) respondents; only those that have completed the survey and have caused the quota cell to be incremented.
In the event several projects satisfy the selection criteria and they all have the same priority, a project will be selected from the group at random.
In the event that no projects satisfy the selection criteria, no project IDs will be returned. When a potential project is found, the system will verify that the respondent has not already participated in that specific survey (username in the respondent table is used as the key); if they have then the survey will not be considered as available for selection and the system will attempt to find another survey. After attempting to find another survey three times (this value is configurable for On-Premise license holders) due to the fact that the respondent has already participated, the system will stop trying to find a survey and will return nothing (as if no surveys are available for selection).
An exact match is required for all the criteria listed in the array. So in this case if a survey in the group does not have a "gender" question, then that survey will not be considered for selection by the algorithm.
RedirectToRouterSurvey
RedirectToRouterSurvey is used to seamlessly route the respondent from one survey to another inside of the Survey Router they are registered with.
RedirectToRouterSurvey(projectId, username, language{, fieldnames})The survey ID that the respondent is to be routed to is supplied in the projectId (string), the unique identifier for the respondent is supplied in the username (string), and the optional list of question IDs that are to be passed to the routed-to survey is supplied in fieldNames (array of Strings). You can explicitly specify the language that the routed-to survey is to use by supplying the optional language value. This is the numeric identifier for the “l” value. If no language value is supplied, the survey default language will be used.
In the following example the respondent will be routed to the project ID stored in the question "targetSurvey" using the unique identifier supplied in the question "uniqueID" and passing the values to questions "age", "gender" and "region".
JScript example:
var fieldNames : String[] = ["age", "gender", "region"]
RedirectToRouterSurvey(f("targetSurvey"), f("uniqueID"), fieldnames);JavaScript example:
var fieldNames = ["age", "gender", "region"]
RedirectToRouterSurvey(f("targetSurvey"), f("uniqueID"), fieldnames);Open text, single choice and numeric questions can be passed to the target survey, other question types are not supported. The questions that are passed can be normal, background or hidden, but no validation is performed on the data until the question is executed in the target survey. If the question passed does not exist in the target survey no error will be reported.
In this example, if the quota of the current project is filled then the respondent will automatically be routed to a new project within their Survey Router group. Both age and gender questions will be passed to the target survey.
Figure 2 - Redirecting via a Survey Router function
Note: Survey router redirection will only occur if the Survey Setting > Web Options > Survey type is set to “Limited survey with external respondent creation” in the target survey.
Typically, you will not want to ask the same questions in the target survey as you have already asked in the initial survey. To prevent this, a question mask can be applied to the questions that are passed to the target survey. In this case you may check if the question has already been answered, and if so, do not display the question again:
Figure 3 - Applying a question mask
Note: If you use this masking, remember to check the "No cleaning on question masking" property. If this property is not checked, then the data will be cleared if the page is empty.
GetRouterName
GetRouterName()The GetRouterName() function can be used to return the name of the router that the survey is assigned to. If the survey is not assigned to a router, this function will return an empty string.