GetResponse4()

The purpose of GetResponse4() is to export the fillout task response data for projects. GetResponse4() is an extension of GetResponse3() with the following new features:

1. Response data for Personalized questions and question bank questions.
2. Response data for date/time questions.
3. Response records for invited raters that did not respond.
4. Subject ID and user ID without a datasource prefix.
5. An option to use the question identifier as a column header rather than the question title.
6. The ability to select which response data to include by listing the identifier for each question.
7. Options related to handling Personalized questions and question bank questions response data.
8. A log file in the ZIP file that provides a listing of any errors or warnings that occur.
9. Responses which are removed are not exported.

Compatible with Blue 5.5.4.03 and newer.

Output:

GetResponse4() generates a ZIP file which contains base64 encoded text files.

Contained within the ZIP file are the following files:

• MessageLog.txt - displays useful system information and non-critical messages. It will log all the input parameters used to generate the response file.
• ErrorLog.txt - file is created when critical errors are encountered that prevent the data from being exported into files.
• Results.csv - if GetResponse4 is set to export to separate files, the responses are split into 2 files: SingleSubject.csv (usually for course responses) and MultipleSubject.csv (usually for instructor responses).

GetResponse4() can only export response data for private projects with tasks. One record will be generated for each invited user whether they responded to the fillout task or not.

Response data from projects that do not have any secondary subjects will be output to a single file. The output generated for response data from projects with secondary subjects will vary depending on the value of the “ExportToSeparateFiles” option.

If the value is “false”, the response data for the primary subject is replicated in instances where there are multiple secondary subjects and only a single file is generated.

If the value is “true”, the response data for the primary subjects is output to one file and the response data for the secondary subjects is output to a separate file.

For surveys, the following data is included in the output:

• UserID
• UserName
• Group
• TaskStatus
• FillOutDate
• Question Responses

For all other projects, the following data is included in the output:

• SubjectID
• SecondarySubjectID
• UserID
• UserName
• Group
• TaskStatus
• FillOutDate
• Question Responses

Fields

• UserID - identifies the primary task owner for the fillout task. The UserID is exported without the datasource prefix.
• UserName - is the primary task owner’s first name and last name.
• SubjectID - identifies the primary subject and, like the UserID, does not include the datasource prefix.
• SecondarySubjectID - is only included if the project contains a secondary subject. It identifies the secondary subject and does not include the datasource prefix.
• Group - is only included if more than one group is assigned Fillout task privileges. The column displays the group caption.
• TaskStatus - indicates the status of the response data for this task. The following values may be returned:
  • DNR - The user did not respond.
  • Saved - The user saved their responses but did not complete their task by submitting them.
  • Submitted - The user completed their Fillout task by submitting their responses.

• FillOutDate - The date format is defined by the “DateFormatStr” input parameter.

Question Responses

Column headers

If the UseQuestionIdentifier input parameter is set to false or is not set, the column headers for the questions will show “Q question number question title”. Spaces are replaced by underscores. Example: “Q3_What_is_your_age”. The question number is determined by the order in which the question was created.

If the UseQuestionIdentifier input parameter is set to true, the column headers for the questions will show the identifiers for each question. If the question does not have an identifier, the column header will be generated as if the UseQuestionIdentifier parameter was set to false.

Special System Responses

Under certain circumstances, the system will generate response data for a particular question. The two system responses are:

• N/A - Not applicable.
• D/A - Did not answer.

Unique Column Names

The column headers generated for the response data must be unique. If duplicates are detected, the column headers will be suffixed with a “_x” “number” and a warning will be included in the error log. For example, there are two questions with the identifier “qrt001”. The first column header will be “qrt001_x1” and the second column header will be “qrt001_x2” and a warning will be added to the log file.

Question Personalization

Each personalized question consists of two columns: the first column contains the title of the question and the second column contains the response.

When using the question title

The column header for the title of the question will be generated as “Q” “number of question” “_QPTitle”. The response column header will be generated as “Q” “number of question” “_QPResp”.

When using the question identifier

The column header for the title of the question will be generated as “question identifier” “_QPTitle”. The response column header will be generated as “question identifier” “_QPResp”.

Question bank

Each question bank question consists of two columns: the first column contains the title of the question and the second column contains the response.

When using the question title

The column header for the title of the question will be generated as “Q” “number of question” “_QbTitle”. The response column header will be generated as “Q” “number of question” “_QbResp”.

When using the identifier

The column header for the title of the question will be generated as “question identifier” “_QbTitle”. The response column header will be generated as “question identifier” “_QbResp”.

Responses which are removed

The GetResponse4 webservice does not export responses which are considered removed.

A response is considered removed if:

1. The primary or secondary subjects are opted-out.
2. The primary subject, secondary subject, or rater are deleted and the **Task Owner Removal ** option is set to Delete Task.

In Blue, if a subject is deleted but the Task Owner Removal option is not set to Delete Task, the responses for that subject are still considered to be Active (Not Deleted).

3. The task for the rater is deleted.

For example, there is a course 'Math 101' with 2 teachers ('Professor Bob', 'Professor Jane') and 2 students ('Student Liz', 'Student Ted'). If the students completed their questionnaire, we have these exported responses:

