A response to the form as a whole. A FormResponse
can be used in three ways: to access
the answers submitted by a respondent (see getItemResponses()
), to programmatically
submit a response to the form (see withItemResponse(response)
and submit()
), and to generate a URL for the form which pre-fills fields using the provided
answers. FormResponse
s can be created or accessed from a Form
.
// Open a form by ID and log the responses to each question. var form = FormApp.openById('1234567890abcdefghijklmnopqrstuvwxyz'); var formResponses = form.getResponses(); for (var i = 0; i < formResponses.length; i++) { var formResponse = formResponses[i]; var itemResponses = formResponse.getItemResponses(); for (var j = 0; j < itemResponses.length; j++) { var itemResponse = itemResponses[j]; Logger.log('Response #%s to the question "%s" was "%s"', (i + 1).toString(), itemResponse.getItem().getTitle(), itemResponse.getResponse()); } }
Methods
Method | Return type | Brief description |
---|---|---|
getEditResponseUrl() | String | Generates a URL that can be used to edit a response that has already been submitted. |
getGradableItemResponses() | ItemResponse[] | Gets all item responses contained in a form response, in the same order that the items appear in the form. |
getGradableResponseForItem(item) | ItemResponse | Gets the item response contained in a form response for a given item. |
getId() | String | Gets the ID of the form response. |
getItemResponses() | ItemResponse[] | Gets all item responses contained in a form response, in the same order that the items appear in the form. |
getRespondentEmail() | String | Gets the email address of the person who submitted a response, if the Form.setCollectEmail(collect) setting is enabled. |
getResponseForItem(item) | ItemResponse | Gets the item response contained in this form response for a given item. |
getTimestamp() | Date | Gets the timestamp for a form response submission. |
submit() | FormResponse | Submits the response. |
toPrefilledUrl() | String | Generates a URL for the form in which the answers are pre-filled based on the answers in this form response. |
withItemGrade(gradedResponse) | FormResponse | Adds the given item response's grades to a form response. |
withItemResponse(response) | FormResponse | Adds the given item response to a form response. |
Detailed documentation
getEditResponseUrl()
Generates a URL that can be used to edit a response that has already been submitted. If the
Form.setAllowResponseEdits(enabled)
setting is disabled, the link leads to a page that
explains that editing form responses is disabled. Anyone who visits the link can edit the
response, although they need an account with access to the form if the Form.setRequireLogin(requireLogin)
setting is enabled. If the Form.setCollectEmail(collect)
setting is enabled, the form records the email address of the user who edited the response
instead of the email address of the original respondent.
For a form response that the script has created but not yet submitted, this method returns
null
.
Return
String
— the URL to change a submitted response
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
getGradableItemResponses()
Gets all item responses contained in a form response, in the same order that the items appear
in the form. This method works similarly to getItemResponses()
, but to allow for grading
a missing answer, it still returns an ItemResponse
if the corresponding Item
can be graded (ie has a point value), even if there isn't an actual response. However, if the
Item
isn't gradable, this method excludes that item from its returned array.
Return
ItemResponse[]
— an array of responses to every question item within the form for which the respondent
could receive a score.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
getGradableResponseForItem(item)
Gets the item response contained in a form response for a given item. This method works
similarly to getResponseForItem(item)
, but to allow for grading a missing answer, it still
returns an ItemResponse
if the corresponding Item
can be graded (ie has a point
value), even if there isn't an actual response. However, if the Item
isn't gradable,
this method returns null
.
Parameters
Name | Type | Description |
---|---|---|
item | Item |
Return
ItemResponse
— the response for a given item, or null
if none exists and the item is ungraded
getId()
Gets the ID of the form response. This method returns null
if the form response has not
been submitted.
Return
String
— the ID of the form response, or null
if the form response has not been
submitted
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
getItemResponses()
Gets all item responses contained in a form response, in the same order that the items appear
in the form. If the form response does not contain a response for a given TextItem
,
DateItem
, TimeItem
, or ParagraphTextItem
, the ItemResponse
returned for that item will have an empty string as the response. If the form response omits a
response for any other item type, this method excludes that item from its returned array.
Return
ItemResponse[]
— an array of responses to every question item within the form for which the respondent
provided an answer
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
getRespondentEmail()
Gets the email address of the person who submitted a response, if the Form.setCollectEmail(collect)
setting is enabled.
For a form response that the script has created but not yet submitted, this method returns
null
.
Return
String
— the email address of the person who submitted this response, if available, or null
if the script created this response but has not yet submitted it
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
getResponseForItem(item)
Gets the item response contained in this form response for a given item.
Parameters
Name | Type | Description |
---|---|---|
item | Item |
Return
ItemResponse
— the response for a given item, or null
if none exists
getTimestamp()
Gets the timestamp for a form response submission.
For a form response that the script has created but not yet submitted, this method returns
null
.
Return
Date
— the timestamp at which this response was submitted, or null
if the script
created this response but has not yet submitted it
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
submit()
Submits the response. Throws a scripting exception if the response has already been submitted.
Return
FormResponse
— a newly created response saved to the form's response store
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
toPrefilledUrl()
Generates a URL for the form in which the answers are pre-filled based on the answers in this form response.
Return
String
— the URL for a form with pre-filled answers
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
withItemGrade(gradedResponse)
Adds the given item response's grades to a form response. This method applies only to form responses that have already been submitted, and only affects stored grades once they are submitted. This method also only updates the item response's grades; it does not affect the actual response (since the response has already been submitted). If this method is called multiple times for the same item, only the last grade is retained. If the ItemResponse contains no grades, this method will remove grades for the item.
// Programmatically award partial credit for a given response var form = FormApp.openById('1234567890abcdefghijklmnopqrstuvwxyz'); var formResponses = form.getResponses(); var formItems = form.getItems(); for (var i = 0; i < formResponses.length; i++) { var formResponse = formResponses[i]; for (var j = 0; j < formItems.length; j++) { var item = formItems[j]; var points = item.asMultipleChoiceItem().getPoints(); var itemResponse = formResponse.getGradableResponseForItem(item); Logger.log('Award half credit for answers containing the word "Kennedy"'); var answer = itemResponse.getResponse(); if (answer != null && answer.includes('Kennedy')) { itemResponse.setScore(points / 2); formResponse.withItemGrade(itemResponse); } } } form.submitGrades(formResponses);
Parameters
Name | Type | Description |
---|---|---|
gradedResponse | ItemResponse |
Return
FormResponse
— this FormResponse
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
withItemResponse(response)
Adds the given item response to a form response. This method applies only to form responses that the script has created but not yet submitted; it cannot affect stored responses. If this method is called multiple times for the same item, only the last item response is retained.
Parameters
Name | Type | Description |
---|---|---|
response | ItemResponse |
Return
FormResponse
— this FormResponse
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms