In this article
This article outlines advanced scripting functions you can use to customize the behavior of the CAPI App. Each section covers a specific use case, including script examples and implementation notes.
1: Prevent CAWI Participant from Being Overwritten by CAPI
By default, if a participant is assigned to CAPI, any changes made in the CAPI App will overwrite the version stored on the server—unless the server version is marked as Complete.
To prevent this behavior for a specific participant, set the following reserved variable to "1" (true):
SetRespondentValue("__CAPINoOverwrite", "1");
When this is enabled, CAPI will not upload the local participant during synchronization. If the participant is opened in CAPI, a message appears stating that uploads are blocked, and the user won't be able to make further changes.
2: Merge Participant Data from CAWI
CAPI now supports updating individual participant variables, even if the participant has already been resumed on CAPI.
To enable this, create a companion tracking variable using the naming pattern [variableName]__changed. For example:
Main variable: q1
Tracking variable: q1__changed
When updating a variable:
SetRespondentValue("q1", "newvalue");
SetRespondentValue("q1__changed", new Date().toISOString());
During sync, CAPI compares timestamps of the __changed variables. If the server version is newer, CAPI will update the variable locally:
If server.q1__changed > capi.q1__changed:
capi.q1 = server.q1
capi.q1__changed = server.q1__changed
3: Automatically Trigger Synchronization
To trigger a sync action automatically whenever a participant is closed (regardless of status), use:
SetSurveyDeviceVariable("__systemSyncOnClose", "true");
This is equivalent to tapping the Sync button manually from the Home screen.
4: Send Data to Another App
var customData = {
'ExternalAppPackage': 'com.confirmit.capitestapp',
'ExternalAppActivity': 'com.confirmit.capitestapp.MainActivity',
'CustomKey': 'Value'
};'
NotifyNativeApp('app', 'sendToExternalApp', customData);
5: Hide Pause Interview Menu Option
To hide the Pause interview menu in the CAPI App:
SetSurveyDeviceVariable("__systemShowPostponeMenu", "false");
Default value: true
6: Hide Cancel Interview Menu Option
To hide the Cancel interview menu in the CAPI App:
SetSurveyDeviceVariable("__systemShowCancelMenu", "false");
Default value: true
7: Clone Participant on Server Completion
When a participant is completed on both CAWI and CAPI, synchronization won't upload the CAPI version to avoid overwriting the complete server version. If the CAPI version contains important local data, you can enable automatic cloning:
SetSurveyDeviceVariable("__systemCloneOnServerCollision", "true");
This creates a cloned participant (with a new rowGUID) if the server version is already marked as complete.
8: Survey Overview - Custom Variable Counts
Overview tab – Custom Variable Counts
It is now possible to display counts for a specific survey variable.
Define the list of answer item labels to display and the value as defined for the variable:
var answerItems = [{ label: "No one home", value: "1" },
{ label: "Busy, come back later", value: "2" },
{ label: "Will not respond", value: "3" } ];
Indicate which survey variable counts to display and include the answer items defined above. In the following example, the survey question ID is “LastOutcome”
var jsonString = JSON.stringify({
variable: {
id: "LastOutcome",
label: "Last Outcome Counts"
},
answerItems
})
Finally, apply this definition to a reserved device variable
SetSurveyDeviceVariable("__systemOverviewTabVariable", jsonString)
Optionally, you can hide the default summary stats. The following example will hide the stats:
SetSurveyDeviceVariable("__systemOverviewTabShowStats", "0")
Requirements:
The variable must be of type single or multi choice
The variable must be a respondent variable and shown on the Respondent tab
The information displayed will be the counts of each category item associated with the variable and will only be data contained on the current device (so essentially only data shown on Respondent tab). For example, if a respondent is unassigned, the counts shown on the Overview tab would adjust to reflect only what is current on the device.
Only one variable can be designated per survey
9: Set Default Respondent Tab Filter
To support advanced multiple respondent workflows, it is now possible to set the default Respondent tab filter via survey scripting. A new reserved system device variable has bee introduced - __systemRespondentFilter
An example of setting the filter to only show respondents where background variable 'household'= '2'
var filter = {'household': '2'}
SetSurveyDeviceVariable("__systemRespondentFilter",JSON.stringify(filter))CAPI users can manually change the filter at any time through the user interface. The manuall set filter will be retained unless the survey device variable is set again during the survey execution.
10: Merge Server Response Data on CAPI Sync
It is now possible to have CAWI (server) response data merged with CAPI (local) response data. This can be helpful in situations where the same survey respondent is being completed on both CAWI and CAPI. However, it is best reserved for situations where different questions are asked on CAWI than CAPI.
To get started, add a new respondent (background) variable to your survey: __CAPIMergeServerResponse
The data merge feature is enabled per respondent, to enable, set this variable to enabled / “1”:
SetRespondentValue("__CAPIMergeServerResponse", "1");
During synchronization, provided the response on CAWI and CAPI is not complete, CAPI app will:
Download the response from CAWI
If __CAPIMergeServerResponse = “1”, for each question, if the existing CAPI value is blank, null, or unanswered, copy the CAWI value
As part of normal sync process, upload the response to CAWI
At this point, the response on CAWI and CAPI will be the same.
Please note that the reserved system variables will not be modified. For example, the dropout question will be different if the respondent reached Q10 on CAWI but only Q5 on CAPI, the dropout question will still appear as Q10.
Note that only response data can be merged, respondent data is not available for merging.
11: Open a Respondent in CAPI from Another App
On an Android device, you can open a CAPI respondent's interview directly from another application. A common use case for CAPI is for on-site door-to-door interviews. If you use a separate field work application and want to automatically load a respondent within CAPI, you can do this on an Android device using a deeplink.
You will need to know your projectID and the respondentID. You can use the deep link from within the source app or from a web browser.
For example, if the projectID is p123456789 and the respondentID is 1234, the deeplink would be:
forsta://capiapp?projectId=p123456789&respondentId=1234
Alternatively, in situations where an interviewer receives a pre-loaded assignment of addresses within CAPI, use the window.open() JavaScript function to show the interviewer on a map where to proceed.
12: Force Overwrite CAPI Response
In the situation where a respondent is in progress in CAPI but it is determined that the in-progress response should be cleared and restarted, deleting the response on the server will not automatically clear the response on CAPI. In these situations, it is generally recommended to create a new respondent and flag the original unwanted respondent as archived by introducing a hidden variable to track the status as desired.
However, if it is determined that the original respondent needs to be retained and the response to be cleared on CAPI, a reserved variable can be used. In your survey:
Add a respondent variable to the survey: __CAPIResponseOverwrite
Assign the value to any string value, suggestion would be the current date as a way to record when this action was taken – e.g. “19Jun2025”
When a sync is performed for a user assigned to this respondent, if the server respondent is not empty and the value of __CAPIResponseOverwrite is not equal to the CAPI local respondent __CAPIResponseOverwrite value then CAPI will proceed to overwrite both the local respondent and response with the respondent and response downloaded from the server.
Example Scenario
CAPI user partially completes response, sync
Data was not collected properly, field manager needs to correct
In Survey Designer, delete response and set __CAPIResponseOverwrite = "19Jun2025" indicating that the response should be restarted as of todays date.
-
CAPI user syncs
because server __CAPIResponseOverwrite has a value and is different than local value … CAPI deletes the local response and respondent
CAPI user resumes, partially completes
-
CAPI user syncs
because server __CAPIResponseOverwrite is the same as local value … CAPI takes no action
Respondent and response are uploaded (and overwrite server as normal)
-
If field manager needs to delete response again
set __CAPIResponseOverwrite to another value other than the previous value used (e.g. “20Jun2025”).
Because server value is different than local, the same overwrite procedure above will occur.
13: Pause Interview - Disable Description Text Requirement
When selecting menu > Pause Interview, the Postpone Interview dialog displays a text field to allow the interviewer to provide a reason for postponing the interview. This field is required by default. To disable the description field from being required, add the following to your survey:
The default description text applied to the respondent will be “postponed”
SetSurveyDeviceVariable("__systemPostponeMenuReasonRequired","false")