General Utilities

Use these functions to send emails etc.

SendMail

SendMail(from,to,subject,body,cc,bcc,mailformat,bodyformat,codepage)

SendMail can be used to send an email from inside a survey. For information on sending of multipart emails, see below.

Arguments:

Argument	Description
From	Message sender (string)
to	Recipient's address (string)
subject	Message subject line (string)
Body	Message body (string)
cc *	Carbon Copy (string)
bcc *	Blind Carbon Copy (string)
mailformat *	(int) (obsolete)
bodyformat *	(int) 0 – HTML, 1 – Plain text
codepage *	(int) The codepage the mail is to be sent with. 1252 is Western European, 65001 is Unicode (UTF-8).

*) optional

The last 5 arguments are optional, but if you include any of them, you have to include all arguments that precede them. For example, if you do not want a carbon copy (cc), just use an empty string ("") for that argument (go to APPENDIX D: Codepage for more information).

Send Confirmation Email at the End of a Survey

Here is an example of a script placed at the end of a pop-up survey to thank the respondent for participating in the survey. The respondent has provided her or his email address in an open text question called email:

//build body of email:
var body = "You have just completed a survey powered by PGForsta.\r\n\r\n";
body += "We would like to thank you very much for your contribution.\r\n\r\n";
body += "Best Regards\r\n\r\n";
body += "PGForsta\r\n";

//send mail:
SendMail("[e-mail]",f("email"),"Thank you!",body,"","[e-mail]");

The email will be sent to the respondent, with a blind copy sent to "[e-mail]". The respondent will not know that this copy has been sent as the address is in the bcc field. You must include an empty string ("") for the cc argument if you do not want to cc anybody but do want to bcc as in this example. If you need more than one email address in either to, cc or bcc, separate the addresses with semi colons (;) inside the string, e.g. "[e-mail];[e-mail]".

Invitation Email to a Different Part of the Same Survey

We want a survey to start as a pop-up survey where the respondent registers email (with validation of the email address) and name. Based on that, an email is to be sent to the email address with the url to the rest of the survey, and the pop-up survey is to terminate.

When the respondent opens the url in the mail, he or she should get a page with a text that includes his or her name.

Build a questionnaire like this:

Figure 1 - Build a questionnaire like this

The first condition checks if there is an answer to the email question. The email question is required, so if it has no answer the respondent should get the first part of the survey.

Then name and email questions follow. In the email question, use the following validation code:

if(!IsEmail(f(CurrentForm()))))
 {
  RaiseError();
  SetQuestionErrorMessage(LangIDs.en,"Please provide a valid email address.");
 }

