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

Start a Survey

MyDataHelps.startSurvey(surveyName)

Launch a specific survey for the user to complete.

If the survey is associated with a task, this operation will launch that survey task. Submitting the results will mark the task as complete.

Survey Options

The launch behavior can be customized with the options parameter.

Passing editResultID effectively allows the participant to edit previous results. It will launch the survey with prior results already loaded (based on the specified survey result ID). Submitting the survey will overwrite those previous results. The specified result ID must exist, or an error will result.

The event parameter is a way of associating the saved result with a Survey Event. However, it works differently depending on whether the survey is configured as Single-Entry or Multi-Entry.

Multi-Entry - Associates the saved result with the specified event.
Single-Entry - If there is a prior result for this combination of survey/event, MyDataHelps will launch the survey with the prior results already loaded. Submitting the survey will replace the prior result. If no prior result exists, the system will automatically launch a new survey and associate the saved results with the event. This is similar to passing editResultID, but saves you from having to look up the prior result ID and check that it exists.

Tip
If you pass editResultID, then event is ignored; the survey will keep whatever event the prior results were associated with.

Parameters

surveyName string (required)

The survey to start.

options

Additional survey options. Omit this parameter to use default options.

Child Fields

options.editResultID string

Associated result ID. See method description for usage details.

options.event string

Associated survey event. See method description for usage details.

Availability

MyDataHelps Views

MyDataHelps Embeddables

Web View Steps

    Starting a Survey
    
  

    // Launches a new survey
MyDataHelps.startSurvey("My Survey");

// Edits an existing survey result
var surveyResultId = "38d0ade3-4d24-4ab6-adf1-7f9d4b0ceea3";
MyDataHelps.startSurvey("My Survey", { editResultID: surveyResultId });

// Opens an existing Single-Entry survey by event
MyDataHelps.startSurvey("My Survey", { event: "First Visit" });
  
// Launches a new survey
MyDataHelps.startSurvey("My Survey");

// Edits an existing survey result
var surveyResultId = "38d0ade3-4d24-4ab6-adf1-7f9d4b0ceea3";
MyDataHelps.startSurvey("My Survey", { editResultID: surveyResultId });

// Opens an existing Single-Entry survey by event
MyDataHelps.startSurvey("My Survey", { event: "First Visit" });

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

Search for answers from surveys matching one of the specified survey names.

event string array

Search for answers associated with one of the specified survey events.

before date

Filters answers to only those recorded by the participant on or before this date.

after date

Filters answers to only those recorded by the participant on or after this date.

insertedBefore date

Filters answers to only those submitted to the system on or before this date.

insertedAfter date

Filters answers to only those submitted to the system on or 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.

Child Fields

result.surveyAnswers collection

A list of SurveyAnswers filtered by the query parameters.

Child Fields

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].participantIdentifier guid

Project-set, unique participant identifier.

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].insertedDate date

Date when the survey answer was added to the system.

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.

Child Fields

result.surveyAnswers[n].schedule.id guid

Unique identifier for the schedule.

result.surveyAnswers[n].schedule.name string

Schedule name.

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.surveyAnswers[n].event string

Shows if the answer is associated with a survey event.

result.surveyAnswers[n].type string

Survey question type (e.g., Question, WebView, etc.)

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: "Sleep Quality",
	after: "2020-02-16T16:00:00+04:00",
	before: "2020-04-20",
	stepIdentifier: "MoodRating",
	resultIdentifier: "MoodRating"
};

MyDataHelps.querySurveyAnswers(queryParameters)
	.then( function(result) {
		console.log(result);
	} );
  var queryParameters = {
	surveyResultID: "92f2e02c-256b-eb11-aa7f-f8e4e3480e0d",
	surveyID: "6ff871f4-e35b-4f14-b055-075f009c2192",
	surveyName: "Sleep Quality",
	after: "2020-02-16T16:00:00+04:00",
	before: "2020-04-20",
	stepIdentifier: "MoodRating",
	resultIdentifier: "MoodRating"
};

MyDataHelps.querySurveyAnswers(queryParameters)
	.then( function(result) {
		console.log(result);
	} );

    Console Output
    
  

    {
  "surveyAnswers": [
    {
      "id": "6b7b384c-1874-ea11-aa92-0afb9334277d",
      "participantID": "82320a5b-4d6a-eb11-aa7f-f8e4e3480e0d",
      "surveyResultID": "92f2e02c-256b-eb11-aa7f-f8e4e3480e0d",
      "surveyID": "6ff871f4-e35b-4f14-b055-075f009c2192",
      "surveyVersion": 4,
      "taskID": "9bd5cf4f-d606-ea11-8184-9494f135fa19",
      "surveyName": "Sleep Quality",
      "surveyDisplayName": "Sleep Quality",
      "date": "2020-04-01T08:57:10-04:00",
      "stepIdentifier": "MoodRating",
      "resultIdentifier": "MoodRating",
      "answers": [ "7" ],
      "insertedDate": "2020-04-01T12:57:12.603Z",
      "schedule": null,
      "type": "Question",
      "participantIdentifier": "PT-345"
    }
  ],
  "nextPageID": null
}
  {
  "surveyAnswers": [
    {
      "id": "6b7b384c-1874-ea11-aa92-0afb9334277d",
      "participantID": "82320a5b-4d6a-eb11-aa7f-f8e4e3480e0d",
      "surveyResultID": "92f2e02c-256b-eb11-aa7f-f8e4e3480e0d",
      "surveyID": "6ff871f4-e35b-4f14-b055-075f009c2192",
      "surveyVersion": 4,
      "taskID": "9bd5cf4f-d606-ea11-8184-9494f135fa19",
      "surveyName": "Sleep Quality",
      "surveyDisplayName": "Sleep Quality",
      "date": "2020-04-01T08:57:10-04:00",
      "stepIdentifier": "MoodRating",
      "resultIdentifier": "MoodRating",
      "answers": [ "7" ],
      "insertedDate": "2020-04-01T12:57:12.603Z",
      "schedule": null,
      "type": "Question",
      "participantIdentifier": "PT-345"
    }
  ],
  "nextPageID": null
}

