This part of the documentation describes functions that can be used in registration and profile update surveys linked to a Standard or Professional Panel to add and update panelists.
Standard Panels and Professional Panels are Forsta add-ons. If you do not have access to this functionality, contact your Forsta account manager for more information.
Registration and profile update surveys are set up as regular Forsta Plus surveys, and are linked to the panel database through a setting on the Project Management > Overview page General tab:
This setting will allow scripts in the survey to add new panelists to the panel database and retrieve and update data from the panel database for the current panelist. Very often the registration and profile update surveys will be linked from the Panel Portal.
CreatePanelist
In a registration survey linked to a Panel as described below, the person registering to participate in the panel can be asked for email (which will be used as the login name and unique identifier), password and other information. The panelist can be added to the panel database with the CreatePanelist function:
CreatePanelist(fieldNames, fieldValues)CreatePanelist will return the panelist id (positive integer) if the insert succeed, or a negative integer if the insert of a new panelist fails, for example because a panelist is already registered with the provided email address (see below).
The parameters are both arrays of Strings: fieldNames are names of the fields in the panel database to insert data into, and fieldValues are the corresponding values to insert into these fields. fieldNames needs at least to include “email”, but if the panel database has other user provided unique fields, these fields need to be included as well.
The codes returned from the insert of a new panelist are listed below. A negative code (less than zero) represents an error and means that the panelist creation did not succeed.
Code |
Description |
| >0 | The panelist was created successfully. A new panelist record is added to the database and the panelist id is returned. |
-1 |
Error on the survey end, for example not being able to connect to the panel database etc. |
-2 |
The unique constraint is violated, i.e. a panelist already exists with the provided values in the unique fields (email + any user provided unique fields) |
-3 |
Other database errors when inserting the new panelist. |
| -5 | The password failed on one or more of the password complexity rules, according to the Panel settings for password complexity. |
Inserting a new Panelist in a Panel
In a registration survey that is linked to a Panel as described above, there is an open text question with question id “email”. In the validation code of this open text question the following script can be included to insert the new panelist in the Panel database, and provide an error message if the insert fails:
JScript example:
var fieldNames : String[] = ["email"];
var fieldValues : String[] = [f('Email')];
var result = CreatePanelist(fieldNames, fieldValues);
if(result<0 && result!= -2 && result!= -5)
{
RaiseError();
SetErrorMessage(LangIDs.en,"Unknown error: Couldn't register with this email address. Error code:" + result);
}
else if (result == -2)
{
RaiseError();
SetErrorMessage(LangIDs.en,"Can't register with this email address. It is already in use.");
}
else if (result == -5)
{
RaiseError();
SetErrorMessage(LangIDs.en,"Password does not comply with password complexity rules. Please choose a different password.");
}
JavaScript example:
var fieldNames = ["email"];
var fieldValues = [f('Email')];
var result = CreatePanelist(fieldNames, fieldValues);
if(result<0 && result!= -2 && result!= -5)
{
RaiseError();
SetErrorMessage(LangIDs.en,"Unknown error: Couldn't register with this email address. Error code:" + result);
}
else if (result == -2)
{
RaiseError();
SetErrorMessage(LangIDs.en,"Can't register with this email address. It is already in use.");
}
else if (result == -5)
{
RaiseError();
SetErrorMessage(LangIDs.en,"Password does not comply with password complexity rules. Please choose a different password.");
}
UpdatePanelVariables
If a survey is linked to a Panel as described above, and the panelists are identified either through panelistid being included in respondent table (a survey you have sampled to), because the survey is opened within a protected page (requires login) in the panel portal (profile update), or because you have just inserted this panelist with the CreatePanelist function (registration survey), you may use the UpdatePanelVariables function to update variables in the panel database.
UpdatePanelVariables(fieldNames, fieldValues)
The parameters of the UpdatePanelVariables function are both arrays of Strings: fieldNames are names of the fields in the panel database to update, and fieldValues are the corresponding values to set in these fields.
UpdatePanelVariables will return a negative integer if the update fails:
Code |
Description |
| 0 | Update successful. |
-1 |
Error on the survey end, for example not being able to connect to the panel database etc. |
-2 |
The unique constraint is violated, i.e. another panelist already exists with the provided value(s) you are trying to set for (one of) the unique field(s) (email + any user provided unique fields). |
-3 |
Other database errors when updating the panelist. |
| -4 | The panelist does not exist. |
| -5 | The password failed on one or more of the password complexity rules, according to the Panel settings for password complexity. |
Update Panel Variables in a Panel
Here is an example from a survey linked to a Panel as described above, where the questions gender, dateofbirth, USstate, householdsize, carowner, empstatus, marstatus and email are asked. A hidden open text question status_desc is used to store the status returned from the update call. The following script can be placed in a script node to update these variables in the panel database for the current panelist:
JScript example:
var fieldNames : String[] = ["gender","dateofbirth","USstate","householdsize","carowner","empstatus","marstatus","email"];
var fieldValues : String[] = [f('Gender'),f('dateofbirth'),f('USstate'),f('householdsize'),f('carowner'),f('empstatus'),f('marstatus'),f('email')];
var result = UpdatePanelVariables(fieldNames, fieldValues);
if(result <0 && result!= -2 && result!= -4 && result!= -5)
{
f('status_desc').set("Unknown error. Error code:" + result);
}
else if(result == -2)
{
f('status_desc').set("Update of email address failed. It is already in use for another panelist.");
}
else if(result == -4)
{
f('status_desc').set("Panelist does not exist in the panelist database.");
}
else if(result == -5)
{
f('status_desc').set("Password does not comply with password complexity rules.");
}
else
{
f('status_desc').set("Succesfully updated.");
}
JavaScript example:
var fieldNames = ["gender","dateofbirth","USstate","householdsize","carowner","empstatus","marstatus","email"];
var fieldValues = [f('Gender'),f('dateofbirth'),f('USstate'),f('householdsize'),f('carowner'),f('empstatus'),f('marstatus'),f('email')];
var result = UpdatePanelVariables(fieldNames, fieldValues);
if(result <0 && result!= -2 && result!= -4 && result!= -5)
{
f('status_desc').set("Unknown error. Error code:" + result);
}
else if(result == -2 )
{
f('status_desc').set("Update of email address failed. It is already in use for another panelist.");
}
else if(result == -4 )
{
f('status_desc').set("Panelist does not exist in the panelist database.");
}
else if(result == -5 )
{
f('status_desc').set("Password does not comply with password complexity rules.");
}
else
{
f('status_desc').set("Succesfully updated.");
}
GetPanelVariables
If a survey is linked to a Panel as described above, and the panelists are identified either through panelistid being included in respondent table (a survey you have sampled to) or because the survey is opened within a protected page (requires login) in the panel portal (profile update), you may use the GetPanelVariables function to update variables in the panel database.
GetPanelVariables(fieldNames)Note: If this function is used in a survey, then the survey must be launched as a Limited survey. Failure to do this will result in an error message being generated for each respondent who attempts but fails to enter the survey either because they are not uploaded or because they do not enter via a portal.
GetPanelVariables will retrieve values from the fields provided in fieldNames (array of Strings) and return these values. The data types will be according to the question types (for example date, numeric, open text etc.).
Retrieving Data for a Panelist in a Panel
The following script can be placed in a script node in the beginning of a profile update survey linked to a panel as described above to retrieve the fields gender, dateofbrith, USstate, carowner, empstatus, marstatus and email and set these values in the corresponding questions in the survey. The script will skip empty values (empty string “” or null), and also shows how true and false for the carowner variable, which is a Boolean in the Panel, are converted to codes 1 and 0.
JScript example:
var fieldNames : String[] = ["gender","dateofbirth","USstate","householdsize","carowner","empstatus","marstatus","email"];
var variables = GetPanelVariables(fieldNames);
for(var i=0;i<fieldNames.length;i++)
{
if(fieldNames[i]=="carowner")
{
if(variables[i])
f(fieldNames[i]).set("1")
else
f(fieldNames[i]).set("0")
}
else if(variables[i]!="" && variables[i]!=null)
f(fieldNames[i]).set(variables[i]);
}
JavaScript example:
var fieldNames = ["gender","dateofbirth","USstate","householdsize","carowner","empstatus","marstatus","email"];
var variables = GetPanelVariables(fieldNames);
for(var i=0;i<fieldNames.length;i++)
{
if(fieldNames[i]=="carowner")
{
if(variables[i])
f(fieldNames[i]).set("1")
else
f(fieldNames[i]).set("0")
}
else if(variables[i]!="" && variables[i]!=null)
f(fieldNames[i]).set(variables[i]);
}
UpdateSurveyHistoryPanelVariables
The function UpdateSurveyHistoryPanelVariables replaces UpdateSurveyHistoryVariables, and is used for updating the survey history of a panelist directly from a script in the panel survey. It requires that the survey from which it is called is linked to the panel as described previously.
UpdateSurveyHistoryPanelVariables(fieldNames, fieldValues)fieldNames and fieldValues are both arrays. fieldNames holds the variable names of the survey history variables you want to update, and fieldValues the corresponding values to assign to them.
Update Survey History Variables in a Panel
This is an example from a survey linked to a Panel as described, where sample has been uploaded from a sample job. The response to a question "surveyrating", asked at the end of the survey, is to be set in the panel's survey history.
JScript example:
var fieldNames : String[] = ["surveyrating"];
var fieldValues : String[] = [f('surveyrating')];
UpdateSurveyHistoryPanelVariables(fieldNames,fieldValues);
JavaScript example:
var fieldNames = ["surveyrating"];
var fieldValues = [f('surveyrating')];
UpdateSurveyHistoryPanelVariables(fieldNames,fieldValues);
UpdateSurveyHistoryVariables
The function UpdateSurveyHistoryVariables is used for updating the survey history of a panelist directly from a script in the panel survey, in a similar way to UpdateSurveyHistoryPanelVariables, but requires providing the panelistID and jobNumber in addition to the variables to update and their values. It requires that the survey from which it is called is linked to the panel as described previously.
UpdateSurveyHistoryVariables(panelistIdString, jobNumber, fieldNames, fieldValues)panelistIDString (string) is the panelistid (the responseid in the panel database). jobNumber (string) is the sample job number. fieldNames and fieldValues are both arrays. fieldNames holds the variable names of the survey history variables you want to update, and fieldValues; the corresponding values to assign to them.
It is recommended that you use UpdateSurveyHistoryPanelVariables instead, as that is simpler. However UpdateSurveyHistoryVariables is still supported.
IsFromCommunityPortal and GetCommunityPortalReturnUrl
When the registration and/or profile update survey is opened from the Panel Portal, it will be opened within a frame in the Panel Portal. The functions IsFromCommunityPortal and GetCommunityPortalReturnUrl are provided to seamlessly handle redirecting back to the Panel Portal for panelists that have opened the survey from within the Panel Portal.
IsFromCommunityPortal()IsFromCommunityPortal() returns true if the survey is opened from the Panel Portal and false if not. The function can be used to determine when to redirect to the Panel Portal Url provided by the GetCommunityPortalReturnUrl function.
GetCommunityPortalReturnUrl()GetCommunityPortalUrl() returns a URL that can be used to redirect back to the Panel Portal, with authentication (so that the panelist does not need to log on again if he/she was already logged in).
The following script can be placed in a script node at the end of a survey to redirect back to the Panel Portal for panelists that open the survey from the Panel Portal:
if(IsFromCommunityPortal())
{
Redirect(GetCommunityPortalReturnUrl());
}
else
{
Redirect("http://www.confirmit.com");
}
IsFieldValueTaken
In Professional and Standard Panels it is possible to set panel variables to be unique. That means that each panelist must have a unique value in this field. The isFieldValueTaken function can be used in panelist recruitment surveys to check if any previous respondents have selected the same value in a given field.
isFieldValueTaken(fieldName, value)isFieldValueTaken returns true if there is already a panelist in the sample with the provided value (string) in the question with question id fieldname (string), false otherwise.
It can be used in the validation code of the question defined in "uniqueid" in a panel survey:
if(isFieldValueTaken("uniqueid", f("uniqueid").get()))
{
SetQuestionErrorMessage(LangIDs.en,"The value in uniqueid is already taken. Please input a different value.");
f("uniqueid").set("");
RaiseError();
}The function can also be used in the same way in ordinary projects to check that the value entered in a question with a given question id is unique. If the function is used in ordinary projects, performance will be improved if the Indexed property is set on the question being checked. If the function is used to check variables in a panel, again performance will be improved if the Indexed property is set on the variable being checked.
Note: This function is not supported in RDG, quick-test and external test mode.
When connected to a panel (Professional, Standard or Basic), this function will look in the panel database to see if the value is taken. When used in a normal survey not connected to a panel, the function will look in the survey database.
Note that if the qid referenced in isFieldValueTaken(qid,value) does not exist in the panel database the function will always return true.
isEmailTaken
The isEmailTaken function is used in panelist recruitment surveys in the same way as isUsernameTaken; to check if any previous respondents have registered with the same email address.
isEmailTaken(email)isEmailTaken returns true if there already is a panelist in the sample with the provided email (string), false otherwise.
The function can also be used in the same way in ordinary projects, to check that the value entered in a question with question id email is unique. If the function is used in ordinary projects, the indexed property should be set on the email question to improve performance.
Note: This function is not supported in RDG, quick-test and external test mode.
Note: If you call the function from a survey that is connected to a panel (for example a registration/update profile survey), then the string argument is compared with the email column in the panel, while if the function is called from a survey that is not connected to any panel, then the argument is compared to the email column in the response database of the actual survey.
DeleteCurrentResponse
Since the data of registration and profile update surveys are usually posted back to the panel database before the end of these surveys, it is usually not necessary to keep the data in the survey itself. Therefore a function is provided to enable deletion of the entire response at the end of the survey after all update scripts have been run:
DeleteCurrentResponse()DeleteCurrentResponse will remove the entire record with all responses from the survey database.
When DeleteCurrentResponse is used at the end of the survey in a script node, it should be followed immediately by a redirect script. This is because any attempt to open a survey page (including the end page) after the record has been deleted will give an error, as the respondent no longer exists.
Functions for Sample Only
RedirectToExternalSurvey and GetExternalSurveyStateNote: “Sample Only” is a Panel add-on to be used by access panel providers who, as a part of their business, sell sample to other companies, on projects where they do not perform the data collection themselves. Any other usage of this functionality is prohibited. Contact your Forsta account manager for more information.
With the "Sample Only" add-on enabled, you can upload a repository of external survey links to the sample job. To upload the links:
Create a text file (.txt) with 'Link' as the only column header and the external survey links listed, one link per row. On "Job Information", the interface shown below is available to upload external survey links to the job:
Figure 1 - Interface within job interface
These survey links will then be included in the sample file(s). These can then be uploaded to a Forsta Plus survey, which must be linked to a Panel on Project Overview:
Figure 2 - Survey links showing in sample file
This project is used for:
- Emailing survey invitations and reminders to panelists
- Redirecting panelists to the external survey links
- Update status, panelist credits etc. if panelists are redirected back to the survey when finished in the external survey link with status.
You can also add questions to this survey; you could for example ask panelists to rate the survey experience etc. when they are finished with the external survey, or you may need an initial screener before respondents are redirected. Note however that you are NOT allowed to use this redirect survey for general data collection.
The following function can be used in this survey to handle redirects and statusing:
RedirectToExternalSurvey(queryString)RedirectToExternalSurvey will redirect the panelist to the url uploaded to the background variable "ExternalSurveyLink", with querystring (optional, String) added to the link. querystring can be used if you need to send in some values with the link. This can be useful if the system running the survey is capable of fetching these values sent in with the link.
For example, if you have a background variable gender in the sample file, you could send in that value with the external survey link by using:
RedirectToExternalSurvey("?gender="+f("gender").get())If you send in several parameters like this, then you must separate them with the ampersand (&) character.
The RedirectToExternalSurvey function will also set a session cookie that will be used when panelists are redirected back to the survey after finishing the external survey, to identify the panelist and set the correct status on the panelist for this job.
At the end of the external survey, there should be a redirect back to the survey with the correct status in the survey link. This status will then be set both on the redirect survey, and back to the panel (in survey history). The statusing URL is one of the following:
http://<server>/wix/<pid>.aspx?status=complete
http://<server>/wix/<pid>.aspx?status=screened
http://<server>/wix/<pid>.aspx?status=quotafull
http://<server>/wix/<pid>.aspx?status=incomplete
http://<server>/wix/<pid>.aspx (this will default to complete)
<server> is to be replaced with either survey.confirmit.com or survey.euro.confirmit.com if you are a SaaS user, or your system’s survey domain if you are an On-Premise user. <pid> is to be replaced with the project id of the survey that is used for the redirect.
When panelists are redirected back, the system will retrieve the necessary information from the cookie to identify the panelist so that the right status is set, and open the survey after the redirect. The survey will be opened on the node following the script node with the Redirect script (for example a question, a script node or a stop node). Additional questions or scripts, for example to set Panelist Credits (points), can be placed after the Redirect script to be executed when the panelist is redirected back to the redirect survey. The redirect survey will be opened automatically at the point where the redirect was done when the panelists return from the external survey, due to the details stored in the cookie.
The cookie is a "session cookie", so is removed when the panelist closes his/her browser.
The function GetExternalSurveyState can be used to keep track of what state the panelist is in, i.e. whether status has been set or not.
GetExternalSurveyState()GetExternalSurveyState will return one of the following state codes:
ExternalSurveyState.NONEExternalSurveyState.NOT_STARTEDExternalSurveyState.IN_PROGRESSExternalSurveyState.STATUS_SETThe GetExternalSurveyState function is useful if a panelist has disabled cookies in his/her browser. If the session cookie cannot be found, you will be unable to automatically update the panelist status. To treat this special case, you can include a condition with the expression
GetExternalSurveyState() == ExternalSurveyState.NONEfollowed by a stop node so that these panelists don't cause any errors in scripts you have for example to update panel variables or points. The text on this stop node could for example notify the panelist that their points status was not updated automatically and that they will have to wait some days for this to be done, depending on the procedures for this. It is probably a good idea to flag these incidents by setting a hidden variable as well so that you keep track on how often it happens.
Figure 3 - Stop node example
Note: The statusing survey must have "Encrypt system request parameters" (default) enabled in Survey Settings/Web for statusing to work.
If you follow the procedure described above, "Interview complete - Sample Only" units will be logged for completes instead of regular "Interview complete - CAWI ". These units are solely intended to be used by access panel providers who, as a part of their business, sell sample to other companies, on projects where they do not perform the data collection themselves. Any other usage of this functionality is prohibited. The following must be in place for the "Interview complete - Sample only" units to be logged:
- The project must be linked to a Standard or Professional Panel.
- The respondent must have a value in the panelistid column in the respondent table.
- The respondent must have a value in the External Survey Link column in the respondent table.
All of this happens automatically when uploading sample from the sample job if you follow the procedure described above.
AddPanelSurveyHistory
This function is used to create a survey history entry for the current panelist, it is used in scenarios where the panelist is participating in a survey linked to the panel that they are a member of, but have not been directly sampled to.
AddPanelSurveyHistory( panelistId, jobNumber)The input parameters are strings: panelistId is the panelist’s ID from the linked panel and jobNumber is the job number in the panel that the survey history entry will be associated with.
The following syntax can be used to update the current panelist in job number 10 in the linked panel. An error will be reported if the insert fails:
AddPanelSurveyHistory(GetRespondentValue('PanelistId'),"10");The following criteria must be met for the panelist’s survey history to be updated successfully:
- The survey must be linked with a Standard or Professional Panel.
- The specified panelist ID must exist in the panel.
- The survey needs the panel fields in the Respondent table:
panelistid,jobnumberandrunnumber
On successful execution of the function, the survey panel history for the specified panelist will be updated in the panel for this survey. If the job number does not exist, a new job will be created with this job number.
Note: This function is required when a Survey Router is used to route panelists from one survey to another where the routed-to survey is one that the panelist was not sampled to.