Skip to content

Commit 4c372f5

Browse files
aleksa-krollsaleksa-krolls
authored
Merge pull request #410 from OpenFn/397-workflow-tutorial
new http to googlesheets tutorial - v2 docs
2 parents d3c6ef9 + 349866e commit 4c372f5

File tree

3 files changed

+169
-2
lines changed

3 files changed

+169
-2
lines changed

‎docs/tutorials/http-to-googlesheets.md

+164
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
---
2+
sidebar_label: HTTP to GoogleSheets
3+
title: HTTP to GoogleSheets Workflow
4+
---
5+
6+
# Create a Workflow connecting a REST API to Google Sheets
7+
8+
In this tutorial, we are going to walk through how to create a simple OpenFn
9+
Workflow that automates syncing data between a REST API and Google Sheets, using
10+
the `http` and `GoogleSheets` [Adaptors](/adaptors).
11+
12+
## Video Walkthrough
13+
14+
Watch the video and follow along with the steps below.
15+
16+
<iframe width="784" height="441" src="https://www.youtube.com/embed/PMj8445gLA4?si=WbJ4tmr_jnKyBfg8" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
17+
18+
## Before you start
19+
20+
Here are some we assume you've looked over before you begin this process.
21+
22+
- You have checked out our glossary and have an understanding of basic OpenFn &
23+
API concepts. Check out the pages below to get started
24+
- [OpenFn Concepts](../get-started/terminology.md)
25+
- [A glossary for data integration](../get-started/glossary.md)
26+
- You have a Google Account. We will use it to create a credential to authorize
27+
with Google Sheets.
28+
- You have access to an OpenFn project (either on a locally installed
29+
[OpenFn v2 app](https://github.com/OpenFn/lightning) or on
30+
[app.openfn.org](https://app.openfn.org)).
31+
32+
## Getting started
33+
34+
In this walkthrough, we will configure a Workflow to **automatically sync `user`
35+
data from a web REST API, and import this data to a GoogleSheet**.
36+
37+
**This integration can be broken up into two parts:**
38+
39+
1. Get data from the REST API (the "source" app)
40+
2. Transforming & importing this data to a table in your GoogleSheet (the
41+
"destination" app)
42+
43+
Let’s get started!
44+
45+
## 1: Create a new Workflow
46+
47+
To create a new Workflow in your Project:
48+
49+
1. Go to the `project dashboard` page.
50+
2. Click `Create new workflow` button.
51+
3. Give your Workflow a descriptive `Name` (e.g., `Sync Users List`).
52+
4. Choose your [Trigger](../build/triggers.md)
53+
5. Edit your first [Step](../build/steps/steps.md)
54+
55+
## 2. Configure your first Step to get data from the REST API
56+
57+
[JSONPlaceholder](https://jsonplaceholder.typicode.com/users) provides a free
58+
fake API for testing and prototyping. We will be using the
59+
[Users Rest API](https://jsonplaceholder.typicode.com/users) for extracting
60+
users data. This involves configuring a step in OpenFn to fetch users data via a
61+
`GET` HTTP request. Click your first step to set up!, Configurate the step with
62+
following options
63+
64+
- Name `Fetch Users`
65+
- Adaptor `http`
66+
- Version: `6.0.0`
67+
- Credentials (Optional: "Raw JSON" credential) -
68+
`{ "baseUrl": "https://jsonplaceholder.typicode.com/"}`
69+
- Job code: Add the operation `get("users")` in the code block if you've
70+
configured the "Raw JSON" credential for the jsonplaceholder as the baseURL.
71+
72+
:::tip Need help writing job code?
73+
74+
Check out the docs on the ["http" Adaptor](/adaptors/packages/http-readme),
75+
[configuring Steps](../build/steps/steps.md), and
76+
[job-writing](../build/steps/jobs.md).
77+
78+
:::
79+
80+
**Once you are finished configuring and writing your Step, save and run it!**
81+
82+
- See the [Workflows section](../build/workflows.md) for more guidance on
83+
building & running Workflows.
84+
85+
**Check out the `Output & Log` panel to see if your run succeeded.** If it
86+
succeeded, you should see:
87+
88+
- Status `success`
89+
- Log tab end with `Run complete with status: success`
90+
- Input tab has `{}`
91+
- Output tab has `{ data: [ {...}]}`
92+
93+
## 3. Configure another Step to transform the data & import your GoogleSheet
94+
95+
Create a new Googlesheet `Credential` using your Google account's email. (Make
96+
sure this Google user has edit access to the GoogleSheet you want to integrate
97+
with.)
98+
99+
For this demo, we have configured the Googlesheet
100+
[like this](https://docs.google.com/spreadsheets/d/1gT4cpHSDQp8A_JIX_5lqTLTwV0xBo_u8u3ZNWALmCLc/edit?usp=sharing)
101+
to store the `users` data.
102+
103+
Create a new step with the `googlesheet` adaptor for loading the users data into
104+
your destination GoogleSheet. Configure the step with the following options
105+
106+
- Name `Sync Users`
107+
- Adaptor `googlesheets`
108+
- Version: `2.2.2`
109+
- Credentials: Create new `GoogleSheet OAuth` Credential and save it
110+
- Step operations: For this job we will use the `appendValues()` operation to
111+
add an array of rows to the spreadsheet. Make sure you update the
112+
`spreadsheetId` to match the Id of your spreadsheet
113+
114+
```js
115+
// Prepare array of users data
116+
fn(state => {
117+
const users = state.data.map(
118+
({ id, name, username, address, phone, website, company }) => [
119+
id,
120+
name,
121+
username,
122+
address.city,
123+
phone,
124+
website,
125+
company.name,
126+
]
127+
);
128+
129+
return { ...state, users };
130+
});
131+
132+
// Append user data to GoogleSheet
133+
appendValues({
134+
spreadsheetId: '1gT4cpHSDQp8A_JIX_5lqTLTwV0xBo_u8u3ZNWALmCLc',
135+
range: 'users!A1:G1',
136+
values: state => state.users,
137+
});
138+
```
139+
140+
- Input - `Final output of Fetch Users`
141+
142+
If you have already ran the `Fetch Users` Step, you will have initial input to
143+
test `Sync Users` Step. Select the input from the input panel and click
144+
`Create New Work Order` to run this Step.
145+
146+
## 4. Time to test!
147+
148+
1. Select and open inspector for `Fetch Users` step
149+
2. Create a new empty input `{}`
150+
3. Click `Create New Work Order` to execute the step
151+
4. Check results in `Output & Logs` panel and ensure that both steps have passed
152+
with status `success`
153+
5. Finally check your spreadsheet to see the synced users data
154+
155+
Encountering errors or getting stuck? Check out the
156+
[Workflow](../build/workflows.md) or
157+
[Troubleshooting](../monitor-history/troubleshooting.md) docs.
158+
159+
:::tip Are you blocked? Have questions?
160+
161+
Reminder to [watch the video](#video-walkthrough) or post on the
162+
[Community](https://community.openfn.org) to ask for help!
163+
164+
:::

‎docs/tutorials/tutorial.md

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
11
---
22
title: Workflow Tutorial
33
---
4+
45
# Tutorial: Creating your first workflow
56

67
:::warning Under construction
78

8-
This docs page is under construction. Check back later for the complete docs, or check out the Docs Version "Platform (v1)".
9+
This docs page is under construction. Check back later for the complete docs, or
10+
check out the Docs Version "Platform (v1)".
911

1012
:::

‎sidebars-main.js

+2-1
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,8 @@ module.exports = {
2929
type: 'category',
3030
label: 'Tutorials',
3131
items: [
32-
'tutorials/tutorial',
32+
'tutorials/tutorial',
33+
'tutorials/http-to-googlesheets',
3334
'tutorials/kobo-to-dhis2',
3435
'tutorials/commcare-to-db'
3536
],

0 commit comments

Comments
 (0)