Surveys

In MyDataHelps, participants typically contribute data by completing surveys. These surveys can be completed in mobile apps, in web browsers, and even by project coordinators on the participants’ behalf.

Because surveys are a fundamental part of RKStudio studies, we strongly recommend reading about survey data concepts.

Start a Survey

MyDataHelps.startSurvey(surveyName)

Launch a specific survey for the user to complete.

If the user was assigned this survey in a task, then this operation will open that task. If no task already exists, the completed survey will be stored without any associated task.

Parameters

surveyName string (required)

The survey to start.

Availability

MyDataHelps Applications
Web View Steps

Query Past Survey Answers

MyDataHelps.querySurveyAnswers(queryParameters)

Retrieve the participant’s responses to QuestionSteps, FormSteps, or WebViewSteps. Often this is used to display past answers to the participant.

Parameters

surveyResultID guid

Identifier for the survey response containing the answer.

surveyID guid

Identifier for the survey for which the survey result was submitted.

surveyName string array

List of names for the surveys which have the answers.

before date

Filters answers to only those submitted before this date.

after date

Filters answers to only those submitted after this date.

stepIdentifier string array

List of identifiers for the survey step for which answers were submitted. Refers to the step identifier field in the RKStudio survey editor.

resultIdentifier string array

List of identifiers for the field on the survey step for which answers were submitted. Relevant for form steps, and refers to their form items’ identifier field.

answer string array

List of matching answer values.

limit int

How many entries to include in each page of results. Default and maximum is 100.

pageID guid

Each page of results will return a nextPageID if there are additional pages that can be queried. Supply that to pageID to query the next page. When excluded, retrieves the first page.

Returns

Promise<SurveyAnswersPage>

Resolves to a result object containing a page of survey answers.

result.surveyAnswers collection

A list of SurveyAnswers filtered by the query parameters.

result.surveyAnswers[n].id guid

Identifier for this survey answer.

result.surveyAnswers[n].participantID guid

Identifier for the participant submitting the answer.

result.surveyAnswers[n].surveyResultID guid

Identifier for the survey submission containing this answer.

result.surveyAnswers[n].surveyID guid

Identifier for the survey containing the step this answer was provided for.

result.surveyAnswers[n].surveyVersion int

Version number of the survey that the participant completed.

result.surveyAnswers[n].taskID guid

Identifier for the task which prompted the participant to complete the survey, if any.

result.surveyAnswers[n].surveyName string

Name for the survey in RKStudio.

result.surveyAnswers[n].surveyDisplayName string

Name of the survey as it was displayed to the participant.

result.surveyAnswers[n].date date

Date and time at which the survey answer was submitted. Different from the time at which the whole survey was submitted.

result.surveyAnswers[n].stepIdentifier string

Identifier for the survey step for which the answer was submitted.

result.surveyAnswers[n].resultIdentifier string

Identifier for the field on the survey step which contains this survey answer.

result.surveyAnswers[n].answers string array

List of answers for this result.

result.nextPageID guid

An ID to be used with subsequent queries. Results from queries using this ID as the pageID parameter will show the next page of results. This field is null if there isn’t a next page.

Availability

MyDataHelps Applications
Web View Steps
Example: Retrieving a Specific Survey Answer
var queryParameters = {
	surveyResultID: "92f2e02c-256b-eb11-aa7f-f8e4e3480e0d",
	surveyID: "6ff871f4-e35b-4f14-b055-075f009c2192",
	surveyName: "MyProject Daily Survey",
	after: "2021-02-16T16:00:00+04:00",
	before: "2021-02-20",
	stepIdentifier: "MoodRating",
	resultIdentifier: "MoodRating",
	answer: "7"
};

MyDataHelps.querySurveyAnswers(queryParameters)
	.then( function(result) {
		console.log(result);
	} );
Console Output
{
	"surveyAnswers": [ 
	{ 
		"id": "f1f2e02c-256b-eb11-aa7f-f8e4e3480e0d", 
		"participantID": "82320a5b-4d6a-eb11-aa7f-f8e4e3480e0d",
		"surveyResultID": "92f2e02c-256b-eb11-aa7f-f8e4e3480e0d",
		"surveyID": "6ff871f4-e35b-4f14-b055-075f009c2192",
		"surveyVersion": 1,
		"taskID": null, 
		"surveyName": "MyProject Daily Survey", 
		"surveyDisplayName": "Daily Mood Report", 
		"date": "2021-02-11T09:32:55.205-05:00",
		"stepIdentifier": "MoodRating", 
		"resultIdentifier": "MoodRating", 
		"answers": ["7"] 
	} ], 
	"nextPageID": null
}

