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 MyDataHelps studies, we strongly recommend reading about survey data concepts.
Contents
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
The survey to start.
Availability
Complete a Web View Step
MyDataHelps.completeStep(optionalAnswerText)
Complete the current survey step. If called with a parameter, that parameter is used as the answer for the step. If no parameter is supplied, then an empty string is used as the answer for the step.
Parameters
The single answer to record for this step. If omitted, an empty string is recorded as the answer for the step.
Availability
<script type="text/javascript">
function next() {
var element = document.getElementById("StepInput");
var answerText = element.value;
MyDataHelps.completeStep(answerText);
}
function skip() {
MyDataHelps.completeStep();
}
</script>
<input type="text" id="StepInput" placeholder="Answer text" />
<button onclick="next()">Next</button>
<button onclick="skip()">Skip</button><script type="text/javascript">
function next() {
var element = document.getElementById("StepInput");
var answerText = element.value;
MyDataHelps.completeStep(answerText);
}
function skip() {
MyDataHelps.completeStep();
}
</script>
<input type="text" id="StepInput" placeholder="Answer text" />
<button onclick="next()">Next</button>
<button onclick="skip()">Skip</button>
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
Identifier for the survey response containing the answer.
Identifier for the survey for which the survey result was submitted.
List of names for the surveys which have the answers.
Filters answers to only those submitted before this date.
Filters answers to only those submitted after this date.
List of identifiers for the survey step for which answers were submitted. Refers to the step identifier field in the MyDataHelps survey editor.
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.
List of matching answer values.
How many entries to include in each page of results. Default and maximum is 100.
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
Resolves to a result object containing a page of survey answers.
A list of SurveyAnswers filtered by the query parameters.
Identifier for this survey answer.
Internal ID for the participant submitting the answer.
Identifier for the survey submission containing this answer.
Identifier for the survey containing the step this answer was provided for.
Version number of the survey that the participant completed.
Identifier for the task which prompted the participant to complete the survey, if any.
Name for the survey in MyDataHelps.
Name of the survey as it was displayed to the participant.
Date and time at which the survey answer was submitted. Different from the time at which the whole survey was submitted.
Identifier for the survey step for which the answer was submitted.
Identifier for the field on the survey step which contains this survey answer.
List of answers for this result.
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
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);
} );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);
} );
{
"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
}{
"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 MyDataHelps’s Survey Editor.
This operation CANNOT be undone.
Parameters
ID for the survey result to delete.
Availability
var surveyResultId = "38d0ade3-4d24-4ab6-adf1-7f9d4b0ceea3";
MyDataHelps.deleteSurveyResult(surveyResultId)
.then( function() {
console.log("Survey Result deleted");
} );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
Describes whether the task is open or closed. If provided, must be one of “Incomplete”, “Closed” or “Complete”.
Identifier for the survey which this task assigns.
List of survey names which tasks have assigned.
Secure and unique identifier for the task, to be used publicly when providing links to a survey.
Return results in the specified order, sorted by when the task was first created. Must be either “Descending” or “Ascending”. Defaults to “Descending”.
How many entries to include in each page of results. Default and maximum is 100.
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
Resolves to a result object containing a page of survey tasks.
A list of survey tasks filtered by the query parameters.
Identifier for this survey task.
Internal ID for the participant assigned this task.
Project-specific participant identifier.
Secure and unique identifier for the Task, to be used publicly when providing links to a survey.
Identifier for the survey which this task assigns.
Name for the survey in MyDataHelps which this task assigns.
Display name of the corresponding survey.
Brief explanation of the survey provided to the participant.
When the participant first began completing the survey task.
When the participant finished the survey.
Describes whether the participant has not completed the task (“Incomplete”), the task was closed (“Closed”) or the participant completed it (“Complete”).
Indicates that the participant has opened the assigned survey and submitted at least one answer, without completing the task.
Date the survey task is due.
Date when the survey task was first created.
Date when the survey task was last modified.
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
var queryParameters = {
status: "Complete"
};
MyDataHelps.querySurveyTasks(queryParameters)
.then( function(result) {
console.log(result);
} );var queryParameters = {
status: "Complete"
};
MyDataHelps.querySurveyTasks(queryParameters)
.then( function(result) {
console.log(result);
} );
{
"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
}{
"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
}
