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
Query Past Survey Answers
Delete a Survey Result
Query Survey Tasks

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 Views

MyDataHelps Embeddables

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. 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 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 Fields

result.surveyAnswers collection

A list of SurveyAnswers filtered by the query parameters.

+ Element Fields

result.surveyAnswers[n].id guid

Identifier for this survey answer.

result.surveyAnswers[n].participantID guid

Internal 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.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 Views

MyDataHelps Embeddables

Web View Steps

    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);
	} );
  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
}
  {
  "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.

Warning
This operation CANNOT be undone.

Parameters

id guid (required)

ID for the survey result to delete.

Availability

MyDataHelps Views

MyDataHelps Embeddables

Web View Steps

    Deleting a Survey Result 
    
  

    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.

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 Fields

result.surveyTasks collection

A list of survey tasks filtered by the query parameters.

+ Element Fields

result.surveyTasks[n].id guid

Identifier for this survey task.

result.surveyTasks[n].participantID guid

Internal ID 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 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.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 Views

MyDataHelps Embeddables

Web View Steps

    Querying Completed Survey Tasks 
    
  

    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);
	} );

    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)",
      "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"
    }
  ],
  "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"
    }
  ],
  "nextPageID": null
}