Credits in Panels

This part of the documentation describes the functions that can be used to give points (credits) to panelists. Some functions can be used only in Standard Panels and Professional Panels, and some can also be used in Basic Panels. Basic Panels and Standard Panels and Professional Panels are Forsta add-ons. If you do not have access to this functionality, please contact your Forsta account manager for more information.

SetPanelistCredit

SetPanelistCredit is used for giving panelists points for registering in the panel and responding to surveys. SetPanelistCredit can be used in Basic Panels, Standard Panels and Professional Panels.

SetPanelistCredit(credit, comment)
SetPanelistCredit(credit, comment, sectionId)
SetPanelistCredit(credit, comment, panelistId)
SetPanelistCredit(credit, comment, panelistId, sectionId)

All of these update a global credit counter in the panel called CreditBalance which can be found inside the PanelistParticipation folder. The instance of the function that is being used, depends on the number of parameters and their type.

credit is an integer that represents the number of points that is to be added to the balance. comment is a String that can be used to include some information about why the points were added. The limit for comment is 256 characters.

If you include just credit and comment as parameters, you set credit points to be added to the credit balance from the survey the panelist is responding to. These points will be added as soon as interview status is set to "complete", "screened" or "incomplete" for the respondent. A repeated call to the function in the same survey will overwrite the previous credit assigned for the survey.

If you would like to assign different sets of points for different parts of a survey, you can also include sectionId. sectionId is a String with maximum 40 characters that can identify different parts of the survey. You can call the sections whatever you like as long as you are within the 40 character limit and do not use Unicode characters. The credits (points) will be active as soon as the respondent's interview status is set. If the panelist does not have any status (=incomplete), a pending flag will be set and the points will not become active until the status changes to for example "complete", "screened" or "quotafull".

If you need to update points for a different panelist, you can do this by including the panelistId (integer) of that panelist. This can for example be done to credit panelist's that refer friends to the panel. You may send the panelistid (respid in panelist survey) of the panelist that referred into the survey in the URL and retrieve it with Request(go to QueryString for more information), and then use SetPanelistCredit to credit his/her points balance.

Note: Panelistid must be a valid number/integer. If panelistid is a String, then the current panelist will be used irrespective of the Panelistid value.

SetPanelistCredit() can over-write an existing row depending on how the function is called. The full function call, including all arguments is:

SetPanelistCredit(credit, comment, panelistId, sectionId)

Credit and comment are required arguments. If you wish to make more than one set from a “single survey record”, you will also need to include the sectionId.

Example: Assuming a starting credit value of 5000, run the following script for a specific record in the survey:

SetPanelistCredit(-1000,'redemption')

At this point you will have a balance of 4000. If you change the script to the following and re-launch and re-enter:

SetPanelistCredit(-2000,'redemption')

on viewing the balance you will see 3000, not the expected 2000. If you wish to have each expression counted “separately”, you must add a sectionId. This will cause separate rows to be written for each. For example:

SetPanelistCredit(-1000, 'redemption','R-20130827170301')

In the example, a sectionID of "R-" is specified and then YYYYMMDDHHMMSS is appended. This is pulled from a new Date() object. You can alter your code to send in a sectionID that will be different each time a panelist runs over the script. This ensures that a new row will be written.

Note: If you just want something unique per row, use .getTime() from a new Date() object.

Note: comment is limited to 256 characters and sectionId is limited to 40 characters.

Also note that rows are marked 'pending' until a status (complete, screened, etc ) is set for the record.

Using Custom Variables with SetPanelistCredit

Custom Variables variables are supported in Standard and Professional Panels.

SetPanelistCreditWithCustomVariables(credit, comment, fieldNames, fieldValues)
SetPanelistCreditWithCustomVariables(credit, comment, sectionId, fieldNames, fieldValues)
SetPanelistCreditWithCustomVariables(credit, comment, panelistId, fieldNames, fieldValues)

fieldNames (array of Strings) are the names of the custom fields in the credit transaction loop in the database to be updated, and fieldValues are the corresponding values to set in these fields.

GetPanelistCreditBalance

GetPanelistCreditBalance() can be used to retrieve the credit balance for a panelist as an integer. You can get either the total balance or the balance within a specific period. GetPanelistCreditBalance is supported in Basic Panels, Standard Panels and Professional Panels.

GetPanelistCreditBalance()

returns the current total for a panelist as an integer.

With the Date Time parameters fromDate and toDate you can get the balance for a panelist within a specific period as an integer (the sum of all the transactions within that period), e.g:

GetPanelistCreditBalance(fromDate, toDate);

Displaying Current Credit Balance in a Survey

If you want to show the panelist their current credit balance in a survey, you can include the following in the text of an info node or question:

^GetPanelistCreditBalance()^

Calculating Credit Balance for the Last 30 Days

The following function can be used to calculate the credit balance, looking at the last 30 days ("adding" -30 days).

JScript example:

function last30()
{
  var toDate : DateTime = DateTime.Now;
  var fromDate : DateTime = toDate.AddDays(-30);

  return GetPanelistCreditBalance(fromDate,toDate);
}

JavaScript example:

function last30() {
  var toDate = new Date();
  var fromDate = new Date();
  fromDate.setDate(fromDate.getDate()-30);
  return GetPanelistCreditBalance(fromDate, toDate);
}

GetPanelistCredits

The GetPanelistCredits function can be used to retrieve a subset of a panelist's transactions, as an array of PanelistCredits objects. GetPanelistCredits is supported in Basic Panels, Standard Panels and Professional Panels.