Delete a Survey Result

MyDataHelps.deleteSurveyResult(surveyResultID)

This feature is only available for surveys with “Results Can Be Deleted” enabled. This option can be enabled from the Settings pane in RKStudio’s Survey Editor.

Parameters

id guid (required)

ID for the survey result to delete.

Availability

MyDataHelps Applications
Web View Steps
Example: Deleting a Survey Result
var surveyResultId = "38d0ade3-4d24-4ab6-adf1-7f9d4b0ceea3";

MyDataHelps.deleteSurveyResult(surveyResultId)
	.then( function() {
		console.log("Survey Result deleted");
	} );

Query Survey Tasks

Query for a list of tasks, often used to show a participant a list of specific types of tasks.

MyDataHelps.querySurveyTasks(queryParameters)

Parameters

status enum

Describes whether the task is open or closed. If provided, must be one of “Incomplete”, “Closed” or “Complete”.

surveyID guid

Identifier for the survey which this task assigns.

surveyName string array

List of survey names which tasks have assigned.

linkIdentifier string

Secure and unique identifier for the task, to be used publicly when providing links to a survey.

sortOrder enum

Return results in the specified order, sorted by when the task was first created. Must be either “Descending” or “Ascending”. Defaults to “Descending”.

limit int

How many entries to include in each page of results. Default and maximum is 100.

pageID guid

Each page of results will return a nextPageID if there are additional pages that can be queried. Supply that to pageID to query the next page. When excluded, retrieves the first page.

Returns

Promise<SurveyTasksPage>

Resolves to a result object containing a page of survey tasks.

result.surveyTasks collection

A list of survey tasks filtered by the query parameters.

result.surveyTasks[n].id guid

Identifier for this survey task.

result.surveyTasks[n].participantID guid

Auto-generated, globally-unique identifier for the participant assigned this task.

result.surveyTasks[n].participantIdentifier string

Project-specific participant identifier.

result.surveyTasks[n].linkIdentifier string

Secure and unique identifier for the Task, to be used publicly when providing links to a survey.

result.surveyTasks[n].surveyID guid

Identifier for the survey which this task assigns.

result.surveyTasks[n].surveyName string

Name for the survey in RKStudio which this task assigns.

result.surveyTasks[n].surveyDisplayName string

Display name of the corresponding survey.

result.surveyTasks[n].surveyDescription string

Brief explanation of the survey provided to the participant.

result.surveyTasks[n].startDate date

When the participant first began completing the survey task.

result.surveyTasks[n].endDate date

When the participant finished the survey.

result.surveyTasks[n].status string

Describes whether the participant has not completed the task (“Incomplete”), the task was closed (“Closed”) or the participant completed it (“Complete”).

result.surveyTasks[n].hasSavedProgress bool

Indicates that the participant has opened the assigned survey and submitted at least one answer, without completing the task.

result.surveyTasks[n].dueDate date

Date the survey task is due.

result.surveyTasks[n].insertedDate date

Date when the survey task was first created.

result.surveyTasks[n].modifiedDate date

Date when the survey task was last modified.

result.nextPageID guid

An ID to be used with subsequent queries. Results from queries using this ID as the pageID parameter will show the next page of results. This field is null if there isn’t a next page.

Availability

MyDataHelps Applications
Web View Steps
Example: Querying Completed Survey Tasks
var queryParameters = {
	status: "Complete"
};

MyDataHelps.querySurveyTasks(queryParameters)
	.then( function(result) {
		console.log(result);
	} );
Console Output
{ 
	"surveyTasks": [ 
		{ 
			"id": "2cd02098-336b-eb11-aa7f-f8e4e3480e0d",
			"participantID": "82320a5b-4d6a-eb11-aa7f-f8e4e3480e0d",
			"participantIdentifier": "Wave2Row13",
			"linkIdentifier": null,
			"surveyID": "95300a5b-4d6a-eb11-aa7f-f8e4e3480e0d",
			"surveyName": "Web Update (Control)",
			"surveyDisplayName": "Weekly Update",
			"surveyDescription": "Basic weekly update questions.",
			"startDate": null,
			"endDate": null,
			"status": "incomplete",
			"hasSavedProgress": true,
			"dueDate": "2021-02-24T00:04:51.358+00:00",
			"insertedDate": "2021-02-10T00:04:51.5Z",
			"modifiedDate": "2021-02-10T00:04:51.5Z"
	} ], 
	"nextPageID": null
}