Google Forms

The Google Forms connector integrates with Swimlane Turbine, facilitating to get response of a form.

Prerequisites:

The Google Forms connector can be authenticated in one of two ways:

Access to the GCP Console using admin privileges on the domain you’re looking to manage.

Access to the GSuite Admin Console using admin privileges on the domain you’re looking to manage.

Asset Setup

Scope:

Get Form Response of a Google Forms requires one of the following OAuth scopes:

https://www.googleapis.com/auth/drive

https://www.googleapis.com/auth/drive.file

https://www.googleapis.com/auth/forms.responses.readonly

Capabilities

This connector provides the following capabilities:

* Get Form Response

GCP Project Creation:

Navigate to this link to create a new project: https://console.cloud.google.com/projectcreate

Name your project and click Create. We recommend specific and recognizable project names.

Navigate to your projects, and select your new project.

Enable the Google Forms API:

Go to the API & Services Dashboard in the Cloud Console.

Click on the "Enable APIs and Services" button.

Search for "Google Forms API" and enable it for your project.

Asset Configuration:

Configuring a Service Account:

Google Forms connector requires a Google service account to authenticate.

Open https://console.developers.google.com/iam-admin/serviceaccounts

Select the appropriate project

Click + CREATE NEW SERVICE ACCOUNT

Assign a name for the service account and add a description, click CREATE AND CONTINUE

Click the Select a Role dropdown and type “Owner” in the filter. Choose Owner and click Continue

For the menu specifying Grant users access to this service account (optional) you may select Users or Skip and click Done. This is not required for the connector

Click on the newly created service account email

Navigate to the KEYS menu

Click ADD KEY, select CREATE NEW KEY, select JSON format, and click CREATE. Make sure you download the .json file presented. This file will be needed when configuring the asset in Swimlane

Navigate to the Details menu at the top of the screen. Copy down the Unique ID to be used in the Setting API Scopes step below

Delegating Domain-Wide Authority (Recommended)

In order to support accessing multiple user's accounts, domain-wide authority must be enabled before creating a service account. Choosing not to delegate domain-wide authority will heavily limit the scope of what this connector can do. If the connector will only operate against a single account, the next section (Setting API Scopes) can be skipped.

Setting API Scopes:

After creating a service account, the necessary API scopes required to be authorized must be set.

From https://admin.google.com, navigate to Security > API Controls and then click Manage Domain Wide Delegation at the bottom of the window.

Click Add new

In the Client ID field, enter the Unique ID from the service account Details menu

Enter the following CSV value into the OAuth Scopes (comma-delimited) input: https://www.googleapis.com/auth/drive,https://www.googleapis.com/auth/drive.file,https://www.googleapis.com/auth/forms.responses.readonly

Click Authorize

Credentials:

The contents of the JSON credentials key file downloaded when creating a service account must be base64-encoded when creating the Google Forms asset.

For Linux and Mac:

$ cat <path_to_credentials.json> | base64

For Windows using Powershell:

[convert]::ToBase64String((Get-Content -path "your_file_path" -Encoding byte))

Now copy the Base64 encoded string and paste it into the Service Account JSON field.

Delegate Account:

The delegate account value is used to determine which account to operate as when running actions. This value should be the email address for the target account (the mailbox you are trying to read/write).

Some actions provide an optional input to override the asset value.

In most - if not all cases an Admin account of the Google Workspace should be used. It should not be the service account email.

Customer ID:

The unique ID for the customer's Google Workspace account. As an account administrator, you can also use the my_customer alias to represent your account's customerId. The customerId is also returned as part of the users resource.

In order to get this value, navigate to https://admin.google.com. Then go to Account - Account Settings, and you will find it listed.

OAuth 2.0

To configure OAuth 2.0 for the Google Forms Connector, follow these steps:

Navigate to the Google Cloud Console.

Select your project from the top menu.

In the left sidebar, select "APIs & Services" > "Credentials."

Click the "+ CREATE CREDENTIALS" button and select "OAuth 2.0 Client ID."

Under "Application type," select "Web application."

Enter a name for the OAuth 2.0 client.

Click "Create." A dialog with your client ID and client secret will appear.

Click "OK" to close the dialog.

Next to the OAuth 2.0 client you just created, click on the pencil icon to edit the client.

Under "Scopes for Google APIs," add the necessary scopes that are required for your connector (as specified in the "Setting API Scopes" section of this README).

Click "Save."

Your OAuth 2.0 client is now configured and ready to be used with the Google Forms Connector.

Once this is configured, you need to provide the refresh token in the asset. If you dont know how to achieve this, Swimlane will provide you with a script that will help you to get the refresh token.

Notes

Google Forms API Authentication

Google Forms API Documentation

Additional Documentation

Google Forms Connector Documentation

Google Forms API Documentation

Configurations

Google Forms Authentication

Authenticates Google Forms using Google credentials

Configuration Parameters

Parameter	Description	Type	Required
client_id	The client ID for the OAuth 2.0 application.	string	Required
client_secret	The client secret for the OAuth 2.0 application.	string	Required
refresh_token	OAuth 2.0 refresh token used to obtain new access tokens. If using a refresh token, you must also provide a client ID and secret.	string	Required
scope	Permission scopes for this action.	array	Optional