Query Survey Results

MyDataHelps.querySurveyResults(queryParams)

Parameters

surveyID guid

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

surveyName string array

Search for results from surveys matching one of the specified survey names.

event string array

Search for results associated with one of the specified survey events.

before date

Filters results to only those recorded by the participant on or before this date.

after date

Filters results to only those recorded by the participant on or after this date.

insertedBefore date

Filters results to only those submitted to the system on or before this date.

insertedAfter date

Filters results to only those submitted to the system on or after this date.

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<SurveyResultsPage>

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

Child Fields

result.surveyResults collection

A list of SurveyResults filtered by the query parameters.

Child Fields

result.surveyResults[n].id guid

Identifier for this survey result.

result.surveyResults[n].participantID guid

Internal, stable, unique ID for the participant submitting the answer.

result.surveyResults[n].participantIdentifier guid

Project-set, unique participant identifier.

result.surveyResults[n].surveyID guid

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

result.surveyResults[n].surveyVersion int

Version number of the survey that the participant completed.

result.surveyResults[n].taskID guid

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

result.surveyResults[n].surveyName string

Name for the survey in MyDataHelps.

result.surveyResults[n].surveyDisplayName string

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

result.surveyResults[n].date date

Date and time at which the survey result was recorded by the participant.

result.surveyResults[n].insertedDate date

Date and time at which the survey result was submitted to the system.

result.surveyResults[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.

Child Fields

result.surveyResults[n].schedule.id guid

Unique identifier for the schedule.

result.surveyResults[n].schedule.name string

Schedule name.

result.surveyResults[n].schedule.category string

User-assigned category for the schedule (optional).

result.surveyResults[n].schedule.interval integer

result.surveyResults[n].schedule.intervalType string

Units for interval. May be days, weeks, months, or years.

result.surveyResults[n].event string

Shows if the result is associated with a survey event.

result.surveyResults[n].userType string

Type of user that created the survey result. Can be one of: Participant, Coordinator, ServiceAccount (for automated submissions).

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 Survey Results
    
  

    var queryParameters = {
	surveyName: "Sleep Time"
};

MyDataHelps.querySurveyTasks(queryParameters)
	.then( function(result) {
		console.log(result);
	} );
  var queryParameters = {
	surveyName: "Sleep Time"
};

MyDataHelps.querySurveyTasks(queryParameters)
	.then( function(result) {
		console.log(result);
	} );

    Console Output
    
  

    {
  "surveyResults": [
    {
      "id": "8aad757b-cb22-eb11-aa9e-0afb9334277d",
      "participantID": "82320a5b-4d6a-eb11-aa7f-f8e4e3480e0d",
      "participantIdentifier": "PT-345",
      "taskID": null,
      "surveyID": "6ff871f4-e35b-4f14-b055-075f009c2192",
      "surveyVersion": 8,
      "surveyName": "Sleep Time",
      "surveyDisplayName": "Sleep Time",
      "date": "2020-11-09T15:38:19-05:00",
      "insertedDate": "2020-11-09T20:38:19.657Z",
      "schedule": {
          "id": "a843df73-07c2-45a3-9808-98745fafc766",
          "name": "Weekly",
          "category": "Phase 1",
          "interval": 1,
          "intervalType": "Week"
      },
      "userType": "Participant"
    }
  ],
  "nextPageID": null
}
  {
  "surveyResults": [
    {
      "id": "8aad757b-cb22-eb11-aa9e-0afb9334277d",
      "participantID": "82320a5b-4d6a-eb11-aa7f-f8e4e3480e0d",
      "participantIdentifier": "PT-345",
      "taskID": null,
      "surveyID": "6ff871f4-e35b-4f14-b055-075f009c2192",
      "surveyVersion": 8,
      "surveyName": "Sleep Time",
      "surveyDisplayName": "Sleep Time",
      "date": "2020-11-09T15:38:19-05:00",
      "insertedDate": "2020-11-09T20:38:19.657Z",
      "schedule": {
          "id": "a843df73-07c2-45a3-9808-98745fafc766",
          "name": "Weekly",
          "category": "Phase 1",
          "interval": 1,
          "intervalType": "Week"
      },
      "userType": "Participant"
    }
  ],
  "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

Search for tasks from surveys matching one of the specified survey names.

surveyCategory string

Search for tasks from a given survey category.

event string array

Search for tasks associated with one of the specified survey events.

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.

Child Fields

result.surveyTasks collection

A list of survey tasks filtered by the query parameters.

Child Fields

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.

Child Fields

result.surveyTasks[n].schedule.id guid

Unique identifier for the schedule.

result.surveyTasks[n].schedule.name string

Schedule name.

result.surveyTasks[n].schedule.category string

User-assigned category for the schedule (optional).

result.surveyTasks[n].schedule.interval integer

result.surveyTasks[n].schedule.intervalType string

Units for interval. May be days, weeks, months, or years.

result.surveyTasks[n].event string

Shows if the task is associated with a survey event.

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",
      "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
}