From e34eaf5e81d9102bfc501b51d0addafe0a2b25e3 Mon Sep 17 00:00:00 2001 From: aleksa-krolls Date: Fri, 23 Aug 2024 23:15:00 +0300 Subject: [PATCH 1/3] adding docs on oauth, updating itnegration options --- adaptors/googlesheets.md | 160 ++++++++++++++------------------------- 1 file changed, 57 insertions(+), 103 deletions(-) diff --git a/adaptors/googlesheets.md b/adaptors/googlesheets.md index f07d4e38aee..9433b21b9cd 100644 --- a/adaptors/googlesheets.md +++ b/adaptors/googlesheets.md @@ -5,10 +5,54 @@ title: Google Forms/Google Sheets ## Google Sheets Adaptor Overview Google Sheets adaptor provides seamless integration between Google Forms, Google -Sheets, and the OpenFn platform, enabling robust data flow management. There are -two primary ways to utilize this adaptor, each catering to specific use cases: +Sheets, and the OpenFn platform, enabling robust data flow management. -### 1. Pushing Data to OpenFn +### Authentication and Authorization + +This adaptor requires OAuth authorization to connect with Google Sheets. This +authorization can be achieved by a user or organization admin consenting to an +OAuth client to access resources. Users can request authorization via the +default OpenFn Google OAuth client or choose to +`Add new (generic) OAuth client(s)` for their account and projects. + +To authorize Google Sheets for your OpenFn workflows, read our documentation on +[using OAuth credentials](/documentation/build/credentials#use-oauth2-credentials). + +:::info Google Oauth Client Setup Tips for Super Users + +Setting up your own generic OAuth client requires that you have an OAuth +application set up. If you are a super user configuring a new Google OAuth +client for your OpenFn deployment, then please refer to Google's documentation +to +[configure an OAuth Client ID](https://developers.google.com/identity/protocols/oauth2/javascript-implicit-flow), +as well as see the standard +[openid-configuration](https://accounts.google.com/.well-known/openid-configuration) +for how to complete the OAuth Client Setup form on OpenFn. + +::: + +#### Permissions (Scopes) + +Permissions and access in an OAuth instance are defined by scopes which are +named differently by providers based on their functions within their platform. + +For GoogleSheets, your super user will likely need to add the following scopes +to the Oauth Client Setup configured for Google in your OpenFn deployment. That said, +please refer to +[Google's documentation on Oauth scopes](https://developers.google.com/identity/protocols/oauth2/scopes) +for the latest information. + +- `openid` +- `email` +- `profile` +- `https://www.googleapis.com/auth/spreadsheets` + +### Integration Options + +There are a couple of primary ways to integrate with this app, each catering to +different use cases. + +#### 1. Pushing Data to OpenFn via Google App Scripts With this method, data from Google Forms or Google Sheets is automatically pushed to an OpenFn webhook trigger workflow whenever new entries are made. This @@ -66,115 +110,21 @@ function onFormSubmit(e) { } ``` -### 2. Pulling Data from Google Sheets +#### 2. Pulling Data from Google Sheets using OpenFn Alternatively, you can pull data from Google Sheets at specific intervals or on-demand using a `cron` workflow in OpenFn, allowing for more controlled data retrieval processes. This method is particularly useful when you need to fetch historical data or perform periodic data updates. +Check out the docs on available [functions](./packages/googlesheets-docs) to +learn how to configure a workflow step to use this OpenFn adaptor to +`getValues()` and fetch data from a target Google Sheet. + **Use Cases:** - Aggregating data for periodic reporting or analysis. - Implementing batch processing for efficiency and resource optimization. -The example below shows how to configure a trigger on Google sheets that sends -data to OpenFn on the first day of the month as well as a code snippet showing -how to retrieve report data from a Google Sheets spreadsheet and send it to -OpenFn. By customizing these functions to suit your specific requirements, you -can effectively manage data flow between Google Sheets and OpenFn. -![Screenshot 2024-05-20 at 20 34 52](https://github.com/OpenFn/docs/assets/167166847/61ccd374-44bb-4634-b66a-556396914e87) - -```js -// Function to send the data to OpenFn using a POST request -function sendToOpenFn(e) { - // Convert the event object to a JSON string - var payload = JSON.stringify(e); - // The URL of the OpenFn Webhook where data will be sent - var url = 'https://www.openfn.org/i/webhook-id-here'; - // Options for the UrlFetchApp.fetch method - var options = { - method: 'post', - contentType: 'application/json', - payload: payload, - }; - // Send the POST request with the payload to the specified URL - var response = UrlFetchApp.fetch(url, options); -} - -// Function to check if a value is a valid Date object -function isDate(v) { - // Check if the value is a Date object - if (Object.prototype.toString.call(v) === '[object Date]') { - // Check if the Date object is valid - if (isNaN(v.getTime())) { - return false; // Invalid date - } else { - return true; // Valid date - } - } else { - return false; // Not a Date object - } -} - -// Function to check if a value is a Number -function isNumber(v) { - // Check if the value is a Number object - if (Object.prototype.toString.call(v) === '[object Number]') { - return true; // It's a number - } else { - return false; // It's not a number - } -} - -// Function to get report data from the active Google Sheet and send it to OpenFn -function getReportData() { - // Initialize an object to hold the form ID and data - var bookReportData = { formId: 'bookReport', data: [] }; - // Get all data from the active sheet as a 2D array - var data = SpreadsheetApp.getActiveSheet().getDataRange().getValues(); - - // Initialize variables to store page count and book rating - var pageCount = 0; - var bookRating = 0; - - // Loop through each row in the data - for (i in data) { - // Check if the first cell in the row is a valid date (to ignore the header line) - if (isDate(data[i][0])) { - // If the page count column (index 3) is a number, store its value - if (isNumber(data[i][3])) { - pageCount = data[i][3]; - } - - // If the rating column (index 6) is a number, store its value - if (isNumber(data[i][6])) { - bookRating = data[i][6]; - } - - // Push the row data as an object to the bookReportData array - bookReportData.data.push({ - Timestamp: data[i][0], // Timestamp of the report - Title: data[i][1], // Title of the book - Author: data[i][2], // Author of the book - NumberOfPages: pageCount, // Number of pages in the book - Summary: data[i][4], // Summary of the book - Protagonist: data[i][5], // Protagonist of the book - Rating: bookRating, // Rating given to the book - EmailTeacher: data[i][7], // Teacher's email - EmailStudent: data[i][8], // Student's email - SendStatus: data[i][9], // Status of the data sending - }); - } - } - - // Log the bookReportData object for debugging (optional) - // Logger.log(bookReportData); - - // Send the collected data to OpenFn - sendToOpenFn(bookReportData); -} -``` - -### 3. Pushing Data to Google Sheets +#### 3. Pushing Data to Google Sheets via OpenFn The Google Sheets adaptor can also be used to push data to Google Sheets from other systems via OpenFn. This allows for seamless integration between external @@ -188,3 +138,7 @@ task tracking systems into Google Sheets for reporting purposes. A step by step guide is found [in this tutorial](https://docs.openfn.org/documentation/tutorials/http-to-googlesheets) that shows us how to get data via a REST API and push it to Google Sheet. + +### API Docs +- [Google Sheets API Overview](https://developers.google.com/sheets/api/guides/concepts) +- OpenFn Workflow Tutorial: [HTTP-to-GoogleSheets](https://docs.openfn.org/documentation/tutorials/http-to-googlesheets) From b3d2ea8a681e19a92c669792022e60b3ac539c29 Mon Sep 17 00:00:00 2001 From: aleksa-krolls Date: Fri, 23 Aug 2024 23:22:21 +0300 Subject: [PATCH 2/3] update general oauth guidance to mention Adaptors docs --- docs/manage-projects/oauth.md | 44 ++++++++++++++++++----------------- 1 file changed, 23 insertions(+), 21 deletions(-) diff --git a/docs/manage-projects/oauth.md b/docs/manage-projects/oauth.md index 3000a33fc52..a6994ae175d 100644 --- a/docs/manage-projects/oauth.md +++ b/docs/manage-projects/oauth.md @@ -44,16 +44,15 @@ Oauth clients can be set up either on the ### Creating an OAuth client (Super Users) -:::note - Currently only users with +:::note Currently only users with [super user privileges](https://docs.openfn.org/documentation/manage-projects/user-roles-permissions#super-user-privileges) -can create and manage OAuth clients. If you're using the OpenFn cloud-hosted platform SaaS, -contact [support@openfn.org](mailto://support@openfn.org) for assistance adding a new Oauth client. -::: +can create and manage OAuth clients. If you're using the OpenFn cloud-hosted +platform SaaS, contact [support@openfn.org](mailto://support@openfn.org) for +assistance adding a new Oauth client. ::: If you have not created a client before or a superuser has not created a client for the projects/users in the deployment, you will see an empty block with a -button prompting you to create a client as shown below. +button prompting you to create a client as shown below. ![New client](/img/create_new_oauth_client.png) @@ -63,12 +62,16 @@ to. In this case click on the `New credential` button and select ![OAuth dropdown](/img/oauth_dropdown.png) -:::note - Make sure you add https://app.openfn.org/authenticate/callback as the +:::note Make sure you add https://app.openfn.org/authenticate/callback as the callback URL for the application when enabling OAuth authentication for the -third party application. +third party application. (Note: You should substitue `https://app.openfn.org/` +with _your_ OpenFn's deployment base URL if you're not using app.openfn.org.) ::: +:::tip For app-specific guidance (e.g., how to set up an Oauth Client +[for Google Sheets](./adaptors/googlesheets)), refer to the relevant +[Adaptor documentation](./adaptors) for app-specific guidance ::: + ### Sharing OAuth Clients A super user has the privilege to share OAuth clients with projects in two ways: @@ -117,10 +120,8 @@ credentials and are associated with clients. ![New credential](/img/new_cred.png) -:::tip -Unlike for OAuth clients, project owners or admins can also create -credentials, not only super users. -::: +:::tip Unlike for OAuth clients, project owners or admins can also create +credentials, not only super users. ::: 2. Then, in the credential type modal, find and select the Oauth client to use for creating the OAuth credential. This will open a new modal for you to @@ -131,18 +132,16 @@ credentials, not only super users. Clicking this button will open a new tab for you to grant OpenFn an authorization token to authenticate your requests. -:::note - When you have siged in, you will be required to grant OpenFn access by +:::note When you have siged in, you will be required to grant OpenFn access by clicking `Allow` on the permissions modal. Please note that this might look different for different applications but the intent is to grant OpenFn perimission to carry out certain actions to the application on your behalf. The user authenticating OAuth clients should have the required permissions in the -application. -::: +application. ::: ### Deleting Clients and Credentials -To delete a credential/client, simply click `Delete`. +To delete a credential/client, simply click `Delete`. ![OAuth edit](/img/oauth_client_edit.png) @@ -152,9 +151,12 @@ As soon as you confirm that you want to delete a credential, you will receive an email to notify you that the credential has been scheduled for deletion. The scheduled deletion date is set by a grace period configured by your instance -administrator. On the [OpenFn hosted instance](https://app.openfn.org/), it will be permanently deleted after 7 days. +administrator. On the [OpenFn hosted instance](https://app.openfn.org/), it will +be permanently deleted after 7 days. ### More on Managing Credentials -Go to the docs on [managing user credentials](../manage-users/user-credentials.md) to learn more -about credential management for the applications you are integrating with on OpenFn. +Go to the docs on +[managing user credentials](../manage-users/user-credentials.md) to learn more +about credential management for the applications you are integrating with on +OpenFn. From e5c2efacb50ce07c12455b1621027d54a9d91e4b Mon Sep 17 00:00:00 2001 From: christad92 Date: Wed, 28 Aug 2024 12:33:21 +0100 Subject: [PATCH 3/3] Minor fixes and prettier --- adaptors/googlesheets.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/adaptors/googlesheets.md b/adaptors/googlesheets.md index 9433b21b9cd..fb303ceab65 100644 --- a/adaptors/googlesheets.md +++ b/adaptors/googlesheets.md @@ -37,8 +37,8 @@ Permissions and access in an OAuth instance are defined by scopes which are named differently by providers based on their functions within their platform. For GoogleSheets, your super user will likely need to add the following scopes -to the Oauth Client Setup configured for Google in your OpenFn deployment. That said, -please refer to +to the Oauth Client Setup configured for Google in your OpenFn deployment. That +said, please refer to [Google's documentation on Oauth scopes](https://developers.google.com/identity/protocols/oauth2/scopes) for the latest information. @@ -139,6 +139,8 @@ A step by step guide is found [in this tutorial](https://docs.openfn.org/documentation/tutorials/http-to-googlesheets) that shows us how to get data via a REST API and push it to Google Sheet. -### API Docs +### Helpful Resources + - [Google Sheets API Overview](https://developers.google.com/sheets/api/guides/concepts) -- OpenFn Workflow Tutorial: [HTTP-to-GoogleSheets](https://docs.openfn.org/documentation/tutorials/http-to-googlesheets) +- OpenFn Workflow Tutorial: + [HTTP-to-GoogleSheets](https://docs.openfn.org/documentation/tutorials/http-to-googlesheets)