Google Forms Service Account Authentication

Authenticates Google Forms using Service Account.

Configuration Parameters

Parameter	Description	Type	Required
credentials	Base64-encoded contents from Service Account JSON credentials file. See README for setup instructions	string	Required
delegate_account	Account to execute integrations under. If not specified, the integration will run as a service account. Using a Service Account will introduce limitations. See Readme	string	Required
scope	Permission scopes for this action.	array	Optional

Actions

Get Form Response

Get one response from the form.

Input

Argument Name	Type	Required	Description
formId	string	Required	Unique identifier
responseId	string	Required	Unique identifier

Input Example

{"formId":"1Ywm8F14oSKhavumjCH8Pg21bMk37m1No9Pldswnkfrs","responseId":"ACYDBNj6GvgmZyBGcpp-HfSxtzFa1CgaSXc2euOmODQ0FjNf8UgxKF0V-uwLdNO1OF075OY"}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
response	object	Output field: response
response.formId	string	Unique identifier
response.responseId	string	Unique identifier
response.createTime	string	Time value
response.lastSubmittedTime	string	Time value
response.respondentEmail	string	Output field: response.respondentEmail
response.answers	object	Output field: response.answers
response.answers.questionId	string	Unique identifier
response.answers.grade	object	Output field: response.answers.grade
response.answers.textAnswers	object	Output field: response.answers.textAnswers
response.answers.fileUploadAnswers	object	Output field: response.answers.fileUploadAnswers
response.totalScore	number	Score value

Output Example

{"status_code":200,"response_headers":{},"reason":"OK","response":{"formId":"1Ywm8F14oSKhavumjCH8Pg21bMk37m1No9Pldswnkfrs","responseId":"ACYDBNj6GvgmZyBGcpp-HfSxtzFa1CgaSXc2euOmODQ0FjNf8UgxKF0V-uwLdNO1OF075OY","createTime":"2024-03-15T11:50:57.255Z","lastSubmittedTime":"2024-03-15T11:50:57.255312Z","respondentEmail":"[email protected]","answers":{"questionId":"","grade":{},"textAnswers":{},"fileUploadAnswers":{}},"totalScore":0}}

List Form Responses

List a form's responses.

Input

Argument Name	Type	Required	Description
formId	string	Required	ID of the Form whose responses to list.
parameters.filter	string	Optional	Which form responses to return. Currently, the only supported filters are timestamp > N, timestamp >= N. timestamp > N - which means to get all form responses submitted after (but not at) timestamp N. timestamp >= N - which means to get all form responses submitted at and after timestamp N.
parameters.pageSize	number	Optional	The maximum number of responses to return. The service may return fewer than this value. If unspecified or zero, at most 5000 responses are returned.
parameters.pageToken	string	Optional	A page token returned by a previous list response. If this field is set, the form and the values of the filter must be the same as for the original request.

Input Example

{"parameters":{"filter":"timestamp > 2024-05-20T01:35:04.061199Z","pageSize":1,"pageToken":"ATwmTS0+9eKxqjzUm7/fOyLxwcIFFyZO2KDxFrAdVQP29WFf1VGG+shSLUFwyjT01BznQglc3gJSa+wGtfvTZsPc5B2zmYkrTgOI8iQIWC2jmwvHh/xhk0ldEkQOvOrQ5h6kc82I3EjpBDum11ms4eQG3WI1gjb8/hokhYHgj0uMJduGwJb2SPWCJomIdJ5KVSaafwcdbtLnoMTQnMqjdBlamJwm/eJi/Kr+qIcrnGHJmIAFANgUh3+4X0pELuPaP+WhUi5AmXwqn1t9THuXVmYYZj7m5NhzN9x2LTIEU/e4dJy/7Zf/vonns"},"formId":"1okCCJzxLmfzE6LOHtbrRjgxJoaXDueD1Nw_Kpd_lNpg"}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
response	object	Output field: response
response.responses	array	Output field: response.responses
response.responses.responseId	string	Unique identifier
response.responses.createTime	string	Time value
response.responses.lastSubmittedTime	string	Time value
response.responses.answers	object	Output field: response.responses.answers
response.responses.answers.72d3dca7	object	Output field: response.responses.answers.72d3dca7
response.responses.answers.72d3dca7.questionId	string	Unique identifier
response.responses.answers.72d3dca7.textAnswers	object	Output field: response.responses.answers.72d3dca7.textAnswers
response.nextPageToken	string	Output field: response.nextPageToken

Output Example

{"status_code":200,"response_headers":null,"reason":"OK","response":{"responses":[{}],"nextPageToken":"ATwmTS0N2XBPyqm2nd55WDDz3ZS2UY+bMHgy9fqEml5g9H+RIGS7nPTDuPjRtlVNnu13cuU1uu6nh+IG..."}}

Response Headers

Header	Description	Example
Content-Type	The media type of the resource	application/json
Date	The date and time at which the message was originated	Thu, 01 Jan 2024 00:00:00 GMT