From e2caafe8f26492322e48145963544760b2c6fca4 Mon Sep 17 00:00:00 2001 From: Emmanuel Evance Date: Tue, 19 Dec 2023 12:03:19 +0300 Subject: [PATCH] improve challenges --- docs/build-for-developers/cli-challenges.md | 300 +++++++++++++------ docs/build-for-developers/cli-walkthrough.md | 11 + 2 files changed, 214 insertions(+), 97 deletions(-) diff --git a/docs/build-for-developers/cli-challenges.md b/docs/build-for-developers/cli-challenges.md index 377eea728b5..47460fd9e8b 100644 --- a/docs/build-for-developers/cli-challenges.md +++ b/docs/build-for-developers/cli-challenges.md @@ -4,130 +4,202 @@ sidebar_label: CLI Challenges slug: /cli-challenges --- -#### 🏆 Challenge: Write a job that prints your name - -1. Modify `hello.js` to print your name. -2. Re-run the job by running `openfn hello.js -a common -o tmp/output.json`. -3. Validate that you receive the logs below: - -```bash -[CLI] ✔ Compiled job from hello.js -[JOB] ℹ My name is { YourName } -[R/T] ✔ Operation 1 complete in 0ms -[CLI] ✔ Writing output to tmp/output.json -[CLI] ✔ Done in 366ms! ✨ -``` - ---- +#### Solve real-world problems and showcase your command-line skills by participating in our CLI challenges. -#### 🏆 Challenge: Get and inspect data via HTTP +:::tip Important Notes -Using the -[https://jsonplaceholder.typicode.com/users](https://jsonplaceholder.typicode.com/users) -API, get a list of users and print the first user object. +- A developer with a bit of Javascript experience should be able to write, run, + and debug complex, multi-step jobs with OpenFn, using nothing but a text + editor and their terminal. +- If you are stuck and need help, please post in + [community.openfn.org](community.openfn.org). +
+ Expand to see bug report template -1. Create file called `getUsers.js` and write your operation to fetch the user. -2. Run the job using the OpenFn/cli - `openfn getUsers.js -a http -o tmp/output.json`. -3. Validate that you receive this expected CLI logs: + ``` -```bash -openfn getUsers.js -a http -o tmp/output.json -``` + Subject: Bug Report - [Brief Description] -
- Expand to see expected CLI logs + **Description:** + [Concise description of the bug.] -``` -[CLI] ✔ Compiled job from hello.js GET request succeeded with 200 ✓ -[R/T] ✔ Operation 1 complete in 581ms -[JOB] ℹ { - id: 1, - name: 'Leanne Graham', - username: 'Bret', - email: 'Sincere@april.biz', - address: { - street: 'Kulas Light', - suite: 'Apt. 556', - city: 'Gwenborough', - zipcode: '92998-3874', - geo: { lat: '-37.3159', lng: '81.1496' } - }, - phone: '1-770-736-8031 x56442', - website: 'hildegard.org', - company: { - name: 'Romaguera-Crona', - catchPhrase: 'Multi-layered client-server neural-net', - bs: 'harness real-time e-markets' - } -} -[R/T] ✔ Operation 2 complete in 2ms -[CLI] ✔ Writing output to tmp/output.json [CLI] ✔ Done in 950ms! ✨ -``` + **Steps to Reproduce:** + 1. + 2. + 3. -
+ **Environment:** + - OS: [e.g., Windows 10] + - CLI: [e.g., v0.4.11] + - Node: [e.g., v 18.17.1] + - NPM: [e.g., 8.19.2] -:::warning Placeholder Data + **Attachments:** + [Screenshots, error messages, or relevant files.] -The data displayed in this CLI logs is generated from a -[JSONPlaceholder](https://jsonplaceholder.typicode.com/) API and does not -represent real-world information. It is intended for testing and development -purposes only. + ``` -For accurate testing, consider using real data from your API or service. +
::: +### 🏆 Create personalized greeting + +**Overview:** + +Create a new `hello.js` job to display a personalized greeting with your name. + +**Objective:** + +Compose a OpenFn job using [common adaptor](/adaptors/packages/common-docs) that +outputs a greeting message containing your name. + +**Requirements:** + +1. Install the latest version of common adaptor. + + ``` + openfn repo install @openfn/language-common + ``` + +**Tasks:** + +1. Create a new file named `hello.js`. +2. Write a JavaScript script in `hello.js` to generate a greeting with your + name. +3. Run the job using the command `openfn hello.js -a common -o tmp/output.json`. +4. Confirm the successful execution. + +**Review Checklist:** + +- [ ] Successfully created a new file `hello.js`. +- [ ] Wrote a JavaScript script in `hello.js` for a personalized greeting. +- [ ] Executed the job using the provided command. +- [ ] Verified the correct logs in the CLI output. + --- -#### 🏆 Challenge: Fetch Covid-19 metadata +### 🏆 Fetch and inspect data via HTTP -1. Using the [disease.sh API](https://disease.sh/), write an operation that - returns all covid-19 metadata. +**Overview:** -:::tip +Write a job to fetch user data from the +[JSONPlaceholder API](https://jsonplaceholder.typicode.com/users) using OpenFn +[http adaptor](/adaptors/packages/http-docs). -`https://disease.sh/v3/covid-19/` as your **baseUrl** in `state.configuration` +**Objective:** -::: +Fetch and print the details of the first user from the JSONPlaceholder API. + +**Requirements:** + +1. Utilize the + [JSONPlaceholder API](https://jsonplaceholder.typicode.com/users). +2. Create a file named `getUsers.js` to contain the script. + +**Tasks:** + +1. Create a file (`getUsers.js`) to house the script. +2. Fetch a list of users from the JSONPlaceholder API. +3. Print the details of the first user. +4. Run the job using OpenFn/cli: + `openfn getUsers.js -a http -o tmp/output.json`. +5. Validate the expected CLI logs. + +**Review Checklist:** -2. Validate your output: there are a lot of ways you might choose to format or - display this data. Share your results with your administrator for feedback. +- [ ] Successful retrieval of user data. +- [ ] Correct printing of the first user's details. +- [ ] Proper use of the OpenFn http adaptor functions. +- [ ] Verified the correct logs in the CLI output. --- -#### 🏆 Challenge: Practice CLI arguments and commands +### 🏆 Retrieve Covid-19 metadata + +**Overview:** + +Fetch and present COVID-19 metadata using the +[disease.sh API](https://disease.sh/). + +**Objective:** + +Write a job that retrieves comprehensive COVID-19 data from the API and group it +by region. + +**Requirements:** + +1. Install the latest version of http adaptor. + +``` +openfn repo install @openfn/language-http +``` -Perform these tasks and submit answers to the discussion questions to your -administrator for feedback. +**Tasks:** -1. Compile a openfn job (**hello.js**). +1. Write an OpenFn operation to pull COVID-19 metadata from the + [disease.sh API](https://disease.sh/). + - Utilize `https://disease.sh/v3/covid-19/` as your **baseUrl** in + `state.configuration`. +2. Run the job using the OpenFn CLI with the command + `openfn your_operation_file.js -a http -o tmp/output.json`. +3. Evaluate the output and explore different ways to format or present the + COVID-19 data by region. - > What's the difference between the job you wrote and the compiled job? +**Review Checklist:** -2. Run a job with the log level set to `none`, and then run it again with the - log level set to `debug`. +- [ ] Successfully created an OpenFn operation file. +- [ ] Implemented code to retrieve COVID-19 metadata from the provided API. +- [ ] Executed the job using the provided CLI command. +- [ ] Explored various formatting or display options for the obtained data. - > When is it appropriate to use these different log levels? +> Feel free to experiment with the data presentation to enhance your +> understanding. Good luck! 🌐🦠 --- -#### 🏆 Challenge: extract names & emails +### 🏆 Extract names & emails + +**Overview:** + +In this challenge, you will use the JSONPlaceholder API to fetch comments for a +specific post (post ID 1). Your task is to extract the "name" and "email" fields +from each comment and log the extracted data. + +**Objective:** + +Write a job that retrieves comments for post ID 1, extracts the "name" and +"email" fields from each comment, and logs the extracted data. + +**Requirements:** + +- Basic knowledge of JavaScript. +- OpenFn CLI installed on your machine. -Using -[https://jsonplaceholder.typicode.com/posts/1/comments](https://jsonplaceholder.typicode.com/posts/1/comments) -API fetch comments for post with id 1 and extract name and email from each -comment in that post +**Tasks:** -1. Get post all comments for post id 1 -2. Extract name and email from comments -3. Log the extracted data from comments +1. **Get Post Comments:** -Discuss the results with your administrator. + - Add an operation to fetch all comments for the post with ID 1 from the + [JSONPlaceholder API](https://jsonplaceholder.typicode.com/posts/1/comments). + +2. **Extract Name and Email:** + + - Write a function to extract the "name" and "email" fields from each + comment. + +3. **Log Extracted Data:** + - Log the extracted data (name and email) from each comment to the console. + +**Review Checklist:** + +- [ ] Successfully fetched comments for post ID 1. +- [ ] Implemented a function to extract "name" and "email" from comments. +- [ ] Logged the extracted data to the console. --- -#### 🏆 Challenge: control error messages +### 🏆 Control error messages Debug what is causing an error on the following line of code and display the error message @@ -137,18 +209,52 @@ error message get('posts/180'); ``` -Discuss the results with your administrator. - --- -#### 🏆 Challenge: Reduce, filter, and map +### 🏆 Data transformation and cleaning + +**Overview:** + +In this challenge, you will use JavaScript global array methods, specifically +`Array.reduce`, `Array.filter`, or `Array.map`, to create a series of operations +that fetch and filter posts by user ID. + +**Objective:** + +Write a job that retrieves posts by a specified user ID `1` + +**Requirements:** + +1. Utilize JSONPlaceholder API `https://jsonplaceholder.typicode.com`. +2. Install the latest version of http adaptor. + +``` +openfn repo install @openfn/language-http +``` + +**Tasks:** + +1. **Create File:** + + - Create a file named `getPosts.js` for your job. + +2. **Get All Posts:** + + - Add the first operation to fetch all posts. Use the provided API or any + other source of your choice that provides a list of posts. + +3. **Filter Posts by ID:** + + - Add a second operation with a function that filters posts by user ID. You + can use `Array.filter` or any other suitable method for this task. + +4. **Fetch Posts for User ID 1:** -Using Javascript globals i.e `Array.reduce`, `Array.filter` or `Array.map`, -build function that will get posts by user id. + - Use the function from the second operation to filter posts for user ID 1. -1. Create a file called job1.js -2. Add the 1st operation which is get all posts -3. Add 2nd operation which has a function that filter posts by id -4. Use the function from 2nd operation to get all post for user id 1 +**Review Checklist:** -Discuss the results with your administrator. +- [ ] Created `getPosts.js` file. +- [ ] Successfully fetched all posts. +- [ ] Implemented a function to filter posts by user ID. +- [ ] Retrieved posts for user ID 1. diff --git a/docs/build-for-developers/cli-walkthrough.md b/docs/build-for-developers/cli-walkthrough.md index 23bf275c0b8..679f0c539cb 100644 --- a/docs/build-for-developers/cli-walkthrough.md +++ b/docs/build-for-developers/cli-walkthrough.md @@ -149,6 +149,17 @@ adaptor using `-i` argument +:::warning Placeholder Data + +The data displayed in this CLI logs is generated from a +[JSONPlaceholder](https://jsonplaceholder.typicode.com/) API and does not +represent real-world information. It is intended for testing and development +purposes only. + +For accurate testing, consider using real data from your API or service. + +::: + ### 3. Understanding `state` If a job expression is a set of instructions for a chef (a recipe?) then the