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.
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)
Availability
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. This method applies to past completed instances of the survey. In a Web View step, use Get Current Survey Answers for the current survey.
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 MyDataHelps 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 as 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
Internal, stable, unique ID 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 MyDataHelps.
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.surveyAnswers[n].schedule
Contains details about the schedule that triggered the survey, if applicable. Will be null if the survey was not triggered by a schedule.
result.surveyAnswers[n].schedule.id
guid
Unique identifier for the schedule.
result.surveyAnswers[n].schedule.name
string
result.surveyAnswers[n].schedule.category
string
User-assigned category for the schedule (optional).
result.surveyAnswers[n].schedule.interval
integer
How often the survey is delivered, based on the interval type. For example, if intervalType is Weeks and interval is 4, it means the survey repeats every 4 weeks. Will be null if the schedule does not repeat.
result.surveyAnswers[n].schedule.intervalType
string
Units for interval. May be Days, Weeks, Months, or Years.
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
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"
],
"schedule": {
"id": "a843df73-07c2-45a3-9808-98745fafc766",
"name": "Weekly",
"category": "Phase 1",
"interval": 1,
"intervalType": "Week"
}
}
],
"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"
],
"schedule": {
"id": "a843df73-07c2-45a3-9808-98745fafc766",
"name": "Weekly",
"category": "Phase 1",
"interval": 1,
"intervalType": "Week"
}
}
],
"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.
Warning
This operation CANNOT be undone.
Parameters
id
guid
(required)
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
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.
surveyCategory
string
Search for tasks from a given survey category.
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 as 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
Internal, stable, unique ID for the participant assigned this task.
result.surveyTasks[n].participantIdentifier
string
Project-set, unique 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 MyDataHelps which this task assigns.
result.surveyTasks[n].surveyCategory
string
The survey’s category, if set.
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.surveyTasks[n].schedule
Contains details about the schedule that triggered the survey, if applicable. Will be null if the survey was not triggered by a schedule.
result.surveyTasks[n].schedule.id
guid
Unique identifier for the schedule.
result.surveyTasks[n].schedule.name
string
result.surveyTasks[n].schedule.category
string
User-assigned category for the schedule (optional).
result.surveyTasks[n].schedule.interval
integer
How often the survey is delivered, based on the interval type. For example, if intervalType is Weeks and interval is 4, it means the survey repeats every 4 weeks. Will be null if the schedule does not repeat.
result.surveyTasks[n].schedule.intervalType
string
Units for interval. May be Days, Weeks, Months, or Years.
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
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)",
"surveyCategory": "Daily",
"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",
"schedule": {
"id": "a843df73-07c2-45a3-9808-98745fafc766",
"name": "Weekly",
"category": "Phase 1",
"interval": 1,
"intervalType": "Week"
}
}
],
"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)",
"surveyCategory": "Daily",
"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",
"schedule": {
"id": "a843df73-07c2-45a3-9808-98745fafc766",
"name": "Weekly",
"category": "Phase 1",
"interval": 1,
"intervalType": "Week"
}
}
],
"nextPageID": null
}