GetPanelistCredits(topN);
GetPanelistCredits(fromDate,toDate);
GetPanelistCredits(topN, fromDate, toDate, startPosition, orderAscending);

GetPanelistCredits(topN) will return an array of PanelistCredits objects (see below), representing the last topN transactions. topN is an integer.

GetPanelistCredits(fromDate,toDate) will return an array of PanelistCredits objects (see below), representing transactions performed between fromDate and toDate. fromDate and toDate are both of type DateTime.

GetPanelistCredits(topN,fromDate,toDate,startPosition,orderAscending) will return an array of PanelistCredits objects (see below), representing the first topN transactions performed between fromDate and toDate, if ordered ascending (true for orderAscending) or descending (false for orderAscending). topN is an integer, fromDate and toDate are both of type DateTime and orderAscending is Boolean.

The PanelistCredits objects in the array returned have the following properties:

pCredit.CreditId

CreditID (integer) is the unique identifier for a transaction.

pCredit.PanelistId

PanelistID (integer) is the responseid of the panelist the credits are assigned to.

pCredit. SecondaryPanelistId

SecondaryPanelistId (integer) is the responseid of another panelist. This field holds a different panelistid if points have been set from a different panelist’s survey (for example for referrals).

pCredit.PanelistTransactionId

PanelistTransactionId (integer) is the id of the transaction, unique to this panelist.

pCredit.SectionId

SectionId (String) is an identifier a survey designer may assign to the credits, for example if assigning credits to panelist at various points in the survey.

pCredit.SurveyId

SurveyID (String) is the project number (pXXXXXX) of the project the credits were assigned from.

pCredit.Credit

Credit (integer) is the number of credits (points) assigned to the panelist in this transaction. A negative number would represent points withdrawn.

pCredit.Comment

Comment (String) is a text assigned to the transaction, for example explaining what the transaction represents.

pCredit.Created

Created (DateTime) is the time the transaction was made (added).

pCredit.Pending

Pending (Boolean) represents whether the transaction is pending (not active) or not. If the transaction is pending, the flag is set to true, if not, it is set to false.

Retrieving and Listing the last 10 Panelist Credits Transactions inside a Survey

The following functions will list out the date, project number and credits (points) of the last 10 credits transactions assigned to the current panelist in an HTML table:

function ShowCredits()
{
 var pCredits = GetPanelistCredits(10);
 var txt = "<table>\n"
 txt += "<tr><td>Date</td><td>Project</td><td>Points</td></tr>\n";
 for(var i : int = 0;i<pCredits.length;i++)
 {
  txt+="<tr><td>"+pCredits[i].Created+"</td>";
  txt+="<td>"+pCredits[i].SurveyId+"</td>";
  txt+="<td>"+pCredits[i].Credit+"</td></tr>\n";
 }
 txt += "</table>\n";
 return txt;
}

Using Custom Variables when Getting Panelist Credits

Custom variables are supported in Standard and Professional Panels.

GetPanelistCreditsWithCustomVariables(topN, fieldNames);GetPanelistCreditsWithCustomVariables(fromDate,toDate, fieldNames);

will retrieve panelist credit transactions with the default properties and in addition any custom variables listed in fieldNames (array of Strings), either the topN first records or the records between fromDate and toDate.

Retrieving and Listing the last 10 Panelist Credits Transactions inside a Survey, including custom variables

The following functions will list out the date, project number, credits (points) and the two custom variables listed in the array fieldNames, of the last 10 credit transactions assigned to the current panelist in an HTML table:

function ShowCreditsWithCustomVariables()
{
 var fieldNames = ['customVariable1', 'customVariable2'];
 var pCredits = GetPanelistCreditsWithCustomVariables(10, fieldNames);

 var txt = "<table>\n"
 txt += "<tr><td>Date</td><td>Project</td><td>Points</td><td>Custom Variable 1</td><td>Custom Variable 2</td></tr>\n";
 for(var i : int = 0;i<pCredits.length;i++)
 {
 txt+="<tr><td>"+pCredits[i].Created+"</td>";
 txt+="<td>"+pCredits[i].SurveyId+"</td>";
 txt+="<td>"+pCredits[i].Credit+"</td>;
 txt+="<td>"+pCredits[i].CustomFieldValues[0] +"</td>;
 txt+="<td>"+pCredits[i].CustomFieldValues[1] +"</td></tr>\n";
 }
 txt += "</table>\n";
 return txt;
}

Adding Panelist Credit Functions

Function Name	Description	Syntax
SetPanelistCreditBySectionId	Credits a panelist by specifying a section ID.	SetPanelistCreditBySectionId(Int32 credit, String comment, String sectionId)
SetPanelistCreditByPanelistId	Credits a panelist by directly using their panelist ID.	SetPanelistCreditByPanelistId(Int32 credit, String comment, Int32 panelistId)
SetPanelistCreditWithCustomVariablesBySectionId	Credits a panelist with custom variables using a section ID. Custom fields and values can be included.	SetPanelistCreditWithCustomVariablesBySectionId(Int32 credit, String comment, String sectionId, String[] fieldNames, String[] fieldValues)
SetPanelistCreditWithCustomVariablesByPanelistId	Credits a panelist with custom variables using their panelist ID. Custom fields and values can be included.	SetPanelistCreditWithCustomVariablesByPanelistId(Int32 credit, String comment, Int32 panelistId, String[] fieldNames, String[] fieldValues)