After the email question there is a script node, which does the emailing (change "survey.confirmit.com" if you are not using Confirmit's ASP):

var body = "Thank you for registering.\r\n\r\n";
body += "Here is the url to your follow up survey:\r\n";
body += GetRespondentUrl()+"\n";

SendMail("[e-mail]",f("email"),"Follow up",body);

Then there is a stop node to end the first part of the interview. When the respondent re-opens the interview with the url, he/she is brought into the same interview with the data from the first part. So since there now is an answer to the email question, the first part will be skipped and the respondent will be brought to the info node (i4).

However, by default, when a condition in Forsta evaluates to false, the interview engine removes all answers to questions in the THEN-branch. This ensures that you get consistent data in your surveys and do not have to do data cleaning. But here, this would mean that the answers to name and email would be deleted, and that is not what we want – we are going to use name in part 2 of the interview.

Fortunately there is a property on conditions that can be used in situations like these: "Do not perform delete". When this property is checked, the interview engine will never remove answers in any of the branches (THEN/ELSE).

Figure 2 - Condition properties

To pipe in the name in the first info node (i4), use the code below:

^f("name")^

SendMailMultipart

SendMailMultipart(from,to,subject,bodyText,bodyHtml,cc,bcc,codepage)

SendMailMultipart can be used to send a multipart email from inside a survey. A multipart email is an email where the body text can be defined both as plain text and as HTML. The recipient’s mail client will determine which version is to be displayed to the recipient.

Arguments:

Argument	Description
From	Message sender (string)
to	Recipient's address (string)
Subject	Message subject line (string)
BodyText	Message body, plain text (string)
BodyHtml	Message body, HTML (string)
cc*	Carbon Copy (string)
bcc*	Blind Carbon Copy (string)
Codepage*	(int) The codepage the mail is to be sent with. 1252 is Western European, 65001 is Unicode (UTF-8) (default value).

* optional

The last 3 arguments are optional, but if you include any of them, you have to include all arguments that precede them. For example, if you do not want a carbon copy (cc), just use an empty string ("") for that argument (go to APPENDIX D: Codepage for more information).

SendPdfMail

The SendPdfMail function allows the generation and emailing of a PDF file from a survey with for example a summary of the respondent's answers. Typically the file is sent to the respondent, but it could also be sent to someone who is to review the respondent’s answers. Note that you can also send PDF mail with copies.

Note: PDFs are only sent when the device is synched with the server.

The syntax of the function is:

SendPdfMail(html,emailSender,emailReceiver,emailBody,emailSubject,outputFileName,pdfPageSize,pdfOrientation)

Arguments (all strings):

Argument	Description
html	A string with the html that the PDF file should be created from.
emailSender	The sender of the message.
emailReceiver	The recipient's address.
emailBody	The message body text (optional).
emailSubject	The message subject (optional).
outputFileName	The filename of the pdf file (optional). Note that the filename can only contain alphanumeric characters. Do not specify the extension of the file.
pdfPageSize	The paper size for which the PDF is formatted (optional). Valid options are A3, A4, A5, B4, B5, Legal, Letter and Tabloid.
pdfOrientation	The orientation of the page (optional). Valid options are Landscape or Portrait.
companyId	The company id (required if pdfPageSize and/or pdfOrientation are included in the function). Each company has one id. Note that normal users do not have access to this information; you must contact Forsta support to retrieve it.
useNewPdfEngine	(Required if PaperSize and/or Orientation are included in the function) This is a Boolean value which can be either true or false.

Figure 3 - Examples of functions

As the content of the PDF file is a string containing HTML, there is considerable flexibility concerning the layout and content of such a respondent-specific report.

If no subject is provided, the subject of the email will be “Respondent Report”. If no filename is provided, the name of the pdf file will be “respondentreport”.

The call to the function initiates a task that runs on the batch servers to generate and send a zipped PDF file. This means that, depending on the queue of tasks on the batch server, there may be a delay in producing and sending the file. If the PDF report is to be sent to the respondent, it is recommended that the respondent is informed of this possible delay. The function will not run in RDG mode.

For SaaS customers there is a charge for each of these reports, just as for PDF exports from Reportal.

The PDF-software does not parse anchor tags; it only adds the link text. So to have clickable links in the PDF file that is generated with SendPdfMail, you must include the URL itself.

http://www.confirmit.com

NOT:

<a href=” HYPERLINK "http://www.confirmit.com/”%3eLink" http://www.confirmit.com/”>Link text</a>

If you want blue text and underline, you can define this in a <span> tag:

<span style="text-decoration: underline; color: blue">HYPERLINK "http://www.confirmit.com%3c/span" http://www.confirmit.com</span>

Sending a PDF to the respondent with answers from the survey

Here is a short example where the respondent answers questions on name, email, age and gender. Following these questions is a script that generates and sends a PDF file with the answers the respondent has given:

var html ="<html><body>\n";
html += "<h1>Answers for "+f("name").get()+"</h1>\n";
html += "<table><tr><th>Question</th><th>Answer</th></tr>\n";
html += "<tr><td>"+f("email").label()+"</td><td>"+f("email").get()+"</td></tr>\n";
html += "<tr><td>"+f("age").label()+"</td><td>"+f("age").get()+"</td></tr>\n";
html += "<tr><td>"+f("gender").label()+"</td><td>"+f("gender").valueLabel()+"</td></tr>\n" ;
html += "</table>\n";
html += "</body></html>\n";

SendPdfMail(html,"[e-mail]",f("email").get(),"Here are your responses to the survey.","Your responses","responses");

Note: Non-ASCII characters are not accepted by the PDF creator. If non-ASCII characters must be used, write valid HTML for the required character and include a metatag such as the following: <meta http-equiv="content-type" content="text/html;charset=utf-8" />

SendPdfMailWithCopy

The SendPdfMailWithCopy function is an extension of the SendPdfMail function, giving you the possibility to copy the mail to others. The function allows the generation and emailing of a PDF file from a survey with for example a summary of the respondent's answers.

Note: PDFs are only sent when the device is synched with the server.

The syntax of the function is:

SendPdfMailWithCopy(html,emailSender,emailReceiver,cc>,bcc>,emailBody,emailSubject,outputFileName,pdfPageSize,pdfOrientation)

Arguments (all strings):

Argument	Description
html	A string with the html that the PDF file should be created from.
emailSender	Message sender.
emailReceiver	Recipient's address.
cc	The email will be copied to these addresses. Separate multiple addresses with comma. The addresses will be visible to other recipients.
bcc	The email will be copied to these addresses. Separate multiple addresses with comma. The addresses will not be visible to other recipients.
emailBody	The message body text (optional).
emailSubject	Message subject (optional).
outputFileName	The filename of the pdf file (optional). Note that the filename must only contain alphanumeric characters. Do not specify the extension of the file.
pdfPageSize	The paper size for which the PDF is formatted (optional). Valid options are A3, A4, A5, B4, B5, Legal, Letter and Tabloid.
pdfOrientation	The orientation of the page (optional). Valid options are Landscape or Portrait.
companyId	The company id (required if pdfPageSize and/or pdfOrientation are included in the function). Each company has one id. Note that normal users do not have access to this information; you must contact Forsta support to retrieve it.
useNewPdfEngine	(Required if PaperSize and/or Orientation are included in the function) This is a Boolean value which can be either true or false.

Note that if this function is used, both cc and bcc must be used.

Redirect

Redirect(url,{noexit})

Redirect can be used to redirect the respondents to a different site (url).

Important
If a redirect is included at the end of the survey, it is important that the interview status is also set using the SetStatus function (go to GetStatus and SetStatus for more information).

Note: The use of redirects, quotas, status-screened or other solutions with the principle purpose of avoiding the survey "complete" status being reached by a respondent having offered a reasonable amount of responses, is prohibited and will be regarded as an attempt to avoid transaction fee obligations to Forsta.

noexit is a Boolean. It is optional, and is used when you want the respondents to be able to reenter the survey, for example if you redirect out of the survey to another url, and then at some point the respondents are redirected back to the survey again (with r (respid) and s (sid)). This is especially important if the survey is set up without "Allow user to modify answers after the interview is complete". With noexit as true, the respondent will be allowed to reenter the survey. With noexit as false (default), the respondent will not be allowed reentry to the survey.

Redirect to Another Site Before the End Page

If you want to send the respondent to another site (here: Google) before he or she reaches the default end-of-survey page in Forsta Plus, you can use a script as below:

SetStatus("complete");
SetInterviewEnd();
Redirect("http://www.google.com",false);

Redirect is used in combination with SetStatus and SetInterviewEnd so that the respondent is given the correct status and end time stamp before being redirected out of the survey.

Note: The use of scripted Redirect() to jump into or out of questions that are in Call Blocks will cause problems and should not be attempted. A key attribute of Call Blocks is that they can be entered from multiple points in a survey, so the survey engine will not have a specific “entry-point” that has been used to enter that call block. Therefore when the Call Block finishes it does not know where in the main body of the survey to return to, and the survey will simply error. Refer to the separate Survey Designer documentation for further details on Blocks.

Opening a Specific Survey Page

If you would like to open a specific survey page with an internal redirect, then you can either use RedirectToRespondentUrl(), or Redirect together with GetRespondentUrl()(go to GetRespondentUrl for more information).

Example:

Redirect(GetRespondentUrl("q9"), true);

Or:

RedirectToRespondentUrl("q9");

Both of these lines will redirect respondents to question q9 and allow the respondent to re-enter the survey again (noexit = true). The difference between these two functions is that Redirect(GetRespondentUrl(),{noexit})) will display the respondent unique link in the URL field, while RedirectToRespondentUrl will redirect without updating the URL visible to the respondent.

