Respondent Records Survey Functions

Note: These functions are only supported when using JavaScript survey engine and operate on the respondent data (not response data). These functions are also excluded from SafetyTimer evaluation.

The following scripting functions assist with interacting between respondent records.

• LookupRespondentRecords

• CreateRespondentRecord

• SetRespondentRecordValues

• RedirectToRespondentRecord

• DuplicateRespondentRecord

• GetRespondentRecordUrl()

These functions are only supported in the following interview modes:

• Web interviewing

• CATI interviewing

• CAPI interviewing

• External test mode (links generated in Survey Designer)

Note: Built-in quick testing is not supported for record-to-record interaction.

LookupRespondentRecords

LookupRespondentRecords

function LookupRespondentRecords(
    filterVariable: string,
    filterValue: string,
    additionalRespondentFields: string[]
): Respondent[]

Description

Retrieves the list of respondents from the 'respondent' records that meet the specified filter criteria. Each respondent will have at least 2 fields available (respid and sid). Any additional fields should be requested via the last function argument.

Returns an empty list on unsupported survey modes.

Notes

• This function can be used with up to 100,000 respondents for Web interviewing and up to 500 for CAPI interviewing

• The max number of respondents that is returned is 100

Example

Get respondents with household_id field equal 123, also get 2 additional fields: first_name and last_name.

var respondents = LookupRespondentRecords('household_id', 123, ['first_name', 'last_name'])
respondents[0].respid      // =1
respondents[0].sid         // =XXXXX
respondents[0].first_name  // =John
respondents[0].last_name   // =Doe
respondents[1].respid      // =2

CreateRespondentRecord

CreateRespondentRecord

	function CreateRespondentRecord(
    respondentData: Respondent
) : Respondent

Calling the CreateRespondentRecord function alone will not generate a corresponding call in CATI. To create a CATI call, the AddRespondentToCati function must also be used. When calling the AddRespondentToCati function in CATI mode, it will only be processed if the respondent.respid parameter is included. For example:

AddRespondentToCati(1,respondent.respid)

Note: The 1 in this example is the parameter used to specify the CATI Extended Status code that should be applied for the call being created.

Description

Adds a new respondent by inserting a new respondent record, populating it with a predefined set of fields.

Returns the respondent that was added (with the 2 fields available: respid and sid).

Returns null in unsupported survey modes.

Notes

• You cannot populate system fields like respid, sid, rowguid as they are controlled by the system.

Example

Create a new respondent in household 123 with first_name John.

var respondent = CreateRespondentRecord({'household_id': 123, 'first_name': 'John'})
respondent.respid          // =3
respondent.sid             // =XXXXX

SetRespondentRecordValues

SetRespondentRecordValues

function SetRespondentRecordValues(
    respondentId: number,
    respondentData: Respondent
)

Description

Updates exiting respondent fields for existing respondent.

Notes

• It updates only respondent data, it does not sync it with response data, but that will be initialized when a background variable is initialized. See SetRespondentValue in the scripting manual for behaviour details.

• You cannot update system fields like respid, sid, rowguid as they are controlled by the system.

Example

Update respondent with respid 1 by setting first name to Jane and last name to Doe.

SetRespondentRecordValues(1, {'first_name': 'Jane', 'last_name': 'Doe'})

RedirectToRespondentRecord

RedirectToRespondentRecord

function RedirectToRespondentRecord(
    respondentId: number,
    respondentSid: string,
    questionId: string,
    isCallBlock: bool,
    userParameter: string,
    loopiters: string[]
)

Description

Redirects to the existing respondent. respid and sid fields are identifying a respondent, other arguments are the same as in standard RedirectToRespondentUrl scripting function.

Notes

• All arguments except respondentId and respondentSid are optional.

• Function behaviour is similar to the RedirectToRespondentUrl. See scripting manual for details.

Example

Create a respondent and redirect to it (to the question q6).

var respondent = CreateRespondentRecord({'household_id': 123, 'first_name': 'John'})
if (respondent) {
    RedirectToRespondentRecord(respondent.respid, respondent.sid, 'q6')
}

DuplicateRespondentRecord

DuplicateRespondentRecord

function DuplicateRespondentRecord(
respondentId: number
) : Respondent

Description

Duplicates the specified respondent, setting all user respondent variables to be the same as the specified respondent record.

Returns the respondent that was added (with the 2 fields available: respid and sid).

Notes

• The duplicated respondent that is created only contains respondent data only, it does not duplicate response data.

• System fields are not duplicated.

Example

Duplicate a specific respondent.

var respondent = DuplicateRespondentRecord( 1 )
respondent.respid       // =3
respondent.sid                    // =XXXXX

GetRespondentRecordUrl()

GetRespondentRecordUrl()

The GetRespondentRecordUrl() function is used to retrieve a specific participant record URL. This function mirrors the arguments and behavior of the RedirectToRespondentRecord() function.

Note: This function has the same limitations as RedirectToRespondentRecord().

Argument	Type	Description
respondentId	int	The unique identifier for the participant.
respondentSid	string	The session ID tied to the participant.
id	string	The survey ID.
isCallblock	bool	Flag to determine call-blocking behavior.
loopQual	ArrayList	List of loop qualifications for the respondent.
userParameters	string	Additional parameters passed with the request.