Math 101 - Professor Bob - Student Liz

Math 101 - Professor Jane - Student Liz

Math 101 - Professor Bob - Student Ted

Math 101 - Professor Jane - Student Ted

If teacher 'Professor Jane' is removed, we only have these responses:

Math 101 - Professor Bob - Student Liz

Math 101 - Professor Bob - Student Ted

If student 'Student Liz' is removed, we only have these responses:

Math 101 - Professor Bob - Student Ted

Math 101 - Professor Jane - Student Ted

If the course 'Math 101' is removed, there are no responses for this course.

Responses which were not filled out

TaskStatus is exported as “DNR” (Did Not Respond) if the user has not Submitted or Saved the questionnaire. These “DNR” responses are exported if the Primary, Secondary, and Rater subjects are all Active (not Removed).

For example, using the case in the previous section, if a third teacher 'Professor Dan' had been added to the course 'Math 101' after the user 'Student Liz' has completed their task, the responses are exported as such:

Mandatory Input Parameters:

• ProjectID - the project must be a private project and contain Fillout tasks, or GetResponse4() will not generate any output. If the project does not contain any Fillout tasks or is not private, a message will be logged in the MessageLog.txt file included in the ZIP file.

Optional Input Parameters:

• OutputType can be either “caption” or “score”; the default value is “caption” if nothing is entered. This value is not case sensitive.
• currentLanguage
  • Specifies the language that column headers, option labels, and other system captions will be used in the exported data.
  • If no language is provided, the returned tasks use the base language of the project.
  • If project does not support the language provided, no tasks from this project will be returned.
  • Accepted values
    * ar-QA - Arabic
    * en-US - English
    * es-ES - Spanish
    * fr-FR - French
    * zh-CN - Chinese
    * de-DE - German
    * ru-RU - Russian
    * pt-BR - Portuguese
    * nl-NL - Dutch
    * da-DK - Danish
• DateFormatStr - Specify the .NET date format that should be used for all response data. The only accepted formats are:
  • MM/dd/yy hh:mm tt
  • MM/dd/yy HH:mm
  • dd/MM/yy hh:mm tt
  • dd/MM/yy HH:mm
    If no format is entered or if the format is not written exactly as mentioned, the default format is set to “MM/dd/yy hh:mm tt”.
• FilloutDateFrom - Specify the earliest fill out date that will be included in the output data following the same format as specified by DateFormatStr. If the fill out date for a response prior to this date, it will not be included in the output.
  The time portion of the date must always be included. For example, if we want the “FilloutDateFrom” parameter to export all responses starting from September 01, 2014 then the parameter must be entered as “09/01/14 00:00 AM”. This date will start at midnight. If the time units are omitted, the “FilloutDateFrom” parameter will not work.
• FilloutDateTo - Specify the latest fill out date that will be included in the output data following the same format as DateFormatStr. If the fill out date for a response is after this date, it will not be included in the output.
  The time of the date must always be entered. For example, if we want the “FilloutDateTo” parameter to export all responses up to December 31, 2014 then the parameter must be entered as “12/31/14 11:59 PM”. This date will end just before midnight. If the time units are omitted, the “FilloutDateFrom” parameter will not work.
  Note: the date/time format is precise to the minute. To include the seconds within that minute, the date/time format should specify the next minute. For example, to include all fill out dates within 11:59 PM in “12/31/14 11:59 PM”, the date/time needs to be changed to “01/01/15 00:00 AM”. This will include all the fill out dates up to and including January 1st, 2015 at midnight.
• IncludeDemographic - Specify which demographic data to include. An empty string means that no demographics are exported. “all” means to include all demographic data. For specific demographic data, a comma-delimited text can include the following:
  • For primary subject demographic data, add the prefix “ps_” before the field name.
  • For secondary subject demographic data, add the prefix “ss_” before the field name.
  • For rater demographic data, add the prefix “r_” before the field name.

If the user did not complete any responses, then the demographic data for the user is not included in the output.

• For user datasources, the required fields use the following predefined names:

• For object datasources, the required fields use the following predefined names:

• UseQuestionIdentifier - Specify how questions are presented in the response data output. If the default value false is used, the full question title will be used as the column header. If the value is true, the identifier for the question will be used as a column header, if the identifier is absent, the question title will be used instead.
• QuestionFilter - Include a comma delimited set of question identifiers to specify which questions are included in the output.

• ExportQP - A true or false value that specifies whether or not responses to personalized questions are included in the output data. Including responses to personalized questions may negatively affect performance.
• UseLatestQP - When true, the personalized question table will be generated and used in the output, but this may negatively impact performance. When false, the previously generated personalized question table will be included in the output if it exists, otherwise it will be generated.
• ExportQbank - A true or false value that specifies whether or not responses to question bank questions are included in the output. Including responses to question bank questions may negatively affect performance.
• ExportToSeparateFiles - A true or false value that specifies whether responses for projects with primary and secondary subjects are generated in one file, or whether primary subject response data is generated in one file and secondary subject response data is generated in a separate file. The default value, false, indicates that only one file will be generated.
• ExportFormat - An optional parameter. Acceptable values are text/csv or application/json. If this parameter is omitted it will return a CSV file, if the parameter is not recognized, then it will return a CSV file.