Redirect between surveys, or between the survey and an external application with encrypted links:

You can use Redirect if you need to send the respondent to a different survey or another application. If you need to send the respondent back into the survey again, then you can add the respondents sid value as a parameter to the link, and use this to send the respondent back into its unique survey link.

Example:

In this example we will send the respondent from survey A into survey B, then when they complete survey B they are sent back into survey A directly to question q4.

Figure 4 - Redirecting from survey A to survey B

Figure 5 - Redirecting from survey B back to survey A

Survey A includes the script “Redirect to survey B”. This will retrieve sid from the respondent link, and add this as a parameter to the target link:

//Get the respondent unique survey link for question q4:
var UniqueLink = GetRespondentUrl("q4");
//split the survey link to retrieve sid:
var sid = UniqueLink.split("__sid__=");
//link to the target survey/application
var RedirectToLink="https://survey.euro.confirmit.com/wix/p1873864785.aspx";
//send the respondent to the link added in RedirectToLink and add parameter SourceSID to the link
Redirect(RedirectToLink + "?SourceSID=" + sid[1], true);

This will send the respondent into survey B (p1873864785 in this example). In the beginning of survey B we will have a script to retrieve the “SourceSID” value from the link and add this into variable “SourceSID”.

Script “Retrieve sid from Survey link”:
var linkBackToSurveyA = Request("SourceSID");
f("SourceSID").set(linkBackToSurveyA);

At the end of survey B there is a script to redirect the respondent back to survey A and into question q4:

Script “Redirect back to survey A”:
Redirect("https://survey.euro.confirmit.com/wix/p1873864538.aspx?__sid__=" + f("SourceSID").get(),true);

Redirect to specific question with unencrypted links:

If you for example use Redirect to redirect the respondent to another application, but want to send the respondent back to the Forsta Plus survey on a particular page, you can include a parameter in the survey link to specify which page is to open. This parameter is __qid (two underscores + qid). Valid values are the question ids of any question on the root level of the survey (outside loops). When opening a survey url with this parameter, the survey will open on the page that contains the question indicated in __qid.

Example:

http://survey.confirmit.com/wix/pXXXXXXXX.aspx? __sid__=ww-redcOmXd5s2yCeqAQYTjtCOc0bqXHg9QNh28l-FFg7WyktC2GBFh8qJPBNGtY0&__qid=q4

This will just open that particular page (here: the page with question q4). No attempt is made to transfer background variables, set interview start, or save any data.

Similarly, if you use __gotoCallBlock=CallBlockID(two underscores + gotoCallBlock), you can direct respondents directly to a specific call block. When the call block is finished, the interview will finish.

Note: To use parameter __qid and the __gotoCallBlock option, the “Disable unencrypted QID request parameter” must be unselected in the Overview page > More Survey Settings > Options section (Survey settings > General Options tab in Professional Authoring).